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.
-
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
-
Create an Xcode project for your Diffusion client.
-
From the File menu, select New > Project...
Xcode prompts you to Choose a template for your new project.
- Select iOS > Application on the left.
-
Select Single View Application on the right and click
Next.
Xcode prompts you to Choose options for your new project.
-
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
-
Click the Next button.
Xcode prompts you to select a destination folder for your new project.
- Select a target folder. For example, ~/Documents/code/, and click Create.
-
From the File menu, select New > Project...
-
Import the Diffusion
iOS
SDK.
Use the Xcode Build Settings to define the location of your Diffusion iOS SDK.
- Go to the Build Settings tab for the Project or Target.
- Click the plus sign (+) and select Add User-Defined Setting.
-
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
-
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.
-
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. -
Go to the Other Linker Flags (OTHER_LDFLAGS) setting and add
the following value:
-lDiffusionTransport
-
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.
- Go to Target > Build Phases > Link Binary With Libraries
- Add libz.dylib
- 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
-
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
-
Import the diffusion.h header file.
This file pulls in the other required header files.
- Conform to the DFClientDelegate protocol, using a category with the same name to enhance readability.
- In the viewDidLoad method, assign serverURL to point to the Diffusion server using the DPT protocol.
-
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.
- Create a DFConnectionDetails object, connectionDetails. Use the initWithServer method to include serverDetails. Request a default, recursive subscription to the Assets topic.
- Define a _diffusionClient instance variable.
- Assign self to the delegate property of _diffusionClient.
- Use the setConnectionDetails method to include connectionDetails.
- Use the connect method to connect _diffusionClient to the Diffusion server.
- Implement the DFClientDelegate category.
- In the DFClientDelegate implementation, implement onConnection: to perform the required actions when the client connects. For example, log that the connection was successful.
- In the DFClientDelegate implementation, implement onMessage: to perform the required actions when a message is received. For example, log the message content.
-
In the DFClientDelegate implementation, implement the other
required methods.
- onAbort:
- onConnectionSequenceExhausted:
- onLostConnection:
- onMessageNotAcknowledged:
- onPing:
- onServerRejectedConnection:
These implementations can be empty.
-
Import the diffusion.h header file.