Search Results

TIBCO eFTL Objective-C Quick Start

Quick Start Contents

Introduction

This quick start guide is intended to provide basic instructions for writing Objective-C applications for TIBCO eFTL. It focuses on a collection of sample applications included in the TIBCO eFTL Messaging SDK for Objective-C.

Getting Started

  • Download the TIBCO eFTL Messaging SDK for Objective-C. This guide will refer to your eFTL installation location as <eftl>.
  • Obtain a URL and authentication key from your TIBCO Cloud Messaging account.
  • In the sample application source files, replace the placeholders TIBCO-CLOUD-MESSAGING-URL and TIBCO-CLOUD-MESSAGING-KEY with your account URL and authentication key.

Building and running samples

Follow the steps below to build and run the samples:

  1. Open the eFTL iOS sample Xcode project.
  2. Add the eFTL Objective-C framework to the project
    • Drag the eFTL framework bundle from a Finder window into the project in the project navigator. Make sure Copy items if needed is checked otherwise the framework will not be properly added to the targets Framework search paths settings.
    • Or, alternatively, add the eFTL framework by choosing the menu options File > Add Files to <App Name> and selecting the eFTL framework bundle. It will be necessary to manually add the eFTL framework bundle location to the Framework Search Paths setting (for both debug and release) in the targets Build Settings > Search Paths settings.
  3. Build and run the eFTL iOS sample application.

Using the eFTL SDK

To use the eFTL Client Framework in your application code, import the eFTL headers:

#import <eFTL/eFTL.h>

Creating new applications

When creating a new eFTL iOS application, along with the inclusion of the eFTL framework bundle, the following steps are required to set up the proper dependencies and configuration for your project. These steps are already a part of the eFTL iOS sample Xcode projects:

  1. Add the required built-in frameworks to the project:
    • In the project navigator, select the project.
    • Click Build Phases at the top of the project editor.
    • Open the Link Binary With Libraries section.
    • Click the add (+) button to add a library or framework.
    • Enter the following library and frameworks in the search field, select and add: libicucore.tbd, CFNetwork.framework, Security.framework.
  2. Add the -ObjC value to the Other Linker Flags build setting.
    • In the project navigator, select the target.
    • Click the Build Setting tab and scroll down to the Linking section.
    • In Other Linker Flags add the value -ObjC.

Connect to TIBCO Cloud Messaging

To establish a connection to TIBCO Cloud Messaging, you need the URL and authentication key. Authentication keys can be obtained only from your TIBCO Cloud Messaging account page on the Authentication key tab. The eFTL client uses the URL to connect to the library. The authentication key is the password used by the eFTL client library to authenticate itself.

Client Identifiers

You must also provide a unique identifier for your client so that it can receive any missed messages while it is disconnected. Note: Client identifiers must be unique; no two clients with the same identifier can be connected simultaneously.

NSDictionary *props = @{
    eFTLPropertyClientId: @"abc123",
	eFTLPropertyPassword: @"6ee7639011dd67ac79272a0844c16671"
};

[eFTL connect:"wss://messaging.cloud.tibco.com/tcm/01BT0Q4Q3QMK65FBC80P1MDP5Q/channel" properties:props listener:self];

Connecting requires the eFTLConnectionListener protocol to be implemented.

// Invoked when a connection to the eFTL server is successful.
- (void)connectionDidConnect:(eFTLConnection *)connection {
			NSLog(@"connected");
}

// Invoked when reconnected to the eFTL server.
- (void)connectionDidReconnect:(eFTLConnection *)connection {
   NSLog(@"reconnected");
}

// Invoked when a connection to the eFTL server is unsuccessful or lost.
- (void)connection:(eFTLConnection *)connection didDisconnectWithCode:(NSInteger)code reason:(NSString *)reason { 
   NSLog(@"disconnected: %@", reason);
}

// Invoked when the eFTL server responds with an error.
- (void)connection:(eFTLConnection *) connection didFailWithCode:(NSInteger)code reason:(NSString *)reason {
   NSLog(@"error: %@", reason);
}

Connect callback

The connect callback is invoked after the connection to TIBCO Cloud Messaging is established. The Connection object passed to the connect callback can be used for subscribing to messages and publishing messages.

Disconnect callback

If the connection cannot be established, or is lost, the disconnect callback is invoked. The reconnect callback is invoked when the client successfully reconnects to TIBCO Cloud Messaging. The error callback is invoked when TIBCO Cloud Messaging sends an error to the client.

Publish Messages

After clients are connected to TIBCO Cloud Messaging, they can publish messages. To publish messages, use the connection returned in the connect callback.

// create a message
// Fields and arrays of type string, numeric, NSDate, and sub-messages are used in messages.
eFTLMessage *message = [eFTLMessage message]; 
[message setField:@"event" asString:@"hello"]; 
[message setField:@"text" asString:@"Hello, World!"]; 

// publish a message to TIBCO Cloud Messaging 
[connection publishMessage:message];

// To be notified if the publish was successful or if an error occurred, callbacks can be provided.
// publish a message to TIBCO Cloud Messaging [connection
publishMessage:message listener:self];

// This requires the eFTLCompletionListener protocol to be implemented.
// Invoked when the message was successfully published. 
- (void)messageDidComplete:(eFTLMessage *)message 
{ 
   NSLog(@"publish success"); 
} 

// Invoked when the message was unsuccessfully published. 
- (void)message:(eFTLMessage *)message didFailWithCode:(NSInteger)code reason:(NSString *)reason 
{
   NSLog(@"publish error: %@", reason); 
}

Receive Messages

After the clients are connected to TIBCO Cloud Messaging, they can create one or more subscriptions to receive messages of interest. You can subscribe to messages by matching on the message fields that are of your interest.

Use the connection returned in the connect callback to register subscriptions.

// create a subscription in TIBCO Cloud Messaging 
//
// this subscription matches all published messages that contain a 
// field named "event" with a value of "hello" 
// 
// this subscription also sets the durable name to "hello" which allows 
// the client to receive messages that were published while disconnected 
// 
[connection subscribeWithMatcher:@"{\"event\":\"hello\"}"
durable:@"hello" listener:self];
Subscribing requires the eFTLSubscriptionListener protocol to be implemented.

// Invoked when the subscription receives messages. 
- (void)didReceiveMessages:(NSArray *)messages { 
   for (id message in messages) { 
      NSLog(@"message received: %@", [message getStringField:@"text"]); 
   } 
} 

// Invoked when the subscription is successful. 
- (void)subscriptionDidSubscribe:(NSString *)subscription { 
   NSLog(@"subscribed"); 
} 
 
// Invoked when the subscription is unsuccessful. 
- (void)subscription:(NSString *)subscription didFailWithCode:(NSInteger)code reason:(NSString *)reason { 
   NSLog(@"subscription error: %@", reason); 
}

Matcher field

The matcher field specifies the messages that are to be received by matching the content in the messages. In this case, the subscription receives all published messages containing a field named “event” whose value is “hello”.

Durable field

The durable field is the unique subscription name used by TIBCO Cloud Messaging to store messages for the client when the client is not connected.

onMessage callback

The onMessage callback is invoked when the content of a published message matches the subscription’s matcher.

onError callback

The onError callback is invoked when an error occurs while registering the subscription, typically because of an invalid matcher or invalid durable.