Table of Contents
Just a second...

Getting started with iOS Classic API

Create a client application within minutes that connects to the Diffusion™ server.

Ensure that the iOS® client libraries are available on your development system. The libraries are included in the Diffusion installation, which is available from the following location: Get the iOS libraries from the Diffusion installation. Install Diffusion and get the diffusion-iphoneos-classic-version.zip file from the clients/apple folder of the installation. For more information, see Installing the Diffusion server.
These instructions have been created using Xcode 6.0.1.
  1. Extract the contents of the diffusion-iphoneos-classic-version.zip file to your preferred location for third-party SDKs for use within Xcode.
    For example, you might have a directory within your Documents folder for code within which you have a sub-directory for software development kits (SDKs). In this case, locate the iOS software development kit (SDK) for Diffusion in the following directory: ~/Documents/code/SDKs/diffusion-iphoneos-classic-version/, where version is the version number, for example 5.9.4
  2. Create an Xcode project for your Diffusion client.
    1. From the File menu, select New > Project...
      Xcode prompts you to Choose a template for your new project.
    2. Select iOS > Application on the left.
    3. Select Single View Application on the right and click Next.
      Xcode prompts you to Choose options for your new project.
    4. Configure your project appropriately for your requirements.

      The Diffusion iOS Classic API does not work with Swift without additional code, so select Objective-C as the Language.

      For example, use the following values:
      • Product Name: TestClient
      • Language: Objective-C
      • Devices: Universal
    5. Click the Next button.
      Xcode prompts you to select a destination folder for your new project.
    6. Select a target folder. For example, ~/Documents/code/, and click Create.
  3. Import the Diffusion iOS SDK.
    Use the Xcode Build Settings to define the location of your Diffusion iOS SDK.
    1. Go to the Build Settings tab for the Project or Target.
    2. Click the plus sign (+) and select Add User-Defined Setting.
    3. Set the name of the user-defined setting to DIFFUSION_ROOT and the value to the top-level directory of your extracted Diffusion iOS SDK.
      We recommend that you use the Xcode SRCROOT property in order to provide a relative location. For example, $(SRCROOT)/../SDKs/diffusion-iphoneos-classic-version defines the location of the Diffusion iOS SDK as the directory given in step 1
    4. Go to the User Header Search Paths (USER_HEADER_SEARCH_PATHS) setting and add the following value: $(DIFFUSION_ROOT)/headers
      Use the default, non-recursive option.
    5. Go to the Library Search Paths (LIBRARY_SEARCH_PATHS) setting and add the following values:
      • Debug configuration: $(DIFFUSION_ROOT)/Debug-universal
      • Release configuration: $(DIFFUSION_ROOT)/Release-universal
      Use the default, non-recursive option.
    6. Go to the Other Linker Flags (OTHER_LDFLAGS) setting and add the following value:
      -lDiffusionTransport
  4. Add the required system libraries
    The Diffusion iOS SDK depends on Zlib and on ICU: International Components for Unicode. These libraries are not included with the linker requirements by default for new Xcode projects so you need to add them.
    1. Go to Target > Build Phases > Link Binary With Libraries
    2. Add libz.dylib
    3. Add libicucore.dylb
    The following libraries are included by default for new Xcode projects and are required by the Diffusion iOS SDK:
    • CFNetwork.framework
    • Foundation.framework
    • Security.framework
  5. Create a client that connects to the Diffusion server when the view controller loads. (ViewController.m)
    #import "ViewController.h"
    #import "diffusion.h"
    
    @interface ViewController (DFClientDelegate) <DFClientDelegate>
    @end
    
    @implementation ViewController
    {
        DFClient *_diffusionClient;
    }
    
    - (void)viewDidLoad
    {
        [super viewDidLoad];
    
        NSURL *const serverURL = [NSURL URLWithString:@"ws://diffusion.example.com:80"];
        DFServerDetails *const serverDetails = [[DFServerDetails alloc] initWithURL:serverURL error:nil];
        DFConnectionDetails *const connectionDetails = [[DFConnectionDetails alloc] initWithServer:serverDetails
                                                                                            topics:@"Assets/"
                                                                                    andCredentials:nil];
        _diffusionClient = [[DFClient alloc] init];
        _diffusionClient.delegate = self;
        [_diffusionClient setConnectionDetails:connectionDetails];
        [_diffusionClient connect];
    }
    
    @end
    
    @implementation ViewController (DFClientDelegate)
    
    -(void)onConnection:(const BOOL)isConnected
    {
        NSLog(@"Diffusion %@connected.", (isConnected ? @"" : @"NOT "));
    }
    
    -(void)onMessage:(DFTopicMessage *const)message
    {
        NSLog(@"Diffusion message: \"%@\" =\"%@\"", message.topic, message.records[0]);
    }
    
    // Implement other required methods
    -(void)onAbort { }
    -(void)onConnectionSequenceExhausted:(DFClient *const)client { }
    -(void)onLostConnection { }
    -(void)onMessageNotAcknowledged:(DFTopicMessage *const)message { }
    -(void)onPing:(DFPingMessage *const)message { }
    -(void)onServerRejectedConnection { }
    
    @end
    1. Import the diffusion.h header file.
      This file pulls in the other required header files.
    2. Conform to the DFClientDelegate protocol, using a category with the same name to enhance readability.
    3. In the viewDidLoad method, assign serverURL to point to the Diffusion server using the DPT protocol.
    4. Create a DFServerDetails object, serverDetails. Use the initWithURL method to wrap serverURL.
      Change the URL from that provided in the example to the URL of the Diffusion server.
    5. Create a DFConnectionDetails object, connectionDetails. Use the initWithServer method to include serverDetails. Request a default, recursive subscription to the Assets topic.
    6. Define a _diffusionClient instance variable.
    7. Assign self to the delegate property of _diffusionClient.
    8. Use the setConnectionDetails method to include connectionDetails.
    9. Use the connect method to connect _diffusionClient to the Diffusion server.
    10. Implement the DFClientDelegate category.
    11. In the DFClientDelegate implementation, implement onConnection: to perform the required actions when the client connects. For example, log that the connection was successful.
    12. In the DFClientDelegate implementation, implement onMessage: to perform the required actions when a message is received. For example, log the message content.
    13. In the DFClientDelegate implementation, implement the other required methods.
      • onAbort:
      • onConnectionSequenceExhausted:
      • onLostConnection:
      • onMessageNotAcknowledged:
      • onPing:
      • onServerRejectedConnection:

      These implementations can be empty.

The client connects to the Diffusion server. It receives a callback from the Diffusion iOS SDK though the onConnection: implementation. When connected the client receives topic messages (both for initial topic load and deltas) from the Diffusion iOS SDK through the onMessage: implementation.