OrtcClient

public class OrtcClient

ORTC client used for real-time connections.

Snippets

Code

// Instantiate OrtcClient
var ortcClient:OrtcClient = new OrtcClient();

ortcClient.connectionMetadata = "clientConnMeta";
ortcClient.clusterUrl = "http://ortc-developers.realtime.co/server/2.1/";

ortcClient.onConnected = function (ortc:OrtcClient):void
{
    // Connected
    
    ortcClient.subscribe("channel1", true, function (ortc:OrtcClient, channel:String, message:String):void
    {
        // Received message 'message' at channel 'channel'
        
        ortcClient.unsubscribe(channel);
    });
};

ortcClient.onDisconnected = function (ortc:OrtcClient):void
{
    // Disconnected
};

ortcClient.onSubscribed = function (ortc:OrtcClient, channel:String):void
{
    // Subscribed to the channel 'channel'

    ortcClient.send(channel, "Message to the channel");
};

ortcClient.onUnsubscribed = function (ortc:OrtcClient, channel:String):void
{
    // Unsubscribed from the channel 'channel'

    ortcClient.disconnect();
};

ortcClient.onException = function (ortc:OrtcClient, error:String):void
{
    // Exception occurred
};

ortcClient.onReconnecting = function (ortc:OrtcClient):void
{
    // Trying to reconnect
};

ortcClient.onReconnected = function (ortc:OrtcClient):void
{
    // Reconnected
};

// Post permissions
try {
    ortcClient.saveAuthentication("http://ortc-developers.realtime.co/server/2.1/", true, "myAuthenticationToken", 0, "myApplicationKey", 1400, "myPrivateKey", channelPermissions, function (result:Boolean):void
    {
        if (result) {
            // Permissions correctly posted
            
            // Connect
            ortcClient.connect("myApplicationKey", "myAuthenticationToken");
        }
        else {
            // Unable to post permissions
        }
    });
}
catch (ex:Error) {
    // Exception posting permissions
}

Properties

String announcementSubChannel

The client announcement subchannel.

String clusterUrl

The cluster server URL.

String connectionMetadata

The client connection metadata.

int connectionTimeout

The connection timeout.

Boolean heartbeatActive

Defines if heart beat is active. Heart beat provides better accuracy for presence data.

int heartbeatFails

Indicates how many times can the client fail the heartbeat.

int heartbeatTime

The heartbeat interval in seconds.

String id

The client identifier.

Boolean isConnected

Indicates whether the client is connected.

String sessionId

The session identifier.

String url

The server URL.

Constructors

ortcClient OrtcClient()

Creates a new instance of the ORTC Client class.

Code

var ortcClient:OrtcClient = new OrtcClient();

Functions

void connect(string applicationKey, string authenticationToken)

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

Parameters

string applicationKey

The application key.

string authenticationToken

The authentication token.

Code

ortcClient.connect("myApplicationKey", "myAuthenticationToken");

void disablePresence(object Object, Function Callback)

Disables presence for the specified channel.

Parameters

object Object

literal with presence attributes.

Properties

String applicationKey

Application key with access to presence service (optional if connected).

String channel

Channel to disable presence.

Boolean isCluster

Specifies if url is cluster (optional if connected).

String privateKey

The private key provided when the ORTC service is purchased.

String url

Server containing the presence service (optional if connected).

Function Callback

with error and result parameters.

Code

ortcClient.disablePresence(
"http://ortc-developers.realtime.co/server/2.1/",
true,
"myApplicationKey",
"privateKey",
"CHANNEL",
true,
function(error:String,result:String):void {
	if(error != null)
	{
		// Error while trying to disable presence data - error	
	}
	else
	{
		// Disable presence result	
	}
});

void disconnect()

Disconnects the client.

Code

ortcClient.disconnect();

void enablePresence(object Object, Function Callback)

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

Parameters

object Object

literal with presence attributes.

Properties

String applicationKey

Application key with access to presence service (optional if connected).

String channel

Channel to activate presence.

Boolean isCluster

Specifies if url is cluster (optional if connected).

Boolean metadata

Defines if to collect first 100 unique metadata.

String privateKey

The private key provided when the ORTC service is purchased.

String url

Server containing the presence service (optional if connected).

Function Callback

with error and result parameters.

Code

ortcClient.enablePresence(
 "http://ortc-developers.realtime.co/server/2.1/",
 true,
 "myApplicationKey",
 "privateKey",
 "CHANNEL",
 true,
 function(error:String,result:String):void {
 	if(error != null)
 	{
 		// Error enabling presence data - error	
 	}
 	else
 	{
 		// Enable presence result	
 	}
});

boolean isSubscribed(string channel)

Indicates whether the client is subscribed to the supplied channel.

Parameters

string channel

The channel name.

Code

var result:Object = ortcClient.isSubscribed("channel1");

// NOTE: result can be null
if (result == true)
{
	// Subscribed
}
else if (result == false)
{
	// Not subscribed
}
else
{
   // Exception occurred
}

void presence(object Object, Function Callback)

Gets a json indicating the subscriptions in the specified channel and if active the first 100 unique metadata.

Parameters

object Object

literal with presence attributes.

Properties

String applicationKey

Application key with access to presence service (optional if connected).

String authenticationToken

Authentication token with access to presence service (optional if connected).

String channel

Channel with presence data active.

Boolean isCluster

Specifies if url is cluster (optional if connected).

String url

Server containing the presence service (optional if connected).

Function Callback

with error and result parameters.

Code

ortcClient.presence(
"http://ortc-developers.realtime.co/server/2.1/",
true,
"myApplicationKey",
"myAuthenticationToken",
"CHANNEL",
function(error:String,data:Object):void {
	if(error != null)
	{
		// Error getting presence data - error	
	}
	else
	{
		if(data == null)
		{
			// Unable to get presence data
		}
		else
		{							
			for(var metadataIndex:String in data["metadata"]){
				// metadataIndex subscriptions : data["metadata"][metadataIndex]	
			}
			// Subscriptions in channel :  data["subscriptions"]	
		}
	}
});

void saveAuthentication(string url, Boolean isCluster, string authenticationToken, Boolean authenticationTokenIsPrivate, string applicationKey, int timeToLive, string privateKey, Dictionary permissions, Function(Boolean) callback)

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

Parameters

string url

The ORTC server URL.

Boolean isCluster

Indicates whether the ORTC server is in a cluster.

string authenticationToken

The authentication token generated by an application server (for instance: a unique session ID).

Boolean authenticationTokenIsPrivate

Indicates whether the authentication token is private.

string applicationKey

The application key provided when the ORTC service is purchased.

int timeToLive

The authentication token time to live (TTL), in other words, the allowed activity time (in seconds).

string privateKey

The private key provided when the ORTC service is purchased.

Dictionary permissions

The channels and their permissions (w: write/read or r: read or p: presence, case sensitive).

Function(Boolean) callback

Function called when the authentication finishes. If 'error' is not null then an error occurred.

Code

var channelPermissions:Dictionary = new Dictionary();

// Write and presence permission
channelPermissions["channel1"] = "wp";
// Write and read permission
channelPermissions["channel2"] = "wr";
// Read permission
channelPermissions["channelread"] = "r";

ortcClient.saveAuthentication(
"http://ortc-developers.realtime.co/server/2.1/", 
true, 
"myAuthenticationToken", 
0, "myApplicationKey", 
1400, 
"myPrivateKey", 
channelPermissions, 
function (result:Boolean):void {
    if (result) {
	    // Permissions correctly posted
    }
    else {
	    // Error posting permissions
    }
});

void send(string channel, string message)

Sends the supplied message to the supplied channel.

Parameters

string channel

The channel name.

string message

The message to send.

Code

ortcClient.send("channel1", "This message goes to channel1");

void subscribe(string channel, boolean subscribeOnReconnected, function(ortc, channel, message) onMessage)

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

Parameters

string channel

The channel name.

boolean subscribeOnReconnected

Indicates whether the client should subscribe to the channel when reconnected (if it was previously subscribed when connected).

function(ortc, channel, message) onMessage

The callback called when a message arrives at the channel.

Code

ortcClient.subscribe("channel1", true, function (ortc:OrtcClient, channel:String, message:String):void
{
    ...
});

void unsubscribe(string channel)

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

Parameters

string channel

The channel name.

Code

ortcClient.unsubscribe("channel1");

Events

onConnected(ortcClient ortc)

Occurs when the client connects.

Parameters

ortcClient ortc

The ORTC Client object

Code

ortcClient.onConnected = function (ortc:OrtcClient):void
{
    ...
};

onDisconnected(ortcClient ortc)

Occurs when the client disconnects.

Parameters

ortcClient ortc

The ORTC Client object.

Code

ortcClient.onDisconnected = function (ortc:OrtcClient):void
{
	...
};

onException(ortcClient ortc, string exception)

Occurs when there is an exception.

Parameters

ortcClient ortc

The ORTC Client object.

string exception

The occurred exception.

Code

ortcClient.onException = function (ortc:OrtcClient, error:String):void
{
	...
};

onReconnected(ortcClient ortc)

Occurs when the client reconnects.

Parameters

ortcClient ortc

The ORTC Client object.

Code

ortcClient.onReconnected = function (ortc:OrtcClient):void
{
	...
};

onReconnecting(ortcClient ortc)

Occurs when the client attempts to reconnect.

Parameters

ortcClient ortc

The ORTC Client object.

Code

ortcClient.onReconnecting = function (ortc:OrtcClient):void
{
	...
};

onSubscribed(ortcClient ortc, string channel)

Occurs when the client subscribes to a channel.

Parameters

ortcClient ortc

The ORTC Client object.

string channel

The channel name.

Code

ortcClient.onSubscribed = function (ortc:OrtcClient, channel:String):void
{
	...
};

onUnsubscribed(ortcClient ortc, string channel)

Occurs when the client unsubscribes from a channel.

Parameters

ortcClient ortc

The ORTC Client object.

string channel

The channel name.

Code

ortcClient.onUnsubscribed = function (ortc:OrtcClient, channel:String):void
{
	...
};