Polycom ReadiVoice Developer's Manual

ReadiVoice CAPI

Developer’s Guide

ReadiVoice CAPI Developer’s Guide

ii Proprietary & Confidential

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

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.

Proprietary & Confidential iii

Contents

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

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

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

Introducing CAPI

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

ReadiVoice CAPI Developer’s Guide

iv Proprietary & Confidential

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

Contents

Proprietary & Confidential v

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

ReadiVoice CAPI Developer’s Guide

vi Proprietary & Confidential

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

Contents

Proprietary & Confidential vii

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

ReadiVoice CAPI Developer’s Guide

viii Proprietary & Confidential

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

Contents

Proprietary & Confidential ix

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

ReadiVoice CAPI Developer’s Guide

x Proprietary & Confidential

Proprietary & Confidential xi

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

iVoice Provisioning Guide

• Re

adiVoice Operator Guide

• Re

adiVoice Subscriber Guide

• Re

adiVoice Administration and Maintenance Guide

ReadiVoice CAPI Developer’s Guide

xii Proprietary & Confidential

Document Conventions

This document uses the following typographical conventions.

Typeface Usage

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

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.

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

According to the VERITAS Cluster Server User

Guide, crash tolerant applications are sometimes

referred to as cluster friendly applications.

code

Computer output, command references within text,

and filenames; for example:

Performs the initial configuration and reads the

.vcsrc

file

code, bold

Command line entries, for example:

>>

Type

cp ../default_group.ini

group.ini

.

code, bold & italics

Command line variables, for example:

>>

Type

cp ../default_group.ini

groupnn.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.

About this Manual

Proprietary & Confidential xiii

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:

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: [email protected]

• Polycom Global Services in U.S.A

800-827-7782

• Denver metro or outside U.S.A.

303-223-5223

• Email: [email protected]

ReadiVoice CAPI Developer’s Guide

xiv Proprietary & Confidential

Proprietary & Confidential 1

1

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

• “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.

ReadiVoice CAPI Developer’s Guide

2 Proprietary & Confidential

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

Introducing CAPI

Proprietary & Confidential 3

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.

• 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.

ReadiVoice CAPI Developer’s Guide

4 Proprietary & Confidential

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.

• 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.

Getting Started

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.

Proprietary & Confidential 5

2

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

• “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.

ReadiVoice CAPI Developer’s Guide

6 Proprietary & Confidential

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

Page is loading ...

Polycom ReadiVoice Developer's Manual

This manual is also suitable for

Polycom ReadiVoice Developer's Manual

Related papers

Other documents