PubNub Class Reference

Inherits from NSObject
Declared in PubNub+Core.h

Overview

Basically used by \b PubNub categories (each for own API group) and manage communication with \b PubNub service and share user-specified configuration.

@author Sergey Mamontov

Core class manage client configuration as well as access to networking layer through which passed request will be sent to \b PubNub service.

@author Sergey Mamontov

Set of API which allow to retrieve information about subscriber(s) on remote data object live feeds and perform heartbeat requests to let \b PubNub service know what client still interested in updates from feed.

@author Sergey Mamontov

Set of API which allow to push data to \b PubNub service. Data pusched to remote data objects called ‘channels’ and then delivered on their live feeds to all subscribers.

@author Sergey Mamontov

Set of API which allow to manage channels collections and manipulate list of channels in collection.

@author Sergey Mamontov

Set of API which allow to fetch events which has been moved from remote data object live feed to persistent storage.

@author Sergey Mamontov

Set of API which allow to push data to \b PubNub service. Data pusched to remote data objects called ‘channels’ and then delivered on their live feeds to all subscribers.

@author Sergey Mamontov

Set of API which allow to manage push notifications on separate channels. If push notifications has been enabled on channels, then device will start receiving notifications while device inactive.

@author Sergey Mamontov

Set of API which allow to fetch events which has been moved from remote data object live feed to persistent storage.

@author Sergey Mamontov

Information

– currentConfiguration

Retrieve reference on current client’s configuration.

- (PNConfiguration *)currentConfiguration

Return Value

Currently used configuration instance copy. Changes to this instance won’t affect receiver’s configuration.

Availability

4.0

Declared In

PubNub+Core.h

– uuid

Retrieve UUID which has been used during client initialization.

- (NSString *)uuid

Return Value

User-provided or generated unique user identifier.

Availability

4.0

Declared In

PubNub+Core.h

Initialization

+ clientWithConfiguration:

Construct new \b PubNub client instance with pre-defined configuration.

+ (instancetype)clientWithConfiguration:(PNConfiguration *)configuration

Parameters

configuration

Reference on instance which store all user-provided information about how client should operate and handle events.

Return Value

Configured and ready to use \b PubNub client.

Availability

4.0

Discussion

If all keys will be specified, client will be able to read and modify data on \b PubNub service.

Note: Client will make configuration deep copy and further changes in \b PNConfiguration after it has been passed to the client won’t take any effect on client.

Note: All completion block and delegate callbacks will be called on main queue.

Note: All required keys can be found on https://admin.pubnub.com

@code @endcode \b Example: @code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; @endcode

Declared In

PubNub+Core.h

+ clientWithConfiguration:callbackQueue:

Construct new \b PubNub client instance with pre-defined configuration.

+ (instancetype)clientWithConfiguration:(PNConfiguration *)configuration callbackQueue:(dispatch_queue_t)callbackQueue

Parameters

configuration

Reference on instance which store all user-provided information about how client should operate and handle events.

callbackQueue

Reference on queue which should be used by client fot comletion block and delegate calls.

Return Value

Configured and ready to use \b PubNub client.

Availability

4.0

Discussion

If all keys will be specified, client will be able to read and modify data on \b PubNub service.

Note: Client will make configuration deep copy and further changes in \b PNConfiguration after it has been passed to the client won’t take any effect on client.

Note: If \c queue is \ nil all completion block and delegate callbacks will be called on main queue.

Note: All required keys can be found on https://admin.pubnub.com

@code @endcode \b Example: @code dispatch_queue_t queue = dispatch_queue_create(“com.my-app.callback-queue”, DISPATCH_QUEUE_SERIAL); PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration callbackQueue:queue]; @endcode

Declared In

PubNub+Core.h

– copyWithConfiguration:completion:

Make copy of client with it’s current state using new configuration.

- (void)copyWithConfiguration:(PNConfiguration *)configuration completion:(void ( ^ ) ( PubNub *client ))block

Parameters

configuration

Reference on configuration which should be used to create new instance from receiver.

block

Copy completion block which will pass only one argument - reference on new \b PubNub client instance with updated configuration. Block will be called on custom queue (if has been passed to receiver during instantiatio) or main queue.

Availability

4.0

Discussion

Allow to retrieve reference on client which will have same state as receiver, but will use updated configuration. If authorization and/or uuid keys has been changed while subscribed, this method will trigger \c leave presence event on behalf of current uuid and subscribe using new one.

Note: Copy will be returned asynchronous, because some operations may require communication with \b PubNub network (like switching active \c uuid while subscribed).

Note: Re-subscription with new \c uuid will be done using catchup and all messages which has been sent while client changed configuration will be handled.

Note: All listeners will be copied to new client.

@code @endcode \b Example: @code weak typeof(self) weakSelf = self; PNConfiguration configuration = [self.client currentConfiguration]; configuration.TLSEnabled = NO; [self.client copyWithConfiguration:configuration completion:^(PubNub client) {

// Store reference on new client with updated configuration.
weakSelf.client - client;

}]; @endcode

Declared In

PubNub+Core.h

– copyWithConfiguration:callbackQueue:completion:

Make copy of client with it’s current state using new configuration.

- (void)copyWithConfiguration:(PNConfiguration *)configuration callbackQueue:(dispatch_queue_t)callbackQueue completion:(void ( ^ ) ( PubNub *client ))block

Parameters

configuration

Reference on configuration which should be used to create new instance from receiver.

callbackQueue

Reference on queue which should be used by client fot comletion block and delegate calls.

block

Copy completion block which will pass only one argument - reference on new \b PubNub client instance with updated configuration. Block will be called on custom queue (if has been passed to receiver during instantiatio) or main queue.

Availability

4.0

Discussion

Allow to retrieve reference on client which will have same state as receiver, but will use updated configuration. If authorization and/or uuid keys has been changed while subscribed, this method will trigger \c leave presence event on behalf of current uuid and subscribe using new one.

Note: Copy will be returned asynchronous, because some operations may require communication with \b PubNub network (like switching active \c uuid while subscribed).

Note: Re-subscription with new \c uuid will be done using catchup and all messages which has been sent while client changed configuration will be handled.

Note: All listeners will be copied to new client.

@code @endcode \b Example: @code weak typeof(self) weakSelf = self; dispatch_queue_t queue = dispatch_queue_create(“com.my-app.callback-queue”, DISPATCH_QUEUE_SERIAL); PNConfiguration configuration = [self.client currentConfiguration]; configuration.TLSEnabled = NO; [self.client copyWithConfiguration:configuration callbackQueue:queue completion:^(PubNub client) {

// Store reference on new client with updated configuration.
weakSelf.client - client;

}]; @endcode

Declared In

PubNub+Core.h

Private Methods

  configuration

Stores reference on active \b PubNub client configuration.

@property (nonatomic, readonly, copy) PNConfiguration *configuration

Availability

4.0

Declared In

PubNub+CorePrivate.h

  subscriberManager

Stores reference on instance which manage all subscribe loop logic and help to deliver updates from remote data objects live feed to the client.

@property (nonatomic, readonly, strong) PNSubscriber *subscriberManager

Availability

4.0

Declared In

PubNub+CorePrivate.h

  clientStateManager

Stores reference on instance which is responsible for cached client state management.

@property (nonatomic, readonly, strong) PNClientState *clientStateManager

Availability

4.0

Declared In

PubNub+CorePrivate.h

  listenersManager

Stores reference on instance which is responsible for subscriber listeners management.

@property (nonatomic, readonly, strong) PNStateListener *listenersManager

Availability

4.0

Declared In

PubNub+CorePrivate.h

  heartbeatManager

Stores reference on instance which is responsible for presence heartbeat management.

@property (nonatomic, readonly, strong) PNHeartbeat *heartbeatManager

Availability

4.0

Declared In

PubNub+CorePrivate.h

  recentClientStatus

Stores reference about recent client state (whether it was connected or not).

@property (nonatomic, readonly, assign) PNStatusCategory recentClientStatus

Availability

4.0

Declared In

PubNub+CorePrivate.h

  callbackQueue

Reference on queue on which completion/processing blocks will be called.

@property (nonatomic, readonly, strong) dispatch_queue_t callbackQueue

Availability

4.0

Discussion

At the end of each operation completion blocks will be called asynchronously on provided queue.

@default By default all callback blocks will be called on main queue (\c dispatch_get_main_queue()).

Declared In

PubNub+CorePrivate.h

– processOperation:withParameters:completionBlock:

Compose request to \b PubNub network basing on operation type and passed \c parameters.

- (void)processOperation:(PNOperationType)operationType withParameters:(PNRequestParameters *)parameters completionBlock:(id)block

Parameters

operationType

One of \b PNOperationType enum fields which represent type of operation which should be issued to \b PubNub network.

parameters

Resource and query path fields wrapped into object.

block

Reference on operation processing completion block.

Availability

4.0

Declared In

PubNub+CorePrivate.h

– processOperation:withParameters:data:completionBlock:

Compose request to \b PubNub network basing on operation type and passed \c parameters.

- (void)processOperation:(PNOperationType)operationType withParameters:(PNRequestParameters *)parameters data:(NSData *)data completionBlock:(id)block

Parameters

operationType

One of \b PNOperationType enum fields which represent type of operation which should be issued to \b PubNub network.

parameters

Resource and query path fields wrapped into object.

data

Reference on data which should be pushed to \b PubNub network.

block

Reference on operation processing completion block.

Availability

4.0

Declared In

PubNub+CorePrivate.h

– cancelAllLongPollingOperations

Cancel any active long-polling operations scheduled for processing.

- (void)cancelAllLongPollingOperations

Availability

4.0

Declared In

PubNub+CorePrivate.h

– packetSizeForOperation:withParameters:data:

Calculate actual size of packet for passed \c operationType which will be sent to \b PubNub network.

- (NSInteger)packetSizeForOperation:(PNOperationType)operationType withParameters:(PNRequestParameters *)parameters data:(NSData *)data

Parameters

operationType

One of \b PNOperationType enum fields which specify for what kind of operation packet size should be calculated.

parameters

List of passed parameters which should be passed to URL builder.

data

Data which can be pushed along with request to \b PubNub network if required.

Return Value

Size of the packet which include request string, host, headers and HTTP post body.

Availability

4.0

Declared In

PubNub+CorePrivate.h

– appendClientInformation:

Add available client information to object instance subclassed from \b PNResult (\b PNStatus)

- (void)appendClientInformation:(PNResult *)result

Parameters

result

Reference on object which should be updated with client information.

Availability

4.0

Declared In

PubNub+CorePrivate.h

– callBlock:status:withResult:andStatus:

Notify user about processing results by calling completion block with specified result and status on callback queue.

- (void)callBlock:(id)block status:(BOOL)callingStatusBlock withResult:(PNResult *)result andStatus:(PNStatus *)status

Parameters

block

Reference on completion block which has been passed by user during API call.

result

Reference on API request processing results.

status

Reference on API request processing status (mostly reports about errors).

Availability

4.0

Declared In

PubNub+CorePrivate.h

APNSProtected Methods

– enablePushNotification:onChannels:withDevicePushToken:andCompletion:

Final designated method which allow to modify push notifications state on set of channels for device specified by \c pushToken.

- (void)enablePushNotification:(BOOL)shouldEnabled onChannels:(NSArray *)channels withDevicePushToken:(NSData *)pushToken andCompletion:(PNPushNotificationsStateModificationCompletionBlock)block

Parameters

shouldEnabled

Whether push notification should be enabled or disabled on \c channels.

channels

List of channels for which notification state should be changed.

pushToken

Reference on device push token for which on specified \c channels push notifications will be enabled or disabled.

block

Push notifications state modification on channels processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Declared In

PubNub+APNS.m

– pushNotificationEnabledChannelsForDeviceWithPushToken:andCompletion:

Request for all channels on which push notification has been enabled using specified \c pushToken.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client pushNotificationEnabledChannelsForDeviceWithPushToken:self.devicePushToken andCompletion:^(PNAPNSEnabledChannelsResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded list of chanels using: result.data.channels
 }
 // Request processing failed.
 else {

    // Handle audition error. Check 'category' property to find out possible issue because of 
    // which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)pushNotificationEnabledChannelsForDeviceWithPushToken:(NSData *)pushToken andCompletion:(PNPushNotificationsStateAuditCompletionBlock)block

Parameters

pushToken

Device push token against which search on \b PubNub service should be performed.

block

Push notifications status processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of push notifications audit operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+APNS.h

Presence Methods

– hereNowWithCompletion:

Request information about subscribers on all remote data objects live feeds.

- (void)hereNowWithCompletion:(PNGlobalHereNowCompletionBlock)block

Parameters

block

Here now processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

This is application wide request for all remote data objects which is registered under publish and subscribe keys used for client configuration.

Note: This API will retrieve only list of UUIDs along with their state for each remote data object and number of subscribers in total for objects and overall.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client hereNowWithCompletion:^(PNPresenceGlobalHereNowResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded presence information using:
    //   result.data.channels - dictionary with active channels and presence information on 
    //                          each. Each channel will have next fields: "uuids" - list of
    //                          subscribers; occupancy - number of active subscribers.
    //                          Each uuids entry has next fields: "uuid" - identifier and 
    //                          "state" if it has been provided.
    //   result.data.totalChannels - total number of active channels.
    //   result.data.totalOccupancy - total number of active subscribers.
 }
 // Request processing failed.
 else {

    // Handle presence audit error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Presence.h

– hereNowWithVerbosity:completion:

Request information about subscribers on all remote data objects live feeds.

- (void)hereNowWithVerbosity:(PNHereNowVerbosityLevel)level completion:(PNGlobalHereNowCompletionBlock)block

Parameters

level

Reference on one of \b PNHereNowVerbosityLevel fields to instruct what exactly data it expected in response.

block

Here now processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

This is application wide request for all remote data objects which is registered under publish and subscribe keys used for client configuration.

@code @endcode Extension to \c hereNowWithCompletion: and allow to specify here now data which should be returned by \b PubNub service.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client hereNowWithVerbosity:PNHereNowState completion:^(PNPresenceGlobalHereNowResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded presence information using:
    //   result.data.channels - dictionary with active channels and presence information on 
    //                          each. Each channel will have next fields: "uuids" - list of
    //                          subscribers; "occupancy" - number of active subscribers.
    //                          Each uuids entry has next fields: "uuid" - identifier and 
    //                          "state" if it has been provided.
    //   result.data.totalChannels - total number of active channels.
    //   result.data.totalOccupancy - total number of active subscribers.
 }
 // Request processing failed.
 else {

    // Handle presence audit error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Presence.h

– hereNowForChannel:withCompletion:

Request information about subscribers on specific channel live feeds.

- (void)hereNowForChannel:(NSString *)channel withCompletion:(PNHereNowCompletionBlock)block

Parameters

channel

Reference on channel for which here now information should be received.

block

Here now processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: This API will retrieve only list of UUIDs along with their state for each remote data object and number of subscribers in total for objects and overall.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client hereNowForChannel:@“pubnub” withCompletion:^(PNPresenceChannelHereNowResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded presence information using:
    //   result.data.uuids - dictionary with active subscriber. Each entry will have next 
    //                       fields: "uuid" - identifier and "state" if it has been provided.
    //   result.data.occupancy - total number of active subscribers.
 }
 // Request processing failed.
 else {

    // Handle presence audit error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Presence.h

– hereNowForChannel:withVerbosity:completion:

Request information about subscribers on specific channel live feeds.

@code @endcode Extension to \c hereNowForChannel:withCompletion: and allow to specify here now data which should be returned by \b PubNub service.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client hereNowForChannel:@“pubnub” withVerbosity:PNHereNowState completion:^(PNPresenceChannelHereNowResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded presence information using:
    //   result.data.uuids - dictionary with active subscriber. Each entry will have next 
    //                       fields: "uuid" - identifier and "state" if it has been provided.
    //   result.data.occupancy - total number of active subscribers.
 }
 // Request processing failed.
 else {

    // Handle presence audit error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)hereNowForChannel:(NSString *)channel withVerbosity:(PNHereNowVerbosityLevel)level completion:(PNHereNowCompletionBlock)block

Parameters

channel

Reference on channel for which here now information should be received.

level

Reference on one of \b PNHereNowVerbosityLevel fields to instruct what exactly data it expected in response.

block

Here now processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+Presence.h

– hereNowForChannelGroup:withCompletion:

Request information about subscribers on specific channel group live feeds.

- (void)hereNowForChannelGroup:(NSString *)group withCompletion:(PNChannelGroupHereNowCompletionBlock)block

Parameters

group

Reference on channel group name for which here now information should be received.

block

Here now processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: This API will retrieve only list of UUIDs along with their state for each remote data object and number of subscribers in total for objects and overall.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client hereNowForChannelGroup:@“developers” withCompletion:^(PNPresenceWhereNowResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded presence information using:
    //   result.data.channels - dictionary with active channels and presence information on 
    //                          each. Each channel will have next fields: "uuids" - list of
    //                          subscribers; occupancy - number of active subscribers.
    //                          Each uuids entry has next fields: "uuid" - identifier and 
    //                          "state" if it has been provided.
    //   result.data.totalChannels - total number of active channels.
    //   result.data.totalOccupancy - total number of active subscribers.
 }
 // Request processing failed.
 else {

    // Handle presence audit error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Presence.h

– hereNowForChannelGroup:withVerbosity:completion:

Request information about subscribers on specific channel group live feeds.

@code @endcode Extension to \c hereNowForChannelGroup:withCompletion: and allow to specify here now data which should be returned by \b PubNub service.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client hereNowForChannelGroup:@“developers” withVerbosity:PNHereNowState completion:^(PNPresenceWhereNowResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded presence information using:
    //   result.data.channels - dictionary with active channels and presence information on 
    //                          each. Each channel will have next fields: "uuids" - list of
    //                          subscribers; occupancy - number of active subscribers.
    //                          Each uuids entry has next fields: "uuid" - identifier and 
    //                          "state" if it has been provided.
    //   result.data.totalChannels - total number of active channels.
    //   result.data.totalOccupancy - total number of active subscribers.
 }
 // Request processing failed.
 else {

    // Handle presence audit error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)hereNowForChannelGroup:(NSString *)group withVerbosity:(PNHereNowVerbosityLevel)level completion:(PNChannelGroupHereNowCompletionBlock)block

Parameters

group

Reference on channel group for which here now information should be received.

level

Reference on one of \b PNHereNowVerbosityLevel fields to instruct what exactly data it expected in response.

block

Here now processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+Presence.h

– whereNowUUID:withCompletion:

Request information about remote data object live feeds on which client with specified UUID subscribed at this moment.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client whereNowUUID:@“Steve” withCompletion:^(PNPresenceWhereNowResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded presence 'where now' information using: result.data.channels
 }
 // Request processing failed.
 else {

    // Handle presence audit error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)whereNowUUID:(NSString *)uuid withCompletion:(PNWhereNowCompletionBlock)block

Parameters

uuid

Reference on UUID for which request should be performed.

block

Where now processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of where now operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+Presence.h

PresenceProtected Methods

– hereNowWithVerbosity:forChannel:withName:withCompletion:

Request information about subscribers on specific remote data object live feeds.

- (void)hereNowWithVerbosity:(PNHereNowVerbosityLevel)level forChannel:(BOOL)forChannel withName:(NSString *)object withCompletion:(id)block

Parameters

level

Reference on one of \b PNHereNowVerbosityLevel fields to instruct what exactly data it expected in response.

forChannel

Whether ‘here now’ information should be pulled for channel or group.

object

Reference on remote data object for which here now information should be received.

block

Here now processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of here now operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: This API will retrieve only list of UUIDs for specified remote data object and number of subscribers on it.

Declared In

PubNub+Presence.m

– heartbeatWithCompletion:

Issue heartbeat request to \b PubNub network.

- (void)heartbeatWithCompletion:(PNStatusBlock)block

Parameters

block

Reference on block which should be called with service information.

Availability

4.0

Discussion

Heartbeat help \b PubNub preence service to control subscribers availability.

Declared In

PubNub+PresencePrivate.h

ChannelGroupProtected Methods

– add:channels:toGroup:withCompletion:

Add or remove channels to/from the \c group.

- (void)add:(BOOL)shouldAdd channels:(NSArray *)channels toGroup:(NSString *)group withCompletion:(PNChannelGroupChangeCompletionBlock)block

Parameters

shouldAdd

Whether provided \c channels should be added to the \c group or removed.

channels

List of channels names which should be used for \c group modification.

group

Name of the group which should be modified with list of passed \c objects.

block

Channel group list modification process completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Declared In

PubNub+ChannelGroup.m

Extension Methods

  subscriptionNetwork

Stores reference on \b PubNub network manager configured to be used for ‘subscription’ API group with long-polling.

@property (nonatomic, strong) PNNetwork *subscriptionNetwork

Availability

4.0

Declared In

PubNub+Core.m

  serviceNetwork

Stores reference on \b PubNub network manager configer to be used for ‘non-subscription’ API group.

@property (nonatomic, strong) PNNetwork *serviceNetwork

Availability

4.0

Declared In

PubNub+Core.m

  reachability

Stores reference on reachability helper.

@property (nonatomic, strong) PNReachability *reachability

Availability

4.0

Discussion

Helper used by client to know about when something happened with network and when it is safe to issue requests to \b PubNub network.

Declared In

PubNub+Core.m

– initWithConfiguration:callbackQueue:

Initialize \b PubNub client instance with pre-defined configuration.

- (instancetype)initWithConfiguration:(PNConfiguration *)configuration callbackQueue:(dispatch_queue_t)callbackQueue

Parameters

configuration

Reference on instance which store all user-provided information about how client should operate and handle events.

callbackQueue

Reference on queue which should be used by client fot comletion block and delegate calls.

Return Value

Initialized and ready to use \b PubNub client.

Availability

4.0

Discussion

If all keys will be specified, client will be able to read and modify data on \b PubNub service.

Declared In

PubNub+Core.m

– prepareReachability

Complete reachability helper configuration.

- (void)prepareReachability

Availability

4.0

Declared In

PubNub+Core.m

– prepareNetworkManagers

Initialize and configure required \b PubNub network managers.

- (void)prepareNetworkManagers

Availability

4.0

Declared In

PubNub+Core.m

– handleContextTransition:

Handle application with active client transition between foreground and background execution contexts.

- (void)handleContextTransition:(NSNotification *)notification

Parameters

notification

Reference on notification which will provide information about to which context application has been pushed.

Declared In

PubNub+Core.m

+ ddLogLevel

Called by Cocoa Lumberjack during initialization.

+ (DDLogLevel)ddLogLevel

Return Value

Desired logger level for \b PubNub client main class.

Availability

4.0

Declared In

PubNub+Core.m

+ ddSetLogLevel:

Allow modify logger level used by Cocoa Lumberjack with logging macros.

+ (void)ddSetLogLevel:(DDLogLevel)logLevel

Parameters

logLevel

New log level which should be used by logger.

Availability

4.0

Declared In

PubNub+Core.m

SubscribePrivate Methods

– unsubscribeFromChannels:withPresence:completion:

Unsubscribe/leave from specified set of channels.

- (void)unsubscribeFromChannels:(NSArray *)channels withPresence:(BOOL)shouldObservePresence completion:(PNSubscriberCompletionBlock)block

Parameters

channels

List of channel names from which client should try to unsubscribe.

shouldObservePresence

Whether client should disable presence observation on specified channels or keep listening for presence event on them.

block

Reference on subscription completion block which is used to notify code.

Availability

4.0

Discussion

Using this API client will push leave presence event on specified \c channels and if it will be required it will re-subscribe on rest of the channels.

Declared In

PubNub+SubscribePrivate.h

– unsubscribeFromChannelGroups:withPresence:completion:

Unsubscribe/leave from specified set of channel groups.

- (void)unsubscribeFromChannelGroups:(NSArray *)groups withPresence:(BOOL)shouldObservePresence completion:(PNSubscriberCompletionBlock)block

Parameters

groups

List of channel group names from which client should try to unsubscribe.

shouldObservePresence

Whether client should disable presence observation on specified channel groups or keep listening for presence event on them.

block

Reference on subscription completion block which is used to notify code.

Availability

4.0

Discussion

Using this API client will push leave presence event on specified \c groups. In this case leave event will be pushed to all channels which is part of \c groups. If it will be required it will re-subscribe on rest of the channels.

Declared In

PubNub+SubscribePrivate.h

PublishPrivate Methods

– requestParametersForMessage:toChannel:compressed:storeInHistory:

Compose set of parameters which is required to publish message.

- (PNRequestParameters *)requestParametersForMessage:(id)message toChannel:(NSString *)channel compressed:(BOOL)compressMessage storeInHistory:(BOOL)shouldStore

Parameters

message

Reference on message which should be published.

channel

Reference on name of the channel to which message should be published.

compressMessage

Whether message should be compressed before publish.

shouldStore

Whether message should be stored in history storage or not.

Return Value

Configured and ready to use request parameters instance.

Availability

4.0

Declared In

PubNub+Publish.m

– mergedMessage:withMobilePushPayload:

Merge user-specified message with push payloads into single message which will be processed on \b PubNub service.

- (NSDictionary *)mergedMessage:(NSString *)message withMobilePushPayload:(NSDictionary *)payloads

Parameters

message

Message which should be merged with \c payloads.

payloads

Dictionary with payloads for different vendors (Apple with “apns” key and Google with “gcm”).

Return Value

Merged message or original message if there is no data in \c payloads.

Availability

4.0

Discussion

In case if aside from \c message has been passed \c payloads this method will merge them into format known by \b PubNub service and will cause further push distribution to specified vendors.

Declared In

PubNub+Publish.m

– encryptedMessage:withCipherKey:error:

Try perform encryption of data which should be pushed to \b PubNub services.

- (NSString *)encryptedMessage:(NSString *)message withCipherKey:(NSString *)key error:(NSError **)error

Parameters

message

Referebce on data which \b PNAES should try to encrypt.

key

Reference on cipher key which should be used during encryption.

error

Reference on pointer into which data encryption error will be passed.

Return Value

Encrypted Base64-encoded string or original message, if there is no \c key has been passed. \c nil will be returned in case if encrytption failed.

Availability

4.0

Declared In

PubNub+Publish.m

– publish:toChannel:mobilePushPayload:storeInHistory:compressed:withCompletion:

Send provided Foundation object to \b PubNub service.

- (void)publish:(id)message toChannel:(NSString *)channel mobilePushPayload:(NSDictionary *)payloads storeInHistory:(BOOL)shouldStore compressed:(BOOL)compressed withCompletion:(PNPublishCompletionBlock)block

Parameters

message

Reference on Foundation object (\a NSString, \a NSNumber, \a NSArray, \a NSDictionary) which will be published.

channel

Reference on name of the channel to which message should be published.

payloads

Dictionary with payloads for different vendors (Apple with “apns” key and Google with “gcm”).

shouldStore

With \c NO this message later won’t be fetched with \c history API.

compressed

Compression useful in case if large data should be published, in another case it will lead to packet size grow.

block

Publish processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Provided object will be serialized into JSON string before pushing to \b PubNub service. If client has been configured with cipher key message will be encrypted as well.

Note: Objects can be pushed only to regular channels.

@code @endcode Extension to \c publish:toChannel:mobilePushPayload:storeInHistory:withCompletion: and specify whether message itself should be compressed or not. Only message will be compressed and \c payloads will be kept in JSON string format.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client publish:@{@“Hello”:@“world”} toChannel:@“announcement” mobilePushPayload:@{@“apns”:@{@“alert”:@“Hello from PubNub”}} storeInHistory:YES compressed:NO withCompletion:^(PNPublishStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Message successfully published to specified channel.
 }
 // Request processing failed.
 else {

     // Handle message publish error. Check 'category' property to find out possible issue 
     // because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Publish.h

– sizeOfMessage:toChannel:compressed:storeInHistory:withCompletion:

Helper method which allow to calculate resulting message before it will be sent to \b PubNub network.

- (void)sizeOfMessage:(id)message toChannel:(NSString *)channel compressed:(BOOL)compressMessage storeInHistory:(BOOL)shouldStore withCompletion:(PNMessageSizeCalculationCompletionBlock)block

Parameters

message

Message for which size should be calculated.

channel

Name of the channel to which message should be sent (it is part of request URI).

compressMessage

\c YES in case if message should be compressed before sending to \b PubNub network.

shouldStore

\c NO in case if message shouldn’t be available after it has been sent via history storage API methods group.

block

Referecnce on block which should be sent, when message size calculation will be completed.

Availability

4.0

Discussion

Size calculation use percent-escaped \c message and all added headers to get full size.

@code @endcode Extension to \c -sizeOfMessage:toChannel:compressed:withCompletion: and specify whether message should be stored in history or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client sizeOfMessage:@{@“Hello”:@“world”} toChannel:@“announcement” compressed:NO storeInHistory:NO withCompletion:^(NSInteger size) {

 // Actual message size is: size

}]; @endcode

Declared In

PubNub+Publish.h

Time Methods

– timeWithCompletion:

Request current time from \b PubNub service servers.

@code @endcode \b Example:

@code PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [client timeWithHandlingBlock:^(PNTimeResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Handle downloaded server time token using: result.data.timetoken
 }
 // Request processing failed.
 else {

     // Handle tmie token download error. Check 'category' property to find out possible
     // issue because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)timeWithCompletion:(PNTimeCompletionBlock)block

Parameters

block

Time request process results handling block which pass two arguments: \c result - in case of successful request processing \c data field will contain server-provided time token; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+Time.h

HistoryPrivate Methods

– handleHistoryResult:withStatus:completion:

History request results handling and pre-processing before notify to completion blocks (if required at all).

- (void)handleHistoryResult:(PNResult *)result withStatus:(PNStatus *)status completion:(PNHistoryCompletionBlock)block

Parameters

result

Reference on object which represent server useful response data.

status

Reference on object which represent request processing results.

block

History pull processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of history request operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+History.m

Publish Methods

– publish:toChannel:withCompletion:

Send provided Foundation object to \b PubNub service.

- (void)publish:(id)message toChannel:(NSString *)channel withCompletion:(PNPublishCompletionBlock)block

Parameters

message

Reference on Foundation object (\a NSString, \a NSNumber, \a NSArray, \a NSDictionary) which will be published.

channel

Reference on name of the channel to which message should be published.

block

Publish processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Provided object will be serialized into JSON string before pushing to \b PubNub service. If client has been configured with cipher key message will be encrypted as well.

Note: Objects can be pushed only to regular channels.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client publish:@{@“Hello”:@“world”} toChannel:@“announcement” withCompletion:^(PNPublishStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Message successfully published to specified channel.
 }
 // Request processing failed.
 else {

     // Handle message publish error. Check 'category' property to find out possible issue 
     // because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Publish.h

– publish:toChannel:compressed:withCompletion:

Send provided Foundation object to \b PubNub service.

- (void)publish:(id)message toChannel:(NSString *)channel compressed:(BOOL)compressed withCompletion:(PNPublishCompletionBlock)block

Parameters

message

Reference on Foundation object (\a NSString, \a NSNumber, \a NSArray, \a NSDictionary) which will be published.

channel

Reference on name of the channel to which message should be published.

compressed

Whether message should be compressed and sent with request body instead of URI part. Compression useful in case if large data should be published, in another case it will lead to packet size grow.

block

Publish processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Provided object will be serialized into JSON string before pushing to \b PubNub service. If client has been configured with cipher key message will be encrypted as well.

Note: Objects can be pushed only to regular channels.

@code @endcode Extension to \c publish:toChannel:withCompletion: and allow to specify whether message should be compressed or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client publish:@{@“Hello”:@“world”} toChannel:@“announcement” compressed:NO withCompletion:^(PNPublishStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Message successfully published to specified channel.
 }
 // Request processing failed.
 else {

     // Handle message publish error. Check 'category' property to find out possible issue 
     // because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Publish.h

– publish:toChannel:storeInHistory:withCompletion:

Send provided Foundation object to \b PubNub service.

- (void)publish:(id)message toChannel:(NSString *)channel storeInHistory:(BOOL)shouldStore withCompletion:(PNPublishCompletionBlock)block

Parameters

message

Reference on Foundation object (\a NSString, \a NSNumber, \a NSArray, \a NSDictionary) which will be published.

channel

Reference on name of the channel to which message should be published.

shouldStore

With \c NO this message later won’t be fetched with \c history API.

block

Publish processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Provided object will be serialized into JSON string before pushing to \b PubNub service. If client has been configured with cipher key message will be encrypted as well.

Note: Objects can be pushed only to regular channels.

@code @endcode Extension to \c publish:toChannel:withCompletion: and allow to specify whether message should be stored in history or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client publish:@{@“Hello”:@“world”} toChannel:@“announcement” storeInHistory:NO withCompletion:^(PNPublishStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Message successfully published to specified channel.
 }
 // Request processing failed.
 else {

     // Handle message publish error. Check 'category' property to find out possible issue 
     // because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Publish.h

– publish:toChannel:storeInHistory:compressed:withCompletion:

Send provided Foundation object to \b PubNub service.

- (void)publish:(id)message toChannel:(NSString *)channel storeInHistory:(BOOL)shouldStore compressed:(BOOL)compressed withCompletion:(PNPublishCompletionBlock)block

Parameters

message

Reference on Foundation object (\a NSString, \a NSNumber, \a NSArray, \a NSDictionary) which will be published.

channel

Reference on name of the channel to which message should be published.

shouldStore

With \c NO this message later won’t be fetched with \c history API.

compressed

Compression useful in case if large data should be published, in another case it will lead to packet size grow.

block

Publish processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Provided object will be serialized into JSON string before pushing to \b PubNub service. If client has been configured with cipher key message will be encrypted as well.

Note: Objects can be pushed only to regular channels.

@code @endcode Extension to \c publish:toChannel:storeInHistory:withCompletion: and allow to specify whether message should be compressed or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client publish:@{@“Hello”:@“world”} toChannel:@“announcement” storeInHistory:NO compressed:YES withCompletion:^(PNPublishStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Message successfully published to specified channel.
 }
 // Request processing failed.
 else {

     // Handle message publish error. Check 'category' property to find out possible issue 
     // because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Publish.h

– publish:toChannel:mobilePushPayload:withCompletion:

Send provided Foundation object to \b PubNub service.

- (void)publish:(id)message toChannel:(NSString *)channel mobilePushPayload:(NSDictionary *)payloads withCompletion:(PNPublishCompletionBlock)block

Parameters

message

Reference on Foundation object (\a NSString, \a NSNumber, \a NSArray, \a NSDictionary) which will be published.

channel

Reference on name of the channel to which message should be published.

payloads

Dictionary with payloads for different vendors (Apple with “apns” key and Google with “gcm”).

block

Publish processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Provided object will be serialized into JSON string before pushing to \b PubNub service. If client has been configured with cipher key message will be encrypted as well.

Note: Objects can be pushed only to regular channels.

@code @endcode Extension to \c publish:toChannel:withCompletion: and allow to specify push payloads which can be sent using different vendors (Apple and/or Google).

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client publish:@{@“Hello”:@“world”} toChannel:@“announcement” mobilePushPayload:@{@“apns”:@{@“alert”:@“Hello from PubNub”}} withCompletion:^(PNPublishStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Message successfully published to specified channel.
 }
 // Request processing failed.
 else {

     // Handle message publish error. Check 'category' property to find out possible issue 
     // because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Publish.h

– publish:toChannel:mobilePushPayload:compressed:withCompletion:

Send provided Foundation object to \b PubNub service.

- (void)publish:(id)message toChannel:(NSString *)channel mobilePushPayload:(NSDictionary *)payloads compressed:(BOOL)compressed withCompletion:(PNPublishCompletionBlock)block

Parameters

message

Reference on Foundation object (\a NSString, \a NSNumber, \a NSArray, \a NSDictionary) which will be published.

channel

Reference on name of the channel to which message should be published.

payloads

Dictionary with payloads for different vendors (Apple with “apns” key and Google with “gcm”).

compressed

Compression useful in case if large data should be published, in another case it will lead to packet size grow.

block

Publish processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Provided object will be serialized into JSON string before pushing to \b PubNub service. If client has been configured with cipher key message will be encrypted as well.

Note: Objects can be pushed only to regular channels.

@code @endcode Extension to \c publish:toChannel:mobilePushPayload:withCompletion: and specify whether message itself should be compressed or not. Only message will be compressed and \c payloads will be kept in JSON string format.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client publish:@{@“Hello”:@“world”} toChannel:@“announcement” mobilePushPayload:@{@“apns”:@{@“alert”:@“Hello from PubNub”}} compressed:YES withCompletion:^(PNPublishStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Message successfully published to specified channel.
 }
 // Request processing failed.
 else {

     // Handle message publish error. Check 'category' property to find out possible issue 
     // because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Publish.h

– publish:toChannel:mobilePushPayload:storeInHistory:withCompletion:

Send provided Foundation object to \b PubNub service.

- (void)publish:(id)message toChannel:(NSString *)channel mobilePushPayload:(NSDictionary *)payloads storeInHistory:(BOOL)shouldStore withCompletion:(PNPublishCompletionBlock)block

Parameters

message

Reference on Foundation object (\a NSString, \a NSNumber, \a NSArray, \a NSDictionary) which will be published.

channel

Reference on name of the channel to which message should be published.

payloads

Dictionary with payloads for different vendors (Apple with “apns” key and Google with “gcm”).

shouldStore

With \c NO this message later won’t be fetched with \c history API.

block

Publish processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Provided object will be serialized into JSON string before pushing to \b PubNub service. If client has been configured with cipher key message will be encrypted as well.

Note: Objects can be pushed only to regular channels.

@code @endcode Extension to \c publish:toChannel:withCompletion: and allow to specify push payloads which can be sent using different vendors (Apple and/or Google).

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client publish:@{@“Hello”:@“world”} toChannel:@“announcement” mobilePushPayload:@{@“apns”:@{@“alert”:@“Hello from PubNub”}} storeInHistory:YES withCompletion:^(PNPublishStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Message successfully published to specified channel.
 }
 // Request processing failed.
 else {

     // Handle message publish error. Check 'category' property to find out possible issue 
     // because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+Publish.h

– sizeOfMessage:toChannel:withCompletion:

Helper method which allow to calculate resulting message before it will be sent to \b PubNub network.

- (void)sizeOfMessage:(id)message toChannel:(NSString *)channel withCompletion:(PNMessageSizeCalculationCompletionBlock)block

Parameters

message

Message for which size should be calculated.

channel

Name of the channel to which message should be sent (it is part of request URI).

block

Referecnce on block which should be sent, when message size calculation will be completed.

Availability

4.0

Discussion

Size calculation use percent-escaped \c message and all added headers to get full size.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client sizeOfMessage:@{@“Hello”:@“world”} toChannel:@“announcement” withCompletion:^(NSInteger size) {

 // Actual message size is: size

}]; @endcode

Declared In

PubNub+Publish.h

– sizeOfMessage:toChannel:compressed:withCompletion:

Helper method which allow to calculate resulting message before it will be sent to \b PubNub network.

- (void)sizeOfMessage:(id)message toChannel:(NSString *)channel compressed:(BOOL)compressMessage withCompletion:(PNMessageSizeCalculationCompletionBlock)block

Parameters

message

Message for which size should be calculated.

channel

Name of the channel to which message should be sent (it is part of request URI).

compressMessage

\c YES in case if message should be compressed before sending to \b PubNub network.

block

Referecnce on block which should be sent, when message size calculation will be completed.

Availability

4.0

Discussion

Size calculation use percent-escaped \c message and all added headers to get full size.

@code @endcode Extension to \c -sizeOfMessage:toChannel:withCompletion: and specify whether message should be compressed or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client sizeOfMessage:@{@“Hello”:@“world”} toChannel:@“announcement” compressed:YES withCompletion:^(NSInteger size) {

 // Actual message size is: size

}]; @endcode

Declared In

PubNub+Publish.h

– sizeOfMessage:toChannel:storeInHistory:withCompletion:

Helper method which allow to calculate resulting message before it will be sent to \b PubNub network.

- (void)sizeOfMessage:(id)message toChannel:(NSString *)channel storeInHistory:(BOOL)shouldStore withCompletion:(PNMessageSizeCalculationCompletionBlock)block

Parameters

message

Message for which size should be calculated.

channel

Name of the channel to which message should be sent (it is part of request URI).

shouldStore

\c YES in case if message should be placed into history storage.

block

Referecnce on block which should be sent, when message size calculation will be completed.

Availability

4.0

Discussion

Size calculation use percent-escaped \c message and all added headers to get full size.

@code @endcode Extension to \c -sizeOfMessage:toChannel:withCompletion: and specify whether message should be stored in history or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client sizeOfMessage:@{@“Hello”:@“world”} toChannel:@“announcement” storeInHistory:NO withCompletion:^(NSInteger size) {

 // Actual message size is: size

}]; @endcode

Declared In

PubNub+Publish.h

ChannelGroup Methods

– channelGroupsWithCompletion:

Fetch list of all (application keys wide) active channel groups.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client channelGroupsWithCompletion:^(PNChannelGroupsResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded list of groups using: result.data.groups
 }
 // Request processing failed.
 else {

    // Handle channel group audition error. Check 'category' property to find out possible issue 
    // because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)channelGroupsWithCompletion:(PNGroupAuditCompletionBlock)block

Parameters

block

Channel groups audition process completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of channel groups audition operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+ChannelGroup.h

– channelsForGroup:withCompletion:

Fetch list of channels which is registered in specified \c group.

- (void)channelsForGroup:(NSString *)group withCompletion:(PNGroupChannelsAuditCompletionBlock)block

Parameters

group

Name of the group from which channels should be fetched.

block

Channels audition process completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of channel groups channels audition operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: If \c group will be set to \c nil this method will work as \c channelGroupsWithCompletion: and return list of channel groups.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client channelsForGroup:@“pubnub” withCompletion:^(PNChannelGroupChannelsResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded list of chanels using: result.data.channels
 }
 // Request processing failed.
 else {

    // Handle channels for group audition error. Check 'category' property to find out possible 
    // issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+ChannelGroup.h

– addChannels:toGroup:withCompletion:

Add new channels to the \c group.

- (void)addChannels:(NSArray *)channels toGroup:(NSString *)group withCompletion:(PNChannelGroupChangeCompletionBlock)block

Parameters

channels

List of channel names which should be added to the \c group.

group

Name of the group into which channels should be added.

block

Channels addition process completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

After addition channels to group it can be used in subscribe request to subscribe on remote data objects live feed with single group name.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client addChannels:@[@“ios”, @“macos”, @“Win”] toGroup:@“os” withCompletion:^(PNAcknowledgmentStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle successful channels list modification for group.
 }
 // Request processing failed.
 else {

    // Handle channels list modificatoin for group error. Check 'category' property to find out 
    // possible issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+ChannelGroup.h

– removeChannels:fromGroup:withCompletion:

Remove specified \c channels from \c group.

- (void)removeChannels:(NSArray *)channels fromGroup:(NSString *)group withCompletion:(PNChannelGroupChangeCompletionBlock)block

Parameters

channels

List of channel names which should be removed from \c group.

group

Name of the group from which channels should be removed.

block

Channels removal process completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

After specified channels will be removed, events from those channel’s live feed won’t be delivered to the client which is subscribed at specified channel group.

Warning: In case if \c nil will be passed as \c channels then this method will work as \c removeChannelsFromGroup:withCompletion: and remove all channels from specified group and group itself.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client removeChannels:@[@“ios”, @“macos”, @“Win”] fromGroup:@“os” withCompletion:^(PNAcknowledgmentStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle successful channels list modification for group.
 }
 // Request processing failed.
 else {

    // Handle channels list modificatoin for group error. Check 'category' property to find out 
    // possible issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+ChannelGroup.h

– removeChannelsFromGroup:withCompletion:

Remove all channels from \c group.

- (void)removeChannelsFromGroup:(NSString *)group withCompletion:(PNChannelGroupChangeCompletionBlock)block

Parameters

group

Name of the group from which all channels should be removed.

block

Channel group removal process completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

After all channels removed from \c group it become invalid and can’t be used in subscribe process anymore.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client removeChannelsFromGroup:@“os” withCompletion:^(PNAcknowledgmentStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle successful channel group removal.
 }
 // Request processing failed.
 else {

    // Handle channel group removal error. Check 'category' property to find out possible issue
    // because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+ChannelGroup.h

History Methods

– historyForChannel:withCompletion:

Allow to fetch up to \b 100 events from specified \c channel’s events storage.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client historyForChannel:@“storage” withCompletion:^(PNHistoryResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded history using: 
    //   result.data.start - oldest message time stamp in response
    //   result.data.end - newest message time stamp in response
    //   result.data.messages - list of messages
 }
 // Request processing failed.
 else {

    // Handle message history download error. Check 'category' property to find out possible 
    // issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)historyForChannel:(NSString *)channel withCompletion:(PNHistoryCompletionBlock)block

Parameters

channel

Name of the channel for hich events should be pulled out from storage.

block

History pull processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of history request operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+History.h

– historyForChannel:start:end:withCompletion:

Allow to fetch events from specified \c channel’s history within specified time frame.

- (void)historyForChannel:(NSString *)channel start:(NSNumber *)startDate end:(NSNumber *)endDate withCompletion:(PNHistoryCompletionBlock)block

Parameters

channel

Name of the channel for hich events should be pulled out from storage.

startDate

Reference on time token for oldest event starting from which next should be returned events.

endDate

Reference on time token for latest event till which events should be pulled out.

block

History pull processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of history request operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: All ‘history’ API group methods allow to fetch up to \b 100 events at once. If in specified time frame there is more then 100 events paging may be required. For paging use last event time token from respone and some distant future date for next portion of events.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; NSNumber startDate = @((unsigned long long)([[NSDate dateWithTimeIntervalSinceNow:-(6060)] timeIntervalSince1970]10000000)); NSNumber endDate = @((unsigned long long)([[NSDate date] timeIntervalSince1970]10000000)); [self.client historyForChannel:@“storage” start:startDate end:endDate withCompletion:^(PNHistoryResult result, PNErrorStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded history using: 
    //   result.data.start - oldest message time stamp in response
    //   result.data.end - newest message time stamp in response
    //   result.data.messages - list of messages
 }
 // Request processing failed.
 else {

    // Handle message history download error. Check 'category' property to find out possible 
    // issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+History.h

– historyForChannel:start:end:limit:withCompletion:

Allow to fetch events from specified \c channel’s history within specified time frame.

- (void)historyForChannel:(NSString *)channel start:(NSNumber *)startDate end:(NSNumber *)endDate limit:(NSUInteger)limit withCompletion:(PNHistoryCompletionBlock)block

Parameters

channel

Name of the channel for hich events should be pulled out from storage.

startDate

Reference on time token for oldest event starting from which next should be returned events.

endDate

Reference on time token for latest event till which events should be pulled out.

limit

Maximum number of events which should be returned in response (not more then \b 100).

block

History pull processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of history request operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: All ‘history’ API group methods allow to fetch up to \b 100 events at once. If in specified time frame there is more then 100 events paging may be required. For paging use last event time token from respone and some distant future date for next portion of events.

@code @endcode Extension to \c historyForChannel:start:end:withCompletion: and allow to specify maximum number of events which should be returned with response, but not more then \b 100.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; NSNumber startDate = @((unsigned long long)([[NSDate dateWithTimeIntervalSinceNow:-(6060)] timeIntervalSince1970]10000000)); NSNumber endDate = @((unsigned long long)([[NSDate date] timeIntervalSince1970]10000000)); [self.client historyForChannel:@“storage” start:startDate end:endDate limit:50 withCompletion:^(PNHistoryResult result, PNErrorStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded history using: 
    //   result.data.start - oldest message time stamp in response
    //   result.data.end - newest message time stamp in response
    //   result.data.messages - list of messages
 }
 // Request processing failed.
 else {

    // Handle message history download error. Check 'category' property to find out possible 
    // issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+History.h

– historyForChannel:start:end:includeTimeToken:withCompletion:

Allow to fetch events from specified \c channel’s history within specified time frame.

- (void)historyForChannel:(NSString *)channel start:(NSNumber *)startDate end:(NSNumber *)endDate includeTimeToken:(BOOL)shouldIncludeTimeToken withCompletion:(PNHistoryCompletionBlock)block

Parameters

channel

Name of the channel for hich events should be pulled out from storage.

startDate

Reference on time token for oldest event starting from which next should be returned events.

endDate

Reference on time token for latest event till which events should be pulled out.

shouldIncludeTimeToken

Whether event dates (time tokens) should be included in response or not.

block

History pull processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of history request operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: All ‘history’ API group methods allow to fetch up to \b 100 events at once. If in specified time frame there is more then 100 events paging may be required. For paging use last event time token from respone and some distant future date for next portion of events.

@code @endcode Extension to \c historyForChannel:start:end:withCompletion: and allow to specify whether event dates (time tokens) should be included in response or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; NSNumber startDate = @((unsigned long long)([[NSDate dateWithTimeIntervalSinceNow:-(6060)] timeIntervalSince1970]10000000)); NSNumber endDate = @((unsigned long long)([[NSDate date] timeIntervalSince1970]10000000)); [self.client historyForChannel:@“storage” start:startDate end:endDate includeTimeToken:YES withCompletion:^(PNHistoryResult result, PNErrorStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded history using: 
    //   result.data.start - oldest message time stamp in response
    //   result.data.end - newest message time stamp in response
    //   result.data.messages - list of dictionaries. Each entry will include two keys: 
    //                          "message" - for body and "timetoken" for date when message has
    //                          been sent.
 }
 // Request processing failed.
 else {

    // Handle message history download error. Check 'category' property to find out possible 
    // issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+History.h

– historyForChannel:start:end:limit:includeTimeToken:withCompletion:

Allow to fetch events from specified \c channel’s history within specified time frame.

- (void)historyForChannel:(NSString *)channel start:(NSNumber *)startDate end:(NSNumber *)endDate limit:(NSUInteger)limit includeTimeToken:(BOOL)shouldIncludeTimeToken withCompletion:(PNHistoryCompletionBlock)block

Parameters

channel

Name of the channel for hich events should be pulled out from storage.

startDate

Reference on time token for oldest event starting from which next should be returned events.

endDate

Reference on time token for latest event till which events should be pulled out.

limit

Maximum number of events which should be returned in response (not more then \b 100).

shouldIncludeTimeToken

Whether event dates (time tokens) should be included in response or not.

block

History pull processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of history request operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: All ‘history’ API group methods allow to fetch up to \b 100 events at once. If in specified time frame there is more then 100 events paging may be required. For paging use last event time token from respone and some distant future date for next portion of events.

@code @endcode Extension to \c historyForChannel:start:end:includeTimeToken:withCompletion: and allow to specify maximum number of events which should be returned with response, but not more then \b 100.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; NSNumber startDate = @((unsigned long long)([[NSDate dateWithTimeIntervalSinceNow:-(6060)] timeIntervalSince1970]10000000)); NSNumber endDate = @((unsigned long long)([[NSDate date] timeIntervalSince1970]10000000)); [self.client historyForChannel:@“storage” start:startDate end:endDate limit:35 includeTimeToken:YES withCompletion:^(PNHistoryResult result, PNErrorStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded history using: 
    //   result.data.start - oldest message time stamp in response
    //   result.data.end - newest message time stamp in response
    //   result.data.messages - list of dictionaries. Each entry will include two keys: 
    //                          "message" - for body and "timetoken" for date when message has
    //                          been sent.
 }
 // Request processing failed.
 else {

    // Handle message history download error. Check 'category' property to find out possible 
    // issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+History.h

– historyForChannel:start:end:limit:reverse:withCompletion:

Allow to fetch events from specified \c channel’s history within specified time frame.

- (void)historyForChannel:(NSString *)channel start:(NSNumber *)startDate end:(NSNumber *)endDate limit:(NSUInteger)limit reverse:(BOOL)shouldReverseOrder withCompletion:(PNHistoryCompletionBlock)block

Parameters

channel

Name of the channel for hich events should be pulled out from storage.

startDate

Reference on time token for oldest event starting from which next should be returned events.

endDate

Reference on time token for latest event till which events should be pulled out.

limit

Maximum number of events which should be returned in response (not more then \b 100).

shouldReverseOrder

Whether events order in response should be reversed or not.

block

History pull processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of history request operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: All ‘history’ API group methods allow to fetch up to \b 100 events at once. If in specified time frame there is more then 100 events paging may be required. For paging use last event time token from respone and some distant future date for next portion of events.

@code @endcode Extension to \c historyForChannel:start:end:limit:withCompletion: and allow to specify whether events order in response should be reversed or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; NSNumber startDate = @((unsigned long long)([[NSDate dateWithTimeIntervalSinceNow:-(6060)] timeIntervalSince1970]10000000)); NSNumber endDate = @((unsigned long long)([[NSDate date] timeIntervalSince1970]10000000)); [self.client historyForChannel:@“storage” start:startDate end:endDate limit:35 reverse:YES withCompletion:^(PNHistoryResult result, PNErrorStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded history using: 
    //   result.data.start - oldest message time stamp in response
    //   result.data.end - newest message time stamp in response
    //   result.data.messages - list of messages
 }
 // Request processing failed.
 else {

    // Handle message history download error. Check 'category' property to find out possible 
    // issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+History.h

– historyForChannel:start:end:limit:reverse:includeTimeToken:withCompletion:

Allow to fetch events from specified \c channel’s history within specified time frame.

- (void)historyForChannel:(NSString *)channel start:(NSNumber *)startDate end:(NSNumber *)endDate limit:(NSUInteger)limit reverse:(BOOL)shouldReverseOrder includeTimeToken:(BOOL)shouldIncludeTimeToken withCompletion:(PNHistoryCompletionBlock)block

Parameters

channel

Name of the channel for hich events should be pulled out from storage.

startDate

Reference on time token for oldest event starting from which next should be returned events.

endDate

Reference on time token for latest event till which events should be pulled out.

limit

Maximum number of events which should be returned in response (not more then \b 100).

shouldReverseOrder

Whether events order in response should be reversed or not.

shouldIncludeTimeToken

Whether event dates (time tokens) should be included in response or not.

block

History pull processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of history request operation; \c status - in case if error occurred during request processing.

Availability

4.0

Discussion

Note: All ‘history’ API group methods allow to fetch up to \b 100 events at once. If in specified time frame there is more then 100 events paging may be required. For paging use last event time token from respone and some distant future date for next portion of events.

@code @endcode Extension to \c historyForChannel:start:end:limit:reverse:withCompletion: and allow to specify whether events order in response should be reversed or not.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; NSNumber startDate = @((unsigned long long)([[NSDate dateWithTimeIntervalSinceNow:-(6060)] timeIntervalSince1970]10000000)); NSNumber endDate = @((unsigned long long)([[NSDate date] timeIntervalSince1970]10000000)); [self.client historyForChannel:@“storage” start:startDate end:endDate limit:35 reverse:YES includeTimeToken:YES withCompletion:^(PNHistoryResult result, PNErrorStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle downloaded history using: 
    //   result.data.start - oldest message time stamp in response
    //   result.data.end - newest message time stamp in response
    //   result.data.messages - list of dictionaries. Each entry will include two keys: 
    //                          "message" - for body and "timetoken" for date when message has
    //                          been sent.
 }
 // Request processing failed.
 else {

    // Handle message history download error. Check 'category' property to find out possible 
    // issue because of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+History.h

Subscribe Methods

– channels

List of channels on which client subscribed now.

- (NSArray *)channels

Return Value

\a NSArray of channel names on which client subscribed at this moment.

Availability

4.0

Declared In

PubNub+Subscribe.h

– channelGroups

List of channels group on which client subscribed now.

- (NSArray *)channelGroups

Return Value

\a NSArray of channel group names on which client subscribed at this moment.

Availability

4.0

Declared In

PubNub+Subscribe.h

– presenceChannels

List of channels for which presence events observation has been enabled.

- (NSArray *)presenceChannels

Return Value

\a NSArray of presence channel names on which client subscribed at this moment.

Availability

4.0

Declared In

PubNub+Subscribe.h

– isSubscribedOn:

Check whether \b PubNub client currently subscribed on specified data object or not.

- (BOOL)isSubscribedOn:(NSString *)name

Parameters

name

Reference on name of data object against which check should be performed.

Return Value

\c YES in case if client currently subscribed to specified data object.

Availability

4.0

Declared In

PubNub+Subscribe.h

– addListener:

Add observer which conform to \b PNObjectEventListener protocol and would like to receive updates based on live feed events and status change.

- (void)addListener:(id<PNObjectEventListener>)listener

Parameters

listener

Listener which would like to receive updates.

Availability

4.0

Discussion

Listener can implement only required callbacks from \b PNObjectEventListener protocol and called only when desired type of event arrive.

Declared In

PubNub+Subscribe.h

– removeListener:

Remove listener from list for callback calls.

- (void)removeListener:(id<PNObjectEventListener>)listener

Parameters

listener

Listener which doesn’t want to receive updates anymore.

Availability

4.0

Discussion

When listener not interested in live feed updates it can remove itself from updates list using this method.

Declared In

PubNub+Subscribe.h

– subscribeToChannels:withPresence:

Try subscribe on specified set of channels.

- (void)subscribeToChannels:(NSArray *)channels withPresence:(BOOL)shouldObservePresence

Parameters

channels

List of channel names on which client should try to subscribe.

shouldObservePresence

Whether presence observation should be enabled for \c channels or not.

Availability

4.0

Discussion

Using subscribe API client is able to subscribe of remote data objects live feed and listen for new events from them.

@code @endcode \b Example:

@code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client subscribeToChannels:@[@“swift”] withPresence:YES]; @endcode

Declared In

PubNub+Subscribe.h

– subscribeToChannels:withPresence:clientState:

Try subscribe on specified set of channels.

- (void)subscribeToChannels:(NSArray *)channels withPresence:(BOOL)shouldObservePresence clientState:(NSDictionary *)state

Parameters

channels

List of channel names on which client should try to subscribe.

shouldObservePresence

Whether presence observation should be enabled for \c channels or not.

state

Reference on dictionary which stores key-value pairs based on channel name and value which should be assigned to it.

Availability

4.0

Discussion

Using subscribe API client is able to subscribe of remote data objects live feed and listen for new events from them. @code @endcode Extension to \c -subscribeToChannels:withPresence: and allow to specify client state information which should be passed to \b PubNub service along with subscription.

@code @endcode \b Example:

@code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client subscribeToChannels:@[@“swift”] withPresence:YES clientState:@{@“swift”: @{@“Type”: @“Developer”}}]; @endcode

Declared In

PubNub+Subscribe.h

– subscribeToChannelGroups:withPresence:

Try subscribe on specified set of channel groups.

- (void)subscribeToChannelGroups:(NSArray *)groups withPresence:(BOOL)shouldObservePresence

Parameters

groups

List of channel group names on which client should try to subscribe.

shouldObservePresence

Whether presence observation should be enabled for \c groups or not.

Availability

4.0

Discussion

Using subscribe API client is able to subscribe of remote data objects live feed and listen for new events from them.

@code @endcode \b Example:

@code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client subscribeToChannelGroups:@[@“developers”] withPresence:YES]; @endcode

Declared In

PubNub+Subscribe.h

– subscribeToChannelGroups:withPresence:clientState:

Try subscribe on specified set of channel groups.

- (void)subscribeToChannelGroups:(NSArray *)groups withPresence:(BOOL)shouldObservePresence clientState:(NSDictionary *)state

Parameters

groups

List of channel group names on which client should try to subscribe.

shouldObservePresence

Whether presence observation should be enabled for \c groups or not.

state

Reference on dictionary which stores key-value pairs based on channel group name and value which should be assigned to it.

Availability

4.0

Discussion

Using subscribe API client is able to subscribe of remote data objects live feed and listen for new events from them. @code @endcode Extension to \c -subscribeToChannelGroups:withPresence: and allow to specify client state information which should be passed to \b PubNub service along with subscription.

@code @endcode \b Example:

@code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client subscribeToChannelGroups:@[@“developers”] withPresence:YES clientState:@{@“developers”: @{@“Name”: @“Bob”}}]; @endcode

Declared In

PubNub+Subscribe.h

– subscribeToPresenceChannels:

Enable presence observation on specified \c channels.

- (void)subscribeToPresenceChannels:(NSArray *)channels

Parameters

channels

List of channel names for which client should try to subscribe on presence observing channels.

Availability

4.0

Discussion

Using this API client will be able to observe for presence events which is pushed to remote data objects.

@code @endcode \b Example:

@code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client subscribeToPresenceChannels:@[@“swift-pnpres”]]; @endcode

Declared In

PubNub+Subscribe.h

– unsubscribeFromChannels:withPresence:

Unsubscribe/leave from specified set of channels.

- (void)unsubscribeFromChannels:(NSArray *)channels withPresence:(BOOL)shouldObservePresence

Parameters

channels

List of channel names from which client should try to unsubscribe.

shouldObservePresence

Whether client should disable presence observation on specified channels or keep listening for presence event on them.

Availability

4.0

Discussion

Using this API client will push leave presence event on specified \c channels and if it will be required it will re-subscribe on rest of the channels.

@code @endcode \b Example:

@code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client unsubscribeFromChannels:@[@“objc”] withPresence:YES]; @endcode

Declared In

PubNub+Subscribe.h

– unsubscribeFromChannelGroups:withPresence:

Unsubscribe/leave from specified set of channel groups.

- (void)unsubscribeFromChannelGroups:(NSArray *)groups withPresence:(BOOL)shouldObservePresence

Parameters

groups

List of channel group names from which client should try to unsubscribe.

shouldObservePresence

Whether client should disable presence observation on specified channel groups or keep listening for presence event on them.

Availability

4.0

Discussion

Using this API client will push leave presence event on specified \c groups. In this case leave event will be pushed to all channels which is part of \c groups. If it will be required it will re-subscribe on rest of the channels.

@code @endcode \b Example:

@code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client unsubscribeFromChannelGroups:@[@“developers”] withPresence:YES]; @endcode

Declared In

PubNub+Subscribe.h

– unsubscribeFromPresenceChannels:

Disable presence events observation on specified channels.

- (void)unsubscribeFromPresenceChannels:(NSArray *)channels

Parameters

channels

List of channel names for which client should try to unsubscribe from presence observing channels

Availability

4.0

Discussion

This API allow to stop presence observation on specified set of channels.

@code @endcode \b Example:

@code PNConfiguration *configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client unsubscribeFromPresenceChannels:@[@“swifty-pnpres”]]; @endcode

Declared In

PubNub+Subscribe.h

APNS Methods

– addPushNotificationsOnChannels:withDevicePushToken:andCompletion:

Enabled push notifications on provided set of \c channels.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client addPushNotificationsOnChannels:@[@“wwdc”,@“google.io”] withDevicePushToken:self.devicePushToken andCompletion:^(PNAcknowledgmentStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle successful push notification enabling on passed channels.
 }
 // Request processing failed.
 else {

    // Handle modification error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)addPushNotificationsOnChannels:(NSArray *)channels withDevicePushToken:(NSData *)pushToken andCompletion:(PNPushNotificationsStateModificationCompletionBlock)block

Parameters

channels

List of channel names for which push notifications should be enabled.

pushToken

Device push token which should be used to enabled push notifications on specified set of channels.

block

Push notifications addition on channels processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Declared In

PubNub+APNS.h

– removePushNotificationsFromChannels:withDevicePushToken:andCompletion:

Disable push notifications on provided set of \c channels.

- (void)removePushNotificationsFromChannels:(NSArray *)channels withDevicePushToken:(NSData *)pushToken andCompletion:(PNPushNotificationsStateModificationCompletionBlock)block

Parameters

channels

List of channel names for which push notifications should be disabled.

pushToken

Device push token which should be used to disable push notifications on specified set of channels.

block

Push notifications removal from channels processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Discussion

Warning: If \c nil will be passed as \c channels then client will remove push notifications from all channels which associated with \c pushToken.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client removePushNotificationsFromChannels:@[@“wwdc”,@“google.io”] withDevicePushToken:self.devicePushToken andCompletion:^(PNAcknowledgmentStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle successful push notification enabling on passed channels.
 }
 // Request processing failed.
 else {

    // Handle modification error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

Declared In

PubNub+APNS.h

– removeAllPushNotificationsFromDeviceWithPushToken:andCompletion:

Disable push notifications from all channels which is registered with specified \c pushToken.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client removeAllPushNotificationsFromDeviceWithPushToken:self.devicePushToken andCompletion:^(PNAcknowledgmentStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

    // Handle successful push notification disabling for all channels associated with specified
    // device push token.
 }
 // Request processing failed.
 else {

    // Handle modification error. Check 'category' property to find out possible issue because
    // of which request did fail.
    //
    // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)removeAllPushNotificationsFromDeviceWithPushToken:(NSData *)pushToken andCompletion:(PNPushNotificationsStateModificationCompletionBlock)block

Parameters

pushToken

Device push token which should be used to disable push notifications on specified set of channels.

block

Push notifications removal from device processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Declared In

PubNub+APNS.h

State Methods

– setState:forUUID:onChannel:withCompletion:

Modify state information for \c uuid on specified remote data object (channel or channel group).

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client setState:@{@“state”:@“online”} forUUID:self.client.uuid onChannel:@“chat” withCompletion:^(PNClientStateUpdateStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Client state successfully modified on specified channel.
 }
 // Request processing failed.
 else {

     // Handle client state modification error. Check 'category' property to find out possible
     // issue because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)setState:(NSDictionary *)state forUUID:(NSString *)uuid onChannel:(NSString *)channel withCompletion:(PNSetStateCompletionBlock)block

Parameters

state

Reference on dictionary which should be bound to \c uuid on specified channel.

uuid

Reference on unique user identifier for which state should be bound.

channel

Name of the channel which will store provided state information for \c uuid.

block

State modification for user on cahnnel processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Declared In

PubNub+State.h

– setState:forUUID:onChannelGroup:withCompletion:

Modify state information for \c uuid on specified channel group.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client setState:@{@“announcement”:@“New red is blue”} forUUID:self.client.uuid onChannelGroup:@“system” withCompletion:^(PNClientStateUpdateStatus status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Client state successfully modified on specified channel group.
 }
 // Request processing failed.
 else {

     // Handle client state modification error. Check 'category' property to find out possible
     // issue because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)setState:(NSDictionary *)state forUUID:(NSString *)uuid onChannelGroup:(NSString *)group withCompletion:(PNSetStateCompletionBlock)block

Parameters

state

Reference on dictionary which should be bound to \c uuid on channel group.

uuid

Reference on unique user identifier for which state should be bound.

group

Name of channel group which will store provided state information for \c uuid.

block

State modification for user on cahnnel processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Declared In

PubNub+State.h

– stateForUUID:onChannel:withCompletion:

Retrieve state information for \c uuid on specified channel.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client stateForUUID:self.client.uuid onChannel:@“chat” withCompletion:^(PNChannelClientStateResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Handle downloaded state information using: result.data.state
 }
 // Request processing failed.
 else {

     // Handle client state audit error. Check 'category' property to find out possible
     // issue because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)stateForUUID:(NSString *)uuid onChannel:(NSString *)channel withCompletion:(PNChannelStateCompletionBlock)block

Parameters

uuid

Reference on unique user identifier for which state should be retrieved.

channel

Name of channel from which state information for \c uuid will be pulled out.

block

State audition for user on cahnnel processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of client state retrieve operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+State.h

– stateForUUID:onChannelGroup:withCompletion:

Retrieve state information for \c uuid on specified channel group.

@code @endcode \b Example:

@code // Client configuration. PNConfiguration configuration = [PNConfiguration configurationWithPublishKey:@“demo” subscribeKey:@“demo”]; self.client = [PubNub clientWithConfiguration:configuration]; [self.client stateForUUID:self.client.uuid onChannelGroup:@“system” withCompletion:^(PNChannelGroupClientStateResult result, PNErrorStatus *status) {

 // Check whether request successfully completed or not.
 if (!status.isError) {

     // Handle downloaded state information using: result.data.channels 
     // Each channel entry contain state as value.
 }
 // Request processing failed.
 else {

     // Handle client state audit error. Check 'category' property to find out possible
     // issue because of which request did fail.
     //
     // Request can be resend using: [status retry];
 }

}]; @endcode

- (void)stateForUUID:(NSString *)uuid onChannelGroup:(NSString *)group withCompletion:(PNChannelGroupStateCompletionBlock)block

Parameters

uuid

Reference on unique user identifier for which state should be retrieved.

group

Name of channel group from which state information for \c uuid will be pulled out.

block

State audition for user on cahnnel group processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of client state retrieve operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+State.h

StateProtected Methods

– setState:forUUID:onChannel:withName:withCompletion:

Modify state information for \c uuid on specified remote data object.

- (void)setState:(NSDictionary *)state forUUID:(NSString *)uuid onChannel:(BOOL)onChannel withName:(NSString *)object withCompletion:(PNSetStateCompletionBlock)block

Parameters

state

Reference on dictionary which should be bound to \c uuid on remote data object.

uuid

Reference on unique user identifier for which state should be bound.

onChannel

Whether state has been provided for channel or channel group.

object

Name of remote data object which will store provided state information for \c uuid.

block

State modification for user on cahnnel processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Declared In

PubNub+State.m

– stateForUUID:onChannel:withName:withCompletion:

Retrieve state information for \c uuid on specified remote data object.

- (void)stateForUUID:(NSString *)uuid onChannel:(BOOL)onChannel withName:(NSString *)object withCompletion:(id)block

Parameters

uuid

Reference on unique user identifier for which state should be retrieved.

onChannel

Whether state has been provided for channel or channel group.

object

Name of remote data object from which state information for \c uuid will be pulled out.

block

State audition for user on remote data object processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of client state retrieve operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+State.m

– handleSetStateStatus:forUUID:atObject:withCompletion:

Process client state modification request completion and notify observers about results.

- (void)handleSetStateStatus:(PNClientStateUpdateStatus *)status forUUID:(NSString *)uuid atObject:(NSString *)object withCompletion:(PNSetStateCompletionBlock)block

Parameters

status

Reference on state modification status instance.

uuid

Reference on unique user identifier for which state should be updated.

object

Name of remote data object for which state information for \c uuid had been bound.

block

State modification for user on cahnnel processing completion block which pass only one argument - request processing status to report about how data pushing was successful or not.

Availability

4.0

Declared In

PubNub+State.m

– handleStateResult:withStatus:forUUID:atChannel:object:withCompletion:

Process client state audition request completion and notify observers about results.

- (void)handleStateResult:(PNChannelClientStateResult *)result withStatus:(PNStatus *)status forUUID:(NSString *)uuid atChannel:(BOOL)isChannel object:(NSString *)object withCompletion:(id)block

Parameters

result

Reference on service response results instance.

status

Reference on state request status instance.

uuid

Reference on unique user identifier for which state should be retrieved.

isChannel

Whether received state information for channel or not.

object

Name of remote data object from which state information for \c uuid will be pulled out.

block

State audition for user on cahnnel processing completion block which pass two arguments: \c result - in case of successful request processing \c data field will contain results of client state retrieve operation; \c status - in case if error occurred during request processing.

Availability

4.0

Declared In

PubNub+State.m