release (#222)

* release 4.2.0 and update branch

README.md

@@ -112,6 +112,36 @@ $token = $session->generateToken(array(
 ));
 ```
 
+## Working with Streams
+
+You can get information about a stream by calling the `getStream($sessionId, $streamId)` method of the
+`OpenTok\OpenTok` class.
+
+```php
+use OpenTok\Session;
+
+// Get stream info from just a sessionId (fetched from a database)
+$stream = $opentok->getStream($sessionId, $streamId);
+
+// Stream properties
+$stream->id; // string with the stream ID
+$stream->videoType; // string with the video type
+$stream->name; // string with the name
+$stream->layoutClassList; // array with the layout class list
+```
+
+You can get information about all the streams in a session by calling the `listStreams($sessionId)` method of the
+`OpenTok\OpenTok` class.
+
+```php
+use OpenTok\Session;
+
+// Get list of streams from just a sessionId (fetched from a database)
+$streamList = $opentok->listStreams($sessionId);
+
+$streamList->totalCount(); // total count
+```
+
 ## Working with Archives
 
 You can only archive sessions that use the OpenTok Media Router
@@ -193,6 +223,58 @@ method (see "Creating Sessions," above).
 For more information on archiving, see the
 [OpenTok archiving](https://tokbox.com/opentok/tutorials/archiving/) programming guide.
 
+## Force Disconnect
+
+Your application server can disconnect a client from an OpenTok session by calling the `forceDisconnect($sessionId, $connectionId)` 
+method of the `OpenTok\OpenTok` class.
+
+```php
+use OpenTok\OpenTok;
+
+// Force disconnect a client connection
+$opentok->forceDisconnect($sessionId, $connectionId);
+```
+## Sending Signals
+
+Once a Session is created, you can send signals to everyone in the session or to a specific connection.
+You can send a signal by calling the `signal($sessionId, $payload, $connectionId)` method of the
+`OpenTok\OpenTok` class.
+
+The `$sessionId` parameter is the session ID of the session.
+
+The `$payload` parameter is an associative array used to set the
+following:
+
+* `data` (string) -- The data string for the signal. You can send a maximum of 8kB.
+
+* `type` (string) -- — (Optional) The type string for the signal. You can send a maximum of 128 characters, and only the following characters are allowed: A-Z, a-z, numbers (0-9), '-', '_', and '~'.
+
+The `$connectionId` parameter is an optional string used to specify the connection ID of
+a client connected to the session. If you specify this value, the signal is sent to
+the specified client. Otherwise, the signal is sent to all clients connected to the session.
+
+
+```php
+use OpenTok\OpenTok;
+
+// Send a signal to a specific client
+$signalPayload = array(
+    'data' => 'some signal message',
+    'type' => 'signal type'
+);
+$connectionId = 'da9cb410-e29b-4c2d-ab9e-fe65bf83fcaf';
+$opentok->signal($sessionId, $signalPayload, $connectionId);
+
+// Send a signal to everyone in the session
+$signalPayload = array(
+    'data' => 'some signal message',
+    'type' => 'signal type'
+);
+$opentok->signal($sessionId, $signalPayload);
+```
+
+For more information, see the [OpenTok signaling developer
+guide](https://tokbox.com/developer/guides/signaling/).
 
 # Samples
 

src/OpenTok/Exception/ForceDisconnectAuthenticationException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+ * Defines the exception thrown when you use an invalid API or secret and call the force disconnect method.
+ */
+class ForceDisconnectAuthenticationException extends \OpenTok\Exception\AuthenticationException implements \OpenTok\Exception\ForceDisconnectException
+{
+}

src/OpenTok/Exception/ForceDisconnectConnectionException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+* Defines an exception thrown when a call to a force disconnect method results in an error response from
+* the server.
+*/
+class ForceDisconnectConnectionException extends \OpenTok\Exception\DomainException implements \OpenTok\Exception\ForceDisconnectException
+{
+  public function __construct($message, $code)
+  {
+      parent::__construct($message, $code);
+  }
+}

src/OpenTok/Exception/ForceDisconnectException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+* The interface used by all exceptions resulting from calls to the signal API.
+*/
+interface ForceDisconnectException
+{
+}

src/OpenTok/Exception/ForceDisconnectUnexpectedValueException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+* Defines an exception thrown when a call to the force disconnect method results in an error due to an
+* unexpected value.
+*/
+class ForceDisconnectUnexpectedValueException extends \OpenTok\Exception\UnexpectedValueException implements \OpenTok\Exception\ForceDisconnectException
+{
+  public function __construct($message, $code)
+  {
+      parent::__construct($message, $code);
+  }
+}

src/OpenTok/Exception/SignalAuthenticationException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+ * Defines the exception thrown when you use an invalid API or secret and call a signal method.
+ */
+class SignalAuthenticationException extends \OpenTok\Exception\AuthenticationException implements \OpenTok\Exception\SignalException
+{
+}

src/OpenTok/Exception/SignalConnectionException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+* Defines an exception thrown when a call to a signal method results in an error response from
+* the server.
+*/
+class SignalConnectionException extends \OpenTok\Exception\DomainException implements \OpenTok\Exception\SignalException
+{
+  public function __construct($message, $code)
+  {
+      parent::__construct($message, $code);
+  }
+}

src/OpenTok/Exception/SignalException.php

@@ -0,0 +1,10 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+* The interface used by all exceptions resulting from calls to the signal API.
+*/
+interface SignalException
+{
+}

src/OpenTok/Exception/SignalUnexpectedValueException.php

@@ -0,0 +1,15 @@
+<?php
+
+namespace OpenTok\Exception;
+
+/**
+* Defines an exception thrown when a call to a signal method results in an error due to an
+* unexpected value.
+*/
+class SignalUnexpectedValueException extends \OpenTok\Exception\UnexpectedValueException implements \OpenTok\Exception\SignalException
+{
+  public function __construct($message, $code)
+  {
+      parent::__construct($message, $code);
+  }
+}

src/OpenTok/OpenTok.php

@@ -3,6 +3,8 @@
 namespace OpenTok;
 
 use OpenTok\Session;
+use OpenTok\Stream;
+use OpenTok\StreamList;
 use OpenTok\Archive;
 use OpenTok\Broadcast;
 use OpenTok\Layout;
@@ -388,21 +390,35 @@ public function deleteArchive($archiveId)
      * recent archive. If you do not specify an offset, 0 is used.
      * @param integer $count Optional. The number of archives to be returned. The maximum number of
      * archives returned is 1000.
+     * @param string $sessionId Optional. The OpenTok session Id for which you want to retrieve Archives for. If no session Id
+     * is specified, the method will return archives from all sessions created with the API key.
+     * 
      * @return ArchiveList An ArchiveList object. Call the items() method of the ArchiveList object
      * to return an array of Archive objects.
      */
-    public function listArchives($offset=0, $count=null)
+    public function listArchives($offset=0, $count=null, $sessionId=null)
     {
         // validate params
         Validators::validateOffsetAndCount($offset, $count);
+        if (!is_null($sessionId)) {
+            Validators::validateSessionIdBelongsToKey($sessionId, $this->apiKey);
+        }
 
-        $archiveListData = $this->client->listArchives($offset, $count);
+        $archiveListData = $this->client->listArchives($offset, $count, $sessionId);
         return new ArchiveList($archiveListData, array( 'client' => $this->client ));
     }
 
+    /**
+     * Force disconnects a specific client connected to an OpenTok session.
+     *
+     * @param string $sessionId The OpenTok session ID where the signal will be sent.
+     *
+     * @param string $connectionId The connectionId of the connection in a session.
+     */
+
     public function forceDisconnect($sessionId, $connectionId)
     {
-        Validators::validateSessionId($sessionId);
+        Validators::validateSessionIdBelongsToKey($sessionId, $this->apiKey);
         Validators::validateConnectionId($connectionId);
 
         return $this->client->forceDisconnect($sessionId, $connectionId);
@@ -490,6 +506,46 @@ public function updateStream($sessionId, $streamId, $properties = array())
         $this->client->updateStream($sessionId, $streamId, $properties);
     }
 
+    /**
+     * Gets an Stream object for the given stream ID.
+     * 
+     * @param String $sessionId The session ID.
+     *
+     * @param String $streamId The stream ID.
+     *
+     * @return Stream The Stream object.
+     */
+
+    public function getStream($sessionId, $streamId)
+    {
+        Validators::validateSessionId($sessionId);
+        Validators::validateStreamId($streamId);
+
+        // make API call
+        $streamData = $this->client->getStream($sessionId, $streamId);
+        return new Stream($streamData);
+
+    }
+
+    /**
+     * Returns a StreamList Object for the given session ID.
+     * 
+     * @param String $sessionId The session ID.
+     *
+     * @return StreamList A StreamList object. Call the items() method of the StreamList object
+     * to return an array of Stream objects.     
+     */
+
+    public function listStreams($sessionId)
+    {
+        Validators::validateSessionIdBelongsToKey($sessionId, $this->apiKey);
+
+        // make API call
+        $streamListData = $this->client->listStreams($sessionId);
+        return new StreamList($streamListData);
+
+    }
+
     /**
      * Initiate an outgoing SIP call
      *
@@ -566,6 +622,52 @@ public function dial($sessionId, $token, $sipUri, $options=array())
         return new SipCall($sipJson);
     }
 
+    /**
+     * Sends a signal to clients (or a specific client) connected to an OpenTok session.
+     *
+     * @param string $sessionId The OpenTok session ID where the signal will be sent.
+     *
+     *
+     * @param array $payload This array defines the payload for the signal. This array includes the
+     * following keys, of which type is optional:
+     *
+     * <ul>
+     *
+     *    <li><code>'data'</code> (string) &mdash; The data string for the signal. You can send a maximum of 8kB.</li>
+     *    <li><code>'type'</code> (string) &mdash; (Optional) The type string for the signal. You can send a maximum of 128 characters, and only the following characters are allowed: A-Z, a-z, numbers (0-9), '-', '_', and '~'. </li>
+     *
+     * </ul>
+     *
+     * 
+     * @param string $connectionId An optional parameter used to send the signal to a specific connection in a session.
+     */
+    public function signal($sessionId, $payload, $connectionId=null)
+    {
+
+        // unpack optional arguments (merging with default values) into named variables
+        $defaults = array(
+            'type' => '',
+            'data' => '',
+        );
+
+        $payload = array_merge($defaults, array_intersect_key($payload, $defaults));
+        list($type, $data) = array_values($payload);
+
+        // validate arguments
+        Validators::validateSessionIdBelongsToKey($sessionId, $this->apiKey);
+        Validators::validateSignalPayload($payload);
+
+        if (is_null($connectionId) || empty($connectionId)) {
+            // make API call without connectionId
+            $this->client->signal($sessionId, $payload);
+        } else {
+            Validators::validateConnectionId($connectionId); 
+            // make API call with connectionId
+            $this->client->signal($sessionId, $payload, $connectionId);
+        }
+
+    }
+
     /** @internal */
     private function _sign_string($string, $secret)
     {

src/OpenTok/Session.php

@@ -144,7 +144,6 @@ public function generateToken($options = array())
     {
         return $this->opentok->generateToken($this->sessionId, $options);
     }
-
 }
 
 /* vim: set ts=4 sw=4 tw=100 sts=4 et :*/

src/OpenTok/Stream.php

@@ -0,0 +1,33 @@
+<?php
+
+namespace OpenTok;
+
+class Stream {
+
+    private $data;
+
+    public function __construct($streamData)
+    {
+
+        $this->data = $streamData;
+    }
+
+    public function __get($name)
+    {
+        switch ($name) {
+            case 'id':
+            case 'videoType':
+            case 'name':
+            case 'layoutClassList':
+                return $this->data[$name];
+                break;
+            default:
+                return null;
+        }
+    }
+
+    public function jsonSerialize()
+    {
+        return $this->data;
+    }
+}