Polycom ReadiVoice Developer's Manual

Category
Software
Type
Developer's Manual

This manual is also suitable for

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
© 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.
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.
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
1 / 1

Polycom ReadiVoice Developer's Manual

Category
Software
Type
Developer's Manual
This manual is also suitable for

Ask a question and I''ll find the answer in the document

Finding information in a document is now easier with AI

Ask the document