Add support to archiveMode

Author: jcague

opentok/__init__.py

@@ -1,4 +1,4 @@
-from .opentok import OpenTok, Roles, MediaModes
+from .opentok import OpenTok, Roles, MediaModes, ArchiveModes
 from .session import Session
 from .archives import Archive, ArchiveList, OutputModes
 from .exceptions import OpenTokException

opentok/opentok.py

@@ -41,6 +41,13 @@ class MediaModes(Enum):
     cannot send and receive each others' streams, due to firewalls on the clients' networks,
     their streams will be relayed using the OpenTok TURN Server."""
 
+class ArchiveModes(Enum):
+    """List of valid settings for the archiveMode parameter of the OpenTok.createSession() method."""
+    manual = u('manual')
+    """The session will be manually archived."""
+    always = u('always')
+    """The session will be automatically archived."""
+
 class OpenTok(object):
     """Use this SDK to create tokens and interface with the server-side portion
     of the Opentok API.
@@ -149,7 +156,7 @@ def generate_token(self, session_id, role=Roles.publisher, expire_time=None, dat
         )
         return token
 
-    def create_session(self, location=None, media_mode=MediaModes.relayed):
+    def create_session(self, location=None, media_mode=MediaModes.relayed, archive_mode=ArchiveModes.manual):
         """
         Creates a new OpenTok session and returns the session ID, which uniquely identifies
         the session.
@@ -196,6 +203,13 @@ def create_session(self, location=None, media_mode=MediaModes.relayed):
                * The OpenTok Media Router supports the archiving feature, which lets
                  you record, save, and retrieve OpenTok sessions (see http://tokbox.com/platform/archiving).
 
+         :param String archiveMode: Whether the session is automatically archived
+             (ArchiveMode.always) or not (ArchiveMode.manual). By default,
+             the setting is ArchiveMode.manual, and you must call the
+             start_archive() method of the OpenTok object to start archiving. To archive the session
+             (either automatically or not), you must set the mediaMode parameter to
+             MediaMode.routed.
+
         :param String location: 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.
@@ -207,7 +221,12 @@ def create_session(self, location=None, media_mode=MediaModes.relayed):
         options = {}
         if not isinstance(media_mode, MediaModes):
             raise OpenTokException(u('Cannot create session, {0} is not a valid media mode').format(role))
+        if not isinstance(archive_mode, ArchiveModes):
+            raise OpenTokException(u('Cannot create session, {0} is not a valid archive mode').format(role))
+        if archive_mode == ArchiveModes.always and media_mode != MediaModes.routed:
+            raise OpenTokException(u('A session with always archive mode must also have the routed media mode.'))
         options[u('p2p.preference')] = media_mode.value
+        options[u('archiveMode')] = archive_mode.value
         if location:
             # validate IP address
             try:
@@ -235,7 +254,7 @@ def create_session(self, location=None, media_mode=MediaModes.relayed):
                 raise AuthError('Failed to create session (code=%s): %s' % (error.attributes['code'].value, error.firstChild.attributes['message'].value))
 
             session_id = dom.getElementsByTagName('session_id')[0].childNodes[0].nodeValue
-            return Session(self, session_id, location=location, media_mode=media_mode)
+            return Session(self, session_id, location=location, media_mode=media_mode, archive_mode=archive_mode)
         except Exception as e:
             raise OpenTokException('Failed to generate session: %s' % str(e))
 

tests/test_session_creation.py

@@ -5,7 +5,7 @@
 from sure import expect
 import httpretty
 
-from opentok import OpenTok, Session, MediaModes, OpenTokException, __version__
+from opentok import OpenTok, Session, MediaModes, ArchiveModes, OpenTokException, __version__
 
 class OpenTokSessionCreationTest(unittest.TestCase):
     def setUp(self):
@@ -24,7 +24,7 @@ def test_create_default_session(self):
 
         expect(httpretty.last_request().headers[u('x-tb-partner-auth')]).to.equal(self.api_key+u(':')+self.api_secret)
         expect(httpretty.last_request().headers[u('user-agent')]).to.contain(u('OpenTok-Python-SDK/')+__version__)
-        expect(httpretty.last_request().body).to.equal(b('p2p.preference=enabled'))
+        expect(httpretty.last_request().body).to.equal(b('archiveMode=manual&p2p.preference=enabled'))
         expect(session).to.be.a(Session)
         expect(session).to.have.property(u('session_id')).being.equal(u('1_MX4xMjM0NTZ-fk1vbiBNYXIgMTcgMDA6NDE6MzEgUERUIDIwMTR-MC42ODM3ODk1MzQ0OTQyODA4fg'))
         expect(session).to.have.property(u('media_mode')).being.equal(MediaModes.relayed)
@@ -41,7 +41,7 @@ def test_create_routed_session(self):
 
         expect(httpretty.last_request().headers[u('x-tb-partner-auth')]).to.equal(self.api_key+u(':')+self.api_secret)
         expect(httpretty.last_request().headers[u('user-agent')]).to.contain(u('OpenTok-Python-SDK/')+__version__)
-        expect(httpretty.last_request().body).to.equal(b('p2p.preference=disabled'))
+        expect(httpretty.last_request().body).to.equal(b('archiveMode=manual&p2p.preference=disabled'))
         expect(session).to.be.a(Session)
         expect(session).to.have.property(u('session_id')).being.equal(u('1_MX4xMjM0NTZ-fk1vbiBNYXIgMTcgMDA6NDE6MzEgUERUIDIwMTR-MC42ODM3ODk1MzQ0OTQyODA4fg'))
         expect(session).to.have.property(u('media_mode')).being.equal(MediaModes.routed)
@@ -87,5 +87,47 @@ def test_create_routed_session_with_location_hint(self):
         expect(session).to.have.property(u('media_mode')).being.equal(MediaModes.routed)
         expect(session).to.have.property(u('location')).being.equal(u('12.34.56.78'))
 
+    @httpretty.activate
+    def test_create_manual_archive_mode_session(self):
+        httpretty.register_uri(httpretty.POST, u('https://api.opentok.com/session/create'),
+                               body=u('<?xml version="1.0" encoding="UTF-8" standalone="yes"?><sessions><Session><session_id>1_MX4xMjM0NTZ-fk1vbiBNYXIgMTcgMDA6NDE6MzEgUERUIDIwMTR-MC42ODM3ODk1MzQ0OTQyODA4fg</session_id><partner_id>123456</partner_id><create_dt>Mon Mar 17 00:41:31 PDT 2014</create_dt></Session></sessions>'),
+                               status=200,
+                               content_type=u('text/xml'))
+
+        session = self.opentok.create_session(media_mode=MediaModes.routed, archive_mode=ArchiveModes.manual)
+
+        expect(httpretty.last_request().headers[u('x-tb-partner-auth')]).to.equal(self.api_key+u(':')+self.api_secret)
+        expect(httpretty.last_request().headers[u('user-agent')]).to.contain(u('OpenTok-Python-SDK/')+__version__)
+        expect(httpretty.last_request().body).to.equal(b('archiveMode=manual&p2p.preference=disabled'))
+        expect(session).to.be.a(Session)
+        expect(session).to.have.property(u('session_id')).being.equal(u('1_MX4xMjM0NTZ-fk1vbiBNYXIgMTcgMDA6NDE6MzEgUERUIDIwMTR-MC42ODM3ODk1MzQ0OTQyODA4fg'))
+        expect(session).to.have.property(u('media_mode')).being.equal(MediaModes.routed)
+        expect(session).to.have.property(u('archive_mode')).being.equal(ArchiveModes.manual)
+
+    @httpretty.activate
+    def test_create_always_archive_mode_session(self):
+        httpretty.register_uri(httpretty.POST, u('https://api.opentok.com/session/create'),
+                               body=u('<?xml version="1.0" encoding="UTF-8" standalone="yes"?><sessions><Session><session_id>1_MX4xMjM0NTZ-fk1vbiBNYXIgMTcgMDA6NDE6MzEgUERUIDIwMTR-MC42ODM3ODk1MzQ0OTQyODA4fg</session_id><partner_id>123456</partner_id><create_dt>Mon Mar 17 00:41:31 PDT 2014</create_dt></Session></sessions>'),
+                               status=200,
+                               content_type=u('text/xml'))
+
+        session = self.opentok.create_session(media_mode=MediaModes.routed, archive_mode=ArchiveModes.always)
+
+        expect(httpretty.last_request().headers[u('x-tb-partner-auth')]).to.equal(self.api_key+u(':')+self.api_secret)
+        expect(httpretty.last_request().headers[u('user-agent')]).to.contain(u('OpenTok-Python-SDK/')+__version__)
+        expect(httpretty.last_request().body).to.equal(b('archiveMode=always&p2p.preference=disabled'))
+        expect(session).to.be.a(Session)
+        expect(session).to.have.property(u('session_id')).being.equal(u('1_MX4xMjM0NTZ-fk1vbiBNYXIgMTcgMDA6NDE6MzEgUERUIDIwMTR-MC42ODM3ODk1MzQ0OTQyODA4fg'))
+        expect(session).to.have.property(u('media_mode')).being.equal(MediaModes.routed)
+        expect(session).to.have.property(u('archive_mode')).being.equal(ArchiveModes.always)
+
+    @httpretty.activate
+    def test_complains_about_always_archive_mode_and_relayed_session(self):
+        httpretty.register_uri(httpretty.POST, u('https://api.opentok.com/session/create'),
+                               body=u('<?xml version="1.0" encoding="UTF-8" standalone="yes"?><sessions><Session><session_id>1_MX4xMjM0NTZ-fk1vbiBNYXIgMTcgMDA6NDE6MzEgUERUIDIwMTR-MC42ODM3ODk1MzQ0OTQyODA4fg</session_id><partner_id>123456</partner_id><create_dt>Mon Mar 17 00:41:31 PDT 2014</create_dt></Session></sessions>'),
+                               status=200,
+                               content_type=u('text/xml'))
+        self.assertRaises(OpenTokException, self.opentok.create_session, media_mode=MediaModes.relayed, archive_mode=ArchiveModes.always)
+
     # TODO: all the cases that throw exceptions
     # TODO: custom api_url requests