Polycom ReadiVoice CAPI Developer's Manual

ReadiVoice CAPI

Developer’s Guide

ReadiVoice CAPI Developer’s Guide

Trademark Information

Polycom®, the Polycom logo design, ReadiVoice®, InnoVox®, and the Voyant logo are registered
trademarks of Polycom, Inc. Voyant Technologies

TM

is a trademark of Polycom, Inc. All other trademarks

are the property of their respective owners.

Patent Information

The accompanying product is protected by one or more U.S. and foreign patents and/or pending patent
applications held by Polycom, Inc.

Catalog No. 3725-70047-009A

v2.55.x

© 2005 Polycom, Inc. All rights reserved.

Polycom Inc.

1765 West 121st Avenue

Westminster, CO 80234-2301 U.S.A.

No part of this document may be reproduced or transmitted in any form or by any means, electronic or
mechanical, for any purpose, without the express written permission of Polycom, Inc. Under the law,
reproducing includes translating into another language or format.

As between the parties, Polycom, Inc. retains title to, and ownership of, all proprietary rights with respect
to the software contained within its products. The software is protected by United States copyright laws
and international treaty provision. Therefore, you must treat the software like any other copyrighted
material (e.g. a book or sound recording).

Every effort has been made to ensure that the information in this manual is accurate. Polycom, Inc. is not
responsible for printing or clerical errors. Information in this document is subject to change without notice.

ii Proprietary & Confidential

Contents

Introducing CAPI

Purpose . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi

Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii

Customer Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii

CAPI Functional Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1

CAPI Technical Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2

ReadiVoice and CAPI Application Architecture . . . . . . . . . . . . . . . . . . . 2

CAPI SDK Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Code Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

Overview of CAPI Enhancements in This Release . . . . . . . . . . . . . . . . . . . . . 4

Getting Started . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4

Developing CAPI Applications

Writing Your CAPI Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5

Installing CAPI Code and Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

System Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

Software . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

ReadiVoice . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

CAPI Installation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Accessing the Documentation and Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 7

Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Understanding CAPI Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8

Understanding CAPI Communication: Synchronous and Asynchronous . 9

Understanding How Ports Are Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Pull Mode and Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Sending Port on the Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Receiving Port on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Push Mode and Ports . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Sending Port on the Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Proprietary & Confidential iii

ReadiVoice CAPI Developer’s Guide

Receiving Port on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Sending Port on the Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Receiving Port on the Client . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Ports and Firewalls . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

Understanding Connections, Sessions, and Logins . . . . . . . . . . . . . . . . . . . 12

Overview of Connections, Sessions, and Logins . . . . . . . . . . . . . . . . . . 12

Application, Moderator, and Participant Logins . . . . . . . . . . . . . . . . . . 13

High-Level Overview of the Conferencing Process . . . . . . . . . . . . . . . 14

Relationships Among Connections, Sessions, and Logins . . . . . . . . . . 14

Basic Relationships . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Login and Session Combinations . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

Login, Session, and Connection Combinations . . . . . . . . . . . . . . . 15

Illustrations of Connection, Session, Conference, and Login

Configurations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16

Benefits and Drawbacks . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18

Considerations for Number of Connections to Use . . . . . . . . . . . . 18

Considerations for Logins . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19

CAPI SDK Components . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Understanding the CAPI Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Push and Pull Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Events Can Be Run By Certain Login Types . . . . . . . . . . . . . . . . . . 20

Responses Versus Notifications . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20

Using the Event Reference Section . . . . . . . . . . . . . . . . . . . . . . . . . . 21

Understanding the CAPI Java Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21

CAPI Java Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22

CAPI Java File Quick Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24

Connecting the CAPI Events and the Java Utility Files . . . . . . . . . 26

Programming Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 28

How the ODPROC and the CSC Work Together . . . . . . . . . . . . . . . . . 28

Application Design and Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . 28

Choosing a Programming Language . . . . . . . . . . . . . . . . . . . . . . . . 28

Object Model Layer . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Storing Configuration Information . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Programming Fundamentals . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Using ACM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30

Using Push and Pull Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 31

Using the Login Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Creating a Connection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Maintaining Open Sessions and Connections . . . . . . . . . . . . . . . . . 33

Programming Tips . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33

Notes on Conference, Participant, and Subscriber IDs . . . . . . . . . 34

Database Conference Information Updates . . . . . . . . . . . . . . . . . . 34

Prerequisites: Connection and Conference, and Session and

Conference IDs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

iv Proprietary & Confidential

Contents

Verifying Events Have Occurred . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

Multiple Requests of Same Event and the Passback parameter . . 35

Implementing the Conference Security Code . . . . . . . . . . . . . . . . . 36

Response to Malformed XML and HTTP . . . . . . . . . . . . . . . . . . . . 36

Dial String Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 36

Commonly Used Conferencing Procedures . . . . . . . . . . . . . . . . . . . . . . . . . 37

Additional Sources of Information . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Procedure Sequence . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Procedure Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Content of Procedures in This Section . . . . . . . . . . . . . . . . . . . . . . . 39

Push Mode Versus Pull Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Application Login Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Initial Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Setting up Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Connecting to the CACS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Maintaining an Open Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Logging Into the CACS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44

Conference Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Starting a Conference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

Saving Conference and Subscriber ID . . . . . . . . . . . . . . . . . . . . . . . 47

Registering the Application Login for Conference Start and Stop

Notification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47

Setting Conference Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Dialing Participants . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Joining a Conference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Using the Waiting Room . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52

Setting the Port for Asynchronous Responses on the Client . . . . 53

Sending Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56

Reading Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Identifying Talkers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58

Using ACM to Interface With External Applications . . . . . . . . . . 59

Conference-End Procedures . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Ending a Conference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 60

Logging Out . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61

Sample Moderator Application . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

SimplePushModerator.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63

SimplePushModeratorHandler.java . . . . . . . . . . . . . . . . . . . . . . . . . . . . 83

Migrating Applications to CAPI

Migration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89

Compatibility Notes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 90

MAPI-to-CAPI Sample Application Comparison . . . . . . . . . . . . . . . . . . . . . 91

Proprietary & Confidential v

ReadiVoice CAPI Developer’s Guide

CAPI Events

Enumerated Types . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 124

ACM_MODE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 125

ACM_REASON_CODE Enum Values . . . . . . . . . . . . . . . . . . . . . . 125

ACM_TYPE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

ANNOUNCEMENT_OPTION Enum Values . . . . . . . . . . . . . . . . 126

CALLFLOW Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 126

CALL_MODE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

CANCELATION_REASON Enum Values . . . . . . . . . . . . . . . . . . 127

CI_REASON Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 127

CONF_RUN_STATE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . 128

LOCK_STATE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

LOCK_TYPE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 128

NACK_REASON Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

OP_REQ_PRIV Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 129

OP_REQ_TYPE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

PART_STATUS Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 130

PART_TYPE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

PI_REASON Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

SI_REASON Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 131

WAV_TYPE Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

WR_OPTION Enum Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 132

SIMPLE_CANCELATION_REASON Enum Values . . . . . . . . . . 132

CAPI Request Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

ACM_CALL_ENTER (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 134

ACM_CDR (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135

ACM_GET_DTMF (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 136

ACM_GET_OPTIONS (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 137

ACM_HEARTBEAT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 138

ACM_PLAY_WAV (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139

ACM_QUERY (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 140

ACM_REGISTER (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 141

ACM_UNREGISTER (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142

ADD_CONTACT_ENTRY_TO_GROUP (CAPI) . . . . . . . . . . . . . 143

APP_REGISTER_CONFS_ACTIVITY (CAPI) . . . . . . . . . . . . . . . . 144

APP_REGISTER_SUBSCR (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . 145

APP_UNREGISTER_CONFS_ACTIVITY (CAPI) . . . . . . . . . . . . . 146

APP_UNREGISTER_SUBSCR (CAPI). . . . . . . . . . . . . . . . . . . . . . . 147

CONF_PLAY_WAV (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 148

CONF_ROLLCALL (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 149

CREATE_CONTACT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 150

CREATE_CONTACT_GROUP (CAPI). . . . . . . . . . . . . . . . . . . . . . 151

DIAL_CALL (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 152

DIAL_GROUP (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 154

DISCONNECT_CALL (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 155

vi Proprietary & Confidential

Contents

END_CONF (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 156

JOIN_PART_TO_CONF (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . 157

LOCK_CONF (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 158

LOGIN_APPLICATION (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . 159

LOGIN_MODERATOR (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 160

LOGIN_PART (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 161

LOGIN_PUSH_MODERATOR (CAPI). . . . . . . . . . . . . . . . . . . . . . 162

LOGOUT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 163

MUTE_ALL (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 164

MUTE_CALL (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 165

ONE_TO_ONE (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 166

OPERATOR_KNOCKING (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . 167

PLAY_NAME (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 168

REGISTER_TALKER_UPDATE (CAPI) . . . . . . . . . . . . . . . . . . . . . 169

REMOVE_CONTACT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 170

REMOVE_CONTACT_ENTRY_FROM_GROUP (CAPI) . . . . . . 171

REMOVE_CONTACT_GROUP (CAPI) . . . . . . . . . . . . . . . . . . . . . 172

REMOVE_PART (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 173

REQ_CONF_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 174

REQ_CONTACT_GROUP_INFO (CAPI). . . . . . . . . . . . . . . . . . . . 175

REQ_CONTACT_GROUP_LIST (CAPI) . . . . . . . . . . . . . . . . . . . . 176

REQ_CONTACT_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 177

REQ_CONTACT_INFO_SEARCH (CAPI). . . . . . . . . . . . . . . . . . . 178

REQ_CONTACT_LIST (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 179

REQ_PART_INFO (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 180

REQ_PART_LIST (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 181

REQ_SESSION_INFO (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 182

REQ_SUBSCR_ID_BY_ACCESS_DATA (CAPI) . . . . . . . . . . . . . . 183

REQ_SUBSCR_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 184

REQ_SYSTEM_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 185

SESSION_HEARTBEAT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . 186

SET_ANNOUNCEMENT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . 187

SET_AUTO_CONT (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 188

SET_CONF_CONT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 189

SET_CONF_MODE (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 190

SET_CONF_SECURITY_CODE (CAPI) . . . . . . . . . . . . . . . . . . . . . 191

SET_CONTACT_GROUP_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . 192

SET_CONTACT_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 193

SET_LISTEN_ONLY_ENTRY (CAPI) . . . . . . . . . . . . . . . . . . . . . . . 195

SET_LOCK_TYPE (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 196

SET_NAME_RECORD (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197

SET_OP_REQ (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198

SET_PART_NAME (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199

SET_QUICK_START(CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 200

SET_SUBSCR_ANNOUNCEMENT (CAPI). . . . . . . . . . . . . . . . . . 201

SET_SUBSCR_NAME_RECORD (CAPI) . . . . . . . . . . . . . . . . . . . . 202

Proprietary & Confidential vii

ReadiVoice CAPI Developer’s Guide

SET_WAITING_ROOM_OPTION (CAPI) . . . . . . . . . . . . . . . . . . . 203

START_CONF (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 204

UNLOCK_CONF (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 205

UNMUTE_ALL (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206

UNMUTE_CALL (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 207

UNREGISTER_TALKER_UPDATE (CAPI) . . . . . . . . . . . . . . . . . . 208

CAPI Response Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

ACK (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 209

ACM_CALL_ENTER_ACK (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . 210

ACM_CALL_ENTERED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . 211

ACM_CALL_LEAVE (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 212

ACM_CALL_LEFT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 213

ACM_DTMF (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 214

ACM_HEARTBEAT_ACK (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . 215

ACM_HEARTBEAT_FAILURE (CAPI) . . . . . . . . . . . . . . . . . . . . . 216

ACM_OPTIONS (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 217

ACM_QUERY_RESP (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 218

ACM_REGISTERED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 219

ANNOUNCEMENT_CHANGED (CAPI) . . . . . . . . . . . . . . . . . . . 220

APPLICATION_SESSION_INFO (CAPI). . . . . . . . . . . . . . . . . . . . 221

BRIDGE_LOGOUT (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222

BRIDGE_STATUS_CHANGED (CAPI) . . . . . . . . . . . . . . . . . . . . . 223

BRIDGE_UP (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 224

CALL_CONNECTED_TO_CHANGED (CAPI) . . . . . . . . . . . . . . 225

CALL_DISCONNECTED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . 226

CALL_LEFT_CONF (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 227

CALL_MODE_CHANGED (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . 228

CALL_STATUS_CHANGED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . 229

CONF_CONT_CHANGED (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . 230

CONF_ENDED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 231

CONF_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 232

CONF_INFO_CHANGED (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . 234

CONF_LOCK_CHANGED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . 235

CONF_MODE_CHANGED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . 236

CONF_SECURITY_CODE_CHANGED (CAPI) . . . . . . . . . . . . . . 237

CONF_STARTED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 238

CONTACT_CREATED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 239

CONTACT_GROUP_CREATED (CAPI) . . . . . . . . . . . . . . . . . . . . 240

CONTACT_GROUP_INFO (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . 241

CONTACT_GROUP_INFO_CHANGED (CAPI) . . . . . . . . . . . . . 242

CONTACT_GROUP_LIST (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . 243

CONTACT_GROUP_REMOVED (CAPI) . . . . . . . . . . . . . . . . . . . 244

CONTACT_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 245

CONTACT_INFO_CHANGED (CAPI) . . . . . . . . . . . . . . . . . . . . . 247

CONTACT_LIST (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 248

CONTACT_REMOVED (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . 249

viii Proprietary & Confidential

Contents

DIALOUT_CONNECTED (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . 250

DIALOUT_STARTED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 251

GROUP_CONTACT_ENTRY_ADDED (CAPI). . . . . . . . . . . . . . . 252

GROUP_CONTACT_ENTRY_REMOVED (CAPI). . . . . . . . . . . . 253

LOCK_TYPE_CHANGED (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . 254

MODERATOR_SESSION_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . 255

NACK (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 256

OP_REQ_ANSWERED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 257

OP_REQ_CANCELED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 258

OP_REQUESTED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 259

PART_INFO (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 260

PART_INFO_CHANGED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . 262

PART_LIST (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263

PART_NAME_CHANGED (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . 264

PART_SESSION_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . 265

PART_TYPE_CHANGED (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . 266

SESSION_HEARTBEAT_ACK (CAPI) . . . . . . . . . . . . . . . . . . . . . . 267

SUBSCR_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 268

SUBSCR_INFO_CHANGED (CAPI). . . . . . . . . . . . . . . . . . . . . . . . 271

SYSTEM_INFO (CAPI) . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 272

TALKER_UPDATE (CAPI). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 273

Proprietary & Confidential ix

ReadiVoice CAPI Developer’s Guide

x Proprietary & Confidential

About this Manual

This introduction provides a brief overview of the ReadiVoice CAPI Developer’s
Guide, describes the conventions used in this manual, and explains how to get

additional information or support.

Purpose

This manual is for developers of a conferencing application. It includes
information about:

• CAPI architecture and process flow

• Writing new conferencing applications using CAPI

• Migrating MAPI applications to the new CAPI

• CAPI events

CAPI applications interact with the ReadiVoice system. To write applications
using CAPI, you need to understand a ReadiVoice CAPI system, its access
type options, its conferencing features and options, and how provisioners,
operators, and other users use the system. We recommend that you review the
information in the following documents:

• Read

• Re

• Re

• Re

iVoice Provisioning Guide

adiVoice Operator Guide

adiVoice Subscriber Guide

adiVoice Administration and Maintenance Guide

Proprietary & Confidential xi

ReadiVoice CAPI Developer’s Guide

Document Conventions

This document uses the following typographical conventions.

Typeface Usage
bold Names of fields, screens, windows, dialog boxes,

italics New terms, book titles, or emphasis; for example:

and other user interface elements; for example:

1 Type the number into the Phone Number

field and click Dial.

2 Click Cancel to close the dialog box.

According to the VERITAS Cluster Server User
Guide, crash tolerant applications are sometimes
referred to as cluster friendly applications.

code

code, bold

code, bold & italics

Computer output, command references within text,
and filenames; for example:

Performs the initial configuration and reads the

.vcsrc

file

Command line entries, for example:

>>

Type

cp ../default_group.ini

group.ini

Command line variables, for example:

>>

Type

groupnn.ini

.

cp ../default_group.ini

replacing

nn

with the

subscriber group number.

SMALL CAPS Specific keys on the keyboard, for example:

>>

Move the cursor by pressing TAB or

SHIFT+TAB.

xii Proprietary & Confidential

Customer Support

Recognizing that technology alone cannot solve today’s complex challenges,
Polycom Global Services provides the industry’s best technical support staff
and programs to let you concentrate on the task at hand. ReadiVoice CAPI
users can select from a variety of support solutions to obtain the level of
support that best meets their needs.

Before contacting your Polycom Global Services representative for technical
assistance, gather as much information as possible about your situation. Any
information you can provide helps us assess the problem and develop an
appropriate solution.

Polycom Global Services Telephone and Email

If you have comments or questions about ReadiVoice CAPI or if you need
technical assistance, contact:

About this Manual

• Polycom Global Services in U.S.A

• Denver metro or outside U.S.A.

• Email: [e-mail]

Polycom Global Services on the Web

For more information about Polycom Global Services, go to

http://www.polycom.com and select the Support Solutions link under the

Global Services category.

Polycom Technical Publications Department

If you have comments or questions about this or any other ReadiVoice CAPI
documentation, contact:

Polycom Technical Publications Department
1765 West 121st Avenue
Westminster, CO 80234-2301 U.S.A.

Email: [e-mail]

800-827-7782
303-223-5223

Proprietary & Confidential xiii

ReadiVoice CAPI Developer’s Guide

xiv Proprietary & Confidential

Introducing CAPI

CAPI allows you to write applications to access the conferencing functions of
the ReadiVoice system. ReadiVoice is the industry-leading, on-demand
conferencing system. It provides an easy-to-use, reliable, scalable, and
full-featured conferencing solution.

This chapter contains the following high-level overview information.

• “CAPI Functional Overview” on page 1

1

• “CAPI Technical Overview” on page 2

• “Overview of CAPI Enhancements in This Release” on page 4

• “Getting Started” on page 4

The subsequent chapters in this guide provide technical detail on developing
and migrating applications.

CAPI Functional Overview

Note: For more information on ReadiVoice features, refer to the ReadiVoice
documentation suite. The following in particular are recommended:

• ReadiVoice CAPI Provisioning Guide

• ReadiVoice CAPI Operator Guide

• ReadiVoice CAPI Subscriber Guide

• ReadiVoice CAPI Administration and Maintenance Guide

ReadiVoice lets subscribers launch and control conferences at any time, using
touchtone or web interface. It isn’t necessary to make reservations ahead of
time or restrict time limits. The features users need to set up and control
conferences is provided in the conferencing application you write using CAPI,
and in the ReadiVoice system that the application connects to. Your CAPI
application can be run as an applet in a browser with a Java 1.4 or higher
plugin, or can be run as a standalone application with a compatible JVM.

Proprietary & Confidential 1

ReadiVoice CAPI Developer’s Guide

CAPI Technical Overview

If you’re not familiar with conferencing applications or ReadiVoice, refer to
the ReadiVoice documentation suite, focusing on the Provisioning Guide and
Subscriber Guide.

ReadiVoice and CAPI Application Architecture

The CAPI tools in this product let you write a client application that interacts
with a ReadiVoice system. A ReadiVoice system has three main parts: the
conferencing client application, the CACS that is the core of the conferencing
system, and the bridges and ports where the conferences take place.

A CAPI client application connects to the CACS, which interacts with and
controls the behavior of the bridges.

You can send two types of messages from the client application to the CACS.

• Synchronous communication, or pull, means a request is sent and the
response is sent back immediately on the same connection.

• Asynchronous communication, or push, means a request is sent and either
a response is not required, or a response is sent later after the information
requested has been obtained, on another connection.

CAPI provides two types so that you can use synchronous communication
when you need it for a stateless protocol, or asynchronous communication for
a more robust set of features.

The overall architecture is shown in Figure 1-1. Synchronous pull mode
communication takes place over the top connection; asynchronous push mode
communication takes place going from client to server over the top connection,
with the response coming back over the bottom connection.

Figure 1-1 ReadiVoice system architecture

2 Proprietary & Confidential

CAPI SDK Components

The heart of CAPI is a set of events that provide functionality. The CAPI
product, however, has far more than just the schema. Polycom provides a set
of tools to make development far quicker and easier—and more reliable—than
simply writing all your code from scratch.

CAPI provides this in the form of a robust set of teleconferencing events in an
XML schema, Java versions of those events already generated for you, plus
Java code that takes care of the complex networking tasks for you such as
networking connections and other tasks.

Note: This guide assumes that you will be writing your application in Java,
using the provided utility and communication files. If you will not be, refer to
use the schema and the detailed event documentation to develop your
application.

Code Files

The new CAPI SDK contains the following components.

Introducing CAPI

• An XML schema defining conferencing events, composing the XML layer
of the API.

• Four types of Java files, built on top of the XML layer, composing the Java
layer of the API.

— Core communication files, which interact with CACS and the core

utility files.

— Core utility files, which interact with the core communication files.

— Castor utility files, which interact with the event files and implement

the core utility files.

— Castor event files, generated from the CAPI schema using the Castor

program. (To learn more about Castor, see www.castor.org.)

Documentation

CAPI also provides a complete set of technical documentation.

• This guide includes procedures for common tasks like logging into the
system, creating a conference, and dialing participants, with sequence
diagrams and explanations of key points.

• Javadocs for the CAPI Java files.

• Simple example application.

Proprietary & Confidential 3

ReadiVoice CAPI Developer’s Guide

Overview of CAPI Enhancements in This Release

CAPI is the latest release of Polycom’s powerful teleconferencing API. Key
enhancements include the following:

• CAPI encapsulates the server components from the conferencing
application, making it easier to write and maintain CAPI applications

• CAPI is XML-based, allowing developers to write applications in a variety
of programming languages. Java utility files and event files are provided,
as well.

• A new login type, Application, is available. The Application is like a
super-moderator, and can monitor several conferences at once. One
capability of the Application is the ability to receive notifications of all
conferences being created and ended.

• A conference can have multiple subscriber and participant logins.

• Log4j and Apache Common Logging have been used to provide logging

functionality.

Getting Started

• CAPI uses XML for all transport. Use of XML allows for better
backward-compatibility between different versions of ReadiVoice.

Note: A MAPI application is compatible with the new release of
ReadiVoice. However, a CAPI application is not compatible with the
previous version of ReadiVoice.

• An ACM event set is provided to allow CAPI applications to interface with
external applications.

• Asynchronous and synchronous functionality is available. Asynchronous
event notifications for conference and participants allow for instant
notification for any change in participant or conference state. Notification
that requires that some information be generated and returned is sent
asynchronously through a second connection.

If you’re new to CAPI, continue to Chapter 2, “Developing CAPI
Applications.” This chapter, combined with the technical reference resources
of the Javadocs and Appendix A, provide what you need to know to write a
conferencing application.

If you’re migrating from MAPI to CAPI, read both Chapter 2, “Developing
CAPI Applications.” and Chapter 3, “Migrating Applications to CAPI.” Use
the technical reference resources of the Javadocs and Appendix A, as well.

4 Proprietary & Confidential

Developing CAPI Applications

Use this chapter and the technical information it references to learn how to
write a conferencing application using CAPI.

This chapter includes the following information:

• “Writing Your CAPI Application” on page 5

• “Installing CAPI Code and Documentation” on page 6

2

• “Accessing the Documentation and Code” on page 7

• “Understanding CAPI Architecture” on page 8

• “Understanding CAPI Communication: Synchronous and

Asynchronous” on page 9

• “Understanding How Ports Are Used” on page 10

• “Understanding Connections, Sessions, and Logins” on page 12

• “CAPI SDK Components” on page 20

• “Programming Guidelines” on page 28

• “Commonly Used Conferencing Procedures” on page 37

• “Sample Moderator Application” on page 63

Note: If you’re migrating from MAPI to CAPI, use this chapter as well as

Chapter 3, “Migrating Applications to CAPI.”

Writing Your CAPI Application

The following list outlines the steps we recommend for learning how to write
CAPI applications.

1 Be sure you’re familiar with conferencing applications. If you aren’t,

review the “CAPI Functional Overview” on page 1 as well as the
additional recommended reading.

2 Install ReadiVoice and CAPI according to the instructions in “Installing

CAPI Code and Documentation” on page 6.

Proprietary & Confidential 5

ReadiVoice CAPI Developer’s Guide

3 Familiarize yourself with the documentation and code provided with

CAPI. See “Accessing the Documentation and Code” on page 7.

4 Review the events and programming information in “CAPI SDK

Components” on page 20, and the technical information in Appendix A

and in the Javadocs, to learn how CAPI events and Java utility files work.

5 Read the “Programming Guidelines” on page 28 to learn how to write

your application.

6 Review the “Sample Moderator Application” on page 63

7 Write your own basic application using the sample as a guideline, to

ensure that core features like connections and creating a conference are
working.

8Add features to the basic application using the Java files and events

provided. Consult the instructions in “Commonly Used Conferencing

Procedures” on page 37, the event migration reference in Appendix A,

and the Javadocs.

Installing CAPI Code and Documentation

Follow the instructions in this section to install the necessary files.

System Requirements

Software

CAPI requires the software listed in this section. Most of the required software
is included with the SDK; Java is not.

Not included in the SDK:

Java 1.4 or higher.

Included in the SDK:

• Castor 0.9.5.3

• Apache Commons Lang 2.0

• Apache Commons Logging 1.0.4

• JUnit 3.8.1

• Log4J 1.2.9

• LogKit 1.2

• XercesImp 1.0

• Xml APIs 1.0

6 Proprietary & Confidential

CAPI Installation

Developing CAPI Applications

ReadiVoice

For ReadiVoice system requirements, see the ReadiVoice installation
instructions.

You can simply copy the provided files to any directory on your system. The
directory structure is as follows:

rvsdk

mapi
capi\rv2550q

\api
\sharedjlib
\simplemoderator

On Solaris, you can also run the install file within the provide CAPI files. That

rvsdk

install program will install the

directory into

/opt

.

Setup

Follow the instructions in the ReadiVoice documentation to set up your
system. This includes setting up system components such as the Apache web
server, configuring the .
recording, and many additional setup tasks.

odprocrc

file for values needed for conference

Accessing the Documentation and Code

Before you get started, we recommend that you bookmark the CAPI
documentation and code components. All documentation and code
components can be accessed from the main CAPI page.

Documentation

The documentation includes:

• Developer’s Guide – This developer’s guide is provided in PDF. You can
view it online and navigate using the bookmarks at the side, or print part
or all of it.

• Javadocs – The Javadocs are provided in standard HTML format.

Proprietary & Confidential 7

ReadiVoice CAPI Developer’s Guide

Code

All documentation and code components can be accessed from the main CAPI
page.

Understanding CAPI Architecture

A CAPI application interacts with the ReadiVoice system. The ReadiVoice
documentation provides extensive information about the system; however,
we’ve provided a high-level view of it here, and subsequently how ReadiVoice
relates to CAPI.

Note: We’re presenting a view of the whole architecture to ensure that you
know all the processes involved. However, when you write CAPI
applications, you don’t need to deal directly with bridge or port IDs, or
understand how the ODPROC or MPLEX processes work. CAPI is set up to
encapsulate the back-end processing details so that the programmer only
needs to work with the API itself.

A ReadiVoice CAPI system includes:

• CACS – A Conference Allocation and Control System (CACS) server. A
CACS is the key component of a conferencing system. The CACS is where
customer and conference data is stored. The CACS allows customers to be
routed to conferences. When a conference is created, the CACS sends the
bridge a conference start package including the conference ID.

Subcomponents or modules include:

— ODPROC – ODPROC stands for on-demand processing. It is the key

component of the CACS, and is the master shell process for
ReadiVoice. It runs on a SUN server.

ODPROC is a multi-threaded process that handles every aspect of
operations conferencing over the bridge. Each of its threads handles a
different aspect of conferencing. There is a BIS (bridge interface
server, one for each bridge) that communicates with the bridge, a call
routing thread that handles the logistics of choosing a bridge,
reserving ports, etc. as well as several others. Events are received,
processed, and sent by ODPROC. If ODPROC is not running, the
system can’t start new processes.

ODPROC knows where the host computer is, where the conference
data is stored, and other configuration information.

— CSC – CSC is a module within the CACS. In previous versions you

needed to deal with multiple components within CACS; in CAPI
communication from the conferencing application only goes to CSC,
which then manages communication with the other CACS modules.

8 Proprietary & Confidential

Developing CAPI Applications

• Apache – An Apache Web server handles the IP connections between
CACS and the conferencing application you write with CAPI.

• Bridges – Each system includes a bridge. You can have multiple bridges,
each of which provides several ports. Each port on the bridge is equivalent
to one phone call, or one person. ODPROC interacts with the bridges.
Conferences take place on a bridge, with a group of ports.

The overall architecture is shown in Figure 2-1.

Figure 2-1 CAPI architecture

Figure 2-1 shows two lines of communication, one for synchronous and one
for asynchronous. They’re also known as pull and push mode, respectively.
The first, pull, is for quick responses on the same connection. The second,
push, is for asynchronous responses on a different connection, typically
returning the results of a requested action.

“Understanding CAPI Communication: Synchronous and Asynchronous” on

page 9 explains more about how the system components communicate using
the synchronous and asynchronous communication shown in the diagram.

Understanding CAPI Communication: Synchronous and Asynchronous

CAPI lets you send requests in two modes: pull (synchronous) and push
(asynchronous). The difference is whether the requested action is simply
acknowledged as having been sent (pull), or whether a response is
immediately sent back (pull) satisfying the request.

• Pull mode – The event request is sent, and the response, ACK for success
and NACK for failure, is sent back immediately over the same connection
on the same ports.

Proprietary & Confidential 9

ReadiVoice CAPI Developer’s Guide

• Push mode – The event is sent and the reply, such as
CONF_INFO_CHANGED or NACK for failure, is sent back over another
connection on two different ports later when the action or information
requested has been created.

Information about to create the second connection and ports to send it
back through is specified when the first connection from the client to the
CACS is created.

Note: In pull mode the instant reply is sent back over the same connection; in
push mode a second connection is created for the asynchronous reply.
However, when “a connection” is discussed in CAPI documentation, both are
considered one connection.

Understanding How Ports Are Used

Ports for pull mode and push mode are handled differently, as noted in

Figure 2-1 on page 9.

Pull Mode and Ports

Push Mode and Ports

Sending Port on the Client

The port from which an event is sent is up to you. Typically when you write
the conferencing application, you’ll request a socket, which will give you a
port automatically.

Receiving Port on the Server

The event is received by default on port 80 on the CACS.

Four ports are used for push (asynchronous) mode:

• The sending port on the client

• The receiving port on the server

• The sending port on the server, for the asynchronous response

• The receiving port on the client, for the asynchronous response

10 Proprietary & Confidential

Developing CAPI Applications

Sending Port on the Client

This is the same as pull mode. The port from which an event is sent is up to
you. Typically when you write the conferencing application, you’ll request a
socket, which will give you a port automatically.

Receiving Port on the Server

This is the same as pull mode. The event is received by default on port 80 on
the CACS.

Sending Port on the Server

The asynchronous response to the event is sent on a port determined by the
server; you set this up through ReadiVoice.

Receiving Port on the Client

Ports and Firewalls

The asynchronous response to the event is received on the port you specify
when you send the event in the first place. You can specify any port you want;
if you specify 0 (zero), the system will just select a locally available port. This
port is sent with the event request.

The asynchronous connection back to the client is created based on the session
ID. This lets the response come back to the right client, using the right
connection, to the expected port.

When you pass the port value, you can specify 0 (zero), which will then choose
a locally available port. See “Setting the Port for Asynchronous Responses on

the Client” on page 53 or “Sample Moderator Application” on page 63 for

sample code.

You need to ensure that CAPI communication can get through your firewalls.
Typically the pull mode requests to port 80 will get through a firewall without
any trouble. Using pull mode doesn’t pose any issues regarding firewalls;
push mode does involve complications. If you’re using firewalls between the
client and CACS, you’ll need to make some configuration adjustments to
accommodate push mode’s second connection back to the client.

Proprietary & Confidential 11

ReadiVoice CAPI Developer’s Guide

Figure 2-2 shows a possible firewall configuration, where the client is behind
one firewall and the CACS is behind another.

Figure 2-2 Firewalls and CAPI architecture

For push mode in particular, you need to ensure that the asynchronous
responses on the two additional ports can get through to the client.

Be sure that the data isn’t filtered or modified in any way as it goes through
the firewalls.

If you want to minimize the number of ports to let communication through,
see “Considerations for Number of Connections to Use” on page 18.

Understanding Connections, Sessions, and Logins

This section describes what they are, how they work, and how to put them to
use in your CAPI application.

• Overview of Connections, Sessions, and Logins

• High-Level Overview of the Conferencing Process

• Relationships Among Connections, Sessions, and Logins

Overview of Connections, Sessions, and Logins

Note: To maintain open connections and sessions, see “Maintaining Open

Sessions and Connections” on page 33.

• An HTTP connection is the networking conduit that enables
communication between a port on the client and a port on the server. You
specify in the connection creation code whether you’re using push or pull
mode.

12 Proprietary & Confidential

Developing CAPI Applications

When you’re in push mode, there are actually two connections, one from
the client to the server, and one back from the server to the client.
However, they work together, and the code that creates the first one
specifies how to create the second one, so are functionally one connection
between the client and CACS.

• A session is a CAPI process that takes place over the connection. Events are
sent through a session.

When your sessions are running over a push mode connection, you get a
session ID. This ID is stored in a cookie on the client and is used to let the
CACS know where to send the reply value back to. The session ID is how
the requests and responses for one session stay separate from other
sessions.

Multiple sessions can run simultaneously over the same connection.
(Event requests and responses running over the same connection are
handled sequentially by the CACS.)

• A login represents a set of capabilities that will function within the session.
A login creates a session. There is a Moderator login and an Application
login, which is like a super-Moderator. There is also a Participant login,
though participants don’t control connections.

A Moderator login can manage the sessions for one conference at a time.
An Application login can manage the sessions for several conferences at a
time.

Application, Moderator, and Participant Logins

Three types of logins are available for a CAPI conference. A login sets the type
of capabilities that will be used within a session.

A session determines what types of capabilities can be used and, implicitly,
what type of user or users will be in the conference.

A session and a login function together; a login creates a session.

There are three types of logins: Application, Moderator, and Participant.
However, there is both a Push Moderator and a Pull Moderator, so the
effective total is four.

• Participant – A participating user with few capabilities. Use the
LOGIN_PART event.

The Participant type is extremely limited in what it can do. It can join the
conference, and mute its own phone, but very little else.

The Participant type is sometimes also referred to as One-Click, since it’s
the type of session that implements the one-click feature. With this feature
you can send a URL to a Participant, who can click to join the conference.

• Push Moderator – A subscriber with extensive capabilities within its own
conference, for use in push mode. Use the LOGIN_PUSH_MODERATOR
event.

Proprietary & Confidential 13

ReadiVoice CAPI Developer’s Guide

Moderators have extensive control over a single conference. However,
they can’t affect any other conference.

• Pull Moderator – A subscriber with extensive capabilities within its own
conference, for use in pull mode. Use the LOGIN_MODERATOR event.

• Application – A “super-Moderator” that has all the capabilities of a
Moderator, plus the ability to affect multiple conferences. Use the
LOGIN_APPLICATION event. Application is a push mode login.

The Application type is new in this release. It provides extended
capabilities beyond what a Moderator can do. Its key features are:

— Monitoring multiple conferences at once

— Receiving notifications of when multiple conferences start and stop

— Running ACM applications

High-Level Overview of the Conferencing Process

The following steps are for a simple implementation of a conference.

1 The CAPI application on the client opens an HTTP connection to the

CACS.

2 The CAPI application creates a session and logs into the CACS. The login

can be by an Application or Moderator login type.

3 The CAPI application creates a conference for that session; the conference

runs on the CACS.

4 The CAPI application sends event requests to the conference on the

CACS, and receives responses back, within the conference’s session.

A session ID is used to ensure that requests and responses for a session are
tracked correctly.

5 When the conference is over, the login controlling the conference ends the

conference, ends the session, and logs out of the connection to the CACS.

Relationships Among Connections, Sessions, and Logins

You might think that for each request/response, or for each conference, you
would create one connection and one session. You have more flexibility than
that, however, combined with a few restrictions.

Note: The Application login is for push mode only, and there is a Moderator
for push and for pull mode.

14 Proprietary & Confidential

Developing CAPI Applications

Basic Relationships

• There is a one-to-many relationship between the connection to the server
and the sessions that can go across it

• There is a one-to-many relationship between the Moderator login and
sessions

• There is a one-to-many relationship between the Application login and
sessions

• There are no restrictions on the number of sessions and the corresponding
number of conferences; there is a many-to-many relationship between the
two.

Login and Session Combinations

• Multiple logins can control multiple sessions at the same time. Possible
implementations of this include:

— One Application login can control all sessions

— One Application login can control one or more sessions, while one

Moderator login can control a session

— One Application login can control one or more sessions, while one

Moderator login can control a session, and another Moderator can
control another session

— Two Application logins can control one or more sessions each, while

one Moderator login can control a session, and another Moderator can
control another session

Login, Session, and Connection Combinations

All of these possible combinations from the previous section can be grouped
over connections in nearly any way you decide.

• All sessions can run over the same connection (for push, the same set of
connections, one client -> server and the returning connection server ->
client)

• Some sessions can run over one connection and the rest can run over
another. The only restriction is that all of the sessions run by a particular
login must take place on the same connection; an Application login can’t
control some sessions on one connection and other sessions on another
connection.

• Each session can take place on a separate connection.

• Each session can manage multiple conferences (if session was created by

an Application login) or many sessions can manage one conference

• Each login’s sessions can have separate connections.

Proprietary & Confidential 15

ReadiVoice CAPI Developer’s Guide

• Multiple Applications, Moderators, and Participants can access a
conference at the same time

Illustrations of Connection, Session, Conference, and Login Configurations

The following illustrations show possible approaches to connections, sessions,
and logins.

Conferences

Conferences

Conferences

Connection

Session

One login controlling sessions for one conference

over one connection

Connection

Session

Session

Two logins controlling sessions for one

conference each over one connection

Connection

Session

Session

Application login controlling sessions for multiple

conferences over one connection

Login

ClientCACS

Login

ClientCACS

Application Login

ClientCACS

Conferences

Connection

Application Login

Session

Session

Moderator Login

Session

Moderator login controlling sessions for one conference

and Application login controlling sessions for multiple

conferences over same connection

Figure 2-3 Possible approaches to connections and sessions

16 Proprietary & Confidential

ClientCACS

Developing CAPI Applications

Conferences

Conferences

Conferences

Connection

Session

Application login controlling one session and two

conferences

Connection

Session

Session

Login controlling a conference using multiple sessions

Connection

Session
Session
Session
Session

Application Login

ClientCACS

L og in

ClientCACS

A p p l i c a t i o n L o g i n

Conferences

Application login controlling multiple conferences with

multiple sessions for each conference

Connection

ClientCACS

Application Login

Session
Session

Moderator Login

Session

Moderator login controlling sessions for one conference

and Application login controlling sessions for multiple

conferences over same connection

Figure 2-4 More possible approaches to connections and sessions

ClientCACS

The next illustration shows combinations that aren’t permitted.

Proprietary & Confidential 17

ReadiVoice CAPI Developer’s Guide

Conferences

Conferences

Conferences

Session

Connection

Session

Connection

Login’s sessions over different connections

Connection

Session

Connection

Session for one conference over two connections

Connection

Session
Session

Moderator login controlling two conferences

Login

ClientCACS

Login

ClientCACS

Moderator Login

ClientCACS

Figure 2-5 Unpermitted approaches to connections and sessions

Benefits and Drawbacks

The choices shown in “Relationships Among Connections, Sessions, and

Logins” on page 14 boil down to a few choices:

• Using multiple connections or fewer

• Using the Application login or the Moderator (or both)

Considerations for Number of Connections to Use

• Number of ports kept open – You read in “Understanding How Ports Are

Used” on page 10 that a pull event involves two ports and a push event

involves four ports. You also read in “Ports and Firewalls” on page 11 that
you need to ensure for push mode in particular that responses can get back
to the client through your firewall. The more connections you have, the
more traffic you need to let through the firewall and the higher the risk
that unwanted traffic will get through. This means that if you want to
minimize the open ports in your firewalls, use one or very few
connections.

18 Proprietary & Confidential

Developing CAPI Applications

• Performance – The fewer connections you use, the slower performance
will be in general. The events are serialized. Additionally, the events are
processed by the server one at a time within the connection, in the order
received. The server can deal with multiple events from multiple
connections at the same time, but events within a connection are dealt with
sequentially.

• Simplicity – Using just one connection for all sessions is simpler.

Considerations for Logins

An Application login has the ability to manage multiple conferences, and to
use the CAPI ACM tools to interface with other applications. If these features
are important to you, use the Application login.

Proprietary & Confidential 19

ReadiVoice CAPI Developer’s Guide

CAPI SDK Components

Review this section to learn about the CAPI events, and the CAPI Java utility
files and event files.

Understanding the CAPI Events

An event contains information describing some behavior or functionality of
the conferencing application or CACS. All control and functionality of CAPI is
accomplished by either sending an event to the CACS, or receiving one back
from the CACS.

For example, to dial a participant or subscriber, you would send a
DIAL_CALL event (or class object) to the CACS with the proper data
(participant’s name, phone number, etc.). The CACS would then send back to
the conferencing application a DIAL_STARTED and
DIALOUT-CONNECTED event when the person picks up the phone. The
reply events contain information such as the conference ID and participant ID
used when completing the requested task.

Note: For more information on callflows, refer to the “Voice Prompts and Call
Flows” appendix of the ReadiVoice Administration and Maintenance Guide.

Push and Pull Mode

Each event can function in either push or pull mode. Pull mode sends back
ACK or NACK responses for success or failure; push mode has a wider variety
of responses. In addition to the replies to the original event, other events can
be affected as well. These are noted where appropriate in this document.

Events Can Be Run By Certain Login Types

Not all events can be run by all login types: many can be run by Moderators
and Applications but not Participants, for instance. The legal login types for
each event are listed in the event reference guide.

Responses Versus Notifications

When you send an event, you can get back a reply. You can also receive
notifications. Here’s the difference between them.

• In pull mode, you only receive replies. You send an event, and
immediately a reply, such as an event containing the requested value, or
ACK or NACK, comes back.

• In push mode, you can also receive replies. You might send a request to
register to be notified every time a conference starts and stops, for
instance.

20 Proprietary & Confidential

Developing CAPI Applications

— The reply to this would tell you that the request was received and

you’re registered.

— The notifications, later, would tell you that a conference has started or

that one has stopped.

Using the Event Reference Section

The event reference section of this document contains extensive technical
information about how to use each event. Be sure to use it as you write your
application.

In the event reference section, pay particular attention the responses for each
event, for pull mode and for push mode. Some responses are standard ACK
for success and NACK for failure; others send alternate or additional
information. Note that NACK is the failure not of the event to get the
requested response, but the failure of the event request to be correctly
processed.

For instance, if you send a request for an operator (SET_OP_REQ) when an
operator isn’t available, you might expect a NACK (failure) response. In pull
mode, this is the case. The response is a failure to get the operator because one
isn’t available, and this is expressed not with NACK but with the
OP_REQ_CANCELED event as a response.

The OP_REQ_CANCELED event response has three possible enum values.
When no operator is available, the event response enum would be
CR_NO_OP_AVAILABLE.

Valid enum values are:

• CR_CALLERS_ACTION

• CR_NO_OP_AVAILABLE

• MAX_CANCELATION_REASON

Understanding the CAPI Java Files

The Javadocs were installed with CAPI. Use them to learn more about how
and when to use each class, interface, and package.

You can access Javadocs using the main CAPI components navigation page.

Use this section to learn more about the Java files provided with CAPI, and
how to use them with events.

Note: This documentation assumes that you are writing your application
using all of the provided Java files, including the Java event files generated by
Castor from the schema.

Proprietary & Confidential 21

ReadiVoice CAPI Developer’s Guide

CAPI Java Files

The new CAPI SDK contains the following components.

• An XML schema defining conferencing events, composing the XML layer
of the API.

• Four sets of Java files, built on top of the XML layer, composing the Java
layer of the API.

— Core communication files, which interact with CACS and the core

utility files.

— Core utility files, which interact with the core communication files.

— Castor utility files, which interact with the event files and implement

the core utility files.

— Castor event files, generated from the CAPI schema using the Castor

program. (To learn more about Castor, see

Figure 2-6 shows the different Java CAPI SDK components, and how they
relate to each other and the conferencing software you write. A partial list of
the Java classes in each category is included.

www.castor.org

.)

22 Proprietary & Confidential

Developing CAPI Applications

Figure 2-6 CAPI SDK architecture with sample class names

Proprietary & Confidential 23

ReadiVoice CAPI Developer’s Guide

CAPI Java File Quick Reference

Table 2-1 provides a quick reference. For technical details, see the Javadocs.

Table 2-1 Files provided with CAPI

Category Filenames Description

Core
Communication

AsyncRecieverConnection.java An implementation of Connection that uses a trivial

protocol. Provides for reading asynchronous data
off a unidirectional connection (does not provide a
way to write to that connection). Internal read is
unbuffered. Trivial protocol is to read 1 integer of
data specifying the size of the rest of the data
packet, then to read that much more off the
connection.

BasicConnection.java Implements Connection class, which provides basic

communication methods that operate on events.
Assumes HTTP protocol and XML data payloads.

BasicCookie.java Implements the Cookie interface. Usually used to

set a cookie on a connection.

BasicListener.java Listener class provides infrastructure for

infrastructure for asynchronous/synchronous
(pull/push) connections. Contains a ServerSocket
that will accept new connections.

BasicMessageBus.java Implements MessageBus. MessageBus objects

handle communications with the CACS utilizing the
RV Simple XML protocol, and HTTP. If given a
Listener, four threads are created: one for reading
HTTP events, one for writing HTTP events, one to
listen for asynchronous server connections, and
one to read from any asynchronous server
connections. If not created with a listener only the
HTTP reader and writer threads are created.

Connection.java Forms the base for all types of socket based CAPI

connections to servers. If not set, will use internal
SocketFactory to create a socket if needed, or a
factory may be set using the appropriate interface
methods.

Cookie.java CookieInterface provides interface for cookie

processing. This interface should be overridden to
provide desired functionality.

CookieInterface.java CookieInterface provides the interface for cookie

processing. This interface should be overridden to
provide desired functionality.

24 Proprietary & Confidential

Developing CAPI Applications

Table 2-1 Files provided with CAPI

Category Filenames Description

HttpConnection.java An implementation of Connection} that uses the

HTTP protocol. Internally uses a BufferedReader
for reading data off the connection, and provides for
writing data to that connection.

Listener.java A utility interface for network components that listen

for new connections
MessageBus.java A utility interface for main communications.
MessageSender.java A utility interface for sending CAPI events.

Core Utility ACMSender.java A utility interface for sending ACM-related events to

the CACS. No passed parameter for any method

may be null or < 0 unless otherwise specified.
AddressBookSender.java A utility class interface for sending address book

related events to the CACS. No passed parameter

for any method may be null or < 0 unless otherwise

specified.
CapiUnmarshaller.java HandlerInterface provides interface for handling

incoming events. This interface should be

overridden to provide desired functionality.
MarshallerException.java Higher-level exception wrapper for any exception

thrown during data marshalling. This higher-level

exception shields the application from having to

deal with the marshalling specific implementations'

exceptions.
UnmarshallerException.java Higher-level exception wrapper for any exception

thrown during data un-marshalling. This

higher-level exception shields the application from

having to deal with the un-marshalling specific

implementations' exceptions.
UnmarshallerInterface.java HandlerInterface provides interface for handling

incoming events. This interface should be

overridden to provide desired functionality.

Castor Utilities CastorAcmSender.java Implements ACMSender. A utility class for sending

ACM-related events.
CastorAddressBookSender.java Implements AddressBookSender. A utility class for

sending address book-related events to the CACS.
CastorMessageHandlerBase.java Implements java.util.Observer. The Castor event

specific base for handling all events. Handle

methods must be overridden by the application to

implement an action to take when a specific event

is received.

Proprietary & Confidential 25

ReadiVoice CAPI Developer’s Guide

Table 2-1 Files provided with CAPI

Category Filenames Description

CastorSender.java Implements MessageSender. The Castor specific

utility to send events.
CastorUnmarshaller.java Extends Observable, implements

UnmarshallerInterface. The Castor speci f ic

implementation to unmarshall data into events.

Castor Events All events from schema. See event reference section.

Connecting the CAPI Events and the Java Utility Files

Typically, you’ll use the procedures in “Commonly Used Conferencing

Procedures” on page 37, and the event reference section, to figure out which

events you need to use. From there, though, you need to determine which Java
files to use to implement those features. Use these tips to make the connection
between events and Java files.

Where to Find Event Methods

The methods that send events are in classes and interfaces with Sender in the
name. The methods that read, or handle, events, are in classes and interfaces
with Handler in the name.

You can also look at “Sample Moderator Application” on page 63 to see how
the code sends and reads events.

Sender methods from the CastorSender,java file

public void appRegisterConfsActivity(java.lang.String

•

passBack, java.lang.String sessionId)

Corresponds to the APP_REGISTER_CONFS_ACTIVITY event.

•

public void dialCall(java.lang.String passBack,
java.lang.String sessionId, int confId, java.lang.String
callTo, boolean promptToConnect, java.lang.String name,
java.lang.String partTypeStr, java.lang.String callflowStr,
boolean delayConf)

Corresponds to the DIAL_CALL event.

•

public void loginParticipant(java.lang.String passBack,
java.lang.String accessNumber, java.lang.String accessCode)

Corresponds to the LOGIN_PART event.

Handler methods, from the CastorMessageHandlerBase.java file:

•

public void handle(RVAPIACK message)

Corresponds to the ACK event.

•

public void handle(RVAPIANNOUNCEMENT_CHANGED message)

26 Proprietary & Confidential

Developing CAPI Applications

Corresponds to the ANNOUNCEMENT_CHANGED event.

•

public void handle(RVAPICALL_DISCONNECTED message)

Corresponds to the CALL_DISCONNECTED event.

Names of Java Files Castor Generates for Each Event

In addition to the Java utility files written for CAPI, a Java file is automatically
generated from the schema for each event by the Castor program. The name of
each automatically generated Java file is based on the event name in the event
reference guide, but with some differences. These differences are part of how
Castor works and ensure uniqueness for the generated code.

• The names of events are all caps with underscores. Some examples are
CONF_INFO_CHANGED, SUBSCR_INFO, and
CALL_DISCONNECTED.

• However, the Castor program attaches the namespace to the front of each
generated class and type. Thus when you directly reference the event files
generated by Castor, you would need to use the name Castor assigns to the
Java files: RVAPICONF_INFO_CHANGED, RVAPISUBSCR_INFO, and
RVAPICALL_DISCONNECTED. Here’s an example:

public void handle( RVAPICONF_INFO_CHANGED message )

Table 2-2 covers the naming changes that Castor makes when it creates the
Castor Events files.

Table 2-2 Event naming conventions

Item type Schema name Castor Java class name Directory Comments

Events EVENTNAME

Example:
ACM_CALL_LEAVE
SET_CONTACT_INFO

Types EVENTNAME

Example:
STRING

Enums EVENTNAME

Example:
NACK_REASON

Enum values EVENTNAME

Example:
NACK_REASON

NAMESPACEEVENTNAME

Examples:
RVAPIACM_CALL_LEAVE
RVAPISET_CONTACT_INFO

EVENTNAME
Example:
STRING

NAMESPACEEVENTNAME
Example:
RVAPINACK_REASON

NAMESPACESIMPLE_
EVENTNAME

Example:
RVAPISIMPLE_NACK_

REASON

\events Complex types go

in this directory.
RVAPI is a

namespace.

\events\types Naming is

identical in name
and case.

\events Naming is the

same as for
events.

\events\types The enumerated

value is wrapped
in the generated
enum.

Proprietary & Confidential 27

ReadiVoice CAPI Developer’s Guide

Programming Guidelines

This section contains important information about designing and writing your
CAPI application.

How the ODPROC and the CSC Work Together

This section explains what happens when ODPROC resyncs with the CSC. It’s
important that you know how this works to be prepard for the events that are
called and sent.

Note: See “Understanding CAPI Architecture” on page 8 for information on
the ODPROC and the CSC.

• Bridge logout – When a bridge logs out (or ODPROC is restarted), each
push mode session that has an active conference on the bridge should
receive the BRIDGE_STATUS_CHANGED event with the BS_DOWN
value. This will also occur, the same way, for Application sessions that
were registered to receive notifications of conference starts and stops.

• Bridge login – When a bridge logs in (after a logout or ODPROC restart),
each push mode session that had an active conference on the bridge before
the logout should receive the BRIDGE_STATUS_CHANGED event with
BS_UP value. This will also occur, the same way, for Application sessions
that were registered to receive notifications of conference starts and stops.

• Bridge login – When a bridge logs in (after a logout or ODPROC restart)
push mode sessions receive CONF_INFO_CHANGED for its conference if
it is still active. This will also occur, the same way, for Application sessions
that were registered to receive notifications of conference starts and stops..
If the Application session is not registered for the subscription, it receives
the CONF_STARTED event.

• Nothing is received for conferences that went away while the bridge was
out.

• No participant events are received in any case.

In genera,l sessions interested in a conference are notified that the conference
is active, and they must ask for more information if they need that.

Application Design and Configuration

Review this section before writing your application and adhere to specified
information.

Choosing a Programming Language

Note: This document assumes in general that you are programming in Java
using the provided Java files.

28 Proprietary & Confidential

Developing CAPI Applications

We recommend that you use Java and the Java files provided with CAPI.

Java 1.4 or higher is required.

See the Javadocs and “Understanding the CAPI Java Files” on page 21 to learn
more about using the Java files provides with CAPI.

If you are programming in another language, you will need to use the schema
as the basis for your program. If the existing extension architecture is not
suitable for your needs, you can use only the schema. For instance, you can use
the schema as a foundation for building a translation server application that
translates events between the CACS Java API and other languages or
platforms.

You can use any language with a socket utility so that you can open the Web
server port of the CACS. You can use C++, Perl, Java, or Visual Basic, among
others. All events must comply with HTTP 1.1.

Object Model Layer

We recommend that you set up an object-model layer between your code and
the code provided by CAPI. This was provided in MAPI, and is likely to be
provided in the future by CAPI, but is not currently available.

Storing Configuration Information

The GUI.INI file and the Config object were used in MAPI to store information
like ports, server IP addresses, and so on. In CAPI, the file and object are no
longer used. You are responsible, for CAPI applications, for determining how
to store this information; however, you have the flexibility to select the
approach you prefer.

Configuration information you might store depends on your system.
However, we recommend that you ensure that the following are easily
available to your application:

• IP addresses and ports on CACS

• Frequency of the heartbeat you send to keep connections open (see

“Maintaining Open Sessions and Connections” on page 33)

• IDs for ACM applications like PINS

Programming Fundamentals

Review this section before writing your application and adhere to specified
guidelines.

Proprietary & Confidential 29

ReadiVoice CAPI Developer’s Guide

Using ACM

ACM is an interface to external applications. It’s a way to develop and
implement functionality and features to callflow and inside a conference, that
aren’t in the standard ReadiVoice or CAPI release.

Essentially, a participant is taken from the normal callflow/conference and
temporarily handed over to an ACM application such as PINS. Once the ACM
application has finished with the participant or participants, and no other
ACM applications want to take control, they’re placed back in the conference
or into the callflow at the point they were taken.

To use ACM, use the events and Java files for ACM. Event and file names are

ACM

all preceded by

ACM Basics

To use an ACM application, first register its existence. Use the
ACM_REGISTER event.

• The application’s identity number must match with that in the database of
ACM applications for the system.

.

• A heartbeat (quick data packet) must be sent from the ACM application
every few seconds. Failure to do so will result in the unregistration of the
application. The timeout period before the application is unregistered is
specified in the .
Maintenance Guide for information on configuring the .

• If an ACM application is unregistered callers will be totally unaware of its
existence, even if the subscriber has selected the option to use it.

ACM applications have a priority number associated with them (set in the data
base). This number tells the ACM manager in what order to pass control of the
channel. This allows ACM applications can be chained together, which is
easier and allows more customization.

Two Types of ACM Applications

The two types of ACM applications are Call Flow and In Conference.

• Call Flow ACMs occur in the call flow just before a caller records their
name for roll-call (if that option is enabled) and is placed in the conference.
This is the only point designated for ACM applications to take over (if
any). As such, Call Flow ACM applications will only work when a
participant dials in and is proceeding through the call flow menus.

• In Conference ACMs happen after participants are in a conference. Unlike
the Call Flow ACMs, these are not automatic, and must be initiated by a
Moderator.

odprocrc

file. Refer to the ReadiVoice Administration and

odprocrc

file.

Examples of preconference ACM applications include the following:

• ACM PINs. Using PINS includes these steps:

— Prompt subscriber and participants for PIN

30 Proprietary & Confidential

Developing CAPI Applications

— ACM application verifies PIN

— PIN written to CDR

• ACM Billing ID. Using Billing ID includes these steps:

— Prompt subscriber for billing code

— Use for bill back to a specific client

— Digits are collected and passed to CDR

For ACM sample code, see “Using ACM to Interface With External

Applications” on page 59 or “Sample Moderator Application” on page 63.

Using Push and Pull Mode

As stated in “Understanding CAPI Communication: Synchronous and

Asynchronous” on page 9, CAPI lets you send requests in two modes: push

(asynchronous) and pull (synchronous). You can specify that any given
session will be in push or pull mode.

Event Return Values for Push and Pull

• The responses to an event for push mode, for success or failure, are listed
in the event reference section. For instance, the
REMOVE_CONTACT_GROUP event returns
CONTACT_GROUP_REMOVED for success and NACK for failure.

• The responses to an event for pull mode vary. For the same event,
REMOVE_CONTACT_GROUP, the responses are ACK for success and
NACK for failure. ACK simply indicates that the request was received.

ACK and NACK are common responses for pull mode. However,
sometimes information will be sent back for the success response. For the
event REQ_CONTACT_GROUP_LIST, which simply asks for information
instead of for a task to be performed, the response for pull mode is
CONTACT_GROUP_LIST for success and NACK for failure. (Push mode
has the same responses.)

If information can simply be retrieved to fulfill a request, pull mode will return
the requested value for success. If a task needs to be performed to fulfill the
request, pull mode will return an ACK for success. Both pull and push return
NACK for failure.

Choosing Push Versus Pull

Push is a more robust, powerful approach. Pull is used when you are working
with a stateless protocol such as HTTP. Push does require you to manage
firewalls to ensure that the response coming back on the second connection
can get through. Generally, push is the better choice unless you have specific
issues with state or firewalls.

Proprietary & Confidential 31

ReadiVoice CAPI Developer’s Guide

Specifying Push or Pull

The type of connection you create with the CACS specifies whether you’re
using push or pull. For push, you need to create a listener and need to specify
the client port that the connection for the response should come back to. For
pull, you don’t need either of these components.

The code for creating a connection is in “Connecting to the CACS” on page 41
and “Sample Moderator Application” on page 63.

For pull, use a Pull Moderator to manage the conference; for push, use a Push
Moderator or Application.

Note: You can create a pull connection and then log in with a Push Moderator,
or vice versa; the type of login determines the session type rather than the
original connection. However, your application won’t work correctly with this
approach.

Push and Firewalls

The second connection that push mode uses can require specific firewall
configuration. See “Ports and Firewalls” on page 11.

Using the Login Types

A session determines what types of capabilities can be used and, implicitly,
what type of user or users will be in the conference.

A session and a login function together; a login creates a session.

Login Types

There are three types of logins: Application, Moderator, and Participant.
However, there is both a Push Moderator and a Pull Moderator, so the
effective total is four.

• Participant – A participating user with few capabilities. Use the
LOGIN_PART event. Participant is a pull mode session.

The Participant type is extremely limited in what it can do. It can join the
conference, and mute its own phone, but very little else.

The Participant type is also referred to as One-Click, since it’s the type of
session that implements the one-click feature. With this feature you can
send a URL to a Participant, who can click to join the conference.

• Push Moderator – A subscriber with extensive capabilities within its own
conference, for use in push mode. Use the LOGIN_PUSH_MODERATOR
event.

Moderators have extensive control over a single conference. However,
they can’t affect any other conference.

• Pull Moderator – A subscriber with extensive capabilities within its own
conference, for use in pull mode. Use the LOGIN_MODERATOR event.

32 Proprietary & Confidential

Developing CAPI Applications

• Application – A “super-Moderator” that has all the capabilities of a
Moderator, plus the ability to affect multiple conferences. Use the
LOGIN_APPLICATION event. Application is a push mode session.

The Application session type is new in this release. It provides extended
capabilities beyond what a Moderator can do. Its key features are:

— Monitoring multiple conferences at once

— Receiving notifications of when multiple conferences start and stop

— Running ACM applications

Session Type and Session ID

Sessions not only specify the capabilities, and thus the events, that can be used
for a specified part of the application, but the session ID is used in push mode
to let the server know where to send the response back to, on the asynchronous
connection.

When you create a push session, you get a session ID. This ID is stored in a
cookie on the client and is used to let the CACS know where to send the reply
value back to.

Programming Tips

Creating a Connection

The code for creating a connection is included in the sample CAPI Moderator
application, in the SimplePushModerator.java file. See “Creating a

Connection” on page 33 or “Sample Moderator Application” on page 63.

Maintaining Open Sessions and Connections

A session takes place over a connection. Both need to stay open to make sure
the conferencing application works.

• A connection will timeout by default after four minutes without a session
over it. This timeout is not configurable.

• A session will timeout by default after two minutes without any traffic.
(You can change this value by editing the .
session open, you need to have some traffic over it. The simplest way to
ensure traffic over the session is to use the SESSION_HEARTBEAT event.

A code example is shown in “Maintaining an Open Session” on page 43.

This section contains more specific, task-related tips to follow when you write
your application.

odprocrc

file.) To keep the

Proprietary & Confidential 33

ReadiVoice CAPI Developer’s Guide

Notes on Conference, Participant, and Subscriber IDs

Conference and Participant IDs Must Be Saved and Sent

MAPI contained an object model, so the conference and participant IDs were
saved in the conference object and sender objects. That layer does not exist
currently in CAPI, so you need to be sure to save the values, and pass them in
when needed.

Here’s an example of the subscriberId and conferenceId.

/*
* We need to save these for future communications.
*/
private int subscriberId = -1;
private int conferenceId = -1;

Conference and Subscriber IDs

In the previous release, there was inconsistent use of SubscrID and ConfId, the
subscription ID and the conference ID. They are two different items; however
for now, they are typically assigned the same number. In CAPI, they are used
consistently as follows:

• SubscrID – Used before a conference has been created, to identify a
subscriber

• ConfID – Used as soon as a conference has been created, to identify a
physical conference

It is important to implement these as different items, even though they are
currently assigned the same number in the Readivoice implementation.

Database Conference Information Updates

CSC is a module within CACS that manages conferences. The information it
manages is divided into two types: database conference information, generally
static settings used to set up the conference, and runtime information, more
dynamic information exchanged during the conference.

When you change one, the same information in the other is not necessarily
changed. You could change an attribute for the current conference session, but
the same information in the database would remain the same. Typically there
are two events to change a piece of information, one to change it in the
conference session and one to change it in the database.

Prerequisites: Connection and Conference, and Session and Conference IDs

Before you run most tasks, such as dialing a participant, you need to make sure
that you’ve created a connection and started a conference.

34 Proprietary & Confidential

Developing CAPI Applications

You also need to be sure that you have saved and can read in the values for the
session ID, conference ID, and subscriber ID.

Verifying Events Have Occurred

Sending a request and receiving an acknowledgment are not sufficient to
ensure the action requested by an event was carried out. We recommend that
you verify each event is both acknowledged and carried out. For example, if
you send a request to start a conference:

• Verify that you receive an ACK, which indicates the system has received
the request, found no problems, and will attempt processing of the
request.

• Poll using REQ_SUBSCR_INFO to verify that ConfRunning is true (which
means that the conference ID returned is valid).

Multiple Requests of Same Event and the Passback parameter

To send multiple requests of the same event, you can change the passback
number of each request to make it easy to correlate each acknowledgment
(ACK) response with its request. ACK contains a passback field parameter, so
when an ACK comes back you can verify that it has the same field you sent.

Here’s an example. Dialing participants uses the DIAL_CALL event, and the
corresponding

dialCall

method is as follows, and the first parameter is

method. The Javadocs show that the syntax for the

passBack

.

public void dialCall(java.lang.String passBack, java.lang.String
sessionId, int confId, java.lang.String callTo, boolean
promptToConnect, java.lang.String name, java.lang.String
partTypeStr, java.lang.String callflowStr, boolean delayConf)

The following example uses the passback number when dialing to
differentiate dialing the first participant and the second participant. When an
ACK response is sent back for each request, it will contain the value

Dial1Passback

try
{
if ( dialCount < 1 )
{
log.info("Dialing part one");

, and

Dial2Passback

.

sender.dialCall("Dial1Passback", getSessionId(), getConferenceId(),
phoneNum1, false, partName1, "PT_SUBSCRIBER", "CF_BLAST",
false);

dialCount++;
}

Proprietary & Confidential 35

ReadiVoice CAPI Developer’s Guide

else if ( dialCount < 2 )
{
log.info("Dialing part two");

sender.dialCall("Dial2Passback", getSessionId(), getConferenceId(),
phoneNum2, false, partName2, "PT_PARTICIPANT", "CF_BLAST",
false);

dialCount++;
}
else
{
log.error("all parts already dialed");
}
}
catch (MarshallerException e)
{
log.fatal("Marshal error in login, exiting", e);
shutdown();
}
}

Implementing the Conference Security Code

The implementation of the conference security code (when
SET_CONF_SECURITY_CODE is sent after JOIN_CONF is sent) has been
updated. CAPI implementation changes the order and requires that
SET_CONF_SECURITY_CODE be sent before JOIN_CONF. This approach
means that SET_CONF_SECURITY_CODE is optional.

Response to Malformed XML and HTTP

Malformed XML and HTTP code is responded to when possible. When it is too
malformed to respond to, it is silently ignored.

Dial String Requirements

Input for the dial string (usually a telephone number) can include parentheses
and hyphens. For example, [phone] would be accepted. CAPI strips the
extra non-numeric characters out automatically; it also translates alphabetic
characters to telephone numbers so that, for example, A,B, and C are
translated to the number 2, based on the standard telephone keypad.

However, you must make sure the following requirements are implemented
by programming the user interface or post-processing:

36 Proprietary & Confidential

• Telephone extensions – Extension must be preceded by a sufficient
delay—specified by commas. For example, [phone],,,,2000 would
successfully dial extension 2000 if it existed.

• Delay – Any required delays to allow for the switch to route the call must

be added by programming the user interface or post-processing. To add
delay, commas (,) need to be inserted into the dial string. Each comma
creates a one-second delay. Usually four commas (,,,,) are sufficient.

Commonly Used Conferencing Procedures

Note: This section contains a limited list of the more commonly used
procedures. To write any procedure in CAPI, you can use the event reference
section to find an event that performs the task. Read the descriptions and other
information to determine how to use it.

Additional Sources of Information

Developing CAPI Applications

Procedure Sequence

For more information on how the features in this section work, refer to the
ReadiVoice documentation suite. The following in particular are
recommended:

• ReadiVoice CAPI Provisioning Guide

• ReadiVoice CAPI Operator Guide

• ReadiVoice CAPI Subscriber Guide

• ReadiVoice CAPI Administration and Maintenance Guide

When you start a conference, you need to perform certain steps in a certain
order. For instance, you need to create a connection to the CACS, then log into
it, then create a conference, then dial participants, and so on.

The procedures in this section are presented in the order in which they should
be used.

1 Perform “Initial Procedures” on page 40 in the order in which they are

listed.

2 Perform “Conference Procedures” on page 46 only after you’ve

completed the initial procedures.

If a procedure logically needs to take place when a conference is already
running, be sure you’ve first performed “Starting a Conference” on
page 46. Some tasks don’t need a conference running first; you wouldn’t
need to be in a conference for “Registering the Application Login for

Conference Start and Stop Notification” on page 47, for instance. A

Proprietary & Confidential 37

ReadiVoice CAPI Developer’s Guide

Moderator also could simply log in, make some changes to settings, and
log out, without creating a conference. However, if you were to perform

“Dialing Participants” on page 48, you’d need to have a conference

running already so that there was a conference for them to join.

3 Perform “Conference-End Procedures” on page 60 to end a conference.

38 Proprietary & Confidential

Procedure Notes

Developing CAPI Applications

A typical order for a set of tasks in a simple application is:

1 Create a connection

2 Log in

3 Start a conference

4 Dial participants

5 Log out

6 End the conference

This section covers important information about what data is provided,
prerequisites, and other tips.

Content of Procedures in This Section

The appropriate information for each event depends on whether it’s an
administrative procedure like creating a connection, or a simpler CAPI
procedure that uses a straightforward event and response. We’ve provided
one or the other for each procedure, and both where possible.

Please refer to the “Sample Moderator Application” on page 63, as well, to see
working CAPI sample code.

Push Mode Versus Pull Mode

CAPI has two modes, push and pull. (See “Understanding CAPI

Communication: Synchronous and Asynchronous” on page 9 and “Using
Push and Pull Mode” on page 31.) The responses you’ll get for sending an

event in push mode are different from the ones in pull mode. We’ve written
these procedures for push mode, since push mode is more robust and
somewhat more complex, and summarized the differences here. If you want
to write a procedure in pull mode, read the push procedure, then make
changes as necessary for the different response values listed in the event
reference guide.

Application Login Prerequisites

For any procedures involving the Application login, be sure that the
Application ID and password are set up in ReadiVoice. Refer to the
ReadiVoice subscriber guide for more information.

Application login is for push mode, so be sure to create a push mode
connection to the server.

Proprietary & Confidential 39

ReadiVoice CAPI Developer’s Guide

Initial Procedures

This section includes procedures you perform in order to get the conference
started.

Setting up Logging

Apache Log4J and Apache Commons logging are available, and included in
the SDK.

Sample Code

Here’s an example of setting up logging. Refer to “Sample Moderator

Application” on page 63 to see the sample code in context.

import org.apache.commons.lang.Validate;
import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;
import org.apache.log4j.BasicConfigurator;
import org.apache.log4j.Level;
import org.apache.log4j.Logger;
import org.apache.log4j.PatternLayout;
import org.apache.log4j.RollingFileAppender;
import org.apache.log4j.TTCCLayout;

...

* Set up the Log4J system
*/
RollingFileAppender appender = new RollingFileAppender(new TTCCLayout(),
"SimplePushModerator.log", true);

PatternLayout pl = new PatternLayout();
pl.setConversionPattern("%d{ISO8601} %-5p [%t]: %m%n");

appender.setLayout(pl);

BasicConfigurator.configure(appender);
}
catch( IOException e )
{
BasicConfigurator.configure();
}

Logger logger = Logger.getLogger("com");
logger.setLevel(Level.toLevel(logLevel));

40 Proprietary & Confidential

Developing CAPI Applications

Connecting to the CACS

You need to create a connection to the CACS before you can do anything else
in the application. You specify in the connection code whether the connection
will be push or pull. The connection is a simple

HttpConnection

also need to create a listener, and specify the client port that the asynchronous
connection will come back to.

Note: This is a required step.

Sample Code

Refer to “Sample Moderator Application” on page 63 to see the sample code
in context.

public SimplePushModerator( String remoteHost, int remotePort, String localAsyncHost,
int localAsyncPort )
{
Validate.notEmpty(remoteHost);
Validate.isTrue(remotePort > 0);
Validate.notEmpty(localAsyncHost);
Validate.isTrue(0 <= localAsyncPort);

; for push you

// The following listener code is used only for push connections.

try
{
/*
* This is the listener for asynchronous event communication. When the server
* contacts for asynchronous communication on the specified port, this object
* will create a connection for the MessageBus.
*/
listener = new BasicListener(localAsyncPort);

// The following cookie code is used only for push connections.

/*
* The server uses the cookie to find out the details on how to establish
* the asynchronous connection with us.
*/
Cookie cookie = new BasicCookie(localAsyncHost, listener.getLocalPort());

// The rest of the code is used for both push and pull connections.

Proprietary & Confidential 41

ReadiVoice CAPI Developer’s Guide

/*
* We need to establish a basic HTTP connection to send commands and queries.
* In push-mode, responses will come back over the asynchronous connection.
*/
httpConnection = new HttpConnection("SimpleModHttp", remoteHost, remotePort, true,
Connection.DEFAULT_URL, cookie);

/*
* This is a handler for all events from the server/CACS.
*/
handler = new SimplePushModeratorHandler(this);

/*
* This objects handles conversion of the raw data off a connection into
* POJO representations of the CAPI events.
*/
unmarshaller = new CastorUnmarshaller(handler);

/*
* Once the CAPIUnmarshaller, the command sending HTTP connection, and the
* asynchronus connection listening service are set up, we give them to a
* MessageBus so it can use them to finish any further connection setup, and
* begin those communications as needed.
*/
messageBus = new BasicMessageBus(unmarshaller, httpConnection, listener);

/*
* This is the utility class that provides methods for sending the CAPI events
* to the server/CACS. These methods will handle marshalling of the passed
* arguments into the POJO representations of those events. It will then
* marshall those POJO representations into raw data and use the
* provided MessageBus to send to the server/CACS.
*/
sender = new CastorSender(messageBus);
shouldRun = true;
/*
* Start the main thread
*/
start();
}
catch( IOException e )
{
log.fatal("Error in setup, exiting", e);
shutdown();
}
}

42 Proprietary & Confidential

Developing CAPI Applications

Maintaining an Open Session

Once you’ve created a connection and a session, you need to have traffic going
to keep both open. The session will timeout by default after two minutes
without traffic; the connection will timeout after four minutes without a
session.

Event

SESSION_HEARTBEAT

Any event can be used to maintain the connection by requesting and receiving
information regularly; however, SESSION_HEARTBEAT was created for that
purpose.

Response

Pull: N/A

Push: SESSION_HEARTBEAT_ACK

Prerequisites

“Creating a Connection” on page 33.

Sample Code

Refer to “Sample Moderator Application” on page 63 to see the sample code
in context.

/*
* Application is responsible for sending heartbeats. This counter
* is just used to limit the number of heartbeats to reduce network traffic.
*/
private static final int HEART_BEAT_COUNTER_DEFAULT = 30;
private int heartBeatCounter = HEART_BEAT_COUNTER_DEFAULT;

public synchronized void heartBeat()
{
if( heartBeatCounter == 0 )
{
log.debug("sending connection heartbeat...");
try
{
sender.sessionHeartbeat("SimpModPassback", sessionId, sHeartBeatSeq++);
}
catch( MarshallerException e )
{

Proprietary & Confidential 43

ReadiVoice CAPI Developer’s Guide

e.printStackTrace();
System.exit(1);
}
heartBeatCounter = HEART_BEAT_COUNTER_DEFAULT;
}
else
{
heartBeatCounter--;
}
}

Logging Into the CACS

Event

LOGIN_APPLICATION, LOGIN_PUSH_MODERATOR,
LOGIN_MODERATOR, LOGIN_PART

Response to LOGIN_APPLICATION

Pull: N/A

Push: ACK for success, NACK for failure.

Response to LOGIN_PUSH_MODERATOR

Pull: N/A

Push: SUBSCR_INFO for success, NACK for failure.

Response to LOGIN_MODERATOR

Pull: MODERATOR_SESSION_INFO for success, NACK for failure.

Push: MODERATOR_SESSION_INFO for success, NACK for failure.

Response to LOGIN_PART

Pull: N/A

Push: PART_SESSION_INFO for success, NACK for failure.

Prerequisites

“Connecting to the CACS” on page 41, “Maintaining an Open Session” on

page 43.

Be sure you create a push mode connection if you’ll use the Application or
Push Moderator login, and a pull mode connection if you’ll use the Pull
Moderator login.

44 Proprietary & Confidential

Developing CAPI Applications

Notes

Use the Pull Moderator login for push mode; use the Application or Push
Moderator login for push mode.

You need to log into CACS before you can run any conferencing tasks. Use an
Application or Moderator login since the Participant has very few capabilities.

The Application Login is new in this release of CAPI. Use the Application
login to monitor multiple concurrent conferences, or for ACM functionality.

Note: This is a required step.

Sample Code

See “Sample Moderator Application” on page 63 to see the sample code in
context.

/**
* Sends a push mode Moderator login.
*/
public synchronized void login()
{
log.debug("log in");

if ( !shouldRun )
{
return;
}

Validate.isTrue(!loggedIn);

try
{
sender.loginPushModerator("PassbackLogin", accessNumber, accessCode,
subPassCode);
}
catch (MarshallerException e)
{
log.fatal("Marshal error in login, exiting", e);
shutdown();
}
}

Proprietary & Confidential 45

ReadiVoice CAPI Developer’s Guide

Conference Procedures

This section contains the majority of the procedures; they can be performed
once the initial procedures are completed.

Starting a Conference

Event

START_CONF

Response

Pull: ACK for success, NACK for failure.

Push: CONF_INFO_CHANGED with CIR_CONF_STARTED for success,
NACK for failure.

Prerequisites

“Initial Procedures” on page 40.

Notes

A conference can have multiple Application, Moderator, and Participant
logins.

Sample Code

Refer to “Sample Moderator Application” on page 63 to see the application.

public synchronized void startConf()

{
log.debug("startConf");
if( !shouldRun )
{
return;
}
Validate.isTrue(loggedIn);
Validate.notEmpty(sessionId);
Validate.isTrue(!confStarted);
try
{

sender.startConference("PassbackStartConf", getSessionId(), getSubscriberId());

}
catch( MarshallerException e )
{
log.fatal("Marshal error in login, exiting", e);
shutdown();
}
}

46 Proprietary & Confidential

Developing CAPI Applications

Saving Conference and Subscriber ID

MAPI contained an object model, so the conference and participant IDs were
saved in the conference object and sender objects. That layer does not exist
currently in CAPI, so you need to be sure to save the values once you’ve
created the conference, and pass them in when needed. (The conference ID is
passed back when you create a conference; take that value and save it.)

Sample Code

Here’s an example of the subscriberId and conferenceId. Refer to “Sample

Moderator Application” on page 63 to see the code in context.

/*
* We need to save these for future communications.
*/
private int subscriberId = -1;
private int confenceId = -1;

Registering the Application Login for Conference Start and Stop Notification

The Application login was created as the mechanism for several new features
in CAPI; the primary one is to receive conference start and stop notification for
multiple concurrent conferences.

Event

APP_REGISTER_CONFS_ACTIVITY to begin getting notifications.

APP_UNREGISTER_CONFS_ACTIVITY to stop getting notifications.

Response

Registering: CONF_STARTED for success, NACK for failure.

Unregistering: No response.

Prerequisites

“Initial Procedures” on page 40 and “Application Login Prerequisites” on

page 39.

Notes

The response to this procedure is CONF_STARTED to indicate that the
registration was received and performed successfully. After that, when a
conference starts or stops, CONF_STARTED or CONF_ENDED will be sent as
a notification.

This procedure is different from an Application simply registering for a
conference, using the APP_REGISTER_CONF and
APP_UNREGISTER_CONF events.

Proprietary & Confidential 47

ReadiVoice CAPI Developer’s Guide

The Application login isn’t associated with a particular conference, since its
primary functions are to monitor multiple conferences, and ACM
applications.

Application is a push login, so this procedure can be used only in push mode.

See “Application, Moderator, and Participant Logins” on page 13 for more
information about Application.

Setting Conference Security

Setting security is optional in CAPI.

Event

SET_CONF_SECURITY_CODE

Response

Pull: ACK for success, NACK for failure.

Push: CONF_SECURITY_CODE_CHANGED success, NACK for failure.

Prerequisites

The implementation of the conference security code (when
SET_CONF_SECURITY_CODE is sent after JOIN_CONF is sent) has been
updated. CAPI implementation changes the order and requires that
SET_CONF_SECURITY_CODE be sent before JOIN_CONF.

See also “Procedure Sequence” on page 37.

Notes

Security needs to be implemented before you have participants join a
conference. When you implement security first, the participants who then join
the conference will be prompted for the security code. If you run security after
they have joined, then they’re already in the conference so won’t be prompted
to enter the security code.

Security applies to anyone dialing in, and to some users dialing out. If the
dialout is set to the Default, then it is assumed that the person dialing out is a
Moderator, is the one setting up the security, and therefore doesn’t need to be
asked for the security code. For the ONE_CLICK dialout, however,
participants will be asked for the security code.

Dialing Participants

Note: For more information on callflows, refer to “Voice Prompts and Call
Flows” appendix of the ReadiVoice Administration and Maintenance Guide.

48 Proprietary & Confidential

Developing CAPI Applications

Dialing participants so that they can join the conference is one of the core tasks
in a conferencing application. CAPI provides a variety of ways to dial
participants:

• Standard dialing – Participants are placed into callflows as if they had
dialed into the system. They type in a conference code, record their name,
and so on.

One of the options with standard dialing is to dial out to a recording
device in addition to the participants; the device records the conference.

• One-click dialing – Participants are placed into a conference as if they had
dialed into the system. In a One-Click Conference, participants have a link
or icon, such as in an e-mail invitation, on which they can click. The
ReadiVoice system identifies the conference from the link’s URL and
returns a Web page asking for the participant’s phone number. When the
system gets this number, it calls and puts the connection in conference (or
on music hold, if the subscriber isn’t present and Quick Start is off). The
subscriber can use the same link, since the Web page provides a checkbox
to indicate subscriber and a field for entering the subscriber password.

• Blast dialing – A group of participants are dialed at once; this is a good
way to contact a large group of conference participants. When participants
pick up the phone, they are automatically joined to the conference.

• Instant dialing – Participants are placed directly into conference without
prompts. A participant is dialed and when he or she picks up the phone,
is instantly joined to the conference.

Event

DIAL_CALL

• Standard dialing – Use the CF_DEFAULT enum for the CallFlow
parameter

• Blast dialing – Use the CF_BLAST enum for the CallFlow parameter

• One-click dialing – Use the CF_ONECLICK enum for the CallFlow

parameter

• Instant-join dialing – Use the CF_INSTANT enum for the CallFlow
parameter

• Dialing out to a recorder – Use the CF_DEFAULT enum for the CallFlow
parameter, set the Part_Type to PT_RECORDER.

Response

Pull: ACK for success, NACK for failure.

Push: DIAL_STARTED or DIALOUT-CONNECTED for success; NACK for
failure.

Prerequisites

See “Procedure Sequence” on page 37.

Proprietary & Confidential 49

ReadiVoice CAPI Developer’s Guide

General Notes

Anytime a participant’s status changes, such as when they join a conference,
the PART_INFO_CHANGED message is sent. When a participant joins the
conference, the message’s value is PIR_CONNECTED_TO_CONF, the
participant’s new state. If you want to track the number of participants in the
conference, you can read the PART_INFO_CHANGED message value and
increment the number of people in the conference.

Notes on Conference Recording

Refer to the ReadiVoice Administration and Maintenance Guide for information on
setting up a system for conference recording. You need to set up values in the

odprocrc

.
value is used by default unless you pass a different phone number when you
send the DIAL_CALL event.

Notes on Joining Participants for Different Callflow Types

There are four types of enums for the callflow type of the CALL_FLOW event.
The simple part of handling the code is to specify the correct enum type, as in
this example:

file, including the

recorderPhone

value. The

recorderPhone

sender.dialCall("Dial1Passback", getSessionId(),
getConferenceId(),phoneNum1, false, partName1, "PT_SUBSCRIBER",
"CF_INSTANT", false);

The main difference is more complex, and involves how you handle the code.
Depending on the call flow type, you need to send a JOIN_PART_TO_CONF
event for that participant to put them into conference.

• If you want the user to complete an action to join the conference, such as
clicking a button, send JOIN_PART_TO_CONF event for that participant
once they complete the action. This applies to the standard callflow for
which you use the CF_DEFAULT enum.

• If you want the user to be automatically included in the conference, use the
auto-joining call flow types: blast, one-click, and instant. For these, you
don’t need to send a join event since that functionality is already built into
the listed events.

Whether you send the join event explicitly, or whether the join happens
automatically because of the callflow, the response is
PART_INFO_CHANGED containing one of several enum values. If the
participant joins the conference, the value is PIR_CONNECTED_TO_CONF,
the participant’s new state.

Sample Code for Blast Dial

See “Sample Moderator Application” on page 63 to see the sample code in
context.

50 Proprietary & Confidential

Developing CAPI Applications

/**
* Dials up to two participants. Session must be active (logged in), and the
* conference started. Each call to this function will dial a participant
* until the maximum/desired number of dial attempts have been made, then it
* will just log an error and return.
*/
public synchronized void dialPart()
{
if ( !shouldRun )
{
return;
}
Validate.isTrue(loggedIn);
Validate.notEmpty(sessionId);
Validate.isTrue(confStarted);
Validate.notEmpty(phoneNum1);
Validate.notEmpty(phoneNum2);
try
{
if ( dialCount < 1 )
{
log.info("Dialing part one");

sender.dialCall("Dial1Passback", getSessionId(), getConferenceId(),
phoneNum1, false, partName1, "PT_SUBSCRIBER", "CF_BLAST",
false);
dialCount++;
}
else if ( dialCount < 2 )
{
log.info("Dialing part two");
sender.dialCall("Dial2Passback", getSessionId(), getConferenceId(),
phoneNum2, false, partName2, "PT_PARTICIPANT", "CF_BLAST",
false);

dialCount++;
}
else
{
log.error("all parts already dialed");
}
}
catch (MarshallerException e)
{
log.fatal("Marshal error in login, exiting", e);
shutdown();
}
}

Proprietary & Confidential 51

ReadiVoice CAPI Developer’s Guide

Joining a Conference

Event

JOIN_PART_TO_CONF

Once a user is connected, send a join to bring them into the conference.

Reply

Pull: ACK for success, NACK for failure.

Push: CALL_CONNECTED_TO_CHANGED, PART_INFO_CHANGED with
PIR_CONNECTED_TO_CONF for success, NACK for failure.

Prerequisites

See “Procedure Sequence” on page 37.

Notes

You need to use this event when you use standard dialing; using
CF_DEFAULT value of the DIAL_CALL event’s CallFlow parameter. When
you use blast, instant, or one-click dialing, the conference join is “built into”
that type of callflow so the conference join doesn’t need to be done explicitly.

Using the Waiting Room

A user is placed into the waiting room when the waiting room is active and the
conference is locked. (If the waiting room is not active, the user will be
disconnected rather than put in the waiting room.)

The waiting room allows a Moderator to keep participants in a separate
location after they have dialed in, but before they have joined the conference.
For more information, refer to the ReadiVoice Subscriber Guide and to Appendix
A of the Readivoice Administration and Maintenance Guide.

Event

Once a participant is in the waiting room, you can use the following events:

• ONE_TO_ONE – Puts the specified participant in a direct, or
“point-to-point” conversation with the conference moderator. You can
also use this event to take the participant out of the conversation and put
him or her back in the waiting room. For the Connect parameter, use True
to connect and False to put back in the waiting room.

• JOIN_PART_TO_CONF – Puts the specified participant in the conference.

• DISCONNECT_CALL – Disconnects the specified participant.

ONE_TO_ONE Response

Pull: ACK for success, NACK for failure.

52 Proprietary & Confidential

Developing CAPI Applications

Push: CALL_STATUS_CHANGED or CALL_CONNECTED_TO_CHANGED
for success, NACK for failure.

JOIN_PART_TO_CONF Response

Pull: ACK for success, NACK for failure.

Push: CALL_CONNECTED_TO_CHANGED, PART_INFO_CHANGED with
PIR_CONNECTED_TO_CONF for success, NACK for failure.

DISCONNECT_CALL Response

Pull: SUBSCR_INFO for success.

Push: N/A

Prerequisites

See “Procedure Sequence” on page 37.

Setting the Port for Asynchronous Responses on the Client

Four ports are used for push (asynchronous) mode:

• The sending port on the client

• The receiving port on the server

• The sending port on the server, for the asynchronous response

• The receiving port on the client, for the asynchronous response

The ports used are selected automatically or set to port 80 (receiving port on
the server). See “Understanding CAPI Communication: Synchronous and

Asynchronous” on page 9. You can specify the receiving port on the client for

the asynchronous response.

You can specify any port you like; a simple approach is to pass the value 0
when you send the event, and the system will in turn pick a locally available
port on the client.

The port is used per connection; you can have several sessions over the same
connection.

Sample Code

See “Sample Moderator Application” on page 63 to see the sample code in
context.

The following code example shows how to set the port to 0; note the lines in
bold. There are two sections of code.

Proprietary & Confidential 53

ReadiVoice CAPI Developer’s Guide

public SimplePushModerator( String remoteHost, int remotePort, String localAsyncHost,
int localAsyncPort )

{
Validate.notEmpty(remoteHost);
Validate.isTrue(remotePort > 0);

Validate.notEmpty(localAsyncHost);
Validate.isTrue(0 <= localAsyncPort);

try
{
/*
* This is the listener for asynchronous event communication. When the server
* contacts for asynchronous communication on the specified port, this object
* will create a connection for the MessageBus.
*/

listener = new BasicListener(localAsyncPort);

/*
* The server uses the cookie to find out the details on how to establish
* the asynchronous connection with us.
*/
Cookie cookie = new BasicCookie(localAsyncHost, listener.getLocalPort());

/*
* We need to establish a basic HTTP connection to send commands and queries.
* In push-mode, responses will come back over the asynchronous connection.
*/
httpConnection = new HttpConnection("SimpleModHttp", remoteHost, remotePort, true,
Connection.DEFAULT_URL, cookie);

/*
* This is a handler for all events from the server/CACS.
*/
handler = new SimplePushModeratorHandler(this);

/*
* This objects handles conversion of the raw data off a connection into
* POJO representations of the CAPI events.
*/
unmarshaller = new CastorUnmarshaller(handler);

/*
* Once the CAPIUnmarshaller, the command sending HTTP connection, and the
* asynchronous connection listening service are set up, we give them to a
* MessageBus so it can use them to finish any further connection setup, and
* begin those communications as needed.
*/
messageBus = new BasicMessageBus(unmarshaller, httpConnection, listener);

54 Proprietary & Confidential

Developing CAPI Applications

/*
* This is the utility class that provides methods for sending the CAPI events
* to the server/CACS. These methods will handle marshalling of the passed
* arguments into the POJO representations of thoes events. It will then
* marshall those POJO representations into raw data and use the
* provided MessageBus to send to the server/CACS.
*/
sender = new CastorSender(messageBus);

shouldRun = true;

/*
* Start the main thread
*/
start();

}
catch( IOException e )
{
log.fatal("Error in setup, exiting", e);
shutdown();
}
}

... // handler class

public static void main( String[] args )
{
String cacsIp = "192.168.56.104";
int cacsPort = 80;
String localAsyncIp = "10.33.48.231";
int localAsyncPort = 0;
String logLevel = "ALL";

try
{
/*
* Set up the Log4J system
*/
RollingFileAppender appender = new RollingFileAppender(new TTCCLayout(),
"SimplePushModerator.log", true);

PatternLayout pl = new PatternLayout();
pl.setConversionPattern("%d{ISO8601} %-5p [%t]: %m%n");

appender.setLayout(pl);

BasicConfigurator.configure(appender);
}

Proprietary & Confidential 55

ReadiVoice CAPI Developer’s Guide

catch( IOException e )
{
BasicConfigurator.configure();
}

Logger logger = Logger.getLogger("com");
logger.setLevel(Level.toLevel(logLevel));
/*
* Create a SimplePushModerator. It should take care of the rest.
*/

SimplePushModerator moderator = new SimplePushModerator(cacsIp, cacsPort, localAsyncIp,
localAsyncPort);

if( moderator.isAlive() )
{
System.out.println("moderator activated");
}
}
}

Sending Events

Event

The event you want to send; see code example and sample application.

Prerequisites

See “Procedure Sequence” on page 37.

Notes

The Java utility files with “sender” in their names have extensive examples of
sending events.

Sample Code

See “Sample Moderator Application” on page 63 to see the sample code in
context. Note the lines in bold.

56 Proprietary & Confidential

Developing CAPI Applications

public synchronized void login()
{
log.debug("log in");
if( !shouldRun )
{
return;
}
Validate.isTrue(!loggedIn);

try
{
sender.loginPushModerator("PassbackLogin", accessNumber, accessCode, subPassCode);
}
catch( MarshallerException e )

{
log.fatal("Marshal error in login, exiting", e);
shutdown();
}
}

Reading Events

To read events using the Java utility classes, you can use the methods in the
CastorMessageHandlerBase class.

Event

Any event you want to read; see code example and sample application.

Prerequisites

See “Procedure Sequence” on page 37.

Notes

The CastorMessageHandlerBase.java utility file and
SimplePushModeratorHandler.java sample file have extensive examples of
reading events.

Sample Code

See “Sample Moderator Application” on page 63 to see the sample code in
context.

Proprietary & Confidential 57

ReadiVoice CAPI Developer’s Guide

public void handle( RVAPICONF_INFO_CHANGED message )
{
log.debug("Conf Info Changed...");

/*
* If this event is telling us that a conference has started inform the
* moderator accordingly
*/
if( message.getCiReason().getContent().getType() == RVAPISIMPLE_CI_REASON.CIR_CONF_STARTED_TYPE )
{
if( !moderator.isConfStarted() )
{
moderator.setConferenceId(message.getConfId().getContent());
moderator.setConfStarted(true);
}
}
}

Identifying Talkers

Identify the people talking in a specified conference.

Event

REGISTER_TALKER_UPDATE and UNREGISTER_TALKER_UPDATE

Response

Pull: N/A (only available to Push Moderator and Application login)

Push: TALKER_UPDATE event containing the participant IDs of the three
lines (the three talkers)

Prerequisites

See “Procedure Sequence” on page 37.

You can register or unregister for talker updates anytime after a conference has
started (you need the conference ID) and before the conference has ended.

Notes

REGISTER_TALKER_UPDATE is a request to register a specified conference
for Talker Update information. The response is the TALKER_UPDATE event
containing the talker information.

Sample Code

Refer to “Sample Moderator Application” on page 63 to see the code in
context.

58 Proprietary & Confidential

Developing CAPI Applications

/*
* You can register or unregister for talker updates anytime after a
* conference has started (you need the conference ID)and before the
* conference has ended.
*/
if ( confStarted && !talkerRegisterSent )
{
registerTalkers();
}

Using ACM to Interface With External Applications

ACM lets CAPI applications interface with external applications. Use the
Application login. See also “Using ACM” on page 30.

Event

ACM events in the event reference section.

Prerequisites

See “Procedure Sequence” on page 37.

Notes

The message passed through the sample code in

acmSender.acmQuery

depends
entirely on the type of messages that the ACM application understands. You
need to ensure that that message is understandable by the ACM application,
and handle any response that it sends.

Sample Code

The following example requests information from an ACM application.

Refer to “Sample Moderator Application” on page 63 to see the code in context.

/**
* Requests Acm data from an ACM application.
* @param acmAppId the application ID to request data from
* @param chanHndl the ID used to identify which channel's data to get
*/
public synchronized void getAcmData( int acmAppId, int chanHndl )
{
Validate.isTrue(loggedIn);
Validate.notEmpty(sessionId);

try
{
/*
* The ACM application ID needs to be known in order to query for data.

Proprietary & Confidential 59

ReadiVoice CAPI Developer’s Guide

* This is the value that is configured in the RV ACM system
* administration. The query and response string formats and content
* are not specified in the API (CAPI) and thus must be the result of
* some kind of agreement between the two applications. This is because
* the server (CACS) only provides a convenience communication mechanism
* between Moderator and ACM applications, so that the two applications
* don't have to communicate directly. This request/response proxy
* feature is only there for convenience, and does not preclude well
* designed applications from direct communication outside of the CACS
* and CAPI framework.
*/
acmSender.acmQuery("SimpModPassback", sessionId, acmAppId,
ACM_QUERY_STRING_CHANHNDL + chanHndl + ","
+ ACM_QUERY_STRING_CONFID + conferenceId);
}
catch (MarshallerException e)
{
log.fatal("Marshal error in talker registration, exiting", e);
shutdown();
}
}

Conference-End Procedures

Use these procedures when you’re ready to end a conference.

Ending a Conference

A conference will end automatically when there are no participants. Here’s
how to end it explicitly.

Event

END_CONF

Response

Pull: ACK for success, NACK for failure.

Push: CONF_ENDED for success, NACK for failure.

Prerequisites

See “Procedure Sequence” on page 37.

Sample Code

Refer to “Sample Moderator Application” on page 63 to see the sample code
in context.

60 Proprietary & Confidential

Developing CAPI Applications

public synchronized void shutdown()
{
log.info("shutting down");

if( shouldRun )
{
shouldRun = false;
if( confStarted )
{
try
{
sender.endConference("SimpModPassback", sessionId, conferenceId);
}
catch( MarshallerException e )
{
e.printStackTrace();
System.exit(1);
}
}
}

Logging Out

Logging out is the last step to complete when a conference is over.

Event

LOGOUT

Response

Pull: N/A

Push: N/A

Prerequisites

See “Procedure Sequence” on page 37.

Sample Code

Refer to “Sample Moderator Application” on page 63 to see the sample code
in context.

if( loggedIn )
{
try
{
/*
* This is not specifically needed since the server will kill
* the logout eventually, but it is good to send if possible.
*/
sender.logout("SimpModPassback", sessionId);

Proprietary & Confidential 61

ReadiVoice CAPI Developer’s Guide

}
catch( MarshallerException e )
{
e.printStackTrace();
System.exit(1);
}
}

if( null != messageBus )
{
messageBus.shutdown();
}
}
else
{
if( null != messageBus )
{
messageBus.shutdown();
}

System.exit(1);
}
}

62 Proprietary & Confidential

Sample Moderator Application

This section presents the CAPI sample application, which you can use as a
starting point for writing your own application.

The sample application contains two classes.

•

SimplePushModerator

thread of the sample application. This class sets up an asynchronous
push-mode Moderator communication system. With a

SimplePushModeratorHandler

application), it will log in, start a conference if one is not already started,
blast-dial two participants, and wait for the conference to end before
exiting.

, which extends

Developing CAPI Applications

Thread

. This class is the main

(the second class in the sample

SimplePushModeratorHandler

•

CastorMessageHandlerBase

class for all events coming to the application.

SimplePushModerator.java

0

1

///////////////////////////////////////////////////////////////////////////////

2

//Copyright (c) 2005 Polycom, Inc

3

///////////////////////////////////////////////////////////////////////////////

4

package com.polycom.readivoice.capi.simplemoderator;

5
6

import java.io.IOException;

7
8

import org.apache.commons.lang.Validate;

9

import org.apache.commons.logging.Log;

10

import org.apache.commons.logging.LogFactory;

11

import org.apache.log4j.BasicConfigurator;

12

import org.apache.log4j.Level;

13

import org.apache.log4j.Logger;

14

import org.apache.log4j.PatternLayout;

15

import org.apache.log4j.RollingFileAppender;

16

import org.apache.log4j.TTCCLayout;

17
18

import com.polycom.readivoice.capi.AcmSender;

19

import com.polycom.readivoice.capi.BasicCookie;

20

import com.polycom.readivoice.capi.BasicListener;

21

import com.polycom.readivoice.capi.BasicMessageBus;

22

import com.polycom.readivoice.capi.CapiUnmarshaller;

23

import com.polycom.readivoice.capi.Connection;

24

import com.polycom.readivoice.capi.Cookie;

, which extends

. This class is the main message-handling

Proprietary & Confidential 63

ReadiVoice CAPI Developer’s Guide

25

import com.polycom.readivoice.capi.HttpConnection;

26

import com.polycom.readivoice.capi.Listener;

27

import com.polycom.readivoice.capi.MarshallerException;

28

import com.polycom.readivoice.capi.MessageBus;

29

import com.polycom.readivoice.capi.MessageSender;

30

import com.polycom.readivoice.capi.castor.CastorAcmSender;

31

import com.polycom.readivoice.capi.castor.CastorSender;

32

import com.polycom.readivoice.capi.castor.CastorUnmarshaller;

33
34

/**

35

* The main thread of our example program. This class will set up an

36

* asynchronous push-mode Moderator communication system. With a

37

* {@link SimplePushModeratorHandler} it will log in, start a conference (if one

38

* is not already started), blast dial 2 participants, and wait for the

39

* conference to end before exiting.

40

*/

41

public class SimplePushModerator extends Thread

42

{

43

private static Log log = LogFactory.getLog(SimplePushModerator.class);

44
45

/*

46

* These are the needed objects to establish communications.

47

*/

48

private Listener listener = null;

49

private SimplePushModeratorHandler handler = null;

50

private CapiUnmarshaller unmarshaller = null;

51

private Connection httpConnection = null;

52

private MessageBus messageBus = null;

53

private MessageSender sender = null;

54

private AcmSender acmSender = null;

55

private String sessionId = null;

56
57

/*

58

* We need to save these for future communications.

59

*/

60

private int subscriberId = -1;

61

private int conferenceId = -1;

62
63

/*

64

* Application is responsible for sending heartbeats. This counter is just

65

* used to limit the number of heartbeats to reduce network traffic.

66

*/

64 Proprietary & Confidential

67

private static final int HEART_BEAT_COUNTER_DEFAULT = 30;

68

private int heartBeatCounter = HEART_BEAT_COUNTER_DEFAULT;

69
70

/*

71

* Internal non-API specific variables to implement program logic.

72

*/

73

private boolean shouldRun = false;

74

private boolean loggedIn = false;

75

private boolean confStarted = false;

76

private boolean talkerRegisterSent = false;

77

private int dialCount = 0;

78

private int dialConnectCount = 0;

79

private String accessNumber = “1111”;

80

private String accessCode = “1111”;

81

private String subPassCode = “1111”;

82

private String phoneNum1 = “5129”;

83

private String phoneNum2 = “5129”;

84

private String partName1 = “Part1”;

85

private String partName2 = “Part2”;

86
87

private static final int THREAD_SLEEP_TIME = 1000; // in ms

88

private static final int LOGIN_COUNTER_DEFAULT = 10;

89

private static final int CONF_START_COUNTER_DEFAULT = 30;

90

private static final int PARTS_CONNECTED_COUNTER_DEFAULT = 120;

91

private static final String CONFERENCE_SECURITY_NUMBER = “1234567890”;

92

private static final String ACM_QUERY_STRING_CHANHNDL = “CHANHNDL=”;

93

private static final String ACM_QUERY_STRING_CONFID = “CONFID=”;

94

private static int sHeartBeatSeq = 0;

95
96

/**

97

* Constructor. Sets up communication system and starts the main thread.

98

*

99

* @param remoteHost

100

* server/CACS’ host name (IP address or name)

101

* @param remotePort

102

* server/CACS’ port where commands/queries will be sent

103

* @param localAsyncHost

104

* host where asynchronous connections should be listened for

105

* @param localAsyncPort

106

* port where asynchronous connections should be listened for,

107

* usually port 80 unless otherwise configured on the server/CACS

108

*/

109

public SimplePushModerator(String remoteHost, int remotePort,

Developing CAPI Applications

Proprietary & Confidential 65

ReadiVoice CAPI Developer’s Guide

110

String localAsyncHost, int localAsyncPort)

111

{

112

Validate.notEmpty(remoteHost);

113

Validate.isTrue(remotePort > 0);

114

Validate.notEmpty(localAsyncHost);

115

Validate.isTrue(0 <= localAsyncPort);

116
117

try

118

{

119

/*

120

* This is the listener for asynchronous event communication. When the

121

* server contacts for asynchronous communication on the specified

122

* port, this object will create a connection for the MessageBus.

123

*/

124

listener = new BasicListener(localAsyncPort);

125
126

/*

127

* The server uses the cookie to find out the details on how to

128

* establish the asynchronous connection with us.

129

*/

130

Cookie cookie = new BasicCookie(localAsyncHost,

131

listener.getLocalPort());

132
133

/*

134

* We need to establish a basic HTTP connection to send commands and

135

* queries. In push-mode, responses will come back over the

136

* asynchronous connection.

137

*/

138

httpConnection = new HttpConnection(“SimpleModHttp”, remoteHost,

139

remotePort, true, Connection.DEFAULT_URL, cookie);

140
141

/*

142

* This is a handler for all events from the server/CACS.

143

*/

144

handler = new SimplePushModeratorHandler(this);

145
146

/*

147

* This objects handles conversion of the raw data off a connection

148

* into POJO representations of the CAPI events.

149

*/

150

unmarshaller = new CastorUnmarshaller(handler);

151

66 Proprietary & Confidential

152

/*

153

* Once the CAPIUnmarshaller, the command sending HTTP connection, and

154

* the asynchronous connection listening service are set up, we give

155

* them to a MessageBus so it can use them to finish any further

156

* connection setup, and begin those communications as needed.

157

*/

158

messageBus = new BasicMessageBus(unmarshaller, httpConnection,

159

listener);

160
161

/*

162

* This is the utility class that provides methods for sending the CAPI

163

* events to the server/CACS. These methods will handle marshalling of

164

* the passed arguments into the POJO representations of those events.

165

* It will then marshall those POJO representations into raw data and

166

* use the provided MessageBus to send to the server/CACS.

167

*/

168

sender = new CastorSender(messageBus);

169
170

/*

171

* An AcmSender and CastorAcmSender are children of base MessageSender

172

* and CastorSender and as such contain all the base’s functionality.

173

* We are using both here just for clarity, otherwise this ACM sender

174

* would be more than sufficent to deal with all our application’s

175

* sending needs.

176

*/

177

acmSender = new CastorAcmSender(messageBus);

178
179

shouldRun = true;

180
181

/*

182

* Start the main thread

183

*/

184

start();

185
186

}

187

catch (IOException e)

188

{

189

log.fatal(“Error in setup, exiting”, e);

190

shutdown();

191

}

192

}

193
194

public synchronized final String getSessionId()

Developing CAPI Applications

Proprietary & Confidential 67

ReadiVoice CAPI Developer’s Guide

195

{

196

return sessionId;

197

}

198
199

public synchronized final void setSessionId( String sessionId )

200

{

201

this.sessionId = sessionId;

202

}

203
204

public synchronized final boolean isConfStarted()

205

{

206

return this.confStarted;

207

}

208
209

public synchronized final void setConfStarted( boolean confStarted )

210

{

211

this.confStarted = confStarted;

212
213

/*

214

* You can register or unregister for talker updates anytime after a

215

* conference has started (you need the conference ID)and before the

216

* conference has ended.

217

*/

218

if ( confStarted && !talkerRegisterSent )

219

{

220

registerTalkers();

221

}

222

}

223
224

public synchronized final boolean isLoggedIn()

225

{

226

return this.loggedIn;

227

}

228
229

public synchronized final void setLoggedIn( boolean loggedIn )

230

{

231

this.loggedIn = loggedIn;

232

}

233
234

public synchronized final boolean shouldRun()

235

{

236

return this.shouldRun;

68 Proprietary & Confidential

237

}

238
239

public synchronized final void setShouldRun( boolean shouldRun )

240

{

241

this.shouldRun = shouldRun;

242

}

243
244

public synchronized final int getSubscriberId()

245

{

246

return this.subscriberId;

247

}

248
249

public synchronized final void setSubscriberId( int subscriberId )

250

{

251

this.subscriberId = subscriberId;

252

}

253
254

public synchronized final int getConferenceId()

255

{

256

return this.conferenceId;

257

}

258
259

public synchronized final void setConferenceId( int confenceId )

260

{

261

this.conferenceId = confenceId;

262

}

263
264

public synchronized final int getDialConnectCount()

265

{

266

return this.dialConnectCount;

267

}

268
269

public synchronized final void setDialConnectCount( int dialConnectCount )

270

{

271

this.dialConnectCount = dialConnectCount;

272

}

273
274

public synchronized final int getDialCount()

275

{

276

return this.dialCount;

277

}

278
279

public synchronized final void setDialCount( int dialCount )

Developing CAPI Applications

Proprietary & Confidential 69

ReadiVoice CAPI Developer’s Guide

280

{

281

this.dialCount = dialCount;

282

}

283
284

/**

285

* Sends a push mode modeartor login.

286

*/

287

public synchronized void login()

288

{

289

log.debug(“log in”);

290
291

if ( !shouldRun )

292

{

293

return;

294

}

295
296

Validate.isTrue(!loggedIn);

297
298

try

299

{

300

sender.loginPushModerator(“PassbackLogin”, accessNumber, accessCode,

301

subPassCode);

302

}

303

catch (MarshallerException e)

304

{

305

log.fatal(“Marshal error in login, exiting”, e);

306

shutdown();

307

}

308

}

309
310

/**

311

* Requests subscriber information from server.

312

*/

313

public synchronized void checkSubscription()

314

{

315

log.debug(“checkSubscription”);

316
317

if ( !shouldRun )

318

{

319

return;

320

}

321

70 Proprietary & Confidential

322

Validate.isTrue(loggedIn);

323

Validate.notEmpty(sessionId);

324
325

try

326

{

327

sender.requestSubscriberInfo(“SimpleModPassback”, getSessionId(),

328

getSubscriberId());

329

}

330

catch (MarshallerException e)

331

{

332

log.fatal(“Marshal error in login, exiting”, e);

333

shutdown();

334

}

335
336

}

337
338

/**

339

* Starts a conference only if application is successfuly logged in and a

340

* conference has not already been started.

341

*/

342

public synchronized void startConf()

343

{

344

log.debug(“startConf”);

345
346

if ( !shouldRun )

347

{

348

return;

349

}

350
351

Validate.isTrue(loggedIn);

352

Validate.notEmpty(sessionId);

353

Validate.isTrue(!confStarted);

354
355

try

356

{

357

sender.startConference(“PassbackStartConf”, getSessionId(),

358

getSubscriberId());

359

}

360

catch (MarshallerException e)

361

{

362

log.fatal(“Marshal error in login, exiting”, e);

363

shutdown();

364

}

Developing CAPI Applications

Proprietary & Confidential 71

ReadiVoice CAPI Developer’s Guide

365

}

366
367

/**

368

* Dials up to 2 participants. Session must be active (logged in), and the

369

* conference started. Each call to this function will dial a participant

370

* until the maximum/desired number of dial attempts have been made, then it

371

* will just log an error and return.

372

*/

373

public synchronized void dialPart()

374

{

375

if ( !shouldRun )

376

{

377

return;

378

}

379
380

Validate.isTrue(loggedIn);

381

Validate.notEmpty(sessionId);

382

Validate.isTrue(confStarted);

383

Validate.notEmpty(phoneNum1);

384

Validate.notEmpty(phoneNum2);

385
386

try

387

{

388

if ( dialCount < 1 )

389

{

390

log.info(“Dialing part one”);

391
392

sender.dialCall(“Dial1Passback”, getSessionId(), getConferenceId(),

393

phoneNum1, false, partName1, “PT_SUBSCRIBER”, “CF_BLAST”,

394

false);

395
396

dialCount++;

397

}

398

else if ( dialCount < 2 )

399

{

400

log.info(“Dialing part two”);

401
402

sender.dialCall(“Dial2Passback”, getSessionId(), getConferenceId(),

403

phoneNum2, false, partName2, “PT_PARTICIPANT”, “CF_BLAST”,

404

false);

405
406

dialCount++;

72 Proprietary & Confidential

407

}

408

else

409

{

410

log.error(“all parts already dialed”);

411

}

412

}

413

catch (MarshallerException e)

414

{

415

log.fatal(“Marshal error in login, exiting”, e);

416

shutdown();

417

}

418

}

419
420

/**

421

* Sends a heartbeat event with an incrementing sequence number.

422

*/

423

public synchronized void heartBeat()

424

{

425

if ( heartBeatCounter == 0 )

426

{

427

log.debug(“sending connection heartbeat...”);

428

try

429

{

430

/*

431

* The server doesn’t really care what the sequence number is, it is

432

* more of a specific passback incase the client would like to match

433

* up heartbeats and heartbeat acknowledgements . This is a good

434

* mechanism for the client

435

*/

436

sender.sessionHeartbeat(“SimpModPassback”, sessionId,

437

sHeartBeatSeq++);

438

}

439

catch (MarshallerException e)

440

{

441

e.printStackTrace();

442

System.exit(1);

443

}

444

heartBeatCounter = HEART_BEAT_COUNTER_DEFAULT;

445

}

446

else

447

{

448

heartBeatCounter--;

449

}

Developing CAPI Applications

Proprietary & Confidential 73

ReadiVoice CAPI Developer’s Guide

450

}

451
452

/**

453

* Registers for talker update notifications. The session must be active and

454

* the conference started for this function to work.

455

*/

456

public synchronized void registerTalkers()

457

{

458

/*

459

* Talker registration must have an active conference to register for,

460

* otherwise there are no timing concerns.

461

*/

462

Validate.isTrue(loggedIn);

463

Validate.notEmpty(sessionId);

464

Validate.isTrue(confStarted);

465
466

try

467

{

468

sender.registerTalkers(“SimpModPassback”, sessionId, conferenceId);

469

talkerRegisterSent = true;

470

}

471

catch (MarshallerException e)

472

{

473

log.fatal(“Marshal error in talker registration, exiting”, e);

474

shutdown();

475

}

476

}

477
478

/**

479

* Sets a security code for the conference. The session must be active, and

480

* the conference must be running.

481

*/

482

public synchronized void setSecurityCode()

483

{

484

/*

485

* The conf security code is now optional. We are sending here just to

486

* illustrate its use. It applies to active conferences’ parts only after

487

* the event is received (new participants dialing in from that point on,

488

* or being dialed out with certain call flows such as CF_CALLFLOW). If a

489

* join event is manually sent for any part not yet in conference, it will

490

* bypass the conference security code (and other call flow for that

491

* matter) and join them to the conference. The code can be altered at any

74 Proprietary & Confidential

492

* time (of the conference’s life) by resending the event with the new

493

* value.

494

*/

495

Validate.isTrue(loggedIn);

496

Validate.notEmpty(sessionId);

497

Validate.isTrue(confStarted);

498
499

try

500

{

501

sender.setConfSecurityCode(“SimpModPassback”, sessionId, conferenceId,

502

CONFERENCE_SECURITY_NUMBER);

503

}

504

catch (MarshallerException e)

505

{

506

log.fatal(“Marshal error in setting conf security number, exiting”, e);

507

shutdown();

508

}

509

}

510
511

/**

512

* Requests ACM data from an ACM application.

513

* @param acmAppId the application ID to request data from

514

* @param chanHndl the ID used to identify which channel’s data to get

515

*/

516

public synchronized void getAcmData( int acmAppId, int chanHndl )

517

{

518

Validate.isTrue(loggedIn);

519

Validate.notEmpty(sessionId);

520
521

try

522

{

523

/*

524

* The ACM application ID needs to be known in order to query for data.

525

* This is the value that is configured in the RV ACM system

526

* administration. The query and response string formats and content

527

* are not specified in the API (CAPI) and thus must be the result of

528

* some kind of agreement between the two applications. This is because

529

* the server (CACS) only provides a convenience communication

530

* mechanism between Moderator and ACM applications, so that the two

531

* applications don’t have to communicate directly. This

532

* request/response proxy feature is only there for convenience, and

533

* does not preclude well designed applications from direct

534

* communication outside of the CACS and CAPI framework.

Developing CAPI Applications

Proprietary & Confidential 75

ReadiVoice CAPI Developer’s Guide

535

*/

536

acmSender.acmQuery(“SimpModPassback”, sessionId, acmAppId,

537

ACM_QUERY_STRING_CHANHNDL + chanHndl + “,”

538

+ ACM_QUERY_STRING_CONFID + conferenceId);

539

}

540

catch (MarshallerException e)

541

{

542

log.fatal(“Marshal error in talker registration, exiting”, e);

543

shutdown();

544

}

545

}

546
547

/**

548

* Shuts down this program, ending the conference if running, logging out if

549

* needed. The termination of the conference is only done here to illistrate

550

* how it is done, not to mandate that when a CAPI application logs out it

551

* should end a conference as a general rule. Typically logging out of a

552

* client should not terminate the conference, unless that is the actual

553

* desired behavior. The unregistrations for talkers and the logging out are

554

* not required per the CAPI spec (as the CACS server will take care of this

555

* on session termination) but it should be done, and thus is illustrated

556

* here.

557

*/

558

public synchronized void shutdown()

559

{

560

log.info(“shutting down”);

561
562

if ( shouldRun )

563

{

564

shouldRun = false;

565
566

if ( confStarted )

567

{

568

try

569

{

570

/*

571

* This will automatically be done at conf end, but to be nice

572

* unregister for the talkers

573

*/

574

sender.unregisterTalkers(“SimpModPassback”, sessionId,

575

conferenceId);

576

76 Proprietary & Confidential

577

/*

578

* The Program is done, end the conference if it is still active.

579

*/

580

sender.endConference(“SimpModPassback”, sessionId, conferenceId);

581
582

}

583

catch (MarshallerException e)

584

{

585

e.printStackTrace();

586

System.exit(1);

587

}

588

}

589
590

if ( loggedIn )

591

{

592

try

593

{

594

/*

595

* This is not specifically needed since the server will kill the

596

* logout eventually, but it is nice of us to send if we can.

597

*/

598

sender.logout(“SimpModPassback”, sessionId);

599

}

600

catch (MarshallerException e)

601

{

602

e.printStackTrace();

603

System.exit(1);

604

}

605

}

606
607

if ( null != messageBus )

608

{

609

messageBus.shutdown();

610

}

611

}

612

else

613

{

614

if ( null != messageBus )

615

{

616

messageBus.shutdown();

617

}

618
619

System.exit(1);

Developing CAPI Applications

Proprietary & Confidential 77

ReadiVoice CAPI Developer’s Guide

620

}

621

}

622
623

/**

624

* This function only contains internal program methods and variables needed

625

* to accomplish the sample’s goal, and has nothing particularly CAPI

626

* specific in it except for the fact that it must initiate the heartbeat

627

* periodically to keep the connection alive. If no traffic is sent to the

628

* server/CACS for a configurable (at the server) amount of time the session

629

* is invalidated and the application will have to log back in to continue.

630

*/

631

public void run()

632

{

633

log.debug(“Main Thread running...”);

634
635

int notLoggedInCounter = LOGIN_COUNTER_DEFAULT;

636

int confNotStartedCounter = CONF_START_COUNTER_DEFAULT;

637

int partsNotConnectedYet = PARTS_CONNECTED_COUNTER_DEFAULT;

638

boolean setupDone = false;

639
640

login();

641
642

while (shouldRun)

643

{

644

try

645

{

646

if ( !setupDone )

647

{

648

if ( !isLoggedIn() )

649

{

650

log.debug(“not logged in yet counter left[“

651

+ notLoggedInCounter + “]”);

652
653

notLoggedInCounter--;

654

if ( notLoggedInCounter < 0 )

655

{

656

log.fatal(“Did not log in before timeout”);

657

shutdown();

658

}

659

}

660

else

661

{

78 Proprietary & Confidential

662

if ( !isConfStarted() )

663

{

664

log.debug(“Conf not Started, counter[“

665

+ confNotStartedCounter + “]”);

666
667

confNotStartedCounter--;

668

if ( confNotStartedCounter < 0 )

669

{

670

log.fatal(“Conf did not start before timeout”);

671

shutdown();

672

}

673

}

674

else

675

{

676

int dialCount = getDialCount();

677

int dialsConnected = getDialConnectCount();

678
679

log.debug(“Conf Started, dialCount[“ + dialCount

680

+ “] dialsConnected[“ + dialsConnected + “]”);

681
682

if ( dialCount < 2 )

683

{

684

dialPart();

685

}

686
687

if ( dialCount > 0 && (dialCount != dialsConnected) )

688

{

689

log.debug(“dials not yet equal counter left[“

690

+ partsNotConnectedYet + “]”);

691
692

partsNotConnectedYet--;

693

if ( partsNotConnectedYet < 0 )

694

{

695

log.fatal(“All parts did not connect”);

696

shutdown();

697

}

698

}

699
700

if ( dialCount > 0 && (dialsConnected >= dialCount) )

701

{

702

log.info(“All parts are connected”);

703
704

/*

Developing CAPI Applications

Proprietary & Confidential 79

ReadiVoice CAPI Developer’s Guide

705

* Arbitraily sent here. It is valid anytime after a

706

* conference is running.

707

*/

708

setSecurityCode();

709
710

setupDone = true;

711

}

712

}

713

}

714

}

715
716

/*

717

* All of our parts were dialed and connected, and now we notice

718

* that no one is left in conf, end the program.

719

*/

720

if ( setupDone && getDialConnectCount() <= 0 )

721

{

722

shutdown();

723

}

724
725

heartBeat();

726
727

sleep(THREAD_SLEEP_TIME);

728

}

729

catch (InterruptedException e)

730

{

731

log.fatal(“sleep was interupted”, e);

732

}

733

}

734
735

log.debug(“exit main while”);

736
737

}

738
739

/**

740

* The main method for program execution. Sets up IP addresses and ports, as

741

* well as the application level logging.

742

*

743

* @param args

744

*/

745

public static void main( String[] args )

746

{

80 Proprietary & Confidential

747

String cacsIp = “192.168.56.104”;

748

int cacsPort = 80;

749

String localAsyncIp = “10.33.48.231”;

750

int localAsyncPort = 0;

751

String logLevel = “ALL”;

752
753

try

754

{

755

/*

756

* Set up the Log4J system, refer to the Log4J manual for more

757

* information. Sets up a single rolling log file called

758

* SimplePushModerator.log

759

*/

760

RollingFileAppender appender = new RollingFileAppender(

761

new TTCCLayout(), “SimplePushModerator.log”, true);

762
763

PatternLayout pl = new PatternLayout();

764

pl.setConversionPattern(“%d{ISO8601} %-5p [%t]: %m%n”);

765
766

appender.setLayout(pl);

767
768

BasicConfigurator.configure(appender);

769

}

770

catch (IOException e)

771

{

772

BasicConfigurator.configure();

773

}

774

/*

775
776

* Sets the logging level for all packages in CAPI, both

777

* this application, and base CAPI classes. This could

778

* be made specific per class file per the Log4J and Apache

779

* commons logging interface manuals.

780

*/

781

Logger logger = Logger.getLogger(“com”);

782

logger.setLevel(Level.toLevel(logLevel));

783
784

/*

785

* Create a SimplePushModerator. It should take care of the rest.

786

*/

787

SimplePushModerator moderator = new SimplePushModerator(cacsIp, cacsPort,

788

localAsyncIp, localAsyncPort);

789

Developing CAPI Applications

Proprietary & Confidential 81

ReadiVoice CAPI Developer’s Guide

790

if ( moderator.isAlive() )

791

{

792

System.out.println(“moderator activated”);

793

}

794

}

795

}

796

82 Proprietary & Confidential

SimplePushModeratorHandler.java

0

1

///////////////////////////////////////////////////////////////////////////////

//Copyright (c) 2005 Polycom, Inc

2

///////////////////////////////////////////////////////////////////////////////

3

package com.polycom.readivoice.capi.simplemoderator;

4
5

import org.apache.commons.logging.Log;

6

import org.apache.commons.logging.LogFactory;

7
8

import com.polycom.readivoice.capi.castor.CastorMessageHandlerBase;

9

import com.polycom.readivoice.capi.castor.events.RVAPIACM_QUERY_RESP;

10

import com.polycom.readivoice.capi.castor.events.RVAPICALL_DISCONNECTED;

11

import com.polycom.readivoice.capi.castor.events.RVAPICONF_ENDED;

12

import com.polycom.readivoice.capi.castor.events.RVAPICONF_INFO;

13

import com.polycom.readivoice.capi.castor.events.RVAPICONF_INFO_CHANGED;

14

import com.polycom.readivoice.capi.castor.events.RVAPINACK;

15

import com.polycom.readivoice.capi.castor.events.RVAPIPART_INFO_CHANGED;

16

import com.polycom.readivoice.capi.castor.events.RVAPISESSION_HEARTBEAT_ACK;

17

import com.polycom.readivoice.capi.castor.events.RVAPISUBSCR_INFO;

18

import com.polycom.readivoice.capi.castor.events.RVAPITALKER_UPDATE;

19

import com.polycom.readivoice.capi.castor.events.types.RVAPISIMPLE_ACM_REASON_CODE;

20

import com.polycom.readivoice.capi.castor.events.types.RVAPISIMPLE_CI_REASON;

21

import com.polycom.readivoice.capi.castor.events.types.RVAPISIMPLE_PI_REASON;

22

import com.polycom.readivoice.capi.castor.events.types.RVSIMPLE_API_EV_TYPE;

23
24

/**

25
26

* Main message handling class for all events coming to the application.

27

*/

28

public class SimplePushModeratorHandler extends CastorMessageHandlerBase

29

{

30

private static Log log = LogFactory.getLog(SimplePushModeratorHandler.class);

31
32

private static final int ACMPINS_APP_ID = 30;

33

private SimplePushModerator moderator;

34
35
36

/**

37

* Constructor. Takes a {@link SimplePushModerator} as a parameter

38

* so that it can set values inside of it, and call methods. Using a proper

39

* object model, this would not be needed.

40

*/

41

public SimplePushModeratorHandler( SimplePushModerator moderator )

42

{

Developing CAPI Applications

Proprietary & Confidential 83

ReadiVoice CAPI Developer’s Guide

43

this.moderator = moderator;

44

}

45

public void handle( RVAPINACK message )

46
47

{

48

log.debug(“Got ACK to message” + message);

49
50

switch( message.getEvent().getContent().getType() )

51

{

52

/*

53

* The login failed for some reason, we can’t do anything else,

54

* exit the application.

55

*/

56

case RVSIMPLE_API_EV_TYPE.ET_LOGIN_PUSH_MODERATOR_TYPE:

57

moderator.setLoggedIn(false);

58

log.fatal(“Could not login, NACK received reason[“

59

+ message.getNackReason().getContent().toString() + “] Message[“

60

+ message.getMessage().getContent() + “]”);

61

moderator.shutdown();

62
63

break;

64

case RVSIMPLE_API_EV_TYPE.ET_START_CONF_TYPE:

65
66

moderator.setConfStarted(false);

67

log.warn(“Could not start conference, NACK received reason[“

68

+ message.getNackReason().getContent().toString() + “] Message[“

69

+ message.getMessage().getContent() + “]”);

70

break;

71
72

/*

73

* You could attempt a re-login here instead of failing

74

*/

75

case RVSIMPLE_API_EV_TYPE.ET_SESSION_HEARTBEAT_TYPE:

76

log.fatal(“Session heartbeat failed, shutdown”);

77

moderator.shutdown();

78

break;

79

default:

80
81

break;

82

}

83

}

84

public void handle( RVAPISUBSCR_INFO message )

85
86

{

87

log.debug(“Got a SUBSCR_INFO: “ + message.toString());

88

84 Proprietary & Confidential

Developing CAPI Applications

89

/*

90

* If this event is a reply to a login request, mark us as logged in,

91

* setting our session and subscription ID values.

92

*/

93

if( message.getEvent().getContent().getType() == RVSIMPLE_API_EV_TYPE.ET_LOGIN_PUSH_MODERATOR_TYPE )

94

{

95

if( !moderator.isLoggedIn() )

96

{

97

moderator.setSessionId(message.getSessionId().getContent());

98

moderator.setSubscriberId(message.getSubscrId().getContent());

99

moderator.setLoggedIn(true);

100

}

101

}

102

if( !moderator.isConfStarted() )

103
104

{

105

if( message.getConfRunning().getContent() )

106

{

107

moderator.setConferenceId(message.getConfId().getContent());

108

moderator.setConfStarted(true);

109

}

110

else

111

{

112

moderator.startConf();

113

}

114

}

115

}

116

public void handle( RVAPICONF_INFO_CHANGED message )

117
118

{

119

log.debug(“Conf Info Changed...”);

120

/*

121
122

* If this event is telling us that a conference has started, inform the

123

* moderator accordingly

124

*/

125

if( message.getCiReason().getContent().getType() == RVAPISIMPLE_CI_REASON.CIR_CONF_STARTED_TYPE )

126

{

127

if( !moderator.isConfStarted() )

128

{

129

moderator.setConferenceId(message.getConfId().getContent());

130

moderator.setConfStarted(true);

131

}

132

}

133

}

134

Proprietary & Confidential 85

ReadiVoice CAPI Developer’s Guide

135
136

/*

137

* This may be sent periodically notifying us of conference information. We

138

* will only get this if the conf is running, so we should inform the

139

* moderator as such if it isn’t already.

140

*/

141

public void handle( RVAPICONF_INFO message )

142

{

143

log.debug(“Got conf info...” + message.toString());

144
145

if( !moderator.isConfStarted() )

146

{

147

moderator.setConferenceId(message.getConfId().getContent());

148

moderator.setConfStarted(true);

149

}

150

}

151

public void handle( RVAPICONF_ENDED message )

152
153

{

154

log.debug(“Got Conf ended...” + message.toString());

155

moderator.shutdown();

156

}

157
158

public void handle( RVAPIPART_INFO_CHANGED message )

159

{

160

if( message.getPiReason().getContent().getType() == RVAPISIMPLE_PI_REASON.PIR_CONNECTED_TO_CONF_TYPE )

161

{

162

moderator.setDialConnectCount(moderator.getDialConnectCount() + 1);

163

moderator.getAcmData(ACMPINS_APP_ID, message.getPartId().getContent());

164

}

165

}

166
167

public void handle( RVAPICALL_DISCONNECTED message )

168

{

169

log.debug(“got part disconnected msg...” + message.toString());

170

moderator.setDialConnectCount(moderator.getDialConnectCount() - 1);

171
172

}

173
174

public void handle( RVAPISESSION_HEARTBEAT_ACK message )

175

{

176

log.debug(“got session heartbeat ack...” + message.toString());

177

}

178
179

public void handle(RVAPITALKER_UPDATE message )

180

{

86 Proprietary & Confidential