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);
        }
    }];

Supply a delegate conforming to one of the PTDiffusionSubscriberStream subprotocols to handle the streaming updates once the Diffusion server has processed the subscription.

The simplest way to supply this delegate is to provide a fallback which will receive streaming updates for all topics compatible with a particular data type which don't have an explicit delegate handler assigned. For example, for the JSON data type, assuming that self declares its conformance to the JSON value stream delegate protocol then it can be added as a fallback at any time like this:

    PTDiffusionValueStream *const stream =
        [PTDiffusionJSON valueStreamWithDelegate:self];
    [session.topics addFallbackStream:stream];

An example conformant delegate protocol implementation would look like this:

- (void)    diffusionStream:(PTDiffusionStream *const)stream
    didSubscribeToTopicPath:(NSString *const)topicPath
              specification:(PTDiffusionTopicSpecification *const)specification {
    NSLog(@"Subscribed: %@", topicPath);
}

- (void)        diffusionStream:(PTDiffusionStream *const)stream
    didUnsubscribeFromTopicPath:(NSString *const)topicPath
                  specification:(PTDiffusionTopicSpecification *const)specification
                         reason:(const PTDiffusionTopicUnsubscriptionReason)reason {
    NSLog(@"Unsubscribed: %@", topicPath);
}

- (void)diffusionStream:(PTDiffusionValueStream *const)stream
     didUpdateTopicPath:(NSString *const)topicPath
          specification:(PTDiffusionTopicSpecification *const)specification
                oldJSON:(PTDiffusionJSON *const)oldJson
                newJSON:(PTDiffusionJSON *const)newJson {
    const id object = [newJson objectWithError:nil];
    NSLog(@"Update \"%@\": %@", topicPath, object);
}

- (void)diffusionDidCloseStream:(nonnull PTDiffusionStream *)stream {
    NSLog(@"Closed");
}

- (void)diffusionStream:(nonnull PTDiffusionStream *)stream
       didFailWithError:(nonnull NSError *)error {
    NSLog(@"Failed. Error: %@", error);
}

Delegate messages are sent on the main dispatch queue.

It is possible to register any number of value streams to a subscription's update events. New values are delivered to each stream's delegate.

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 *const note)
    {
        PTDiffusionSessionStateChange * change = note.userInfo[PTDiffusionSessionStateChangeUserInfoKey];
        NSLog(@"Session State Change: %@", change);
    }];