/**
* @internal
*/
function __construct($opentok, $sessionId, $properties = array())
{
// unpack arguments
$defaults = array('mediaMode' => MediaMode::ROUTED, 'location' => null);
$properties = array_merge($defaults, array_intersect_key($properties, $defaults));
list($mediaMode, $location) = array_values($properties);
Validators::validateOpenTok($opentok);
Validators::validateSessionId($sessionId);
Validators::validateLocation($location);
Validators::validateMediaMode($mediaMode);
$this->opentok = $opentok;
$this->sessionId = $sessionId;
$this->location = $location;
$this->mediaMode = $mediaMode;
}
/**
* Creates a new OpenTok session and returns the session ID, which uniquely identifies
* the session.
* <p>
* For example, when using the OpenTok JavaScript library, use the session ID when calling the
* <a href="http://tokbox.com/opentok/libraries/client/js/reference/OT.html#initSession">
* OT.initSession()</a> method (to initialize an OpenTok session).
* <p>
* OpenTok sessions do not expire. However, authentication tokens do expire (see the
* generateToken() method). Also note that sessions cannot explicitly be destroyed.
* <p>
* A session ID string can be up to 255 characters long.
* <p>
* Calling this method results in an OpenTokException in the event of an error.
* Check the error message for details.
* <p>
* You can also create a session using the
* <a href="http://www.tokbox.com/opentok/api/#session_id_production">OpenTok
* REST API</a> or the <a href="https://dashboard.tokbox.com/projects">OpenTok dashboard</a>.
*
* @param array $options (Optional) This array defines options for the session. The array includes
* the following keys (all of which are optional):
*
* <ul>
*
* <li><code>'archiveMode'</code> (ArchiveMode) — Whether the session is automatically
* archived (<code>ArchiveMode::ALWAYS</code>) or not (<code>ArchiveMode::MANUAL</code>).
* By default, the setting is <code>ArchiveMode.MANUAL</code>, and you must call the
* <code>OpenTok->startArchive()</code> method to start archiving. To archive the session
* (either automatically or not), you must set the <code>mediaMode</code> key to
* <code>MediaMode::ROUTED</code>.</li>
*
* <li><code>'location'</code> (String) — An IP address that the OpenTok servers
* will use to situate the session in its global network. If you do not set a location hint,
* the OpenTok servers will be based on the first client connecting to the session.</li>
*
* <li><code>'mediaMode'</code> (MediaMode) — Whether the session will transmit
* streams using the OpenTok Media Router (<code>MediaMode.ROUTED</code>) or not
* (<code>MediaMode.RELAYED</code>). By default, the <code>mediaMode</code> property
* is set to <code>MediaMode.RELAYED</code>.
*
* <p>
* With the <code>mediaMode</code> parameter set to <code>MediaMode.RELAYED</code>, the
* session will attempt to transmit streams directly between clients. If clients cannot
* connect due to firewall restrictions, the session uses the OpenTok TURN server to relay
* audio-video streams.
*
* <p>
* The
* <a href="https://tokbox.com/opentok/tutorials/create-session/#media-mode" target="_top">
* OpenTok Media Router</a> provides the following benefits:
*
* <ul>
* <li>The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
* (When the <code>mediaMode</code> parameter is set to <code>MediaMode.ROUTED</code>,
* each client must send a separate audio-video stream to each client subscribing to
* it.)</li>
* <li>The OpenTok Media Router can improve the quality of the user experience through
* recovery</a>. With these features, if a client's connectivity degrades to a degree
* that it does not support video for a stream it's subscribing to, the video is dropped
* on that client (without affecting other clients), and the client receives audio only.
* If the client's connectivity improves, the video returns.</li>
* <li>The OpenTok Media Router supports the
* <a href="https://tokbox.com/opentok/tutorials/archiving" target="_top">archiving</a>
* feature, which lets you record, save, and retrieve OpenTok sessions.</li>
* </ul>
*
* </ul>
*
* @return \OpenTok\Session A Session object representing the new session. Call the
* <code>getSessionId()</code> method of this object to get the session ID. For example,
* when using the OpenTok.js library, use this session ID when calling the
* <code>OT.initSession()</code> method.
*/
public function createSession($options = array())
{
if (array_key_exists('archiveMode', $options) && $options['archiveMode'] != ArchiveMode::MANUAL) {
if (array_key_exists('mediaMode', $options) && $options['mediaMode'] != MediaMode::ROUTED) {
throw new InvalidArgumentException('A session must be routed to be archived.');
} else {
$options['mediaMode'] = MediaMode::ROUTED;
}
}
// unpack optional arguments (merging with default values) into named variables
$defaults = array('mediaMode' => MediaMode::RELAYED, 'archiveMode' => ArchiveMode::MANUAL, 'location' => null);
$options = array_merge($defaults, array_intersect_key($options, $defaults));
list($mediaMode, $archiveMode, $location) = array_values($options);
// validate arguments
Validators::validateMediaMode($mediaMode);
Validators::validateArchiveMode($archiveMode);
Validators::validateLocation($location);
// make API call
$sessionXml = $this->client->createSession($options);
// check response
$sessionId = $sessionXml->Session->session_id;
if (!$sessionId) {
$errorMessage = 'Failed to create a session. Server response: ' . (string) $sessionXml;
throw new UnexpectedValueException($errorMessage);
}
return new Session($this, (string) $sessionId, array('location' => $location, 'mediaMode' => $mediaMode, 'archiveMode' => $archiveMode));
}
/**
* Creates a new OpenTok session and returns the session ID, which uniquely identifies
* the session.
* <p>
* For example, when using the OpenTok JavaScript library, use the session ID when calling the
* <a href="http://tokbox.com/opentok/libraries/client/js/reference/OT.html#initSession">
* OT.initSession()</a> method (to initialize an OpenTok session).
* <p>
* OpenTok sessions do not expire. However, authentication tokens do expire (see the
* generateToken() method). Also note that sessions cannot explicitly be destroyed.
* <p>
* A session ID string can be up to 255 characters long.
* <p>
* Calling this method results in an OpenTokException in the event of an error.
* Check the error message for details.
* <p>
* You can also create a session using the
* <a href="http://www.tokbox.com/opentok/api/#session_id_production">OpenTok
* REST API</a> or the <a href="https://dashboard.tokbox.com/projects">OpenTok dashboard</a>.
*
* @param array $options (Optional) This array defines options for the session. The array includes
* the following keys (all of which are optional):
*
* <ul>
*
* <li><code>'mediaMode'</code> (String) — Whether the session will transmit
* streams using the OpenTok Media Router (<code>MediaMode.ROUTED</code>) or not
* (<code>MediaMode.RELAYED</code>). By default, the <code>mediaMode</code> property
* is set to <code>MediaMode.RELAYED</code>.
*
* <p>
* With the <code>mediaMode</code> parameter set to <code>MediaMode.RELAYED</code>, the
* session will attempt to transmit streams directly between clients. If clients cannot
* connect due to firewall restrictions, the session uses the OpenTok TURN server to relay
* audio-video streams.
*
* <p>
* The <a href="http://tokbox.com/#multiparty" target="_top"> OpenTok Media Router</a>
* provides the following benefits:
*
* <ul>
* <li>The OpenTok Media Router can decrease bandwidth usage in multiparty sessions.
* (When the <code>mediaMode</code> parameter is set to <code>MediaMode.ROUTED</code>,
* each client must send a separate audio-video stream to each client subscribing to
* it.)</li>
* <li>The OpenTok Media Router can improve the quality of the user experience through
* <a href="http://tokbox.com/#iqc" target="_top">Intelligent Quality Control</a>. With
* Intelligent Quality Control, if a client's connectivity degrades to a degree that
* it does not support video for a stream it's subscribing to, the video is dropped on
* that client (without affecting other clients), and the client receives audio only.
* If the client's connectivity improves, the video returns.</li>
* <li>The OpenTok Media Router supports the
* <a href="http://tokbox.com/platform/archiving" target="_top">archiving</a>
* feature, which lets you record, save, and retrieve OpenTok sessions.</li>
* </ul>
*
* <p>
* You will be billed for streamed minutes if you use the OpenTok Media Router or if the
* session uses the OpenTok TURN server to relay streams. For information on pricing, see the
* <a href="http://www.tokbox.com/pricing" target="_top">OpenTok pricing page</a>.
*
* <li><code>'location'</code> (String) — An IP address that the OpenTok servers
* will use to situate the session in its global network. If you do not set a location hint,
* the OpenTok servers will be based on the first client connecting to the session.</li>
*
* </ul>
*
* @return string A session ID for the new session. For example, when using the OpenTok.js
* library, use this session ID when calling the <code>OT.initSession()</code> method.
*/
public function createSession($options = array())
{
// unpack optional arguments (merging with default values) into named variables
$defaults = array('mediaMode' => MediaMode::RELAYED, 'location' => null);
$options = array_merge($defaults, array_intersect_key($options, $defaults));
list($mediaMode, $location) = array_values($options);
// validate arguments
Validators::validateMediaMode($mediaMode);
Validators::validateLocation($location);
// make API call
$sessionXml = $this->client->createSession($options);
// check response
$sessionId = $sessionXml->Session->session_id;
if (!$sessionId) {
$errorMessage = 'Failed to create a session. Server response: ' . (string) $sessionXml;
throw new UnexpectedValueException($errorMessage);
}
return new Session($this, (string) $sessionId, array('location' => $location, 'mediaMode' => $mediaMode));
}