OrtcClient Class Reference

Inherits from NSObject
Declared in OrtcClient.h
OrtcClient.m

Overview

OrtcClient Usage - Code Example

  • ViewController.h

#import "OrtcClient.h"
@interface ViewController : UIViewController OrtcClientDelegate
{
@private

    OrtcClient* ortcClient;
    void (^onMessage)(OrtcClient* ortc, NSString* channel, NSString* message);
    // ...
}
// ...
@end

  • ViewController.m

#import "ViewController.h"
@implementation ViewController

- (void)viewDidLoad
{
    [super viewDidLoad];
    
    // Instantiate OrtcClient
    ortcClient = [OrtcClient ortcClientWithConfig:self];
    
    // Post permissions
    @try {
        NSMutableDictionary* myPermissions = [[NSMutableDictionary alloc] init];
        
        [myPermissions setObject:@"w" forKey:@"channel1"];
        [myPermissions setObject:@"w" forKey:@"channel2"];
        [myPermissions setObject:@"r" forKey:@"channelread"];
        
        BOOL postResult = [ortcClient saveAuthentication:@"http://ortc_server"
                            isCLuster:YES authenticationToken:@"myAuthenticationToken"
                            authenticationTokenIsPrivate:NO applicationKey:@"myApplicationKey"
                            timeToLive:1800 privateKey:@"myPrivateKey" permissions:myPermissions];
        
        if (postResult) {
            // Permissions correctly posted
        }
        else {
            // Unable to post permissions
        }
    }
    @catch (NSException* exception) {
        // Exception posting permissions
    }
    
    // Set connection properties
    [ortcClient setConnectionMetadata:@"clientConnMeta"];
    [ortcClient setClusterUrl:@"http://ortc_server"];
    
    // Connect
    [ortcClient connect:@"myApplicationKey" authenticationToken:@"myAuthenticationToken"];
}

- (void) onConnected:(OrtcClient*) ortc
{
    // Connected
    onMessage = ^(OrtcClient* ortc, NSString* channel, NSString* message) {
    // Received message 'message' at channel 'channel'
        [ortcClient unsubscribe:channel];
    };
    
    [ortcClient subscribe:@"channel1" subscribeOnReconnected:YES onMessage:onMessage];
    [ortcClient subscribe:@"channel2" subscribeOnReconnected:NO onMessage:onMessage];
    [ortcClient subscribeWithNotifications:@"channel3" subscribeOnReconnected:YES onMessage:onMessage];
}

- (void) onDisconnected:(OrtcClient*) ortc
{
    // Disconnected
}

- (void) onReconnecting:(OrtcClient*) ortc
{
    // Trying to reconnect
}

- (void) onReconnected:(OrtcClient*) ortc
{
    // Reconnected
}

- (void) onSubscribed:(OrtcClient*) ortc channel:(NSString*) channel
{
    // Subscribed to the channel 'channel'
    [ortcClient send:channel message:@"Message to the channel"];
}

- (void) onUnsubscribed:(OrtcClient*) ortc channel:(NSString*) channel
{
    // Unsubscribed from the channel 'channel'
    [ortcClient disconnect];
}

- (void) onException:(OrtcClient*) ortc error:(NSError*) error
{
    // Exception occurred
}

@end

Class Methods

+ ortcClientWithConfig:

Initializes a new instance of the ORTC class.

+ (id)ortcClientWithConfig:(id<OrtcClientDelegate>)delegate

Parameters

delegate

The object holding the ORTC callbacks, usually ‘self’.

Return Value

New instance of the ORTC class.

Discussion

Initializes a new instance of the ORTC class.

Declared In

OrtcClient.h

Instance Methods

– connect:authenticationToken:

Connects with the application key and authentication token.

- (void)connect:(NSString *)applicationKey authenticationToken:(NSString *)authenticationToken

Parameters

applicationKey

The application key.

authenticationToken

The authentication token.

Discussion

Connects with the application key and authentication token.

Declared In

OrtcClient.h

– send:message:

Sends a message to a channel.

- (void)send:(NSString *)channel message:(NSString *)message

Parameters

channel

The channel name.

message

The message to send.

Discussion

Sends a message to a channel.

Declared In

OrtcClient.h

– publish:message:ttl:callback:

Publish a message to a channel.

- (void)publish:(NSString *)channel message:(NSString *)aMessage ttl:(NSNumber *)ttl callback:(void ( ^ ) ( NSError *error , NSString *seqId ))callback

Parameters

channel

The channel name.

ttl

The message expiration time in seconds (0 for maximum allowed ttl).

callback

Returns error if message publish was not successful or published message unique id (seqId) if sucessfully published

message

The message to publish.

Discussion

Publish a message to a channel.

Declared In

OrtcClient.h

– subscribe:subscribeOnReconnected:onMessage:

Subscribes to a channel to receive messages sent to it.

- (void)subscribe:(NSString *)channel subscribeOnReconnected:(BOOL)aSubscribeOnReconnected onMessage:(void ( ^ ) ( OrtcClient *ortc , NSString *channel , NSString *message ))onMessage

Parameters

channel

The channel name.

onMessage

The callback called when a message arrives at the channel.

subscribeOnReconnected

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

Discussion

Subscribes to a channel to receive messages sent to it.

Declared In

OrtcClient.h

– subscribeWithOptions:onMessageWithOptionsCallback:

Subscribes to a channel to receive messages sent to it with given options.

- (void)subscribeWithOptions:(NSDictionary *)options onMessageWithOptionsCallback:(void ( ^ ) ( OrtcClient *ortc , NSDictionary *msgOptions ))onMessageWithOptionsCallback

Parameters

options

The subscription options dictionary, EX: “options = { channel, subscribeOnReconnected, // optional, default = true, withNotifications (Bool), // optional, default = false, use push notifications as in subscribeWithNotifications filter, // optional, default = ”“, the subscription filter as in subscribeWithFilter subscriberId // optional, default = ”“, the subscriberId as in subscribeWithBuffer }”.

onMessageWithOptionsCallback

The callback called when a message arrives at the channel, data is provided in a dictionary.

Discussion

Subscribes to a channel to receive messages sent to it with given options.

Declared In

OrtcClient.h

– subscribeWithBuffer:subscriberId:onMessageWithBufferCallback:

Subscribes to a channel to receive messages published to it.

- (void)subscribeWithBuffer:(NSString *)channel subscriberId:(NSString *)subscriberId onMessageWithBufferCallback:(void ( ^ ) ( OrtcClient *ortc , NSString *channel , NSString *seqId , NSString *message ))onMessageWithBufferCallback

Parameters

channel

The channel name.

subscriberId

The subscriberId associated to the channel.

onMessageWithBufferCallback

The callback called when a message arrives at the channel and message seqId number.

Discussion

Subscribes to a channel to receive messages published to it.

Declared In

OrtcClient.h

– subscribeWithFilter:subscribeOnReconnected:filter:onMessageWithFilter:

Subscribes to a channel, with a filter, to receive messages sent to it that validate the given filter.

- (void)subscribeWithFilter:(NSString *)channel subscribeOnReconnected:(BOOL)aSubscribeOnReconnected filter:(NSString *)aFilter onMessageWithFilter:(void ( ^ ) ( OrtcClient *ortc , NSString *channel , BOOL filtered , NSString *message ))onMessageWithFilter

Parameters

channel

The channel name. Only channels with alphanumeric name and the following characters: “_” “-” “:” are allowed.

onMessageWithFilter

The callback called when a message arrives at the channel.

subscribeOnReconnected

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

filter

The subscription filter

Discussion

Subscribes to a channel, with a filter, to receive messages sent to it that validate the given filter.

Declared In

OrtcClient.h

– subscribeWithNotifications:subscribeOnReconnected:onMessage:

Subscribes to a channel, with Push Notifications Service, to receive messages sent to it.

- (void)subscribeWithNotifications:(NSString *)channel subscribeOnReconnected:(BOOL)aSubscribeOnReconnected onMessage:(void ( ^ ) ( OrtcClient *ortc , NSString *channel , NSString *message ))onMessage

Parameters

channel

The channel name. Only channels with alphanumeric name and the following characters: “_” “-” “:” are allowed.

onMessage

The callback called when a message or a Push Notification arrives at the channel.

subscribeOnReconnected

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

Discussion

Subscribes to a channel, with Push Notifications Service, to receive messages sent to it.

Declared In

OrtcClient.h

– unsubscribe:

Unsubscribes from a channel to stop receiving messages sent to it.

- (void)unsubscribe:(NSString *)channel

Parameters

channel

The channel name.

Discussion

Unsubscribes from a channel to stop receiving messages sent to it.

Declared In

OrtcClient.h

– disconnect

Disconnects.

- (void)disconnect

Discussion

Disconnects.

Declared In

OrtcClient.h

– isSubscribed:

Indicates whether is subscribed to a channel or not.

- (NSNumber *)isSubscribed:(NSString *)channel

Parameters

channel

The channel name.

Return Value

TRUE if subscribed to the channel or FALSE if not.

Discussion

Indicates whether is subscribed to a channel or not.

Declared In

OrtcClient.h

– saveAuthentication:isCLuster:authenticationToken:authenticationTokenIsPrivate:applicationKey:timeToLive:privateKey:permissions:

Saves the channels and its permissions for the authentication token in the ORTC server.

- (BOOL)saveAuthentication:(NSString *)url isCLuster:(BOOL)isCluster authenticationToken:(NSString *)authenticationToken authenticationTokenIsPrivate:(BOOL)authenticationTokenIsPrivate applicationKey:(NSString *)applicationKey timeToLive:(int)timeToLive privateKey:(NSString *)privateKey permissions:(NSMutableDictionary *)permissions

Parameters

url

ORTC server URL.

isCluster

Indicates whether the ORTC server is in a cluster.

authenticationToken

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

authenticationTokenIsPrivate

Indicates whether the authentication token is private (1) or not (0).

applicationKey

The application key provided together with the ORTC service purchasing.

timeToLive

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

privateKey

The private key provided together with the ORTC service purchasing.

permissions

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

Return Value

TRUE if the authentication was successful or FALSE if it was not.

Discussion

Saves the channels and its permissions for the authentication token in the ORTC server.

Warning: This function will send your private key over the internet. Make sure to use secure connection.

Declared In

OrtcClient.h

– enablePresence:isCLuster:applicationKey:privateKey:channel:metadata:callback:

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

- (void)enablePresence:(NSString *)aUrl isCLuster:(BOOL)aIsCluster applicationKey:(NSString *)aApplicationKey privateKey:(NSString *)aPrivateKey channel:(NSString *)channel metadata:(BOOL)aMetadata callback:(void ( ^ ) ( NSError *error , NSString *result ))aCallback

Parameters

channel

Channel with presence data active.

callback

Callback with error (NSError) and result (NSString) parameters

applicationKey

Application key with access to presence service.

isCluster

Specifies if url is cluster.

metadata

Defines if to collect first 100 unique metadata.

privateKey

The private key provided when the ORTC service is purchased.

url

Server containing the presence service.

Discussion

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

Warning: This function will send your private key over the internet. Make sure to use secure connection.

Declared In

OrtcClient.h

– disablePresence:isCLuster:applicationKey:privateKey:channel:callback:

Disables presence for the specified channel.

- (void)disablePresence:(NSString *)aUrl isCLuster:(BOOL)aIsCluster applicationKey:(NSString *)aApplicationKey privateKey:(NSString *)aPrivateKey channel:(NSString *)channel callback:(void ( ^ ) ( NSError *error , NSString *result ))aCallback

Parameters

channel

Channel with presence data active.

callback

Callback with error (NSError) and result (NSString) parameters

applicationKey

Application key with access to presence service.

url

Server containing the presence service.

isCluster

Specifies if url is cluster.

privateKey

The private key provided when the ORTC service is purchased.

Discussion

Disables presence for the specified channel.

Warning: This function will send your private key over the internet. Make sure to use secure connection.

Declared In

OrtcClient.h

– presence:isCLuster:applicationKey:authenticationToken:channel:callback:

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

- (void)presence:(NSString *)aUrl isCLuster:(BOOL)aIsCluster applicationKey:(NSString *)aApplicationKey authenticationToken:(NSString *)aAuthenticationToken channel:(NSString *)channel callback:(void ( ^ ) ( NSError *error , NSDictionary *result ))aCallback

Parameters

channel

Channel with presence data active.

callback

Callback with error (NSError) and result (NSDictionary) parameters

applicationKey

Application key with access to presence service.

url

Server containing the presence service.

isCluster

Specifies if url is cluster.

authenticationToken

Authentication token with access to presence service.

Discussion

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

Declared In

OrtcClient.h

– setPublishTimeout:

Set publish messages timeout.

- (void)setPublishTimeout:(int)timeout

Discussion

Set publish messages timeout.

Declared In

OrtcClient.h

– getPublishTimeout

Return publish messages timeout.

- (int)getPublishTimeout

Discussion

Return publish messages timeout.

Declared In

OrtcClient.h

– getHeartbeatTime

Get heartbeat interval.

- (int)getHeartbeatTime

Discussion

Get heartbeat interval.

Declared In

OrtcClient.h

– setHeartbeatTime:

Set heartbeat interval.

- (void)setHeartbeatTime:(int)newHeartbeatTime

Discussion

Set heartbeat interval.

Declared In

OrtcClient.h

– getHeartbeatFails

Get how many times can the client fail the heartbeat.

- (int)getHeartbeatFails

Discussion

Get how many times can the client fail the heartbeat.

Declared In

OrtcClient.h

– setHeartbeatFails:

Set heartbeat fails. Defines how many times can the client fail the heartbeat.

- (void)setHeartbeatFails:(int)newHeartbeatFails

Discussion

Set heartbeat fails. Defines how many times can the client fail the heartbeat.

Declared In

OrtcClient.h

– isHeartbeatActive

Indicates whether heartbeat is active or not.

- (BOOL)isHeartbeatActive

Discussion

Indicates whether heartbeat is active or not.

Declared In

OrtcClient.h

– enableHeartbeat

Enables the client heartbeat

- (void)enableHeartbeat

Discussion

Enables the client heartbeat

Declared In

OrtcClient.h

– disableHeartbeat

Disables the client heartbeat

- (void)disableHeartbeat

Discussion

Disables the client heartbeat

Declared In

OrtcClient.h