Cisco Conductor Client SDK Developer's Guide · Cisco Conductor Client SDK for Java is designed for...

OL-25913-01

Cisco Conductor Client SDK Developer's Guide

Please Read

Important

Please read this entire guide. If this guide provides installation or operation instructions, give particular attention to all safety statements included in this guide.

Notices

Trademark Acknowledgments

Cisco and the Cisco logo are trademarks or registered trademarks of Cisco and/or its affiliates in the U.S. and other countries. To view a list of Cisco trademarks, go to this URL: www.cisco.com/go/trademarks.

Third party trademarks mentioned are the property of their respective owners.

The use of the word partner does not imply a partnership relationship between Cisco and any other company. (1110R)

Publication Disclaimer

Cisco Systems, Inc. assumes no responsibility for errors or omissions that may appear in this publication. We reserve the right to change this publication at any time without notice. This document is not to be construed as conferring by implication, estoppel, or otherwise any license or right under any copyright or patent, whether or not the use of any information in this document employs an invention claimed in any existing or later issued patent.

Copyright

© 2012 Cisco and/or its affiliates. All rights reserved. Printed in the United States of America.

Information in this publication is subject to change without notice. No part of this publication may be reproduced or transmitted in any form, by photocopy, microfilm, xerography, or any other means, or incorporated into any information retrieval system, electronic or mechanical, for any purpose, without the express permission of Cisco Systems, Inc.

OL-25913-01 iii

Contents

About This Guide v

Chapter 1 Introduction 1

Overview ................................................................................................................................... 2 Develop Environment Requirements .................................................................................... 4 Develop Java Applications on Conductor Client SDK ....................................................... 7 Develop C/C++ Applications on Conductor Client SDK ................................................ 13 Develop Objective C Applications on Conductor Client SDK ........................................ 16

Chapter 2 Java API Specification 19

Software Architecture............................................................................................................ 20 Client APIs .............................................................................................................................. 21

Chapter 3 C/C++ API Specification 45

Software Architecture............................................................................................................ 46 Client SDK Basic Rules .......................................................................................................... 47 Client APIs .............................................................................................................................. 48

Chapter 4 Objective C API Specification 89

Software Architecture............................................................................................................ 90 Client APIs .............................................................................................................................. 91 Delegates ............................................................................................................................... 105

Chapter 5 Conductor Service Development on Android 111

Develop Environment Requirements ................................................................................ 112 Develop Conductor Service-Based Applications on Android Platform ...................... 113

Chapter 6 Customer Information 123

Appendix A Additional Information 125

Type Supported by Data binding in Client SDK ............................................................. 126 wsld 2java Script Usage ...................................................................................................... 127 Conductor-Defined Error Code/Error String .................................................................. 128 Classes Defined for Customized Filter Implementation ................................................ 129

Contents

iv OL-25913-01

About This Guide

OL-25913-01 v

About This Guide

Introduction

The Cisco Conductor Client SDK provides an integrated package for developers of client-based applications. This user guide also gives a simple overview of the architecture of the Cisco Conductor Client SDK.

Purpose

This guide describes how to develop applications based on the Cisco Conductor Client SDK.

Audience

This guide is intended for application programmers who develop applications for the Conductor Client.

Document Version

This is the first formal release of this document.

OL-25913-01 1

The Cisco Conductor Client SDK provides an integrated package to develop Extensible Messaging and Presence Protocol (XMPP) based applications. This chapter gives a simple overview of the architect of Cisco Conductor Client SDK and describes how to develop XMPP applications based on the Cisco Conductor Client SDK.

1 Chapter 1 Introduction

In This Chapter

Overview .................................................................................................. 2

Develop Environment Requirements .................................................. 4

Develop Java Applications on Conductor Client SDK ...................... 7

Develop C/C++ Applications on Conductor Client SDK ............... 13

Develop Objective C Applications on Conductor Client SDK ....... 16

Chapter 1 Introduction

2 OL-25913-01

Overview The Client SDK is a product aimed at the developers who design and write client application software for Conductor Services like Control Suite, Media Suite, and so on. The SDK defines a set of client APIs to encapsulate the complexity of the Conductor system, which makes the developers be able to design and implement a Conductor client application in a short time.

Relating to Conductor’s architecture, the client SDK consists of the following three layers: XMPP Stack, Conductor Client, and Service Clients.

Conductor Client APIs for C and Objective C implementation provide a set of APIs extended to third-party developers to develop client applications which could communicate with services that are hosted in the conductor cloud.

Overview

OL-25913-01 3

Conductor Client APIs libraries are to provide least special APIs for full use of conductor client. C-style API is easy to port to more platforms, such as IOS system. However, the Objective C version is implemented with a wrapper to provide IOS user-friendly APIs.

The API user does not care about the detailed stack of XMPP. It only needs to call some simple APIs to implement their functions.

Conductor client focuses on the following functions: Registration, login, Presence, Roster, Companion device, PubSub, and Message.


4 OL-25913-01

Develop Environment Requirements

For Java

Cisco Conductor Client SDK for Java is designed for Android platform XMPP application development. User should install Google Android SDK and all necessary plug-ins. In this chapter, we give the Android development environment installation and configuration simple summary.

1 Download and install Eclipse for java software package.

You can get Eclipse for java package from the link: http://www.eclipse.org/downloads/

You can choose download Windows version or Linux version, depending on your host development OS. Then you need to unzip the package and install it.

2 Download Google Android SDK package.

You can choose download Windows, Linux, or Mac versions from http://developer.android.com/sdk/index.html.

After you download it, you can extract it directly to disk. You do not need to install it.

3 Install Android Development Tools (ADT) Plugin.

Start Eclipse, then select Help > Install New Software....

Click Add, in the top-right corner.

In the Add Repository dialog that appears, enter "ADT Plugin" for the Name and the following URL for the Location: http://dl-ssl.google.com/android/eclipse/

Click OK

In the Available Software dialog, select the checkbox next to Developer Tools and click Next.

In the next window, you'll see a list of the tools to be downloaded. Click Next.

Read and accept the license agreements, then click Finish. (Note: If you get a security warning saying that the authenticity or validity of the software can't be established, click OK.)

When the installation completes, restart Eclipse.

4 Install Android SDK API and additional materials.

Develop Environment Requirements

OL-25913-01 5

Restart Eclipse, you will see an android SDK and AVD operation icon in menu bar:

Click the icon, you will see:

Click ‘Available packages’, you can get all available SDK API and samples, choose latest one or the one you want to install and update them.

Follow above 4 steps, you can easily setup your Google Android development environment and is ready for development Android application based on Cisco Conductor Client SDK API. For more details regarding Android development setup and configuration, you can refer to Google Android development official site: http://developer.android.com/sdk/index.html

For C/C++

Cisco Conductor Client SDK for C is designed for Linux platform XMPP application development. The install Linux build environment and client application should be built and running on Linux OS.

The libraries of Conductor Client SDK for C are built on Fedora release 10 (Cambridge), with Linux kernel version 2.6.27.5-117.fc10.i686.PAE, and gcc version 4.3.2 20081105 (Red Hat 4.3.2-7).


6 OL-25913-01

The libraries of Conductor Client SDK for C depend on the following libraries: libexpat.so and libresolv.so, use "yum" to install the libraries if it prompts they are not installed in the build environment.

For Objective C

Cisco Conductor Client SDK for Objective C is designed for IOS platform XMPP application development. User should install XCode (4.2 Recommended) build environment and client application should be built and run on Mac OS X (10.6 or above Recommended).

The libraries of Conductor Client SDK for Objective C are built on XCode Version 4.2 Build 4C104, with Mac OS X 10.6.8, and Apple LLVM compiler 3.0. The iOS version is 5.0 (9A5220p).

The libraries of Conductor Client SDK for Objective C depend on the following libraries: libz.dylib and libresolv.dylib.

Develop Java Applications on Conductor Client SDK

OL-25913-01 7


Cisco Conductor Client SDK so far provides such components to Conductor application developer as:

Login

Presence

Roster

PubSub

Message

RawIQ

All of them will be built and package into a jar file named conductorClientJavaAPI.jar.

Other necessary jar files for building Android Conductor client applications include:

smack.jar

smackx.jar

dnsjava-2.1.1.jar

microlog4android-1.0.0.jar

All of them are available from the release package.

The following table gives a short summary of the folders contained in the Client SDK API for Java release package.

Folder Content Description

document Conductor_SDK_for_Android_Development_Guide This guide.

lib axis.jar Conductor SDK package for Conductor service development on Android client.

wsdl4j-1.5.1.jar

commons-discovery-0.2.jar

jaxrpc.jar

conductorClientJavaAPI.jar Conductor SDK package for XMPP message API.

smack.jar

smackx.jar


8 OL-25913-01

dnsjava-2.1.1.jar

microlog4android-1.0.0.jar

sample

Sample projects

Realtime (XMPP) API sample code and Conductor service for Android client sample code.

bin wsdl2java.bat

Script to run wsdl2java tool for windows OS.

wsdl2java.sh Script to run wsdl2java tool for Linux & Mac OS.

Import and Run Sample Code

Sample code in release package gives simple and clear example to use Cisco Conductor Client SDK API.

Take ‘CdtExample.zip’ as example.

1 Unzip CdtExample.zip.

2 Start Eclipse IDE, and click File>New>Android Project. A submenu appears, as shown below:


OL-25913-01 9

3 Choose Create project from existing source and select the location of the unzipped sample project in step 1, then click Finish. From the file explorer, you can see the sample project.

4 Click the folder called lib and select all of the jar files in it, then right-click and choose Add to Build Path to add all jar packages into the building path.


10 OL-25913-01

5 To run the sample project, right-click the project name and choose Run

As>Android Application.

6 To get debug information, you can click Window>Open perspective>other>DDMS to open Android debug windows to see the Android device output.

Create Your Own Android Conductor Client Project

You can use sample project as a project template to create your own project. Normally, Conductor Client login API will be the first API you have to use. After you successfully login into XMPP server, you can use other Conductor APIs as list in the beginning of this chapter. For example, you can use presence API to send presence information to a specific buddy, receive buddy’s presence information. More details regarding Conductor Client SDK API, you could refer to Client SDK API Specification documentation.


OL-25913-01 11

Below code stanza is simple example to show us how to use Conductor Client SDK to login to XMPP server and send presence information and register buddy’s presence change notification:

package com.cisco.thirdwave.conductor.clientSDK.sample;

import com.cisco.thirdwave.conductor.clientSDK.CdtLog;

import com.cisco.thirdwave.conductor.clientSDK.misc.CdtMisc;

import com.cisco.thirdwave.conductor.clientSDK.presence.CdtPresence;

import

com.cisco.thirdwave.conductor.clientSDK.presence.CdtPresenceHandler;

import

com.cisco.thirdwave.conductor.clientSDK.presence.CdtPresenceInfo;

import

com.cisco.thirdwave.conductor.clientSDK.presence.CdtPresenceMode;

import android.app.Activity;

import android.os.Bundle;

public class Hello extends Activity {

@Override

public void onCreate(Bundle savedInstanceState)

{

super.onCreate(savedInstanceState);

setContentView(R.layout.main);

CdtMisc misc = new CdtMisc();

String serverName = "xmpp.com";

String serverIpAddress ="72.163.255.90";//"10.74.27.140";

int portNumber = 5222;

String userName = "test1";

String userPassword = "test1";

try

{

misc.login(serverName, serverIpAddress, portNumber,

userName, userPassword);

}

catch (Exception e)

{

e.printStackTrace();

}


12 OL-25913-01

while(true)

{

if(CdtMisc.connection.isConnected())

{

break;

}

}

String jid = "[email protected]";

String status = "hello world";

int priority = 1;

CdtPresence presence = new CdtPresence();

presence.sendPresence (jid,

status,priority,CdtPresenceMode.available);

presence.registerPresenceChangeNotify(new

CdtPresenceHandler()

{

@Override

public void presenceChangedNotify(CdtPresenceInfo

status)

{

if(status!=null)

{

CdtLog.d("presenceNotify: ", " received

roster presence change notification ##!");

CdtLog.d("", "====== received presence

information=====");

CdtLog.d("", " jid: %s",status.jid);

CdtLog.d("", "status: %s",status.status);

CdtLog.d("", " type: %s",status.type);

CdtLog.d("", " mode: %s",status.mode);

CdtLog.d("", "");

}

}

});

……

Develop C/C++ Applications on Conductor Client SDK

OL-25913-01 13


Cisco Conductor Client SDK so far provides such functions to Conductor application developers:

Login

Presence

Roster

PubSub

Message

RawIQ

All of them will be built and package into a tgz file named conductorClientCAPI.tgz.

Untar the package. The resource files are as follows:

Directory Resource file Description

include cdtclient_api.h Exported header file of Conductor Client APIs

Libraries, include structure and functions definition

lib libCdtClientAPI.a

libCdtClientAPI.so

libCdtClientStack.a

libCdtClientStack.so

libgloox.a

libgloox.so

Static library of client API layer

Dynamic library of client API layer

Static library of client stack layer

Dynamic library of client stack layer

Static library of XMPP stack layer

Dynamic library of client stack layer

example client_test.cpp

presence_example.cpp

rawiq_example.cpp

message_example.cpp

pubsub_example.cpp

roster_example.cpp

Makefile

test case sample file (presence, rawIQ, message, pubsub, roster)

Presence API use case sample file

RawIq API use case sample file

Message API use case sample file

Pubsub API use case sample file

Roster API use case sample file

Makefile sample file


14 OL-25913-01

Import and Run Sample Code

Sample code in release package gives simple and clear example to use Cisco Conductor Client SDK API.

It can use Eclipse with CDT(C/C++ Development Tooling) for build environment, please refer to http://www.eclipse.org/cdt/

In Eclipse, click File>New>Makefile Project with Existing Code to import sample codes to build example project. Then click build/run the example application under Eclipse.

Sample

Basic rules of calling sequence in client application

1 Register your callback functions

2 Call login API to do login

3 Execute your operations by calling the function APIs, such as send message, and so on.

Message part sample

#include "cdtclient_api.h"

#include <stdio.h>

#include <pthread.h>

#include <unistd.h>

void test_ConnectionChangeListenerCallback(const

CdtConnectionErrorType ConnectionStatusCode)

{

printf( " Test:connected: %d\n", ConnectionStatusCode );

}

void test_MessageListenerCallback(const char* JID, const char*

body, const char* subject)

{

printf( "\n From %s: %s\n", JID, body );

if(body)

{

CdtMessageSetChatState ( JID, CdtChatStateComposing);

CdtMessageSend ( JID, "How are you!", "" );

}

sleep(2);


OL-25913-01 15

CdtMessageSetChatState ( JID, CdtChatStatePaused);

}

void test_ChatStateChangeListenerCallback(const char* JID, const

CdtChatStateType state)

{

printf( "\n From %s: chatstate = %d\n", JID, state );

}

void test_sendMessage()

{

sleep(3);

printf("send\n");

CdtMessageSend ( "[email protected]/Tao-Lins-MacBook-Pro", "hello

world", "" );

}

int main( int /*argc*/, char** /*argv*/ )

{

//Register your callback functions

CdtMiscRegisterConnectionChangeListener (

test_ConnectionChangeListenerCallback);

CdtMessageRegisterReceiveListener ( "[email protected]/Tao-Lins-

MacBook-Pro" , test_MessageListenerCallback );

CdtMessageRegisterChatStateChangeListener ( "[email protected]/Tao-

Lins-MacBook-Pro" , test_ChatStateChangeListenerCallback );

//do login

CdtMiscLogin("xmpp.com", "", -1, "linta", "linta", "");

//execute operations

test_sendMessage();

return 0;

}


16 OL-25913-01

Develop Objective C Applications on Conductor Client SDK

Cisco Conductor Client SDK so far provides such functions to Conductor application developers:

Login

Presence

Roster

PubSub

Message

RawIQ

All of them will be built and package into a tgz file named conductorClientObjCAPI.tgz.

Untar the package. The resource files are as follows:

Directory Resource file Description

include

cAPIs cdtclient_api.h Exported header file of Conductor Client APIs

Libraries, include structure and functions definition

wrapper LoginController.h MessageController.h PresenceController.h PubsubController.h RawIQController.h RosterController.h XmppProxy.h

Objective wrapper header files, delegation definitions included.

lib

ConductorClientSDK

iphoneos libConductorClientSDK.a

Static library of client API layer for iOS device.

iphonesimulator

libConductorClientSDK.a

Static library of client API layer for iOS simulator.

ConductorClientSDKWrapper

iphoneos libConductorClientSDKWrapper.a

Static library of client API Objective C wrapper for iOS device.

iphonesimulator

libConductorClientSDKWrapper.a

Static library of client API Objective C wrapper for iOS simulator.

gloox iphoneos libgloox.a Static library of XMPP stack layer for iOS device.

iphonesi libgloox.a Static library of XMPP stack layer for iOS

Develop Objective C Applications on Conductor Client SDK

OL-25913-01 17

mulator simulator.

example

GetCapability UseClientSdkObjectiveLib.xcodeproj

A sample project to demo how to use capability related APIs.

sample2 sample2.xcodeproj A sample project to demo how to use Login APIs.

Run Sample Code

Go to example/sample2, double click file sample2.xcodeproj, XCode should open the sample project, choose iPhone simulator on the build profile, simple build and run, the project, you will get an app with Login feature. But it might not login correctly, as the XMPP server and jid/password is hard code in sample2AppDelegate.mm, please modify it as needed.

Sample

There are two ways to use conductor client SDK in iOS platform:

1 Directly use the c/c++ library.

Use gloox and ConductorClientSDK only, you will get a C style APIs and Callback registration functions.

2 Use objective c wrapper.

Use gloox, ConductorClientSDK and ConductorClientSDKWrapper, you will get an objective C style APIs as well as delegates which implement the callback mechanism.

Below we take use objective C wrapper as example to demonstrate how to use it.

Add Libraries

Copy library files to your project directoryd library to your project

Add some system libraries:

libz.dylib for zip compression

libresov.dylib for DNS address resolveter add system libraries,w we got all the libraries which client SDK needs.

Coding

Take login as the example to demonstrate how to use.


18 OL-25913-01

Add header file search directories in building settings.Change one of your source file *.m to *.mm to trigger the xcode compiler using cpp linker as the xmpp core stack is implemented in C++.

In your class header file, make the class comforted with LoginDelegate

In class implementation file, call the API you want to use and implement the delegate function.

Then compile and run, you will get an application with the login function.

OL-25913-01 19

This chapter contains the Conductor Client SDK API specification for Java (Android).

2 Chapter 2 Java API Specification

In This Chapter

Software Architecture .......................................................................... 20

Client APIs ............................................................................................. 21

Chapter 2 Java API Specification

20 OL-25913-01

Software Architecture The Client SDK is intended for developers who design and write client application software for Conductor Services such as Control Suite, Media Suite, and so on. The SDK defines a set of client APIs to encapsulate the complexity of the Conductor system, which lets the developers design and implement a Conductor client application in a short time.


Client APIs

OL-25913-01 21

Client APIs

Common Data Structure Definition 1 public class CdtResult

{

public CdtStatus status;

public String reason;

}

2 public enum CdtStatus

{ SUCCESSFUL,FAILED; }

Login/Logout

Login and logout APIs let the user log in to or log out of the XMPP server.

Package Name: com.cisco.thirdwave.conductor.clientSDK.misc

Class Name: CdtMisc

Methods:

public CdtMisc();

public void registerConnectionListener (CdtConnectionListener listener);

public void login (String serverName, String serverIpAddress, int portNumber, String userName, String userPassword) throws Exception;

public void login (String serverName, String serverIpAddress, int portNumber, String userName, String userPassword, String resource) throws Exception;

public void logout () throws Exception;

CdtMisc

Description

This is the constructor for the class CdtMisc.

Declaration

void CdtMisc ()


22 OL-25913-01

registerConnectionListener

Description

Lets a user register a method to register the callback function, which will be called when conductor client connects to or disconnects from a server.

Declaration

void registerConnectionListener (CdtConnectionListener listener)

Parameters

Para Name Type Direction Description

listener CdtConnectionChangeListener

In ConnectionChangeListener is an interface. Its definition is as shown below.

public interface CdtConnectionListener

{

public void connectionChanged (ConnectionStatusCode code);

}

Enum ConnectionStatusCode Constant Summary

SUCCESSFUL The connection has connected successfully to the server

CLOSED Notification that the connection was closed normally.

ERROR Notification that the connection was closed due to an exception.

login

Description

Allows the user to request to log in to a server.

Declaration

void login (String serverName, String serverIpAddress, int portNumber, String userName, String userPassword) throws Exception

void login (String serverName, String serverIpAddress, int portNumber, String userName, String userPassword, String resource) throws Exception

Parameters


serverName String In Name of the server where the user wants to register.

Client APIs

OL-25913-01 23

serverIpAddress String In IP address of the server where the user wants to register. This can be left blank if the device can recognize the server from the serverName.

portNumber int In The port number of server.

userName String In The user name.

userPassword String In The user Password.

resource String In The resource.

logout

Description

Allows the user to request to log out from a server.

Declaration

void logout () throws Exception

Presence

Presence APIs allow the user to get his buddies’ status, such as online/offline, current status, and so on.

Package Name

com.cisco.thirdwave.conductor.clientSDK.presence

Class Name

CdtPresence

Methods:

public void send (String jid, String status,int priority, CdtPresenceMode mode,CdtPresenceType type) throws Exception

public void registerPresenceChangeNotification(CdtPresenceHandler handler)

CdtPresence

Description

Constructor for class CdtPresence.

Declaration

public CdtPresence()


24 OL-25913-01

Parameters

No

send

Description

Send presence information to buddy.

Declaration

public void send (String jid, String status,int priority, CdtPresenceMode mode,CdtPresenceType type) throws Exception)

Parameters


jid String In If ‘jid’ is null, the presence will be broadcast to all rosters.

status String In Status string.

priority int In Normally an integer from -128 to 127.

mode CdtPresenceMode In Presence mode is defined in the table below.

type CdtPresenceType In Presence type is defined in the table below.

Note: This parameter is required.

Enum CdtPresenceMode Constant Summary

available Available (the default).

away Away.

chat Free to chat.

dnd Do not disturb.

xa Away for an extended period of time.

Enum CdtPresenceType Constant Summary

available The user is available to receive messages (default)

unavailable The user is unavailable to receive messages.

subscribe Request subscription to recipient's presence.

subscribed Grant subscription to sender's presence.

unsubscribe Request removal of subscription to sender's presence.

unsubscribed Grant removal of subscription to sender's presence.

Client APIs

OL-25913-01 25

error The presence packet contains an error message.

registerPresenceChangeNotification

Description

Calls the notification handler registered by this API whenever one of the user's buddies has a change to presence status.

Declaration

public void registerPresenceChangeNotification(CdtPresenceHandler handler)

Parameters


handler CdtPresenceHandler In CdtPresenceHandler is an interface. Its definition is as shown below.

public interface CdtPresenceHandler

{

public void presenceChangedNotify(CdtPresenceInfo info);

}

public class CdtPresenceInfo

{

public String jid;

public CdtPresenceType type;

public CdtPresenceMode mode;

public String status;

}

Example XMPP stanza:

Call > sendPresence (PresenceType.available, "setcurrentprogram 1", 1, PresenceMode.away)

<presence from="yonggang@socialtv_demo/[email protected]/Smack" id="OAht0-5" to="kip@socialtv_demo" >

<status>setcurrentprogram 1</status>

<show>away</show>

<priority>1</priority>

</presence>


26 OL-25913-01

Roster API

Roster is the user’s contact list, which generated by bidirectional presence subscription. It is usually used to display presence information of user’s contact list. When the user logs in, he will receive the roster by integrating the presence data he receives into a useful, familiar interface.

The roster can be used not only to store a flat list of contacts, but also to group into various categories. Roster groups are used to organize contacts in the user’s list . These roster groups are not exclusive and function more as flexible tags instead of exclusive buckets.

Package Name:

com.cisco.thirdwave.conductor.clientSDK.roster

Class Name:

CdtRoster

Methods:

public CdtResult addBuddy(String jid,String name,String[] groups)

public CdtResult deleteBuddy(String jid)

public CdtResult deleteBuddyfromGroup(String jid, String group)

public CdtResult moveRosterBetweenGroup(String jid, String srcGroup,String targetGroup)

public List<CdtRosterEntry> getBuddyList( )

public void registerRosterNotify(CdtRosterHandler handler)

CdtRoster

Description

Constructor for class CdtRoster.

Declaration

public CdtRoster();

Parameters

No

addBuddy

Description

Add one more buddy to buddy list and groups.

Client APIs

OL-25913-01 27

Declaration

public CdtResult addBuddy(String jid,String name,String[] groups)

Parameters


jid String In The buddy jid to be added. (e.g. [email protected]) Note: Use bare jid.

name String In The nickname (display name) of the user.

groups String[] In The list of group names the entry will belong to. If blank, the roster entry will not belong to a group.

deleteBuddy

Description

Removes the specified buddy from the buddy list and from all groups that the user id belongs to. If the given roster does not exist, an error status will be returned.

Declaration

public CdtResult deleteBuddy(String jid)

Parameters


jid String In buddy jid to be deleted. (e.g. [email protected]). Note: Use bare jid.

deleteBuddyfromGroup

Description

Remove the specified roster from an existing group. If the given roster is not part of the group or the given group name does not exist, an error status will be returned.

Declaration

public CdtResult deleteBuddyfromGroup(String jid, String group)

Parameters


jid String In buddy jid to be deleted. (e.g. [email protected]).


28 OL-25913-01

Note: Use bare jid.

group String In The group to which the user belongs. If the group is null or empty, the buddy with jid will be removed from user’s buddy list. The effect is same as invoking deleteBuddy.

moveRosterBetweenGroup

Description

Move a roster from an existing group to another. If source group name is blank, and target group name is not blank, a target group will be created, and the buddy will be moved into target group. If target group name is blank, and the source group name is not blank, the buddy will be moved out of the source group.

Declaration

public CdtResult moveRosterBetweenGroup(String jid, String srcGroup,String targetGroup)

Parameters


jid String In buddy jid to be moved. (e.g. [email protected]).

Note: Use bare jid.

srcGroup String In The group to which the user belongs.

targetGroup String In The group where the user will be moved.

getBuddyList

Description

Get user’s buddy list.

Declaration

public List<CdtRosterEntry> getBuddyList( )

Parameters


List<CdtRosterEntry> Out The output buddy list. CdtRosterEntry is defined as shown below.

public class CdtRosterEntry

{

Client APIs

OL-25913-01 29

public String jid;

public String resource;

public String status;

public String displayName;

public CdtPresenceMode presenceMode;

public CdtPresenceType presenceType;

public List<String> groups;

}

registerRosterNotify

Description

When buddy list maintained by this class has any change, notification handler registered by this API will be called. User should use API-getBuddyList to update the buddy list in this class when this notification is received.

Declaration

public void registerRosterNotify(CdtRosterHandler handler)

Parameters


handler CdtRosterHandler In CdtRosterHandler is an interface. Its definition is shown below.

public interface CdtRosterHandler

{

public void rosterNotify(CdtRosterUpdateInfo info);

}

public class CdtRosterUpdateInfo

{

public List<String> jid;

public CdtRosterAction action;

}

public enum CdtRosterAction

{

/*

* a new roster entry is added


30 OL-25913-01

*/

ADDED,

/*

* a roster entry is deleted

*/

DELETEED,

/*

* a roster entry is updated

*/

UPDATED,

/*

* other operation,like subcribed, happens

*/

OTHER

}

PubSub

A person or application publishes information, and an event notification (with or without payload) is broadcast to all authorized subscribers. In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts event notifications to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. The point for publication and subscription is a "node" to which publishers send data and from which subscribers receive event notifications.

Package Name:

com.cisco.thirdwave.conductor.clientSDK.pubsub

Class Name:

CdtPubSub

Methods:

public CdtPubSub ();

Client APIs

OL-25913-01 31

public CdtPubSub (String jid);

public void subscribe (String nodeName) throws Exception;

public void unsubscribe (String nodeName) throws Exception;

public void registerReceiveListener (CdtPubsubListener listener);

public void publish (String node, String payload, String itemId) throws Exception;

public List <String> discoveryNodes () throws Exception;

CdtPubsub

Description

This is the constructor for the class CdtPubSub.

Declaration

CdtPubsub ()

CdtPubsub (String jid)

Parameters


jid String In JID of Service hosting the node. If it is blankL, the system will use default JID (pubsub.<server name>).

subscribe

Description

This is the API for the user to send a subscribe request to one node. If the subscription request is successfully processed, the server must inform the requesting entity that it is now subscribed.

Declaration

void subscribe (String nodeName) throws Exception

Parameters


nodeName String In The ID of the node to which the user wants to subscribe. This cannot be left blank.


32 OL-25913-01

unsubscribe

Description

This is the API for the user to send an unsubscribe request to one node. If the unsubscription request is successfully processed, the server MUST inform the requesting entity that it is now unsubscribed.

Declaration

void unsubscribe String nodeName) throws Exception

Parameters


nodeName String In The ID of the node from which the user wants to unsubscribe. This cannot be left blank.

registerReceiveListener

Description

This is the API for a user to request to register notification to the node this user had subscribed, so when a message sent to a subscriber, which will inform an event.

Declaration

void registerReceiveListener (CdtPubsubListener listener)

Parameters


listener CdtPubsubListener In CdtPubsubListener is an interface. Its definition is described below.

public interface CdtPubsubListener

{

public void processItem( String node, String payload, String itemId, String error);

}

publish

Description

This is the API for a user to request to publish items to a node. If the publish request is successfully processed, the server MUST inform the requesting entity that it is now published.

Client APIs

OL-25913-01 33

Declaration

void publish (String node, String payload) throws Exception

Parameters


node String In ID of the node to want to subscribe

Note: it cannot be NULL

payload String In XML format string of the item to be published

discoveryNodes

Description

This is the API for a user to request to get nodes list.

Declaration

List <String> discoveryNodes () throws Exception

Parameters


node String In ID of the node name, it can be NULL

List Out The result of node name list.

Message

Instant Message is mainly used as person-to-person chat, at its core it provides the ability to quickly route messages from one place to another over the network. Instant Message interactions usually take the form of chat sessions: short bursts of messages exchanged between two parties.

Chat state notifications can help to answer a variety of questions about the participation of a person in a real-time chat conversation, such as composed a message, temporarily paused, actively or inactively engaged in the chat, and gone, which fully describe the possible states of a person's participation in or involvement with a chat conversation.

Package Name:

com.cisco.thirdwave.conductor.clientSDK.message

Class Name:

CdtMessage


34 OL-25913-01

Methods:

public CdtMessage ();

public void send ( String jid, String messageBody, String messageSubject ) throws Exception;

public void setChatState (String jid, ChatState state) throws Exception;

public void registerReceiveListener (String jid, CdtMessageListener listener);

public void registerChatStateListener (String jid, CdtChatStateListener listener);

CdtMessage

Description

This is the constructor for the class CdtMessage.

Declaration

CdtMessage ()

send

Description

This is the API for a user to make a person-to-person chat with one of his contact, the user can open a message session for short bursts of messages exchanged between him and his contact.

Declaration

void send ( String jid, String messageBody, String messageSubject ) throws Exception

Parameters


jid String In JID of the entry the user wants to communicate.

messageBody String In The body of the message.

messageSubject String In The subject information of the message.

setChatState

Description

This is the API for a user to set his chat state to the contact, so the contact can be informed.

Client APIs

OL-25913-01 35

Declaration

void setChatState (String jid, ChatState state) throws Exception

Parameters

void SetChatState (String jid, ChatState state)

This is the API for a user to set his chat state to the contact, so the contact can be informed


jid String In JID of the entry the user want to communicate.

state ChatState In The chat state. See Enum ChatState.

Enum ChatState Constant Summary

active User is actively participating in the chat session.

composing User is composing a message.

gone User has effectively ended their participation in the chat session.

inactive User has not been actively participating in the chat session.

paused User had been composing but now has stopped.

registerReceiveListener

Description

This is the API for a user to register a method to receive the message, which includes message body, session id and chat status information. When message comes, client agent will call this method to inform user..

Declaration

void registerReceiveListener (String jid, CdtMessageListener listener)

Parameters


jid String In JID of the entry with whom the user wants to communicate.

Note: If toJID is NULL, the callback Func is to be used to receive all message from any source; If toJID is not NULL, the callback Func is to be used to receive from one special JID

listener CdtMessageListener In CdtMessageListener is an interface. Its


36 OL-25913-01

definition is as follows.

public interface CdtMessageListener

{

public void processMessage (String fromJID, String

messageBody,String messageSubject);

}

registerChatStateListener

Description

This is the API for a user to register a method to receive the chat state from the contact, so when the contact’s chat state changed, the user can be informed.

Declaration

void registerChatStateListener (String jid, CdtChatStateListener listener)

Parameters

void registerChatStateListener (String jid, CdtChatStateListener listener)



Jid String In JID of the entry the user want to communicate.

Note: If toJID is NULL, CdtChatStateListener is to receive all message whatever from.

Listener CdtChatStateListener In CdtChatStateListener is an interface. Its definition is as follows.

public interface CdtChatStateListener

{

public void chatStateChanged (String fromJID, ChatState

state);

}

Raw IQ

User can request to send or receive raw IQ payload.

Package Name:

com.cisco.thirdwave.conductor.clientSDK.rawIq

Client APIs

OL-25913-01 37

Class Name:

CdtRawIq

Methods:

public String send(String jid, CdtRawIqType type,String id, String payload ) throws Exception;

public CdtRawIqInfo sendIqGetResponse(String jid,String id,String xmlns,String startTag,CdtRawIqType type,String payload) throws Exception;

public void registerListener(CdtRawIqHandler handler,String xmlns, String startTag);

CdtRawIq

Description

Constructor for this class.

Declaration

public CdtRawIq();

Parameters

No

send

Description

This is the API for a user to send raw IQ packets. If the jid or id is null or empty, an exception will be thrown with error string: ’Parameter error: jid’,’ Parameter error: id’,’ Parameter error: jid & packet id’, depends on jid or id value.

Declaration

public void send(String jid, CdtRawIqType type,String id, String payload ) throws Exception;

Parameters


jid String In the jid to which the iq packets is sent

type CdtRawIqType In iq packet type.

id String In stanza id

payload String In string content to be sent.


38 OL-25913-01

sendIqGetResponse

Description

This is the API for a user to send raw IQ packets and get response IQ packet. If the jid or id is null or empty, an exception will be thrown with error string: ’Parameter error: jid’,’ Parameter error: id’,’ Parameter error: jid & packet id’, depends on jid or id value.

Declaration

public CdtRawIqInfo sendIqGetResponse(String jid,String id,String xmlns,String startTag,CdtRawIqType type,String payload) throws Exception;

Parameters


jid String In The jid to which the iq packets is sent.

type CdtRawIqType In IQ packet type.

xmlns String In Name space to which iq stanza belongs.

id String In Stanza ID.

payload String In String content to be sent.

startTag String In Raw IQ start tag name.

CdtRawIqInfo Out Response IQ packet information. See definition below:

public class CdtRawIqInfo

{

public CdtRawIqType type;

public String fromJid;

public String toJid;

public String payload;

public String id;

//for error type IQ only

public int error_code;

public CdtRawIqError.ErrorType error_type;

public String error_condiction;

public String error_message;

}

public enum CdtRawIqType

Client APIs

OL-25913-01 39

{

set, get, result, error;

}

public static enum ErrorType

{

/*retry after waiting (the error is temporary)*/

WAIT,

/*do not retry (the error is unrecoverable)*/

CANCEL,

/*retry after changing the data sent*/

MODIFY,

/*retry after providing credentials*/

AUTH,

/*proceed (the condition was only a warning)*/

CONTINUE

}

registerListener

Description

This is the API for a user to register raw IQ packed received callback.

Declaration

public void registerListener(String xmlns, String startTag,CdtRawIqHandler handler);

Parameters


handler CdtRawIqHandler In Defined below.

xmlns String In XML namespace for raw IQ start tag.

startTag String In Raw IQ start tag name.

public enum CdtRawIqType

{

set, get, result, error;

}

public class CdtRawIqInfo


40 OL-25913-01

{

public String fromJid;

public CdtRawIqType type;

public String payload;

public String id;

public String xmlns;

}

public interface CdtRawIqHandler

{

public void rawIqReceivedProcess(CdtRawIqInfo info);

}

Capabilities

Support XEP-0115.

Package Name: com.cisco.thirdwave.conductor.clientSDK. capabilities

Class Name: CdtCapabilities

Methods:

public CdtCapabilities ();

public void setIdentity(String category, String name, String type) throws Exception;

public void addFeature(String f) throws Exception;

public void removeFeature(String f) throws Exception;

public void setNode(String node) ) throws Exception;

public CdtCapsInfo getCapsInfo(String jid)

Class Name: CdtCapsInfo

Methods:

public List<String> getFeatures()

public String getIdentityCategory()

public String getIdentityName()

public String getIdentityType()

CdtCapabilities

Description

This is the constructor for the class CdtCapabilities.

Client APIs

OL-25913-01 41

Declaration

CdtCapabilities ()

setIdentity

Description

This is the API for a user to set the identity of the application. Please refer to http://xmpp.org/registrar/disco-categories.xml. The api can be called before or after login and the setting value remains regardless of the connection status.

Declaration

void setIdentity(String category, String name, String type) throws Exception


category String In The category of identity. The default is "client".

name String In The name of the identity. Not null.

type String In Type according to the category.

addFeature

Description

This is the API for a user to add a feature to local capabilities. The features added by this api will be lost when the connection is closed.

void addFeature(String f) throws Exception


f String In The feature name to add. Not null.

removeFeature

Description

This is the API for a user to add a feature to local capabilities.

void removeFeature(String f) throws Exception


f String In The feature name to remove. Not null.


42 OL-25913-01

setNode

Description

This is the API for a user to add a feature to local capabilities.

void setNode(String node) throws Exception


node String In The node name of local capabilities.

Note: The null name will not disable the capabilities but cause an exception.

getCapsInfo

getCapsInfo

Description

This is the API for a user to get capabilities information of a user.

Declaration

CdtCapsInfo getCapsInfo(String jid)


jid String In The full jid of a user.

CdtCapsInfo Out The CdtCapsInfo instance contains the information of capabilities.

getFeatures

Description

This is the API for a user to get features list from a CdtCapsInfo instance.

Declaration

List<String> getFeatures()


List Out The list of features string var.

getIdentityCategory

Description

This is the API for a user to get category of identity from a CdtCapsInfo instance.

Client APIs

OL-25913-01 43

Declaration

String getIdentityCategory ()


String Out The category string of the identity.

getIdentityName

Description

This is the API for a user to get name of identity from a CdtCapsInfo instance.

Declaration

String getIdentityName ()


String Out The name string of the identity.

getIdentityType

Description

This is the API for a user to get category of identity from a CdtCapsInfo instance.

Declaration

String getIdentitType ()


String Out The type string of the identity.

OL-25913-01 45

This chapter contains the Conductor Client SDK API specification for C/C++.

3 Chapter 3 C/C++ API Specification

In This Chapter


Client SDK Basic Rules ......................................................................... 47

Client APIs ............................................................................................. 48

Chapter 3 C/C++ API Specification

46 OL-25913-01

Software Architecture The Client SDK is a product aimed at the developers who design and write client application software for Conductor Services like Control Suite, Media Suite, and so on. The SDK defines a set of client APIs to encapsulate the complexity of the Conductor system, which makes the developers be able to design and implement a Conductor client application in a short time.

Relating to Conductor’s architecture, the client SDK consists of the following three layers: XMPP Stack, Conductor Client, and Client API.

Client SDK Basic Rules

OL-25913-01 47

Client SDK Basic Rules For the Client API libraries, all functions use asynchronous mode. Specifically, when a function sends a request to a service, the function also registers a callback function. In this way, the application user may process other requests while waiting for a response to previously sent requests. When the application user receives a callback notification for a particular request, the application user receives the server response - either success or failure response.


48 OL-25913-01

Client APIs The design aim of APIs is to provide simple, effective APIs for full use of conductor client. C style API is easy to port to more platforms, such as IOS system. The APIs user does not care about the detailed XMPP stacks. They just need to call some simple APIs to implement their functions. Conductor client focuses on the following function: Registration, login, Presence, Roster, Companion device, PubSub, Message and MUC.

Login and Logout

User can request to register to server and login or logout.

CdtMiscRegisterConnectionChangeListener

Description:

This is the API for a user to register a method to register callback function which will be called when conductor client connects or disconnects to the server.

Declaration:

CdtReturnType CdtMiscRegisterConnectionChangeListener ( const ConnectionChangeListenerCallback callbakFunc );

Parameters

Parameter name

Direction Type Description

callbakFunc In ConnectionChangeListenerCallback

The callback function to handle connection or disconnection

typedef void (*ConnectionChangeListenerCallback)

(const CdtConnectionErrorType ConnectionStatusCode);

typedef enum CdtConnectionErrorType

{

CdtConnNoError, /**< Not really an error. Everything went just fine. */

CdtConnStreamError, /**< A stream error occurred. The stream has been closed.

……

Client APIs

OL-25913-01 49

CdtConnUserDisconnected, /**< The user (or higher-level protocol) requested a disconnect. */

CdtConnNotConnected /**< There is no active connection. */

}CdtConnectionErrorType;

Note: It’s forbidden to call CdtMiscLogin and CdtMiscLogout inside the callback function.

Return values

Type Description

CdtReturnType typedef enum CdtReturn{

CDTRETURN_OK, /*OK*/

CDTRETURN_ERROR /*Error*/

}CdtReturnType;

CdtMiscLogin

Description:

This is the API for a user to request a login to one server.

Declaration:

CdtReturnType CdtMiscLogin( const char* serverName, const char* serverIpAddress, const int portNumber, const char* userName, const char* userPassword, const char* userResource );

Parameters

Parameter name Direction Type Description

serverName In char* Server name that the user wants to register to.

It cannot be NULL

serverIpAddress In char* Server IP Address that the user wants to register to.

It can be NULL when device knows the server IP Address from server name according to correct DNS setting in device

portNumber In int The port number of server

It can be -1 when device knows the port number from server name according to correct DNS SRV record in device


50 OL-25913-01

userName In char* The user name

It cannot be NULL

userPassword In char* The user Password

It cannot be NULL

userResource In char* The name of resource which the user device

It cannot be NULL

Return values

Type Description




}CdtReturnType;

Note: In the process of login, conductor client stack will help decide to use SASL or non-SASL mode according to the features of SASL which server supports. The client will also receive the encrypted key from the server, therefore, application user doesn’t care about SASL mode.

CdtMiscLogout

Description:

This is the API for a user to request to logout from one server.

Declaration:

CdtReturnType CdtMiscLogout();

Parameters

None.

Return values

Type Description




}CdtReturnType;

Client APIs

OL-25913-01 51

CdtMiscSetCapabilitiesNode

Description:

This is the API for a user to set own capabilities node for presence capabilities extension

Declaration:

CdtReturnType CdtMiscSetCapabilitiesNode (const char * node);

Parameters

Parameter name


node In char* node represents the client software the user is using, one attribute in presence capabilities extension, refer to XEP-0115

Note: If it is set as NULL or empty string, it will remove capabilities extension when send presence.

Return values

Type Description




}CdtReturnType;

CdtMiscSetDiscoIdentity

Description:

This is the API for a user to set own Identity for the use of discovery by others.

Declaration:

CdtReturnType CdtMiscSetDiscoIdentity (const char* category, const char* name, const char* type);

Parameters


category In char* the category attribute of user entity’s identity

It cannot be NULL or empty string. Default string is "client".


52 OL-25913-01

name In char* the name attribute of user entity’s identity

It can be NULL or empty string. Default string is empty string

type In char* the type attribute of user entity’s identity

It cannot be NULL or empty string. Default string is "bot".

Return values

Type Description




}CdtReturnType;

CdtMiscAddDiscoFeature

Description:

This is the API for a user to add own feature for the use of discovery by others.

Declaration:

CdtReturnType CdtMiscAddDiscoFeature(const char* feature);

Parameters


feature In char* user entity’s feature string

It cannot be NULL or empty string.

If add one duplicate feature which had been added before, function will return error.

Return values

Type Description




}CdtReturnType;

Client APIs

OL-25913-01 53

CdtMiscRemoveDiscoFeature

Description:

This is the API for a user to remove own feature for the use of discovery by others.

Declaration:

CdtReturnType CdtMiscRemoveDiscoFeature(const char* feature);

Parameters


feature In char* user entity’s feature string

It cannot be NULL or empty string.

If remove one non-exist feature, function will return error.

Return values

Type Description




}CdtReturnType;

Presence

You can know when a contact of yours is online and available for communication using a technology called presence.

There are two defined APIs for presence.

CdtPresenceSend

Description:

This is the API for a user to send a presence message to one or more users.

Declaration:

CdtReturnType CdtPresenceSend( const char* toJID, PresenceType pres, int priority,

const char* status );


54 OL-25913-01

Parameters

Below listed information could be contained in a presence message.

Parameter name


toJID In char* Target user to send presence.

Bare JID – a presence to all resources with given id

Full JID – a presence to specific JID

pres In CdtPresenceType (enum)

The different valid presence types:

enum CdtPresenceType

{

CdtPresenceAvailable,

/**< The entity is online. */

CdtPresenceChat,

/**< The entity is 'available for chat'. */

CdtPresenceAway,

/**< The entity is away. */

CdtPresenceDND, /**< The entity is DND (Do Not Disturb). */

CdtPresenceXA, /**< The entity is XA (eXtended Away). */

CdtPresenceUnavailable, /**< The entity is offline. */

CdtPresenceProbe,

/**< This is a presence probe. */

CdtPresenceError,

/**< This is a presence error. */

CdtPresenceSubscribe,

/**< subscription request.. */

CdtPresenceSubscribed, /**< subscription notification.. */

CdtPresenceUnsubscribe, /**< subscription request.. */

CdtPresenceUnsubscribed, /**< Unsubscription notification.. */

CdtPresenceInvalid

/**< The stanza is invalid. */

Client APIs

OL-25913-01 55

};

priority In int

An optional presence priority. Legal range is between -128 and +127.

status In char* An optional status message (e.g. "gone fishing").

It can be NULL

Return values

Type Description




}CdtReturnType;

Message stanza

<presence to='[email protected]/gloox'

from='[email protected]/gloox' xmlns='jabber:client'>

<show>away</show>

<priority>1</priority>

<status>on the phone</status>

</presence>

CdtPresenceRegisterReceiveListener

Description:

This API registers a callback function to handle roster presence status change event. When roster presence status changes, the registered function will be called automatically.

Declaration:

CdtReturnType CdtPresenceRegisterReceiveListener ( const PresenceCallback lpChangeCallback ) ;

Parameters


lpChangeCallback In PresenceCallback The callback function used to handle presence change.

typedef void (*PresenceCallback)( const char* fromjid, CdtPresenceType


56 OL-25913-01

pres, const char* status);

Note: fromjid is full JID, like username@servername/resource, when user application get this callback notification, just inform user application that this buddy’s presence state on one resource has changed, user application could change its own roster list or sync roster list by calling CdtRosterGetBuddyList.

Note: It’s forbidden to call CdtPresenceRegisterReceiveListener inside the callback function.

Return values

Type Description




}CdtReturnType;

Message stanza

None

Capabilities

A presence-based mechanism is used to exchange information about entity capabilities. Client API libraries will cache the capabilities information of one buddy if this buddy’s presence with capabilities extension, and it will update cached capabilities information when the capabilities extension changed in this buddy’s new presence.

CdtCapabilitiesGetBuddyCapabilities

Description:

This is the API for a user to get the capabilities of buddy.

Declaration:

CdtReturnType CdtCapabilitiesGetBuddyCapabilities(const char* jid, CdtCapabilities** caps);

Client APIs

OL-25913-01 57

Parameters

Parameter name


jid In char* Full JID of target user.

It cannot be NULL

caps out CdtCapabilities**

The pointer to get capabilities

It cannot be NULL

typedef struct featureItem CdtCapsFeatureItem; /* feature item*/

typedef struct featureItem* CdtCapsFeatureList; /*feature list (the pointer to first feature item in feature list)*/

struct featureItem

{

char* name; /*name of group*/

CdtCapsFeatureItem* next; /*pointer to next group Item*/

};

typedef struct capsIdentity CdtCapsIdentity;

struct capsIdentity

{

char* category; /*category*/

char* type; /*type*/

char* name; /* name*/

};

typedef struct capabilities CdtCapabilities;

struct capabilities

{

CdtCapsIdentity* identity; /*identity*/

CdtCapsFeatureList features; /* feature list*/

};


58 OL-25913-01

Return values

Type Description




}CdtReturnType;

Roster

Roster is the user’s contact list which generated by bidirectional presence subscription. It is usually used to display presence information of user’s contact list. When the user logs in, he will receive the roster by integrating the presence data he receives into a useful, familiar interface.

The roster can be used not only to store a flat list of contacts, but also to group into various categories. Roster groups are used to organize a user’s contact list as more buddies are added. These roster groups are not exclusive, it’s better to think of them as flexible tags instead of exclusive buckets.

For application users, roster is just the buddies list itself. Roster include every buddy’s information on jid/name/presence/resource/group.

CdtRosterGetBuddyList

Description:

Return all buddies’ information in the roster list of current user.

Declaration:

int CdtRosterGetBuddyList(CdtRosterList* plist);

Parameters

Parameter name


plist output CdtRosterList* The pointer of roster list

It cannot be NULL.

typedef struct resourceItem CdtResourceItem; /*resource item*/

typedef struct resourceItem* CdtResourceList; /*resource list (the pointer to first resource item in resource list)*/

struct resourceItem

Client APIs

OL-25913-01 59

{

char* name; /*name of the resource*/

int priority; /*priority of the resource*/

CdtPresenceType pres; /*presence status*/

char* msg; /*presence status message*/

CdtResourceItem* next; /*pointer to next resource Item*/

};

typedef struct groupItem CdtGroupItem;

/* group item*/

typedef struct groupItem* CdtGroupList; /*group list (the pointer to first group item in group list)*/

struct groupItem

{


CdtGroupItem* next; /*pointer to next group Item*/

};

typedef struct rosterItem CdtRosterItem;

/*roster item*/

typedef struct rosterItem* CdtRosterList;

/* roster list (the pointer to first roster item in roster list)*/

struct rosterItem{

char * jid; /*JID of user*/

char * displayname; /*display name of user*/

CdtSubscriptionType sub; /*subscription type of user*/

CdtResourceList rlist; /*list of resource items*/

CdtGroupList glist; /*list of group items*/

CdtRosterItem* next; /*pointer to next


60 OL-25913-01

roster Item*/

};

Return values

Type Description

int The count of buddies in roster list

0 express no buddy or getting roster list failed

CdtRosterAddBuddy

Description:

Add one person in his contact list as his buddy. This function will help to do actual operation to send the request of adding buddy to server, include send a presence subscription request to the buddy.

Declaration:

CdtReturn CdtRosterAddBuddy( const char* jid, const char* name, const CdtGroupList groups, const RosterResultCallBack callbackFunc );

Parameters


jid In char* The JID to add.

It cannot be NULL

name In char* The displayed name of the contact.

It cannot be NULL

groups In CdtGroupList A list of groups the contact belongs to.

It can be NULL if no groups

typedef struct groupItem CdtGroupItem;

/* group item*/

typedef struct groupItem* CdtGroupList; /*group list (the pointer to first group item in group list)*/

struct groupItem

{


CdtGroupItem* next; /*pointer to next group Item*/

};

Client APIs

OL-25913-01 61

callbackFunc In RosterResultCallBack

The callback function to handle the result of adding buddy

typedef enum CdtReturn{



}CdtReturnType;

typedef enum CdtRosterCommandType{

CDTROSTER_ADDBUDDY, /*add one buddy*/

CDTROSTER_DELETEBUDDY, /*delete one buddy*/

CDTROSTER_BUDDYUPDATE, /*buddy’s information updated*/

CDTROSTER_SUBSCRIBED, /* buddy subscribed */

CDTROSTER_UNSUBSCRIBED, /*buddy unsubscribed*/ CDTTOSTER_SUBSCRIPTIONREQUEST, /* get subscription request from buddy*/ CDTTOSTER_UNSUBSCRIPTIONREQUEST /* get un-subscription request from buddy*/

}CdtRosterCommandType;

typedef void (*RosterResultCallBack)( const char* jid, const CdtRosterCommandType cmd, const CdtReturnType result);

Note: if recall CdtRosterAddBuddy whether the other parameters are same or not, the new callback function will replace old one; if callbackFunc is NULL, do unregister callback function

When get this callback, user application could sync the roster list by calling CdtRosterGetBuddyList

Because of the asynchronous mode, don’t suggest to call CdtRosterGetBuddyList after calling CdtRosterAddBuddy and before getting corresponding callback notification.

Note: It’s forbidden to call


62 OL-25913-01

CdtRosterAddBuddy inside the callback function.

Return values

Type Description

CdtReturn typedef enum CdtReturn{



}CdtReturn;

Message stanza

<iq id='uid:4db50bd8:56f32f43' type='set'


<query xmlns='jabber:iq:roster'>

<item jid='[email protected]' name='linta'>

<group>group1</group>


</item>

</query>

</iq>

CdtRosterDeleteBuddy

Description:

Remove one contact from his buddy list. This function will help to do actual operation to send the request of deleting buddy to server, include send a presence unsubscription request to the buddy.

Declaration:

CdtReturn CdtRosterDeleteBuddy( const char* jid, const RosterResultCallBack callbackFunc);

Parameters


jid In char* The contact’s JID.

It cannot be NULL


The callback function to handle the result of deleting roster

typedef void (*RosterResultCallBack)(

Client APIs

OL-25913-01 63

const char* jid, const CdtRosterCommandType cmd, const CdtReturnType result);

Note: if recall CdtRosterDeleteBuddy whether the other parameters are same or not, the new callback function will replace old one; if callbackFunc is NULL, do unregister callback


Because of the asynchronous mode, don’t suggest to call CdtRosterGetBuddyList after calling CdtRosterDeleteBuddy and before getting corresponding callback notification.

Note: It’s forbidden to call CdtRosterDeleteBuddy inside the callback function.

Return values

Type Description




}CdtReturnType;

Message stanza

<iq id='uid:4db65e9b:56f32f43' type='set'



<item jid='[email protected]' subscription='remove'/>

</query>

</iq>

CdtRosterDeleteFromGroup

Description:

Remove a roster from an existing group. If the given roster does not exist in the group or the given group name does not exist, API returns ERROR. In fact, this function is implemented internally by calling CdtRosterAddBuddy.


64 OL-25913-01

Declaration:

Return CdtRosterDeleteFromGroup( const char* delelteJID, const char* groupName, const RosterResultCallBack callbackFunc);

Parameters


deleteJID In char* The JID of roster to be deleted.

It cannot be NULL

groupName In char* The group name.

It cannot be NULL


The callback function to handle the result of deleting buddy from a group


Note: if recall CdtRosterDeleteFromGroup whether the other parameters are same or not, the new callback function will replace old one; if callbackFunc is NULL, do unregister callback function


Because of the asynchronous mode, don’t suggest to call CdtRosterGetBuddyList after calling CdtRosterDeleteFromGroup and before getting corresponding callback notification.

Note: It’s forbidden to call CdtRosterDeleteFromGroup and CdtRosterMoveBetweenGroups inside the callback function.

Return values

Type Description




Client APIs

OL-25913-01 65

}CdtReturnType;

CdtRosterMoveBetweenGroups

Description:

Move a roster from an existing group to another. If the given roster does not exist in the group or the given group name does not exist, API returns ERROR. In fact, this function is implemented internally by calling CdtRosterAddBuddy.

Declaration:

CdtReturnType CdtRosterMoveBetweenGroups( const char* moveJID, const char* oldGroupName, const char* newGroupName, const RosterResultCallBack callbackFunc);

Parameters


moveJID In char* The JID of roster to be moved.

It cannot be NULL

oldGroupName In char* The original group’s name.

It cannot be NULL

newGroupName In char* The destination group name.

It cannot be NULL


The callback function to handle the result of moving buddy between groups


Note: if recall CdtRosterMoveBetweenGroups whether the other parameters are same or not, the new callback function will replace old one; if callbackFunc is NULL, do unregister callback function


Because of the asynchronous mode, don’t suggest to call CdtRosterGetBuddyList after calling CdtRosterMoveBetweenGroups and


66 OL-25913-01

before getting corresponding callback notification.

Note: It’s forbidden to call CdtRosterDeleteFromGroup and CdtRosterMoveBetweenGroups inside the callback function.

Return values

Type Description




}CdtReturnType;

CdtRegisterRosterSubscriptionCallback

Description:


Declaration:

CdtReturnType CdtRegisterRosterSubscriptionCallback(

const RosterSubscribeCallBack callbackFunc);

Parameters

Parameter name


callbackFunc In RosterSubscribeCallBack The callback function to handle received roster’s requests and responses to subscription

typedef void (*RosterSubscribeCallBack)( const char* jid, const CdtRosterCommandType cmd, const char* msg);

typedef enum CdtRosterCommandType{

CDTROSTER_ADDBUDDY, /*add buddy*/

CDTROSTER_DELETEBUDDY, /*delete buddy*/

Client APIs

OL-25913-01 67

CDTROSTER_UPDATEBUDDY, /*buddy updated*/

CDTROSTER_SUBSCRIBED, /* buddy subscribed */

CDTROSTER_UNSUBSCRIBED, /*buddy unsubscribed*/ CDTTOSTER_SUBSCRIPTIONREQUEST, /* get subscription request from buddy*/ CDTTOSTER_UNSUBSCRIPTIONREQUEST /* get un-subscription request from buddy*/

}CdtRosterCommandType;

Note: if callbackFunc is NULL, do unregister the callback function; if callbackFunc is not NULL, the new one will replace old one.

Note: It’s forbidden to call CdtRegisterRosterSubscriptionCallback inside the callback function.

Return values

Type Description




}CdtReturnType;

PubSub

A person or application publishes information, and an event notification (with or without payload) is broadcasted to all authorized subscribers. In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts event notifications to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. The point for publication and subscription is a "node" to which publishers send data and from which subscribers receive event notifications.


68 OL-25913-01

CdtPubsubSubscribe

Description:

This is the API for a user to send subscribe requirement to one node. If the subscription request is successfully processed, the server MUST inform the requesting entity that it is now subscribed

Declaration:

CdtReturnType CdtPubsubSubscribe ( const char* serviceJID, const char* node,

const PubSubSubscriptionResultCallBack callbackFunc );

Parameters

Parameter name


serviceJID In char* JID of Service hosting the node.


node In char* ID of the node to want to subscribe


callbackFunc In PubSubSubscriptionResultCallBack

The callback function to handle the subscription to one node result from pubsub service

typedef void (*PubSubSubscriptionResultCallBack)( const char* serviceJID, const char* node, const CdtReturnType result);

Note: if recall CdtsubscribeToOneNode whether the parameter service JID and node are same or not, the new callback function will replace old one; if callbackFunc is NULL, do unregister callback function

Note: It’s forbidden to call CdtPubsubSubscribe inside the callback function.

Return values

Type Description




}CdtReturnType;

Client APIs

OL-25913-01 69

Message stanza

<iq type='set'

from='[email protected]/barracks'

to='pubsub.shakespeare.lit'

id='sub1'>

<pubsub xmlns='http://jabber.org/protocol/pubsub'>

<subscribe

node='princely_musings'

jid='[email protected]'/>

</pubsub>

</iq>

If successful,

<iq type='result'

from='pubsub.shakespeare.lit'

to='[email protected]/barracks'

id='sub1'>


<subscription


jid='[email protected]'

subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'

subscription='subscribed'/>

</pubsub>

</iq>

if failed,

<iq type='error'



id='sub1'>


70 OL-25913-01

<error type='modify'>

<bad-request xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>

<invalid-jid

xmlns='http://jabber.org/protocol/pubsub#errors'/>

</error>

</iq>

CdtPubsubUnsubscribe

Description:

This is the API for a user to send unsubscribe requirement to one node. If the un subscription request is successfully processed, the server MUST inform the requesting entity that it is now unsubscribed

Declaration:

CdtReturnType CdtPubsubUnsubscribe ( const char* serviceJID, const char* node,

const PubSubUnsubscriptionResultCallBack callbackFunc );

Parameters

Parameter name




node In char* ID of the node to want to unsubscribe


callbackFunc In PubSubUnsubscriptionResultCallBack

The callbak function to handle the unsubscription to one node result from pubsub service

typedef void (*PubSubUnsubscriptionResultCallBack)( const char* serviceJID, const char* node, const CdtReturnType result);

note:if recall CdtUnsubscribeToOneNode whether the parameter service JID and node are same or not, the new callback function will replace old one; if callbackFunc is NULL, do unregister callback function

Note: It’s forbidden to call CdtPubsubUnsubscribe inside the callback function.

Client APIs

OL-25913-01 71

Return values

Type Description




}CdtReturnType;

Message stanza

<iq type='set'



id='unsub1'>


<unsubscribe



</pubsub>

</iq>

If successful,

<iq type='result'



id='unsub1'/>

If failed,

<iq type='error'



id='unsub1'>



72 OL-25913-01


<subid-required


</error>

</iq>

CdtPubsubPublish

Description:

This is the API for a user to request to publish items to a node. If the publish request is successfully processed, the server MUST inform the requesting entity that it is now published

Declaration:

CdtReturnType CdtPubsubPublish ( const char* serviceJID, const char* node,

const char* itempayload, const char* itemid,

const PubSubPublishItemResultCallBack callbackFunc );

Parameters

Parameter name




node In char* ID of the node to want to subscribe


itempayload In char* Payload string of the item to be published

Note: it can be NULL, which express without payload

It must be the xml string.

itemid In char* ID of the item to be published


callbackFunc In PubSubPublishItemResultCallBack

The callbak function to handle the publish item to one Node result from pubsub service

typedef void (*PubSubPublishItemResultCallBack)( const char* serviceJID, const char* node, const char* itempayload, const char* itemid, const CdtReturnType result);

Note: if recall CdtPublishItemToNode whether the parameters(serviceJID, node,

Client APIs

OL-25913-01 73

itempayload, itemid) are same or not, the new callback function will replace old one; if callbackFunc is NULL, do unregister callback function.

Note: It’s forbidden to call CdtPubsubPublish inside the callback function.

Return values

Type Description




}CdtReturnType;

Message stanza

<iq type='set'

from='[email protected]/blogbot'


id='publish1'>


<publish node='princely_musings'>

<item id='bnd81g37d61f49fgn581'>

<entry xmlns='http://www.w3.org/2005/Atom'>

<title>Soliloquy</title>

<summary>

To be, or not to be: that is the question:

Whether 'tis nobler in the mind to suffer

The slings and arrows of outrageous fortune,

Or to take arms against a sea of troubles,

And by opposing end them?

</summary>

<link rel='alternate' type='text/html'

href='http://denmark.lit/2003/12/13/atom03'/>

<id>tag:denmark.lit,2003:entry-32397</id>


74 OL-25913-01

<published>2003-12-13T18:30:02Z</published>

<updated>2003-12-13T18:30:02Z</updated>

</entry>

</item>

</publish>

</pubsub>

</iq>

If successful,

<iq type='result'


to='[email protected]/blogbot'

id='publish1'>



<item id='ae890ac52d0df67ed7cfdf51b644e901'/>

</publish>

</pubsub>

</iq> id='unsub1'/>

If failed,

<iq type='error'


id='publish1'>

<error type='auth'>

<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>

</error>

</iq>

CdtPubsubDiscoveryNodes

Description:

This is the API for a user to request to get node list of one server. If the discovery is successfully processed, the server MUST inform the user.

Client APIs

OL-25913-01 75

Declaration:

CdtReturnType CdtPubsubDiscoveryNodes ( const char* serviceJID,

const PubSubDiscoveryNodesResultCallBack callbackFunc );

Parameters

Parameter name



Note: It cannot be NULL

callbackFunc In PubSubDiscoveryNodesResultCallBack

The callbak function to handle the discovery nodes result from pubsub service

typedef struct nodeItem CdtNodeItem;

struct nodeItem

{

char* jid;

char* node;

char* name;

CdtNodeItem* next;

};

typedef void (*PubSubDiscoveryNodesResultCallBack)( const char* serviceJID, const CdtNodeList nodeList, const CdtReturnType result);

Note: If recall CdtPubsubDiscoveryNodes whether the parameter serviceJID is same or not, the new callback function will replace old one; if callbackFunc is NULL, do unregister callback function.

Note: It’s forbidden to call CdtPubsubDiscoveryNodes inside the callback function.

Return values

Type Description



76 OL-25913-01



}CdtReturnType;

Message stanza

<iq type='get'



id='nodes1'>

<query xmlns='http://jabber.org/protocol/disco#items'/>

</iq>

If successful,

<iq type='result'



id='nodes1'>

<query xmlns='http://jabber.org/protocol/disco#items'>

<item jid='pubsub.shakespeare.lit'

node='blogs'

name='Weblog updates'/>


node='news'

name='News and announcements'/>

</query>

</iq>

CdtPubsubRegisterReceiveListener

Description:

This is the API for user applications to request to register publish message notification callback. When the messages is published from the nodes which the user had subscribed, user application will get notification by this callback function.

Client APIs

OL-25913-01 77

Declaration:

CdtReturnType CdtPubsubRegisterReceiveListener (

const PubSubMessageNotificationCallBack callbackFunc );

Parameters

Parameter name


callbackFunc In PubSubMessageNotificationCallBack

The callbak function to handle pubsub notification message from pubsub service

typedef void (*PubSubMessageNotificationCallBack ( const char* serviceJID, const char* node, const char* itempayload, const char* itemid);

Note: If recall CdtRegisterPubsubNotificationListener, the new callback function will replace old one; ; if callbackFunc is NULL, do unregister callback function.

Note: It’s forbidden to call CdtPubsubRegisterReceiveListener inside the callback function.

Return values

Type Description




}CdtReturnType;

Message stanza

<message from='pubsub.shakespeare.lit' to='[email protected]'

id='foo'> <event xmlns='http://jabber.org/protocol/pubsub#event'> <items node='princely_musings'> <item id='ae890ac52d0df67ed7cfdf51b644e901'> [ ... ENTRY ... ] </item> </items> </event> </message>


78 OL-25913-01

Message



CdtMessageSend

Description:


Declaration:

CdtReturnType CdtMessageSend ( const char* toJID, const char* messageBody,

const char* messageSubject );

Parameters


toJID In char* JID of the entry the user wants to communicate.

Note: JID cannot be NULL

messageBody In char* The body of the message

Note: messageBody can be NULL; If messageBody and messageSubject are both NULL, it will close the message session for this JID

messageSubject In char* The subject information of the message

Note: messageSubject can be NULL; If messageBody and messageSubject are both NULL, it will close the message session for this JID

Return values

Type Description



Client APIs

OL-25913-01 79


}CdtReturnType;

CdtMessageSetChatState

Description:


Declaration:

CdtReturnType CdtMessageSetChatState ( const char* toJID, const ChatStateType chatState);

Parameters



Note: JID cannot be NULL

chatState In CdtChatStateType The chat state.

enum CdtChatStateType

{

CdtChatStateActive /*User is actively participating in the chat session*/

CdtChatStateComposing /* User is composing a message*/

CdtChatStatePaused /*User had been composing but now has stopped*/

CdtChatStateInactive /*User has not been actively participating in the chat session*/

CdtChatStateGone /*User has effectively ended their participation in the chat session*/

CdtChatStateInvalid /*Invalid type*/

}

Notes:

The default chat state when chat begins is CdtChatStateGone.

If call CdtMessageSetChatState


80 OL-25913-01

and the parameter chatState is same with the last time when call CdtMessageSetChatState, this time this function will return error.

Return values

Type Description




}CdtReturnType;

CdtMessageRegisterReceiveListener

Description:

This is the API for a user to register a method to receive the message, which includes message body, message subject information. When message comes, client agent will call this method to inform user.

Note: Current API won’t support to inform the message with error to user

Declaration:

CdtReturnType CdtMessageRegisterReceiveListener ( const char* toJID,

const MessageListenerCallback callbakFunc );

Parameters



Note: If toJID is NULL, the callback function is used to receive all messages from any source; If toJID is not NULL, the callback function is used to receive from one special JID

callbakFunc In MessageListenerCallback

The callbak function to handle received message

typedef void (*MessageListenerCallback (const char* fromJID , const char* messageBody, const char* messageSubject);

Note: callback is related with the other

Client APIs

OL-25913-01 81

parameter toJID; When JID is same, if callbackFunc is NULL, do unregister the callback function; if callbackFunc is not NULL, the new one will replace old one.

Note: It’s forbidden to call CdtMessageRegisterReceiveListener inside the callback function.

Return values

Type Description




}CdtReturnType;

CdtMessageRegisterChatStateChangeListener

Description:


Declaration:

CdtReturnType CdtMessageRegisterChatStateChangeListener ( const char* toJID,

const ChatStateChangeListenerCallback callbakfunc );

Parameters

Parameter name



Note: If toJID is NULL, this function will return an error, because chat state makes sense only when chat with one special JID begins; If toJID is not NULL, the callback function is used to receive from one special JID

callbakfunc In ChatStateChangeListenerCallback

The callback function to handle received message

typedef void (*ChatStateChangeListenerCallback)(const char* fromJID, const CdtChatStateType);

Note: callback is related with the other parameter toJID; When JID is same, if


82 OL-25913-01

callbackFunc is NULL, do unregister the callback function; if callbackFunc is not NULL, the new one will replace old one.

Note: It’s forbidden to call CdtMessageRegisterChatStateChangeListener inside the callback function.

Return values

Type Description




}CdtReturnType;

Raw IQ


CdtRawIqSend

Description:

This is the API for a user to send raw IQ payload.

Declaration:

CdtReturnType CdtRawIqSend( const char* toJID,const char* id, const CdtIqType type, const char* xmlns, const char* payload);

Parameters

Parameter name


toJID In char* The JID of the entry the user want to send IQ to.

It cannot be NULL

type In IQType The type of IQ command

enum CdtIQType

{

CdtGet /* The stanza is a request for information or requirements.*/

CdtSet /* The stanza provides required data, sets new values, or replaces existing values.*/

CdtResult /* The stanza is a response to a successful get

Client APIs

OL-25913-01 83

or set request.*/

CdtError /* An error has occurred regarding processing or delivery of a previously-sent get or set.*/

CdtInvalid/* The stanza is invalid*/

}

xmlns In char* The name space of IQ command

It can be NULL

payload In char* Raw data string of IQ payload

It can be NULL, and payload string must be xml string

id In char* The iq string of IQ command

It cannot be NULL

Return values

Type Description




}CdtReturnType;

CdtRawIqRegisterReceiveCallback

Description:

This is the API for a user to register the callback function for receiving raw IQ payload.

Declaration:

CdtReturnType CdtRawIqRegisterReceiveCallback( const char* startTag, const ReceiveIQPayloadCallback callbackFunc);

Parameters

Parameter name


startTag In char* The string of the tag header in the IQ payload which the user want to get

It cannot be NULL

callbackFunc In ReceiveIQPayloadCallback

The callbak function to receive the payload of IQ command

typedef void


84 OL-25913-01

(*ReceiveIQPayloadCallback)(const char* fromJID, const char* id, const CdtIqType, const char* xmlns, const char* startTag, const char* payload);

Note: callback is related with the other parameter startTag; When startTag is same, if callbackFunc is NULL, do unregister the callback function; if callbackFunc is not NULL, the new one will replace old one.

Note: It’s forbidden to call CdtRawIqRegisterReceiveCallback inside the callback function.

MUC(TBD)

Multiple users can exchange messages in the context of a room or channel. In addition to standard chatroom features such as room topics and invitations, user can define a strong room control model.

In MUC, user can join a room and send messages that are delivered to all the other participants. Thus the room acts as a kind of message multiplier(one incoming message is multiplied into many outgoing messages). User can process for joining, participating in, and leaving a chat room; sending and receiving messages; delayed delivery of the room history; reserving a nickname using the In-Band Registration protocol; configuring a room using the Data Forms extension; and enforcing appropriate security and privacy measures, such as kicking and banning users, naming room moderators and administrators, requiring membership or passwords in order to join the room, disabling room logging, and preventing anyone except registered room members from joining the room.

CdtMucCreateRoom

Description:

This is the API for a user to create rooms is restricted to certain users, which can require to create a room and configure the setting of room.

Declaration:

void CdtMucCreateRoom ( const char* roomJID );

Parameters

Parameter name


roomJID In char* JID of the room

Client APIs

OL-25913-01 85

CdtMucDestroyRoom

Description:

This is the API for a user to destroy the room he created. All the occupants will be removed from the room

Declaration:

void CdtMucDestroyRoom ( const char* roomJID);

Parameters

Parameter name



CdtMucInviteOccupant

Description:

This is the API for a user to invite one occupant to join the room.

Declaration:

void CdtMucInviteOccupant ( const char* roomJID, const char* inviteeJID);

Parameters

Parameter name



inviteeJID In Char* JID of the invitee

CdtMucGetOccupantsList

Description:

This is the API for occupant to retrieve the list of room members

Declaration:

void CdtMucGetOccupantsList ( const char* roomJID,

const GetOccupantsListCallback callbackfunc);


86 OL-25913-01

Parameters

Parameter name



callbackfunc In GetOccupantsListCallback

CdtMucKickParticipant

Description:

This is the API for moderator to kick certain kinds of occupants from a room

Declaration:

void CdtMucKickParticipant ( const char* roomJID, const char* occupantJID );

Parameters

Parameter name



occupantJID In char* JID of the occupant will be kicked out

CdtMucBanUser

Description:

This is the API to ban a user from the room. Depending on service and/or room configuration and role/affiliation this may not always succeed

Declaration:

void CdtMucBanUser ( const char* roomJID, const char* occupantJID );

Parameters

Parameter name



occupantJID In char* JID of the occupant will be kicked out

CdtMucJoinRoom

Description:

This is the API for user to join the room.

Client APIs

OL-25913-01 87

Declaration:

void CdtMucJoinRoom ( const char* roomJID );

Parameters

Parameter name



CdtLeaveRoom

Description:

This is the API for a user to leave the room.

Declaration:

void CdtMucLeaveRoom ( const char* roomJID );

Parameters

Parameter name



CdtMucSendMessage

Description:

This is the API for a user to send a message to all other occupants in the room.

Declaration:

void CdtMucSendMessage ( const char* roomJID, const char* messageBody );

Parameters

Parameter name



messageBody In char* The body of message

CdtMucSendPrivateMessage

Description:

This is the API for a user to send a "private message" to a selected occupant.


88 OL-25913-01

Declaration:

void CdtMucSendPrivateMessage ( const char* roomJID, const char* occupantJID,

const char*messageBody );

Parameters

Parameter name



occupantJID In char* JID of the occupant the user want to send private message to

messageBody In char* The body of message

OL-25913-01 89

This chapter contains the Conductor Client SDK API specification for Objective C.

4 Chapter 4 Objective C API Specification

In This Chapter


Client APIs ............................................................................................. 91

Delegates .............................................................................................. 105

Chapter 4 Objective C API Specification

90 OL-25913-01

Software Architecture The Client SDK is a product aimed at the developers who design and write client application software for Conductor Services like Control Suite, Media Suite, and so on. The SDK defines a set of client APIs to encapsulate the complexity of the Conductor system, which makes the developers be able to design and implement a Conductor client application in a short time.


Client APIs

OL-25913-01 91

Client APIs The design aim of APIs is to provide least special APIs for fully use of conductor client. The APIs user doesn’t care about the detailed XMPP stacks, they just need to call some simple APIs to implement their functions.

Conductor client focuses on the following function: Registration, login, Presence, Roster, Companion device, PubSub, Message and MUC (MUC not contained in this version).

Login/Logout

User can request to register to server and do login/logout.

Login

/*!

@function

@abstract perform client login

@param serverName xmpp server domain name

@param serverIpAddress xmpp server ip address

@param portNumber xmpp server port, default 5222

@param userName user name, the part before @ in a jid

@param userPassword user password

@param resource resource indicates user device

*/

CdtReturnType CdtMiscLoginObjc( const NSString * serverName,

const NSString * serverIpAddress, const int portNumber, const

NSString * userName, const NSString * userPassword, const

NSString * resource);

Logout

/*!

@function

@abstract perform client logout

*/

CdtReturnType CdtMiscLogoutObjc();


92 OL-25913-01

Presence

You can know when a contact of yours is online and available for communication using a technology called presence.

There are two defined APIs for presence.

Send Presence

/*!

@function

@abstract send prensce to roster

@param toJID destination jid

@param pres presence type

@param priority priority of presence

@param status status message in this presence

*/

CdtReturnType CdtPresenceSendObjc(const NSString *toJID, const

CdtPresenceType pres, const NSInteger priority, const NSString *

status);

enum PresenceType

{

available,

chat,

away,

dnd,

xa,

unavailable,

probe,

error,

invalid,

};

Client APIs

OL-25913-01 93

Roster

Roster is the user’s contact list which generated by bidirectional presence subscription. It is usually used to display presence information of user’s contact list. When the user logs in, he will receive the roster by integrating the presence data he receives into a useful, familiar interface.

The roster can be used not only to store a flat list of contacts, but also to group into various categories. Roster groups are used to organize the user’s contact list as more buddies are added on the network. These roster groups are not exclusive; it’s better to think of them as flexible tags instead of exclusive buckets.

Get Roster List

/*!

@function

@abstract get the roster list of given user

@param plist given user jid

@return number of RosterItems

*/

NSInteger CdtRosterGetBuddyListObjc(CdtRosterList* plist);

typedef struct rosterItem* CdtRosterList;

/* roster list (the pointer to first roster item in roster

list)*/

struct rosterItem{

char * jid; /*JID of user*/

char * displayname; /*display name of user*/

CdtSubscriptionType sub; /*subscription type of user*/

CdtResourceList rlist; /*list of resource items*/

CdtGroupList glist; /*list of group items*/

CdtRosterItem* next; /*pointer to next roster Item*/

};

Return

Returns a const list of RosterItem.


94 OL-25913-01

Add Contact

/*!

@function

@abstract add a contact

@param jid user to add

@param name display name of user

@param groups a list of groups that contact belong to

if (groups = NULL); (groups->name = NULL &&

groups ->next =NULL); (groups ->name=""). Contact is added in

to default group.

*/

CdtReturnType CdtRosterAddBuddyObjc( const NSString* jid, const

NSString* name, const CdtGroupList groups);

Message stanza

<iq id='uid:4db50bd8:56f32f43' type='set'



<item jid='[email protected]' name='linta'>



</item>

</query>

</iq>

Delete Contact

/*!

@function

@abstract delete a contact

@param jid user to delete

*/

CdtReturnType CdtRosterDeleteBuddyObjc( const NSString* jid);

Message stanza

<iq id='uid:4db65e9b:56f32f43' type='set'



Client APIs

OL-25913-01 95

<item jid='[email protected]' subscription='remove'/>

</query>

</iq>

Move Contact to Group

/*!

@function

@abstract move a contact to a list of groups

a user can be add to different groups

@param moveJID user to move

@param oldGroupName old group name

@param newGroupName new group name

*/

CdtReturnType CdtRosterMoveBetweenGroupsObjc( const NSString*

moveJID, const NSString* oldGroupName, const NSString*

newGroupName);

Delete Contact from Group

/*!

@function

@abstract delete a contact to a list of groups

when a group has none members, delete it.

@param delelteJID user to delete

@param groupName group name which user delete from

*/

CdtReturnType CdtRosterDeleteFromGroupObjc( const NSString*

delelteJID, const NSString* groupName);

PubSub

A person or application publishes information, and an event notification (with or without payload) is broadcasted to all authorized subscribers. In general, the relationship between the publisher and subscriber is mediated by a service that receives publication requests, broadcasts event notifications to subscribers, and enables privileged entities to manage lists of people or applications that are authorized to publish or subscribe. The point for publication and subscription is a "node" to which publishers send data and from which subscribers receive event notifications.


96 OL-25913-01

Subscribe to Node

Description:

This is the API for a user to send subscribe requirement to one node. If the subscription request is successfully processed, the server MUST inform the requesting entity that it is now subscribed

/*!

@function

@abstract subscribe to a node using pub/sub

@param serviceJID service jid

@param node node name

*/

CdtReturnType CdtPubsubSubscribeObjc ( const NSString*

serviceJID, const NSString* node);

Message stanza

<iq type='set'



id='sub1'>


<subscribe



</pubsub>

</iq>

If successful,

<iq type='result'



id='sub1'>


<subscription

Client APIs

OL-25913-01 97


jid='[email protected]'

subid='ba49252aaa4f5d320c24d3766f0bdcade78c78d3'

subscription='subscribed'/>

</pubsub>

</iq>

If failed,

<iq type='error'



id='sub1'>



<invalid-jid


</error>

</iq>

Unsubscribe from Node

Description:

This is the API for a user to send unsubscribe requirement to one node. If the un subscription request is successfully processed, the server MUST inform the requesting entity that it is now unsubscribed.

/*!

@function

@abstract unsubscribe to a node using pub/sub

@param serviceJID service jid


*/

CdtReturnType CdtPubsubUnsubscribeObjc ( const NSString*

serviceJID, const NSString* node);


98 OL-25913-01

Message stanza

<iq type='set'



id='unsub1'>


<unsubscribe



</pubsub>

</iq>

If successful,

<iq type='result'



id='unsub1'/>

If failed,

<iq type='error'



id='unsub1'>



<subid-required


</error>

</iq>

Client APIs

OL-25913-01 99

Publish to Node

Description:

This is the API for a user to request to publish items to a node. If the publish request is successfully processed, the server MUST inform the requesting entity that it is now published

/*!

@function

@abstract publish item to a node using pub/sub

@param serviceid service jid


@param itempayload payload to publish

@param itemid id of item to publish

*/

CdtReturnType CdtPubsubPublishObjc ( const NSString* serviceJID,

const NSString* node, const NSString* itempayload, const

NSString* itemid);

Message stanza

<iq type='set'

from='[email protected]/blogbot'


id='publish1'>



<item id='bnd81g37d61f49fgn581'>

<entry xmlns='http://www.w3.org/2005/Atom'>

<title>Soliloquy</title>

<summary>

To be, or not to be: that is the question:

Whether 'tis nobler in the mind to suffer

The slings and arrows of outrageous fortune,

Or to take arms against a sea of troubles,

And by opposing end them?


100 OL-25913-01

</summary>

<link rel='alternate' type='text/html'

href='http://denmark.lit/2003/12/13/atom03'/>

<id>tag:denmark.lit,2003:entry-32397</id>

<published>2003-12-13T18:30:02Z</published>

<updated>2003-12-13T18:30:02Z</updated>

</entry>

</item>

</publish>

</pubsub>

</iq>

If successful,

<iq type='result'


to='[email protected]/blogbot'

id='publish1'>



<item id='ae890ac52d0df67ed7cfdf51b644e901'/>

</publish>

</pubsub>

</iq> id='unsub1'/>

If failed,

<iq type='error'


id='publish1'>

<error type='auth'>

<forbidden xmlns='urn:ietf:params:xml:ns:xmpp-stanzas'/>

</error>

</iq>

Client APIs

OL-25913-01 101

Discovery Node

Description:

This is the API for a user to request to get node list of one server. If the discovery is successfully processed, the server MUST inform the user.

/*!

@function

@abstract discovery nodes to a given service jid


*/

CdtReturnType CdtPubsubDiscoveryNodesObjc ( const NSString*

serviceJID);

Message stanza

<iq type='get'



id='nodes1'>

<query xmlns='http://jabber.org/protocol/disco#items'/>

</iq>

If successful,

<iq type='result'



id='nodes1'>

<query xmlns='http://jabber.org/protocol/disco#items'>


node='blogs'

name='Weblog updates'/>


node='news'

name='News and announcements'/>


102 OL-25913-01

</query>

</iq>

Message



Send Message

Description:


/*!

@function

@abstract send message to a given jid

@param toJID receiver user jid

@param messageBody message body

@param messageSubject message subject

*/

CdtReturnType CdtMessageSendObjc ( const NSString* toJID, const

NSString* messageBody, const NSString* messageSubject );

Set Chat State

Description:


/*!

@function

@abstract set chat state

@param toJID receiver user jid

Client APIs

OL-25913-01 103

@param chatState chat state

*/

CdtReturnType CdtMessageSetChatStateObjc ( const NSString* toJID,

const CdtChatStateType chatState);

enum ChatStateType

{

active, /*User is actively participating in the chat

session*/

composing, /* User is composing a message*/

paused, /*User had been composing but now has stopped*/

inactive, /*User has not been actively participating in

the chat session*/

gone, /*User has effectively ended their participation

in the chat session*/

invalid, /*Invalid type*/

}

Raw IQ


Send Raw IQ

Description:

This is the API for a user to send raw Iq payload.

/*!

@function

@abstract send raw iq data

@param to destination jid

@param iqid the id of this iq

@param type type of this iq

@param xmlns namespace of this iq

@param payload raw data string of this iq

*/

CdtReturnType CdtRawIqSendObjc( const NSString* toJID,const

NSString* id, const CdtIqType type, const NSString* xmlns, const

NSString* payload);


104 OL-25913-01

Receive Raw IQ

Description:

This is the API for a user to register a callback to receive raw IQ.

/*!

@function

@abstract send raw iq data

@param startTag start tag of raw IQ

@param callbackFunc the callback function to receive a specific

kind of raw IQ

*/

CdtReturnType CdtRawIqRegisterReceiveCallbackObjc( const

NSString* startTag, const ReceiveIQPayloadCallback callbackFunc);

typedef void (*ReceiveIQPayloadCallback)( const char* fromJID,

const char* id, const CdtIqType type, const char*xmlns, const

char* startTag, const char* payload);

Delegates

OL-25913-01 105

Delegates

LoginDelegate

LoginDelegate declares the protocol function for client to process a login status change message from server.

Class LoginController is used to perform the specific delegate function, user call sharedSingleton to get a shared instance of LoginController, and register its delegate to corresponding user class which implement the delegate function.

Protocol define:

@protocol LoginDelegate <NSObject>

/*!

@function

@abstract notify connection status change to user

@param connectionStatusCode user connection status code

*/

- (void)receiveLoginChangeMsg:(const

CdtConnectionErrorType)connectionStatusCode;

@end

PresenceDelegate

PresenceDelegate declares the protocol function for client to process a presence status change message from server.

Class PresenceController is used to perform the specific delegate function, user call sharedSingleton to get a shared instance of PresenceController, and register its delegate to corresponding user class which implement the delegate function.

Protocol define:

@protocol PresenceDelegate <NSObject>

/*!

@function

@abstract return connection presence change to user


106 OL-25913-01

@param fromId resoruce jid

@param type type of presence

@param status status message of presence

*/

- (void)receivePresenceChangeMsg:(NSString *)fromId

Type:(CdtPresenceType) type Status:(NSString*)status;

@end

RosterDelegate

RosterDelegate declares the protocol function for client to process a roster status change message from server.

Class RosterController is used to perform the specific delegate function, user call sharedSingleton to get a shared instance of RosterController, and register its delegate to corresponding user class which implement the delegate function.

Protocol define:

@protocol RosterDelegate <NSObject>

/*!

@function

@abstract receive roster operation result

@param fromId the operated user jid

@param type type code of operation

@param returntype return type

*/

- (void)receiveRosterMsg:(NSString *)fromId

CmdType:(CdtRosterCommandType) type ReturnType:(CdtReturnType)

returntype;

/*!

@function

@abstract receive roster subscribe message

@param fromId the operated user jid

@param type type code of operation

@param msg subscribe message content

Delegates

OL-25913-01 107

*/

- (void)receiveRosterSubscribeMsg:(NSString *)fromId

CmdType:(CdtRosterCommandType) type Message:(NSString*) msg;

@end

MessageDelegate

MessageDelegate declares the protocol functions for client to process a general message from server.

Class MessageController is used to perform the specific delegate function, user call sharedSingleton to get a shared instance of MessageController, and register its delegate to corresponding user class which implement the delegate function.

Protocol define:

@protocol MessageDelegate <NSObject>

/*!

@function

@abstract receive message from user

@param jid resoruce jid

@param body message body

@param subject message subject

*/

- (void)receiveMessageFrom:(const NSString*)jid

Body:(const NSString*) body

Subject:(const NSString*)

subject;

/*!

@function

@abstract receive chat state change from user

@param jid resoruce jid

@param type chat state of user

*/


108 OL-25913-01

- (void)receiveChatStateChangeFrom:(const NSString*)jid

Type:(const

CdtChatStateType)type;

@end

PubsubDelegate

PubsubDelegate declares the protocol functions for client to process pubsub related messages from server.

Class PubsubController is used to perform the specific delegate function, user call sharedSingleton to get a shared instance of PubsubController, and register its delegate to corresponding user class which implement the delegate function.

Protocol define:

@protocol PubsubDelegate <NSObject>

/*!

@function

@abstract receive subscription result from user


@param node pubsub node

@param type return type

*/

- (void)receiveSubscription:(const NSString*)serviceid

Node:(const NSString*)

node

ReturnType:(const

CdtReturnType)type;

/*!

@function

@abstract receive unsubscription result from user



*/

- (void)receiveUnsubscription:(const NSString*)serviceid

Node:(const NSString*)node ReturnType:(const CdtReturnType) type;

Delegates

OL-25913-01 109

/*!

@function

@abstract receive publish item result from user



@param payloadid payload string

@param itemid id string


*/

- (void)receivePublish:(const NSString*)serviceid

Node:(const NSString*) node

PayloadID:(const NSString*) payloadid

ItemID:(const NSString*)itemid

ReturnType:(const CdtReturnType) type;

/*!

@function

@abstract receive subscription result from user


@param list nodes in the service id

*/

- (void)receiveDiscoveryNodes:(const NSString*)serviceid

List:(const

CdtNodeList) list;

/*!

@function

@abstract receive publish notification from user



@param payload payload string

@param itemid id string

*/

- (void)receiveNotification:(const NSString*)serviceid


110 OL-25913-01

Node:(const NSString*)

node

Payload:(const NSString*)

payload

ItemID:(const

NSString*)itemid;

@end

OL-25913-01 111

Conductor leverages the XMPP (Extensible Messaging and Presence Protocol) as its data and messaging fabric supports the creation of a scalable cloud infrastructure (e.g. Iaas) to which both clients and services can connect simultaneously. Cisco Conductor server team has defined Conductor service delivery protocol based on the XMPP IQ stanza.

Conductor service running in the cloud and client running on an Android phone will exchange data based on the Conductor service delivery protocol. Conductor SDK for Service on Android will help Android developers to construct service requirement IQ stanza or extract data from service response IQ stanza.

This SDK package also provides an automatic WSDL tool to help developers generate stub functions, so that Android developers don't need to worry about how to process the Conductor service delivery protocol IQ stanza. They only need to invoke stub APIs with Java programming language and focus on the service business logic.

5 Chapter 5 Conductor Service Development on Android

In This Chapter

Develop Environment Requirements .............................................. 112

Develop Conductor Service-Based Applications on Android Platform ................................................................................................ 113

Chapter 5 Conductor Service Development on Android

112 OL-25913-01

Develop Environment Requirements Cisco Conductor SDK for Service on Android is designed for Android platform Conductor service based application development. Users should install Google Android SDK and all necessary plug-ins. There is a very detailed description in chapter 2 of the Conductor Client SDK User Guide for Java (EDCS-1083882).

In addition to the Android development environment, a running Conductor service in remote Conductor server is necessary. In order to develop a Conductor service and run it, developers can refer to the Conductor Service SDK developer guide (EDCS-1083437).

Develop Conductor Service-Based Applications on Android Platform

OL-25913-01 113


This section provides steps to develop Conductor service on the Android platform with Client SDK and run an example in the release package.

The following flow chart gives an overview of how to develop Conductor service on Android:

1 Create the Conductor service for Android client project.

Create a new Android project. For more information, refer to http://zed.cisco.com/confluence/display/SPVTG/Conductor+Client+SDK+Android+API or http://developer.android.com/sdk/installing.html


114 OL-25913-01

2 Import the Conductor SDK libs for Service on the Android platform from the release package.

Add all Client SDK jars to the project building path.

3 Get the WSDL file and target service JID from service developer.

4 Generate the client stub codes and put them into project source code folder.

Run the WSDL tool script from release package to generate stub code:

wsdl2java –d c:/demodir –p demo.client.stub c:/SimpleTwitterService.wsdl

5 Implement your own service filter:

Service Virtualization addresses Virtual service (VS) as a logic service which includes a set of same service instances (SI). The name space (NS) is the identity of VS. The format example of NS is as follows: conductor://cisco.com/videoService#xxx. ‘conductor’ is protocol header, ‘xxx’ normally is service version. It's possible to discover several version services running at one time, as follows:

conductor://cisco.com/videoService#1.0.0

conductor://cisco.com/videoService#1.1.1

In order to choose one of the discovered VS to invoke, you must implement a filter class to decide which one of the services to use as target service. The filter example code is shown in step 5 of Create Your Own Android Conductor Service Client Project (on page 119).

6 Write code to generate a service reference. You need a new ‘xxxLocator’ class which is already in stub code folder generated from previous step. Get the service’s ‘xxxPortType’ [xxx standards for service name related string].

7 Write code to invoke service operations. You can directly call member methods in ‘xxxPortType’ to invoke remote service.

Important: Before doing this, make sure that the Android client has already logged in to the XMPP server and implemented the virtual service filter.

A very typical example code is shown in #Code2, #Code4 in Create Your Own Android Conductor Service Client Project (on page 119).

8 Build, install & run the service client program on the Android platform.

Build the project with the ‘ant’ tool, following the build script in the example project. You will get an *.apk file. Install this file to the Android phone, and run it.

These steps give you an overview to develop Conductor service on Android client with Conductor SDK. In later sections, we will give you more details by introducing an example project in the release package.

Import and Run Sample Code 1 Take the sample code in the folder ‘example/ CdtServiceExample’ in the release

package.


OL-25913-01 115

2 Start Eclipse IDE, and Click ‘File>Import…’

3 A submenu appears as shown below:

Choose ‘General>Existing Projects into Workspace’, then click ‘Next’ button.


116 OL-25913-01

4 Another submenu appears:

5 Click ‘Browse…’ button, and put project location, and click ‘Finish’ button.

6 Now you can see the project from Eclipse package explorer


OL-25913-01 117

7 If the jars in the lib folder are not in the reference lib list, select all jars in lib folder, and right click, then select ‘Build Path>Add to Build Path’ as shown below:


118 OL-25913-01

8 Now you can see that all of the jars are in the building path.


OL-25913-01 119

9 Make sure the android SDK path is set correctly by checking the Eclipse menu ‘Window>Preferences>Android’:

10 Build and run the Android service client project by right-clicking the project name in the package explorer in Eclipse, and selecting ‘Run As>Android Application’

Then from the DDMS window, you can see the running output.

Create Your Own Android Conductor Service Client Project

You can use sample project in release package as a project template to create your own project. We can follow the steps listed at the beginning of this chapter.

1 Create the Android project in Eclipse;

2 Copy the ‘lib’ folders from the release package, and put them into your project root directory. Remove unnecessary jar files -- wsdl4j-1.5.1.jar & jaxrpc.jar.


120 OL-25913-01

3 Copy the ‘bin’ & ‘lib’ folders from the release package, and put them in any place you want in your computer. Make sure both folders are in the same directory.

4 Get the service WSDL xml file from service developers and service JID, and run the script in the ‘bin’ folder to generate stub functions:

bin\ folder\dir\wsdl2java.bat -d c:\output -p com.cisco.example c:\xml\example.wsdl

‘-d’ parameter indicates the stub files output location;

‘-p’ parameter indicates the stub classes package name;

The last input ‘c:\xml\example.wsdl’ indicates where the WSDL xml file are located.

Note: if you want to generate stub code in Windows OS, you must enter ‘bin’ folder, otherwise this tool will not run.

When you run this command, you can get the stub files in directory c:\output. Copy all stub files to your android project directory, or you can change ‘c:\output’ directory into your Android project root;

5 Start service client coding. Following is an example for PrintService:

a Implement the virtual service filter class. Your implementation must extend from the parent class ‘VSFilterImpBase’ and override the method ‘filter’, as shown in this example code:

package xxxxx

import java.util.Iterator;

import com.cisco.conductor.client.service.virtualization.*;

import java.util.Iterator;

import org.apache.axis.javax.xml.rpc.ServiceException;

import com.cisco.conductor.client.service.ExceptionCodeConstants;

import com.cisco.conductor.client.service.virtualization.*;

public class HelloWorldServiceFilter extends VSFilterImpBase {

@Override

public ServiceInfo filter(VirtualService vs) throws ServiceException

{

String filterkey = "1.5.0";

Iterator<ServiceInfo> i = vs.getServiceInfos().iterator();

while(i.hasNext())

{

ServiceInfo info = i.next();

// adding your code to filter out the service info you want, and

// return to service request part for remote service invocation

// this is an example

if(info.getVersion().endsWith(filterkey))


OL-25913-01 121

{

return info;

}

}

throw new

ServiceException(ExceptionCodeConstants.FilterProcessErrorCode,

"No service found for key-"+filterkey,

"No service found for key-"+filterkey);

}

}

Class ‘VirtualService’ and ‘ServiceInfo’ public methods definition can

refer to appendix

b Service invoke coding

……

CdtMisc misc = new CdtMisc();

String serverName = "jsm.conductortest";

String serverIpAddress ="10.74.27.153";

int portNumber = 5222;

String userName = "jerry";

String userPassword = "jerry";

String resource = "jerry";

//---------------------- login to Conductor server #Code 1 ----------------------

---

misc.login(serverName, serverIpAddress, portNumber, userName, userPassword,

resource);

//-------------------- get PrintService PortType #Code 2 -----------------

PrintServicePortType portType = null;

PrintServiceLocator serviceLocator = new PrintServiceLocator();

portType = serviceLocator.getPrintServicePort();

//---------------------- configure PrintService Info #Code 3 --------------------

-

String serviceNameSpace = "conductor://cisco.com/demo/helloforit";

HelloWorldServiceFilter filter = new HelloWorldServiceFilter();

try{

serviceLocator.cfgServiceInfo (serviceNameSpace,filter);


122 OL-25913-01

}catch{

//make sure virtual service information is got normally

System.out.println("error msg:"+e.getMessage());

return;

}

//----------------------- Service Invocation #Code 4 ----------------------------

//invoke printInt remote method

Integer input = 10;

Integer ret = null;

try{

ret = portType.printInt(input);

System.out.println("remote method - printInt return value:"+ret);

}catch (RemoteException e) {

System.out.println("error code:"+e.getExceptionCode());

System.out.println("error String:"+ e.getExceptionString());

System.out.println("error detail:"+e.getExceptionDetail());

}

……

Classes or APIs showed in RED color are from automatically generated

stub code

6 After finish the coding, we can start to build Android project. Please follow steps 6 through 9 in Import and Run Sample Code (on page 114).

OL-25913-01 123

If You Have Questions

If you have technical questions, call Cisco Services for assistance. Follow the menu options to speak with a service engineer.

Access your company's extranet site to view or order additional technical publications. For accessing instructions, contact the representative who handles your account. Check your extranet site often as the information is updated frequently.

6 Chapter 6 Customer Information

OL-25913-01 125

A Appx auto letter Appendix A Additional Information This appendix contains information that may be necessary to develop applications for Android devices.

In This Appendix

Type Supported by Data binding in Client SDK ............................ 126

wsld 2java Script Usage ..................................................................... 127

Conductor-Defined Error Code/Error String ................................. 128

Classes Defined for Customized Filter Implementation ............... 129

Appendix A Additional Information

126 OL-25913-01

Type Supported by Data binding in Client SDK

# Java Data Type Data Type In XML

Java Data Type From XML Note

1 Boolean/boolean xs:boolean Boolean/boolean

2 Integer/int xs:int Integer/int

3 Byte/byte xs:byte Byte/byte

4 Character/char xs:unsignedShort org.apache.axis.types.UnsignedShort in 0~65535

5 Double/double xs:double Double/double

6 Float/float xs:float Float/float

7 Long/long xs:long Long/long

8 Short/short xs:short Short/short

9 String xs:string String

10 Date xs:datetime Calendar

11 Calendar xs:datetime Calendar

12 List xs:string Array

13 Set xs:string Array

14 Array xs:string Array

15 Map xs:complexType Map*

Note: For Calendar type, all send out data will be automatically converted into GMT 0 time; if the response xml data type is ‘xs:datetime’, it will be automatically converted into local time base on Android phone locale information.

wsld 2java Script Usage

OL-25913-01 127

wsld 2java Script Usage

# Parameter Description Note

1 -d Location to store output stub files

2 -p stub classes package name

3 -h print help information

Example:

wsdl2java –d c:/example –p example.client.stub c:/example.wsdl

Run this command will get stub files in directory c:/example from WSDL file ‘example.wsdl’ located in c:\, and all stub classes is in package namespace:

example.client.stub

[Please notice: if you want to generate stub code in Windows OS, you must enter ‘bin’ folder, otherwise you can’t make this tool run.]

Appendix A Additional Information

128 OL-25913-01

Conductor-Defined Error Code/Error String

Error Code Error String Error detail

Codes below 1000 are assigned to XCP system:

400 Bad request Bad request

402 Payment required Payment required for this service

403 Not Authorized Not authorized for this service

404 Remote service not found

Remote Service not found

500 Internal Error Internal error occur

503 Service unavailable Service unavailable, please try again

504 Service Time Out Remote service timeout

Codes between 1000 to 2000 are assigned to conductor service call:

1001 Error Format message xml content

1002 No Such Operation Method ${concrete method} doesn’t exist

2000 Service Error General Service Error Information

Codes above 2000 are for customer design:

2001 Discovery node error

2002 Filter result is empty Filter result is empty; no target service can be invoked

2003 Filter processing error Filter processing error

2004 Virtual service domain or filter to be discovered is null

Virtual service domain or filter to be discovered is null

2005 XMPP connection with Conductor server has not setup successfully

XMPP connection with Conductor server has not setup successfully

2006 Service client side has not login successfully

Service client side has not login successfully

Classes Defined for Customized Filter Implementation

OL-25913-01 129

Classes Defined for Customized Filter Implementation Package com.cisco.conductor.client.service.virtualization Note

Class VirtualService

Public methods

void addServiceInfoItem(ServiceInfo info)

add serviceInfo item

Set<ServiceInfo> getServiceInfos() get VS service info set

Package com.cisco.conductor.client.service.virtualization Note

Class ServiceInfo

Public methods

String getLocation() get VS Jid

String getBareNs() get VS bare namesapce

String getVersion() get VS version

Cisco Systems, Inc. 5030 Sugarloaf Parkway, Box 465447 Lawrenceville, GA 30042

678 277-1120 800 722-2009

www.cisco.com

This document includes various trademarks of Cisco Systems, Inc. Please see the Notices section of this document for a list of the Cisco Systems, Inc. trademarks used in this document. Product and service availability are subject to change without notice.

© 2012 Cisco and/or its affiliates. All rights reserved. November 2012 Printed in USA

Part Number OL-25913-01

Date post:	18-Jul-2020
Category:	Documents
Upload:	others
View:	20 times
Download:	0 times

Cisco Conductor Client SDK Developer's Guide · Cisco Conductor Client SDK for Java is designed for...

Documents