/**
* Starts archiving an OpenTok session.
* <p>
* Clients must be actively connected to the OpenTok session for you to successfully start
* recording an archive.
* <p>
* You can only record one archive at a time for a given session. You can only record archives
* of sessions that use the OpenTok Media Router (sessions with the
* <a href="http://tokbox.com/opentok/tutorials/create-session/#media-mode">media mode</a>
* set to routed); you cannot archive sessions with the media mode set to relayed.
* <p>
* For more information on archiving, see the
* <a href="https://tokbox.com/opentok/tutorials/archiving/">OpenTok archiving</a> programming
* guide.
*
* @param String $sessionId The session ID of the OpenTok session to archive.
* @param array $options (Optional) This array defines options for the archive. The array
* includes the following keys (all of which are optional):
*
* <ul>
*
* <li><code>'name'</code> (String) — The name of the archive. You can use this name to
* identify the archive. It is a property of the Archive object, and it is a property of
* archive-related events in the OpenTok client SDKs.</li>
*
* <li><code>'hasVideo'</code> (Boolean) — Whether the archive will record video
* (true, the default) or not (false). If you set both <code>hasAudio</code> and
* <code>hasVideo</code> to false, the call to the <code>startArchive()</code> method results
* in an error.</li>
*
* <li><code>'hasAudio'</code> (Boolean) — Whether the archive will record audio
* (true, the default) or not (false). If you set both <code>hasAudio</code> and
* <code>hasVideo</code> to false, the call to the <code>startArchive()</code> method results
* in an error.</li>
*
* <li><code>'outputMode'</code> (OutputMode) — Whether all streams in the
* archive are recorded to a single file (<code>OutputMode::COMPOSED</code>, the default)
* or to individual files (<code>OutputMode::INDIVIDUAL</code>).</li>
*
* <ul>
*
* @return Archive The Archive object, which includes properties defining the archive, including
* the archive ID.
*/
public function startArchive($sessionId, $options = array())
{
// support for deprecated method signature, remove in v3.0.0 (not before)
if (!is_array($options)) {
$options = array('name' => $options);
}
// unpack optional arguments (merging with default values) into named variables
$defaults = array('name' => null, 'hasVideo' => true, 'hasAudio' => true, 'outputMode' => OutputMode::COMPOSED);
$options = array_merge($defaults, array_intersect_key($options, $defaults));
list($name, $hasVideo, $hasAudio, $outputMode) = array_values($options);
// validate arguments
Validators::validateSessionId($sessionId);
Validators::validateArchiveName($name);
Validators::validateArchiveHasVideo($hasVideo);
Validators::validateArchiveHasAudio($hasAudio);
Validators::validateArchiveOutputMode($outputMode);
// make API call
$archiveData = $this->client->startArchive($sessionId, $options);
return new Archive($archiveData, array('client' => $this->client));
}
