PNSubscriber Class Reference

Inherits from NSObject
Declared in PNSubscriber.h

Overview

Track subscription and time token information. Subscriber manage recovery as well.

@author Sergey Mamontov

State Information and Manipulation

– allObjects

Retrieve list of all remote data objects names to which client subscriber at this moment.

- (NSArray *)allObjects

Return Value

Object names list.

Availability

4.0

Declared In

PNSubscriber.h

– channels

List of channels.

- (NSArray *)channels

Return Value

Return list of channels on which client subscribed at this moment.

Availability

4.0

Declared In

PNSubscriber.h

– channelGroups

List of channel groups.

- (NSArray *)channelGroups

Return Value

Return list of channel groups on which client subscribed at this moment.

Availability

4.0

Declared In

PNSubscriber.h

– presenceChannels

List of presence channels.

- (NSArray *)presenceChannels

Return Value

Return list of presence channels for which client observing for presence events.

Availability

4.0

Declared In

PNSubscriber.h

Initialization and Configuration

+ subscriberForClient:

Construct subscribe loop manager for concrete \b PubNub client.

+ (instancetype)subscriberForClient:(PubNub *)client

Parameters

client

Reference on client which will be weakly stored in subscriber.

Return Value

Configured and ready to use subscribe manager instance.

Availability

4.0

Declared In

PNSubscriber.h

– inheritStateFromSubscriber:

Copy specified subscriber’s state information.

- (void)inheritStateFromSubscriber:(PNSubscriber *)subscriber

Parameters

subscriber

Reference on subscriber whose information should be copied into receiver’s state objects.

Availability

4.0

Declared In

PNSubscriber.h

Subscription information modification

– addChannels:

Add new channels to the list at which client subscribed.

- (void)addChannels:(NSArray *)channels

Parameters

channels

List of channels which should be added to the list.

Availability

4.0

Declared In

PNSubscriber.h

– removeChannels:

Remove channels from the list on which client subscribed.

- (void)removeChannels:(NSArray *)channels

Parameters

channels

List of channels which should be removed from the list.

Availability

4.0

Declared In

PNSubscriber.h

– addChannelGroups:

Add new channel groups to the list at which client subscribed.

- (void)addChannelGroups:(NSArray *)groups

Parameters

groups

List of channel groups which should be added to the list.

Availability

4.0

Declared In

PNSubscriber.h

– removeChannelGroups:

Remove channel groups from the list on which client subscribed.

- (void)removeChannelGroups:(NSArray *)groups

Parameters

groups

List of channel groups which should be removed from the list.

Availability

4.0

Declared In

PNSubscriber.h

– addPresenceChannels:

Add new presence channels to the list at which client subscribed.

- (void)addPresenceChannels:(NSArray *)presenceChannels

Parameters

presenceChannels

List of presence channels which should be added to the list.

Availability

4.0

Declared In

PNSubscriber.h

– removePresenceChannels:

Remove presence channels from the list on which client subscribed.

- (void)removePresenceChannels:(NSArray *)presenceChannels

Parameters

presenceChannels

List of presence channels which should be removed from the list.

Availability

4.0

Declared In

PNSubscriber.h

Subscription

– subscribe:withState:completion:

Perform initial subscription with \b 0 timetoken.

- (void)subscribe:(BOOL)initialSubscribe withState:(NSDictionary *)state completion:(PNSubscriberCompletionBlock)block

Parameters

initialSubscribe

Stores whether client trying to subscriber using \b 0 time token and trigger all required presence notifications or not.

state

Reference on client state which should be bound to channels on which client has been subscribed or will subscribe now.

block

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

Availability

4.0

Discussion

Subscription with \b 0 timetoken “register” client in \b PubNub network and allow to receive live updates from remote data objects live feed.

Declared In

PNSubscriber.h

– restoreSubscriptionCycleIfRequiredWithCompletion:

Try restore subscription cycle by using \b 0 time token and if required try to catch up on previous subscribe time token (basing on user configuration).

- (void)restoreSubscriptionCycleIfRequiredWithCompletion:(PNSubscriberCompletionBlock)block

Parameters

block

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

Availability

4.0

Declared In

PNSubscriber.h

– continueSubscriptionCycleIfRequiredWithCompletion:

Continue subscription cycle using \c currentTimeToken value and channels, stored in cache.

- (void)continueSubscriptionCycleIfRequiredWithCompletion:(PNSubscriberCompletionBlock)block

Parameters

block

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

Availability

4.0

Declared In

PNSubscriber.h

– unsubscribeFrom:objects:completion:

Perform unsubscription operation.

- (void)unsubscribeFrom:(BOOL)channels objects:(NSArray *)objects completion:(PNSubscriberCompletionBlock)block

Parameters

channels

Whether unsubscribing from list of channels or channel groups.

objects

List of objects from which client should unsubscribe.

block

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

Availability

4.0

Discussion

If suitable objects has been passed, then client will ask \b PubNub presence service to trigger \c ‘leave’ presence events on passed objects.

Declared In

PNSubscriber.h

Extension Methods

  client

Weak reference on client for which subscribe manager manage subscribe loop.

@property (nonatomic, weak) PubNub *client

Availability

4.0

Declared In

PNSubscriber.m

  currentState

Stores reference on current subscriber state.

@property (nonatomic, assign) PNSubscriberState currentState

Availability

4.0

Declared In

PNSubscriber.m

  mayRequireSubscriptionRestore

Stores whether subscriber potentially should expect for subscription restore call or not.

@property (nonatomic, assign) BOOL mayRequireSubscriptionRestore

Availability

4.0

Discussion

In case if client tried to connect and failed or disconnected because of network issues this flag should be set to \c YES

Declared In

PNSubscriber.m

  channelsSet

Actual storage for list of channels on which client subscribed at this moment and listen for updates from live feeds.

@property (nonatomic, strong) NSMutableSet *channelsSet

Availability

4.0

Declared In

PNSubscriber.m

  channelGroupsSet

Actual storage for list of channel groups on which client subscribed at this moment and listen for updates from live feeds.

@property (nonatomic, strong) NSMutableSet *channelGroupsSet

Availability

4.0

Declared In

PNSubscriber.m

  presenceChannelsSet

Actual storage for list of presence channels on which client subscribed at this moment and listen for presence updates.

@property (nonatomic, strong) NSMutableSet *presenceChannelsSet

Availability

4.0

Declared In

PNSubscriber.m

  currentTimeToken

Reference on time token which is used for current subscribe loop iteration.

@property (nonatomic, strong) NSNumber *currentTimeToken

Availability

4.0

Discussion

\b 0 for initial subscription loop and non-zero for long-poll requests.

Declared In

PNSubscriber.m

  lastTimeToken

Reference on time token which has been used for previous subscribe loop iteration.

@property (nonatomic, strong) NSNumber *lastTimeToken

Availability

4.0

Discussion

\b 0 for initial subscription loop and non-zero for long-poll requests.

Declared In

PNSubscriber.m

  resourceAccessQueue

Stores reference on queue which is used to serialize access to shared subscriber information.

@property (nonatomic, strong) dispatch_queue_t resourceAccessQueue

Availability

4.0

Declared In

PNSubscriber.m

  retryTimer

Stores reference on GCD timer used to re-issue subscrbibe request.

@property (nonatomic, strong) dispatch_source_t retryTimer

Availability

4.0

Discussion

Timer activated in cases if previous subscribe loop failed with category type which can be temporary.

Declared In

PNSubscriber.m

– initForClient:

Initialize subscribe loop manager for concrete \b PubNub client.

- (instancetype)initForClient:(PubNub *)client

Parameters

client

Reference on client which will be weakly stored in subscriber.

Return Value

Initialized and ready to use subscribe manager instance.

Availability

4.0

Declared In

PNSubscriber.m

– updateStateTo:withStatus:

Update current subscriber state.

- (void)updateStateTo:(PNSubscriberState)state withStatus:(PNSubscribeStatus *)status

Parameters

state

New state from \b PNSubscriberState enum fields.

status

Reference on status object which should be passed along to listeners.

Availability

4.0

Discussion

If possible, state transition will be reported to the listeners.

Declared In

PNSubscriber.m

– startRetryTimer

Launch subscription retry timer.

- (void)startRetryTimer

Availability

4.0

Discussion

Launch timer with default 1 second interval after each subscribe attempt. In most of cases timer used to retry subscription after PubNub Access Manager denial because of client doesn’t has enough rights.

Declared In

PNSubscriber.m

– stopRetryTimer

Terminate previously launched subscription retry counter.

- (void)stopRetryTimer

Availability

4.0

Discussion

In case if another subscribe request from user client better to stop retry timer to eliminate race of conditions.

Declared In

PNSubscriber.m

– handleSubscriptionStatus:

Handle subscription status update.

- (void)handleSubscriptionStatus:(PNSubscribeStatus *)status

Parameters

status

Reference on status object which has been received from \b PubNub network.

Availability

4.0

Discussion

Depending on passed status category and whether it is error it will be sent for processing to corresponding methods.

Declared In

PNSubscriber.m

– handleSuccessSubscriptionStatus:

Process successful subscription status.

- (void)handleSuccessSubscriptionStatus:(PNSubscribeStatus *)status

Parameters

status

Reference on status object which has been received from \b PubNub network.

Availability

4.0

Discussion

Success can be called as result of initial subscription successful ACK response as well as long-poll response with events from remote data objects live feed.

Declared In

PNSubscriber.m

– handleFailedSubscriptionStatus:

Process failed subscription status.

- (void)handleFailedSubscriptionStatus:(PNSubscribeStatus *)status

Parameters

status

Reference on status object which has been received from \b PubNub network.

Availability

4.0

Discussion

Failure can be cause by Access Denied error, network issues or called when last subscribe request has been canceled (to execute new subscription for example).

Declared In

PNSubscriber.m

– handleSubscription:timeToken:

Handle subscription time token received from \b PubNub network.

- (void)handleSubscription:(BOOL)initialSubscription timeToken:(NSNumber *)timeToken

Parameters

initialSubscription

Whether subscription is initial or received time token on long-poll request.

timeToken

Reference on time token which has been received from \b PubNub nrtwork.

Availability

4.0

Declared In

PNSubscriber.m

– handleLiveFeedEvents:

Handle long-poll service response and deliver events to listeners if required.

- (void)handleLiveFeedEvents:(PNSubscribeStatus *)status

Parameters

status

Reference on status object which has been received from \b PubNub network.

Availability

4.0

Declared In

PNSubscriber.m

– handleNewMessage:

Process message which just has been received from \b PubNub service through live feed on which client subscribed at this moment.

- (void)handleNewMessage:(PNMessageResult *)data

Parameters

data

Reference on result data which hold information about request on which this response has been received and message itself.

Availability

4.0

Declared In

PNSubscriber.m

– handleNewPresenceEvent:

Process presence event which just has been receoved from \b PubNub service through presence live feeds on which client subscribed at this moment.

- (void)handleNewPresenceEvent:(PNPresenceEventResult *)data

Parameters

data

Reference on result data which hold information about request on which this response has been received and presence event itself.

Availability

4.0

Declared In

PNSubscriber.m

– subscribeRequestParametersWithState:

Compose request parameterts instance basing on current subscriber state.

- (PNRequestParameters *)subscribeRequestParametersWithState:(NSDictionary *)state

Parameters

state

Reference on merged client state which should be used in request.

Return Value

Configured and ready to use parameters instance.

Availability

4.0

Declared In

PNSubscriber.m

– appendSubscriberInformation:

Append subscriber information to status object.

- (void)appendSubscriberInformation:(PNStatus *)status

Parameters

status

Reference on status object which should be updated with subscriber information.

Availability

4.0

Declared In

PNSubscriber.m