Table of Contents
Just a second...

Using the iOS Classic API

There are features, issues, and considerations that are specific to clients that are implemented using the iOS® Classic API.

Diffusion™ Delegate

The Diffusion Delegate class is a custom class that must adhere to the DFClientDelegate protocol. The protocol consists of the following methods

/**
 Protocol implemented by classes wishing to receive notifications.
 Notification primarily of new messages and the state of the connection to the server.
 */
@protocol DFClientDelegate

/**
 * This method is called when the DFClient tries to connect, if the connection is made, isConnected is true
 * @param isConnected
 */
- (void) onConnection:(BOOL) isConnected;

/**
 * This method is called when the DFClient has lost connection
 */
- (void) onLostConnection;

/**
 * This method is called when the Diffusion server has terminated the connection (barred)
 */
- (void) onAbort;

/**
 * This method is called when a message has been received from the Diffusion server.
 * This method is called as well as any topicListeners that might match the topic.
 */
- (void) onMessage:(DFTopicMessage *) message;

/**
 * This method is called on receipt of the ping request
 * @see DFClient
 * @param message PingMessage
 */
- (void) onPing:(DFPingMessage *) message;

/**
 * This method is called after a send credentials message, and the server rejected the credentials
 * @see DFClient
 */
- (void) onServerRejectedConnection;

/**
 * This method is called if the server did not respond to an Ack message in time
 * @see TopicMessage
 */
- (void) onMessageNotAcknowledged:(DFTopicMessage *) message;

/**
 The list of DFServerDetails object has been exhausted, and no connection can be placed.
 Once this method is called the set of DFServerDetails is reset and further connections can be placed. In most simple scenarios where
 there is only one DFServerDetails object in the DFConnectionDetails object call method [client connect] here.
 @param client DFClient that has exhausted its set of DFServerDetails object from the DFClientDetails object.
 */
-(void)onConnectionSequenceExhausted:(DFClient*)client;

@optional

/**
 Conveys news from the Diffusion server that the named topic no longer exists
 */
-(void)onTopicRemoved:(NSString*) topicName;

/**
 The given DFServerDetails object has been selected for connection.
 @param details Details object that has been chosen.
 @param client DFClient that has chosen this DFServerDetails
 */
-(void)onConnectionDetailsAcquired:(DFServerDetails*)details forClient:(DFClient*)client;

You can receive an onConnection event after you have successfully connected, this might be because of a lost connection.

Credentials

When credentials are required, use the credentials property on the DFClient class. Create a DFCredentials class and set it on the client before you call connect.

onMessage event

When messages arrive from the Diffusion server on a subscribed topic, the onMessage method is called on the delegate provided. The message is wrapped in a class called TopicMessage. This class contains helper methods that surround the message itself, such as the topic and isInitialLoad properties. For more information, see iOS Classic API documentation.

Subscriptions

Once the client has connected, you can issue subscribe and unsubscribe commands. The subscribe and unsubscribe methods take a string format, that can be a topic selection pattern, a list of topics that are comma delimited, or a single topic.

Send

Once connected, you can send messages to the Diffusion server on a particular topic path. To do this, use the send method.

[mClient send:"Fred" :"Hello Fred"];

In the example above, the registered message handler for topic Fred receives a messageFromClient notification. If you want to send a message with user headers, use the sendTopicMessage method. A TopicMessage enables you to set user headers.

Ping

You can ping the Diffusion server. The delegate is notified by the onPing method. The resulting ping event has two attributes in it, firstly the time stamp of the request. The second attribute is how many items are currently in the client queue at the server. This information enables the client to get some vital connection information. It is down to the implementation of the client to specify the ping frequency, if at all required.

Topic listeners

During the lifetime of the connection, it might be required to have modular components notified about topic messages – these are topic listeners. A topic listener calls a supplied method with a TopicMessage class when the topic path of the message matches the topic name.

Note: For performance the iOS topic listeners do not have regular expression patterns but topic name matching.

You can have many topic listeners on the same topic pattern if required. For example, if you want to be notified about a particular topic, issue the following listener:

[mClient addTopicListener:aTopicListener];

Where a topic listener implements the protocol DFTopicListenerDelegate which is shown below.

/**
 Protocol for receiving messages from a particular topic.
 */
@protocol DFTopicListenerDelegate

/**
 * This method is called if the TopicMessage matches the message received from Diffusion
 *
 * @param message
 * @return YES if the message is consumed and must not be relayed to subsequent DFTopicListenerDelegate, nor the default listener.
 */
- (BOOL) onMessage:(DFTopicMessage *) message;

/**
 * This is the topic used to see if the message from Diffusion matches (equals) this String
 */
- (NSString *) getTopic;

Topic listeners can be removed by calling the removeTopicListener method on the DFClient class.