ORTC API C
 All Data Structures Files Functions Variables
Data Structures | Functions
libortc.h File Reference
#include <pthread.h>
#include <regex.h>
#include "dlist.h"

Go to the source code of this file.

Data Structures

struct  ortc_metadataRecord
 Metadata Record Structure. More...
 
struct  ortc_presenceData
 Presence Data Structure. More...
 
struct  ortc_channelPermissions
 Channel Permission Structure. More...
 

Functions

ortc_context * ortc_create_context (void)
 
void ortc_free_context (ortc_context *context)
 
void ortc_set_cluster (ortc_context *context, char *cluster)
 
char * ortc_get_cluster (ortc_context *context)
 
void ortc_set_url (ortc_context *context, char *url)
 
char * ortc_get_url (ortc_context *context)
 
void ortc_set_connection_metadata (ortc_context *context, char *connection_metadata)
 
char * ortc_get_connection_metadata (ortc_context *context)
 
void ortc_set_announcementSubChannel (ortc_context *context, char *announcementSubChannel)
 
char * ortc_get_announcementSubChannel (ortc_context *context)
 
char * ortc_get_sessionId (ortc_context *context)
 
int ortc_is_connected (ortc_context *context)
 
int ortc_is_subscribed (ortc_context *context, char *channel)
 
void ortc_connect (ortc_context *context, char *applicationKey, char *authenticationToken)
 
void ortc_disconnect (ortc_context *context)
 
void ortc_subscribe (ortc_context *context, char *channel, int subscribeOnReconnected, void(*onMessage)(ortc_context *, char *, char *))
 
void ortc_unsubscribe (ortc_context *context, char *channel)
 
void ortc_send (ortc_context *context, char *channel, char *message)
 
void ortc_set_onConnected (ortc_context *context, void(*onConnected)(ortc_context *))
 
void ortc_set_onDisconnected (ortc_context *context, void(*onDisconnected)(ortc_context *))
 
void ortc_set_onReconnected (ortc_context *context, void(*onReconnected)(ortc_context *))
 
void ortc_set_onReconnecting (ortc_context *context, void(*onReconnecting)(ortc_context *))
 
void ortc_set_onException (ortc_context *context, void(*onException)(ortc_context *, char *))
 
void ortc_set_onSubscribed (ortc_context *context, void(*onSubscribed)(ortc_context *, char *))
 
void ortc_set_onUnsubscribed (ortc_context *context, void(*onUnsubscribed)(ortc_context *, char *))
 
void ortc_enable_presence (ortc_context *context, char *privateKey, char *channel, int metadata, void(*callback)(ortc_context *, char *, char *, char *))
 
void ortc_enable_presence_ex (ortc_context *context, char *url, int isCluster, char *appKey, char *privateKey, char *channel, int metadata, void(*callback)(ortc_context *, char *, char *, char *))
 
void ortc_disable_presence (ortc_context *context, char *privateKey, char *channel, void(*callback)(ortc_context *, char *, char *, char *))
 
void ortc_disable_presence_ex (ortc_context *context, char *url, int isCluster, char *appKey, char *privateKey, char *channel, void(*callback)(ortc_context *, char *, char *, char *))
 
void ortc_presence (ortc_context *context, char *channel, void(*callback)(ortc_context *, char *, char *, ortc_presenceData *))
 
void ortc_presence_ex (ortc_context *context, char *url, int isCluster, char *appKey, char *authToken, char *channel, void(*callback)(ortc_context *, char *, char *, ortc_presenceData *))
 
void ortc_save_authentication (ortc_context *context, char *authToken, int isPrivate, int ttl, char *privateKey, ortc_channelPermissions *permissions, int sizeOfChannelPermissions, void(*callback)(ortc_context *, char *, char *))
 
void ortc_save_authentication_ex (ortc_context *context, char *url, int isCluster, char *authToken, int isPrivate, char *appKey, int ttl, char *privateKey, ortc_channelPermissions *permissions, int sizeOfChannelPermissions, void(*callback)(ortc_context *, char *, char *))
 

Function Documentation

void ortc_connect ( ortc_context *  context,
char *  applicationKey,
char *  authenticationToken 
)

Connects to ORTC service using the supplied application key and authentication token.

Parameters
contextpointer to ortc_context structure
applicationKeynull-terminated string containing the application key
authenticationTokennull-terminated string containing the authentication token
ortc_context* ortc_create_context ( void  )

Creates an ortc_context
Creating an ortc_context is the first thing that need to be done. All methods requires the first parameter to be pointer to ortc_context structure. When the ortc_context is no longer needed, please remember to free it with ortc_free_context() method to prevent memory leaks.

Returns
pointer to initialized ortc_context structure
void ortc_disable_presence ( ortc_context *  context,
char *  privateKey,
char *  channel,
void(*)(ortc_context *, char *, char *, char *)  callback 
)

Disables presence for the specified channel.
Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

Parameters
contextpointer to ortc_context structure
privateKeynull-terminated string containing private key provided when the ORTC service is purchased
channelnull-terminated string containing channel name
callbackthe callback with channel, error and result parameters
void ortc_disable_presence_ex ( ortc_context *  context,
char *  url,
int  isCluster,
char *  appKey,
char *  privateKey,
char *  channel,
void(*)(ortc_context *, char *, char *, char *)  callback 
)

Disables presence for the specified channel.
This method does not require previous connection.
Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

Parameters
contextpointer to ortc_context structure
urlnull-terminated string containing ORTC server URL
isClusterindicates whether the ORTC server is in a cluster (1 - yes, 0 - no)
appKeynull-terminated string containing the application key
privateKeynull-terminated string containing private key provided when the ORTC service is purchased
channelnull-terminated string containing channel name
callbackthe callback with channel, error and result parameters
void ortc_disconnect ( ortc_context *  context)

Disconnects from ORTC service for given context.

Parameters
contextpointer to ortc_context structure
void ortc_enable_presence ( ortc_context *  context,
char *  privateKey,
char *  channel,
int  metadata,
void(*)(ortc_context *, char *, char *, char *)  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.

Parameters
contextpointer to ortc_context structure
privateKeynull-terminated string containing private key provided when the ORTC service is purchased
channelnull-terminated string containing channel name
metadatadefines if to collect first 100 unique metadata (1 - yes, 0 - no)
callbackthe callback with channel, error and result parameters
void ortc_enable_presence_ex ( ortc_context *  context,
char *  url,
int  isCluster,
char *  appKey,
char *  privateKey,
char *  channel,
int  metadata,
void(*)(ortc_context *, char *, char *, char *)  callback 
)

Enables presence for the specified channel with first 100 unique metadata if true.
This method does not require previous connection.
Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

Parameters
contextpointer to ortc_context structure
urlnull-terminated string containing ORTC server URL
isClusterindicates whether the ORTC server is in a cluster (1 - yes, 0 - no)
appKeynull-terminated string containing the application key
privateKeynull-terminated string containing private key provided when the ORTC service is purchased
channelnull-terminated string containing channel name
metadatadefines if to collect first 100 unique metadata (1 - yes, 0 - no)
callbackthe callback with channel, error and result parameters
void ortc_free_context ( ortc_context *  context)

Free all resources used by ortc_context.

Parameters
context- a pointer to ortc_context structure
char* ortc_get_announcementSubChannel ( ortc_context *  context)

Gets an announcement subchannel.

Parameters
contextpointer to ortc_context structure
Returns
null-terminated string containing announcement subchannel
char* ortc_get_cluster ( ortc_context *  context)

Gets a cluster url for ortc connection

Parameters
contextpointer to ortc_context structure
Returns
null-terminated string containing url address
char* ortc_get_connection_metadata ( ortc_context *  context)

Gets a connection metadata.

Parameters
contextpointer to ortc_context structure
Returns
null-terminated string containing connection metadata
char* ortc_get_sessionId ( ortc_context *  context)

Gets a sessionId.

Parameters
contextpointer to ortc_context structure
Returns
null-terminated string containing sessionId
char* ortc_get_url ( ortc_context *  context)

Gets a server url for ortc connection.

Parameters
contextpointer to ortc_context structure
Returns
null-terminated string containing url address
int ortc_is_connected ( ortc_context *  context)

Indicates whether connection is established in given context.

Parameters
contextpointer to ortc_context structure
Returns
1 when connection is established otherwise 0
int ortc_is_subscribed ( ortc_context *  context,
char *  channel 
)

Indicates whether subscription is valid to the supplied channel in given context.

Parameters
contextpointer to ortc_context structure
channelnull-terminated string containing the channel name
Returns
1 when subscription to the supplied channel is valid otherwise 0
void ortc_presence ( ortc_context *  context,
char *  channel,
void(*)(ortc_context *, char *, char *, ortc_presenceData *)  callback 
)

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

Parameters
contextpointer to ortc_context structure
channelnull-terminated string containing channel name
callbackthe callback with channel, error and result (ortc_presenceData) parameters
void ortc_presence_ex ( ortc_context *  context,
char *  url,
int  isCluster,
char *  appKey,
char *  authToken,
char *  channel,
void(*)(ortc_context *, char *, char *, ortc_presenceData *)  callback 
)

Gets a presence data indicating the subscriptions number in the specified channel and if active the first 100 unique metadata.
This method does not require previous connection.

Parameters
contextpointer to ortc_context structure
urlnull-terminated string containing ORTC server URL
isClusterindicates whether the ORTC server is in a cluster (1 - yes, 0 - no)
appKeynull-terminated string containing the application key
authTokennull-terminated string containing the authentication token
channelnull-terminated string containing channel name
callbackthe callback with channel, error and result (ortc_presenceData) parameters
void ortc_save_authentication ( ortc_context *  context,
char *  authToken,
int  isPrivate,
int  ttl,
char *  privateKey,
ortc_channelPermissions permissions,
int  sizeOfChannelPermissions,
void(*)(ortc_context *, char *, char *)  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.

Parameters
contextpointer to ortc_context structure
authTokennull-terminated string containing the authentication token
isPrivateindicates whether the authentication token is private (1 - yes, 0 - no)
ttlthe authentication token time to live (TTL), in other words, the allowed activity time (in seconds)
privateKeynull-terminated string containing private key provided when the ORTC service is purchased
permissionspointer to array of structures (ortc_channelPermissions) containing channels and their permissions (read, write or presence)
sizeOfChannelPermissionssize of permissions array
callbackthe callback with channel, error and result (ortc_presenceData) parameters
void ortc_save_authentication_ex ( ortc_context *  context,
char *  url,
int  isCluster,
char *  authToken,
int  isPrivate,
char *  appKey,
int  ttl,
char *  privateKey,
ortc_channelPermissions permissions,
int  sizeOfChannelPermissions,
void(*)(ortc_context *, char *, char *)  callback 
)

Saves the channel and its permissions for the supplied application key and authentication token.
This method does not require previous connection.
Note: This method will send your Private Key over the Internet. Make sure to use secure connection.

Parameters
contextpointer to ortc_context structure
urlnull-terminated string containing ORTC server URL
isClusterindicates whether the ORTC server is in a cluster (1 - yes, 0 - no)
authTokennull-terminated string containing the authentication token
isPrivateindicates whether the authentication token is private (1 - yes, 0 - no)
appKeynull-terminated string containing the application key
ttlthe authentication token time to live (TTL), in other words, the allowed activity time (in seconds)
privateKeynull-terminated string containing private key provided when the ORTC service is purchased
permissionspointer to array of structures (ortc_channelPermissions) containing channels and their permissions (read, write or presence)
sizeOfChannelPermissionssize of permissions array
callbackthe callback with channel, error and result (ortc_presenceData) parameters
void ortc_send ( ortc_context *  context,
char *  channel,
char *  message 
)

Sends the supplied message to the supplied channel.

Parameters
contextpointer to ortc_context structure
channelnull-terminated string containing the channel name
messagenull-terminated string containing the message
void ortc_set_announcementSubChannel ( ortc_context *  context,
char *  announcementSubChannel 
)

Sets an announcement subchannel.

Parameters
contextpointer to ortc_context structure
announcementSubChannelnull-terminated string containing announcement subchannel
void ortc_set_cluster ( ortc_context *  context,
char *  cluster 
)

Sets a cluster url for ortc connection
You have to call this method or ortc_set_url() before calling the ortc_connect() method.

Parameters
contextpointer to ortc_context structure
clusternull-terminated string containing url address
void ortc_set_connection_metadata ( ortc_context *  context,
char *  connection_metadata 
)

Sets a connection metadata.

Parameters
contextpointer to ortc_context structure
connection_metadatanull-terminated string containing connection metadata
void ortc_set_onConnected ( ortc_context *  context,
void(*)(ortc_context *)  onConnected 
)

Sets the callback which occurs when the connection is established.

Parameters
contextpointer to ortc_context structure
onConnectedmethod to be called when the connection is established
void ortc_set_onDisconnected ( ortc_context *  context,
void(*)(ortc_context *)  onDisconnected 
)

Sets the callback which occurs when the connection is closed.

Parameters
contextpointer to ortc_context structure
onDisconnectedmethod to be called when the connection is closed
void ortc_set_onException ( ortc_context *  context,
void(*)(ortc_context *, char *)  onException 
)

Sets the callback which occurs when there is an exception.

Parameters
contextpointer to ortc_context structure
onExceptionmethod to be called when there is an exception
void ortc_set_onReconnected ( ortc_context *  context,
void(*)(ortc_context *)  onReconnected 
)

Sets the callback which occurs when the connection restates.

Parameters
contextpointer to ortc_context structure
onReconnectedmethod to be called when the connection restates
void ortc_set_onReconnecting ( ortc_context *  context,
void(*)(ortc_context *)  onReconnecting 
)

Sets the callback which occurs when the connection attempts to restate.

Parameters
contextpointer to ortc_context structure
onReconnectingmethod to be called when the connection attempts to restate
void ortc_set_onSubscribed ( ortc_context *  context,
void(*)(ortc_context *, char *)  onSubscribed 
)

Sets the callback which occurs when subscription to the channel was successful.

Parameters
contextpointer to ortc_context structure
onSubscribedmethod to be called when subscription to the channel is successful
void ortc_set_onUnsubscribed ( ortc_context *  context,
void(*)(ortc_context *, char *)  onUnsubscribed 
)

Sets the callback which occurs when unsubscription from the channel was successful.

Parameters
contextpointer to ortc_context structure
onUnsubscribedmethod to be called when unsubscription from the channel is successful
void ortc_set_url ( ortc_context *  context,
char *  url 
)

Sets a server url for ortc connection
You have to call this method or ortc_set_cluster() before calling the ortc_connect() method.

Parameters
contextpointer to ortc_context structure
urlnull-terminated string containing url address
void ortc_subscribe ( ortc_context *  context,
char *  channel,
int  subscribeOnReconnected,
void(*)(ortc_context *, char *, char *)  onMessage 
)

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

Parameters
contextpointer to ortc_context structure
channelnull-terminated string containing the channel name
subscribeOnReconnected1 - Indicates whether subscription to the channel should be restated when reconnected (if it was previously subscribed when connected).
onMessageThe callback called when a message arrives at the channel.
void ortc_unsubscribe ( ortc_context *  context,
char *  channel 
)

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

Parameters
contextpointer to ortc_context structure
channelnull-terminated string containing the channel name