Quick Start

Connecting

A client session maintains a connection to the server. To create a session use one of the open methods on the PTDiffusionSession class:

    [PTDiffusionSession openWithURL:[NSURL URLWithString:@"ws://localhost"]
                  completionHandler:^(PTDiffusionSession * session, NSError * error)
    {
        if (session) {
            NSLog(@"Session Open.");
            self.session = session;
        } else {
            NSLog(@"Session Failed to Open with Error: %@", error);
        }
    }];

Your completion handler is called on the main dispatch queue. You must maintain a strong reference to the session instance for it to stay open, as in this example where we set the session property on self, which has been defined in our interface as follows:

@property PTDiffusionSession* session;

Subscribing to topics

Data in Diffusion is distributed on topics. A topic carries a single value, which can be updated. Each topic is addressed by a unique path.

The way that a session receives data is by using a subscription. These allow the session to select a particular topic, and register a delegate to handle that topic's data. A session may subscribe to many topics, as well as subscribe to the same topic multiple times.

A client session subscribes to receive topic updates using the Topics feature:

    [session.topics subscribeWithTopicSelectorExpression:@"*Assets//"
                                       completionHandler:^(NSError * error)
    {
        if (!error) {
            NSLog(@"Subscription Successful.");
        } else {
            NSLog(@"Failed to Subscribe with Error: %@", error);
        }
    }];

A delegate conforming to PTDiffusionTopicStreamDelegate needs to be supplied in order to handle the streaming updates once the Diffusion server has processed the subscription.

There are a couple of ways to supply this delegate but the simplest is to provide a fallback which will receive streaming updates for all topic streams which don't have an explicit delegate handler. Assuming that self declares its conformance to the topic stream delegate protocol then it can be added as a fallback at any time like this:

    [session.topics addFallbackTopicStreamWithDelegate:self];

An example conformant delegate protocol implementation would look like this:

-(void)diffusionStream:(PTDiffusionStream *)stream
    didUpdateTopicPath:(NSString *)topicPath
               content:(PTDiffusionContent *)content
               context:(PTDiffusionUpdateContext *)context
{
    NSLog(@"Update for Topic Path \"%@\", Content: %@", topicPath, content);
}

Delegate messages are sent on the main dispatch queue.

It is possible to register any number of topic streams to a subscription's update events. They will each have their delegates called when a new value is received.

Observing session state changes

Changes in session state are broadcast via the default notification center for the application process. They are posted on the main dispatch queue and can be observed in the standard manner:

    NSNotificationCenter * nc = [NSNotificationCenter defaultCenter];
    [nc addObserverForName:PTDiffusionSessionStateDidChangeNotification
                    object:session
                     queue:nil
                usingBlock:^(NSNotification * note)
    {
        PTDiffusionSessionStateChange * change = note.userInfo[PTDiffusionSessionStateChangeUserInfoKey];
        NSLog(@"Session State Change: %@", change);
    }];