ORTC Python API

About

The ORTC (Open Real-Time Connectivity) was developed to add a layer of abstraction to real-time full-duplex web communications platforms by making real-time web applications independent of those platforms.

ORTC provides a standard software API (Application Programming Interface) for sending and receiving data in real-time over the web.

This API is tested only on Python 2.7

Installation

  1. This API requires the module websocket.py to be installed. Please process the installation instruction of websocket.py at: https://github.com/liris/websocket-client
  2. Copy the files ortc.py and ortc_extensibility.py to your project directory
  3. Place in your source code the line: import ortc
  4. Follow the sample code in: example_simple.py or example_menu.py
  5. See the documentation: doc/_build/html/index.html

Sample source

#!/usr/bin/python
# -*- coding: utf-8 -*-

import ortc
import time

ortc_client = ortc.OrtcClient()

def on_connected(sender):
    print 'ORTC Connected'
    ortc_client.subscribe('blue', True, on_message)

def on_disconnected(sender):
    print 'ORTC Disconnected'
    import thread
    thread.interrupt_main()

def on_message(sender, channel, message):
    print r'ORTC Message ('+channel+'): ' + message
    ortc_client.unsubscribe(channel)

def on_subscribed(sender, channel):
    print 'ORTC Subscribed to: '+channel
    ortc_client.send(channel, 'Python API message')

def on_unsubscribed(sender, channel):
    print 'ORTC Unsubscribed from: '+channel
    ortc_client.disconnect()

ortc_client.set_on_connected_callback(on_connected)
ortc_client.set_on_disconnected_callback(on_disconnected)
ortc_client.set_on_subscribed_callback(on_subscribed)
ortc_client.set_on_unsubscribed_callback(on_unsubscribed)

ortc_client.cluster_url = "https://ortc-developers.realtime.co/server/ssl/2.1"
ortc_client.connect('your_application_key')

try:
     while True:
           time.sleep(1)
except:
     pass

ORTC Module

ORTC Python API.

ortc.save_authentication(url, is_cluster, authentication_token, is_private, application_key, time_to_live, private_key, channels_permissions, callback)

Saves the channel and its permissions for the supplied application key and authentication token.

Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

  • url - The ORTC server URL.
  • is_cluster - Indicates whether the ORTC server is in a cluster.
  • authentication_token - The authentication token generated by an application server (for instance: a unique session ID).
  • is_private - Indicates whether the authentication token is private.
  • application_key - The application key provided when the ORTC service is purchased.
  • time_to_live - The authentication token time to live (TTL), in other words, the allowed activity time (in seconds).
  • private_key - The private key provided when the ORTC service is purchased.
  • channels_permissions - The dictionary containing channels and their permissions (read, write or presence).
  • callback - The callback raised after save authentication have been performed.

Returns boolean- Indicates whether the authentication was successful.

Usage:

>>> def save_authentication_callback(error, result):
>>>     if result:
>>>         print 'ORTC Save Authentication success'
>>>     else:
>>>         print 'ORTC Save Authentication Error: ' + str(error)
>>> channels_permissions = {}
>>> channels_permissions['blue'] = 'r'
>>> channels_permissions['yellow'] = 'wp'
>>> ortc.save_authentication('https://ortc-developers.realtime.co/server/ssl/2.1', True, 'Your authentication token', False, 'Your application key', 1800, 'Your private key', channels_permissions, save_authentication_callback)
ortc.presence(url, is_cluster, application_key, authentication_token, channel, callback)

Gets a dictionary indicating the subscriptions number in the specified channel and if active the first 100 unique metadata. * url - The ORTC server URL. * is_cluster - Indicates whether the ORTC server is in a cluster. * application_key - The application key provided when the ORTC service is purchased. * authentication_token - The authentication token generated by an application server (for instance: a unique session ID). * channel - The channel name with presence data active. * callback - The callback with error and result parameters.

Usage:

>>> def presence_callback(error, result):
>>>     if not error == None:
>>>         print 'ORTC Presence error: ' + error
>>>     else:
>>>         print str(result)
>>> ortc.presence('http://ortc-developers.realtime.co/server/2.1', True, 'Your application key', 'Your authentication token', 'blue', presence_callback)
ortc.enable_presence(url, is_cluster, application_key, private_key, channel, metadata, callback)

Enables presence for the specified channel with first 100 unique metadata if true.

Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

  • url - The ORTC server URL.
  • is_cluster - Indicates whether the ORTC server is in a cluster.
  • application_key - The application key provided when the ORTC service is purchased.
  • private_key - The private key provided when the ORTC service is purchased.
  • channel - The channel name to activate presence.
  • metadata - Defines if to collect first 100 unique metadata (boolean).
  • callback - The callback with error and result parameters.

Usage:

>>> def presence_callback(error, result):
>>>     if not error == None:
>>>         print 'ORTC Presence error: ' + error
>>>     else:
>>>         print str(result)
>>> ortc.enable_presence('http://ortc-developers.realtime.co/server/2.1', True, 'Your application key', 'Your private key', 'blue', True, presence_callback)
ortc.disable_presence(url, is_cluster, application_key, private_key, channel, callback)

Disables presence for the specified channel.

Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

  • url - The ORTC server URL.
  • is_cluster - Indicates whether the ORTC server is in a cluster.
  • application_key - The application key provided when the ORTC service is purchased.
  • private_key - The private key provided when the ORTC service is purchased.
  • channel - The channel name to disable presence.
  • callback - The callback with error and result parameters.

Usage:

>>> def presence_callback(error, result):
>>>     if not error == None:
>>>         print 'ORTC Presence error: ' + error
>>>     else:
>>>         print str(result)
>>> ortc.disable_presence('http://ortc-developers.realtime.co/server/2.1', True, 'Your application key', 'Your private key', 'blue', presence_callback)
class ortc.OrtcClient

A class representing an ORTC Client

announcement_subchannel

The client announcement subchannel

Usage:

>>> ortc_client.announcement_subchannel = 'announcement_subchannel'
cluster_url

The cluster server URL

Usage:

>>> ortc_client.cluster_url = "https://ortc-developers.realtime.co/server/ssl/2.1"
connect(application_key, authentication_token='PM.Anonymous')

Connects the client using the supplied application key and authentication token.

  • application_key - Your ORTC application key.
  • authentication_token - Your ORTC authentication token, this parameter is optional.

Usage:

>>> import ortc
>>> ortc_client = ortc.OrtcClient()
>>> ortc_client.connect('Your application key', 'Your authentication token') 
connection_metadata

The client connection metadata

Usage:

>>> ortc_client.connection_metadata = 'My metadata'        
disable_presence(private_key, channel, callback)

Disables presence for the specified channel.

Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

  • private_key - The private key provided when the ORTC service is purchased.
  • channel - The channel name to disable presence.
  • callback - The callback with error and result parameters.

Usage:

>>> def presence_callback(error, result):
>>>     if not error == None:
>>>         print 'ORTC Presence error: ' + error
>>>     else:
>>>         print str(result)
>>> ortc_client.disable_presence('Your private key', 'blue', presence_callback)
disconnect()

Disconnects the client.

Usage:

>>> ortc_client.disconnect()
enable_presence(private_key, channel, metadata, callback)

Enables presence for the specified channel with first 100 unique metadata if true.

Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

  • private_key - The private key provided when the ORTC service is purchased.
  • channel - The channel name to activate presence.
  • metadata - Defines if to collect first 100 unique metadata (boolean).
  • callback - The callback with error and result parameters.

Usage:

>>> def presence_callback(error, result):
>>>     if not error == None:
>>>         print 'ORTC Presence error: ' + error
>>>     else:
>>>         print str(result)
>>> ortc_client.enable_presence('Your private key', 'blue', True, presence_callback)
is_connected

Indicates whether the client is connected (read only)

Usage:

>>> ortc_client.is_connected
False
is_subscribed(channel)

Indicates whether the client is subscribed to the supplied channel.

  • channel - The channel name.

Returns boolean - Indicates whether the client is subscribed to the supplied channel.

Usage:

>>> print ortc_client.is_subscribed('blue')
True
presence(channel, callback)

Gets a dictionary indicating the subscriptions number in the specified channel and if active the first 100 unique metadata. * channel - The channel name with presence data active. * callback - The callback with error and result parameters.

Usage:

>>> def presence_callback(error, result):
>>>     if not error == None:
>>>         print 'ORTC Presence error: ' + error
>>>     else:
>>>         print str(result)
>>> ortc_client.presence('blue', presence_callback)
send(channel, message)

Sends the supplied message to the supplied channel.

  • channel - The channel name.
  • message - The message to send.

Usage:

>>> ortc_client.send('blue', 'This is a message')
session_id

The client session identifier (read only)

Usage:

>>> print ortc_client.session_id
4RtV2sq0
set_on_connected_callback(callback)

Sets the callback which occurs when the client connects.

  • callback - Method to be interpreted when the client connects.

Usage:

>>> def on_connected(sender):
>>>     print 'Connected'
>>> ortc_client.set_on_connected_callback(on_connected)
set_on_disconnected_callback(callback)

Sets the callback which occurs when the client disconnects.

  • callback - Method to be interpreted when the client disconnects.

Usage:

>>> def on_disconnected(sender):
>>>     print 'Disconnected'
>>> ortc_client.set_on_disconnected_callback(on_disconnected)
set_on_exception_callback(callback)

Sets the callback which occurs when there is an exception.

  • callback - Method to be interpreted when there is an exception.

Usage:

>>> def on_exception(sender, exception):
>>>     print 'Exception: ' + exception
>>> ortc_client.set_on_exception_callback(on_exception)
set_on_reconnected_callback(callback)

Sets the callback which occurs when the client reconnects.

  • callback - Method to be interpreted when the client reconnects.

Usage:

>>> def on_reconnected(sender):
>>>     print 'Reconnected'
>>> ortc_client.set_on_reconnected_callback(on_reconnected)
set_on_reconnecting_callback(callback)

Sets the callback which occurs when the client attempts to reconnect.

  • callback - Method to be interpreted when the client attempts to reconnect.

Usage:

>>> def on_reconnecting(sender):
>>>     print 'Reconnecting'
>>> ortc_client.set_on_reconnecting_callback(on_reconnecting)
set_on_subscribed_callback(callback)

Sets the callback which occurs when the client subscribes to a channel.

  • callback - Method to be interpreted when the client subscribes to a channel.

Usage:

>>> def on_subscribed(sender, channel):
>>>     print 'Subscribed to: ' + channel
>>> ortc_client.set_on_subscribed_callback(on_subscribed)       
set_on_unsubscribed_callback(callback)

Sets the callback which occurs when the client unsubscribes from a channel.

  • callback - Method to be interpreted when the client unsubscribes from a channel.

Usage:

>>> def on_unsubscribed(sender, channel):
>>>     print 'Unsubscribed from: ' + channel
>>> ortc_client.set_on_unsubscribed_callback(on_unsubscribed)       
subscribe(channel, subscribe_on_reconnect, on_message)

Subscribes to the supplied channel to receive messages sent to it.

  • channel - The channel name.
  • subscribe_on_reconnect -Indicates whether the client should subscribe to the channel when reconnected (if it was previously subscribed when connected).
  • on_message - The callback called when a message arrives at the channel.

Usage:

>>> def on_message(sender, channel, message):
>>>     print 'Message received on ('+channel+'): ' + message
>>> ortc_client.subscribe('blue', True, on_message)
unsubscribe(channel)

Unsubscribes from the supplied channel to stop receiving messages sent to it.

  • channel - The channel name.

Usage:

>>> ortc_client.unsubscribe('blue')
url

The server URL

Usage:

>>> ortc_client.url = "https://ortc-developers-euwest1-S0001.realtime.co:443"

Indices and tables

Table Of Contents

This Page