OPAL Version 3.10.4

- Main Page
- Related Pages
- Namespaces
- Data Structures
- Files

- File List
- Globals

opal.h
Go to the documentation of this file.
1 /*
2 * opal.h
3 *
4 * "C" language interface for OPAL
5 *
6 * Open Phone Abstraction Library (OPAL)
7 *
8 * Copyright (c) 2008 Vox Lucida
9 *
10 * The contents of this file are subject to the Mozilla Public License
11 * Version 1.0 (the "License"); you may not use this file except in
12 * compliance with the License. You may obtain a copy of the License at
13 * http://www.mozilla.org/MPL/
14 *
15 * Software distributed under the License is distributed on an "AS IS"
16 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
17 * the License for the specific language governing rights and limitations
18 * under the License.
19 *
20 * The Original Code is Open Phone Abstraction Library.
21 *
22 * The Initial Developer of the Original Code is Vox Lucida (Robert Jongbloed)
23 *
24 * This code was initially written with the assisance of funding from
25 * Stonevoice. http://www.stonevoice.com.
26 *
27 * Contributor(s): ______________________________________.
28 *
29 * $Revision: 26939 $
30 * $Author: rjongbloed $
31 * $Date: 2012-02-07 01:17:49 -0600 (Tue, 07 Feb 2012) $
32 */
33
34 #ifndef OPAL_OPAL_H
35 #define OPAL_OPAL_H
36
37 #include <stdlib.h>
38
39
40 #ifdef __cplusplus
41 extern "C" {
42 #endif
43
70 #ifdef _WIN32
71 #define OPAL_EXPORT __stdcall
72 #else
73 #define OPAL_EXPORT
74 #endif
75
77 typedef struct OpalHandleStruct * OpalHandle;
78
79
80 typedef struct OpalMessage OpalMessage;
81
83 #define OPAL_C_API_VERSION 26
84
85
87
138 OpalHandle OPAL_EXPORT OpalInitialise(unsigned * version, const char * options);
139
143 #define OPAL_INITIALISE_FUNCTION "OpalInitialise"
144
148 typedef OpalHandle (OPAL_EXPORT *OpalInitialiseFunction)(unsigned * version, const char * options);
149
150
152
161 void OPAL_EXPORT OpalShutDown(OpalHandle opal);
162
166 #define OPAL_SHUTDOWN_FUNCTION "OpalShutDown"
167
171 typedef void (OPAL_EXPORT *OpalShutDownFunction)(OpalHandle opal);
172
173
175
212 OpalMessage * OPAL_EXPORT OpalGetMessage(OpalHandle opal, unsigned timeout);
213
217 #define OPAL_GET_MESSAGE_FUNCTION "OpalGetMessage"
218
222 typedef OpalMessage * (OPAL_EXPORT *OpalGetMessageFunction)(OpalHandle opal, unsigned timeout);
223
224
226
267 OpalMessage * OPAL_EXPORT OpalSendMessage(OpalHandle opal, const OpalMessage * message);
268
272 typedef OpalMessage * (OPAL_EXPORT *OpalSendMessageFunction)(OpalHandle opal, const OpalMessage * message);
273
277 #define OPAL_SEND_MESSAGE_FUNCTION "OpalSendMessage"
278
279
281
285 void OPAL_EXPORT OpalFreeMessage(OpalMessage * message);
286
290 #define OPAL_FREE_MESSAGE_FUNCTION "OpalFreeMessage"
291
295 typedef void (OPAL_EXPORT *OpalFreeMessageFunction)(OpalMessage * message);
296
297
299
300 #define OPAL_PREFIX_H323 "h323"
301 #define OPAL_PREFIX_SIP "sip"
302 #define OPAL_PREFIX_IAX2 "iax2"
303 #define OPAL_PREFIX_PCSS "pc"
304 #define OPAL_PREFIX_LOCAL "local"
305 #define OPAL_PREFIX_POTS "pots"
306 #define OPAL_PREFIX_PSTN "pstn"
307 #define OPAL_PREFIX_IVR "ivr"
308
309 #define OPAL_PREFIX_ALL OPAL_PREFIX_H323 " " \
310 OPAL_PREFIX_SIP " " \
311 OPAL_PREFIX_IAX2 " " \
312 OPAL_PREFIX_PCSS " " \
313 OPAL_PREFIX_LOCAL " " \
314 OPAL_PREFIX_POTS " " \
315 OPAL_PREFIX_PSTN " " \
316 OPAL_PREFIX_IVR
317
318
321 typedef enum OpalMessageType {
322 OpalIndCommandError,
325 OpalCmdSetGeneralParameters,
327 OpalCmdSetProtocolParameters,
330 OpalCmdRegistration,
334 OpalIndRegistration,
339 OpalCmdSetUpCall,
343 OpalIndIncomingCall,
346 OpalCmdAnswerCall,
350 OpalCmdClearCall,
355 OpalIndAlerting,
359 OpalIndEstablished,
363 OpalIndUserInput,
366 OpalIndCallCleared,
369 OpalCmdHoldCall,
371 OpalCmdRetrieveCall,
373 OpalCmdTransferCall,
376 OpalCmdUserInput,
378 OpalIndMessageWaiting,
381 OpalIndMediaStream,
384 OpalCmdMediaStream,
386 OpalCmdSetUserData,
387 OpalIndLineAppearance,
390 OpalCmdStartRecording,
392 OpalCmdStopRecording,
394 OpalIndProceeding,
402 OpalCmdAlerting,
404 OpalIndOnHold,
406 OpalIndOffHold,
408 OpalIndTransferCall,
411 OpalIndCompletedIVR,
415 // Always add new messages to ethe end to maintain backward compatibility
416 OpalMessageTypeCount
417 } OpalMessageType;
418
419
423 typedef enum OpalSilenceDetectMode {
424 OpalSilenceDetectNoChange,
425 OpalSilenceDetectDisabled,
426 OpalSilenceDetectFixed,
427 OpalSilenceDetectAdaptive
428 } OpalSilenceDetectMode;
429
430
434 typedef enum OpalEchoCancelMode {
435 OpalEchoCancelNoChange,
436 OpalEchoCancelDisabled,
437 OpalEchoCancelEnabled
438 } OpalEchoCancelMode;
439
440
455 typedef int (*OpalMediaDataFunction)(
456 const char * token,
458 const char * stream,
462 const char * format,
463 void * userData,
464 void * data,
465 int size
466 );
467
468
485 typedef int (*OpalMessageAvailableFunction)(
486 const OpalMessage * message
487 );
488
489
497 typedef enum OpalMediaDataType {
498 OpalMediaDataNoChange,
499 OpalMediaDataPayloadOnly,
501 OpalMediaDataWithHeader
503 } OpalMediaDataType;
504
505
523 typedef enum OpalMediaTiming {
524 OpalMediaTimingNoChange,
525 OpalMediaTimingSynchronous,
527 OpalMediaTimingAsynchronous
529 } OpalMediaTiming;
530
531
564 typedef struct OpalParamGeneral {
565 const char * m_audioRecordDevice;
566 const char * m_audioPlayerDevice;
567 const char * m_videoInputDevice;
568 const char * m_videoOutputDevice;
569 const char * m_videoPreviewDevice;
570 const char * m_mediaOrder;
573 const char * m_mediaMask;
576 const char * m_autoRxMedia;
580 const char * m_autoTxMedia;
584 const char * m_natRouter;
586 const char * m_stunServer;
588 unsigned m_tcpPortBase;
590 unsigned m_tcpPortMax;
592 unsigned m_udpPortBase;
594 unsigned m_udpPortMax;
596 unsigned m_rtpPortBase;
598 unsigned m_rtpPortMax;
600 unsigned m_rtpTypeOfService;
602 unsigned m_rtpMaxPayloadSize;
604 unsigned m_minAudioJitter;
608 unsigned m_maxAudioJitter;
612 OpalSilenceDetectMode m_silenceDetectMode;
615 unsigned m_silenceThreshold;
617 unsigned m_signalDeadband;
619 unsigned m_silenceDeadband;
621 unsigned m_silenceAdaptPeriod;
624 OpalEchoCancelMode m_echoCancellation;
626 unsigned m_audioBuffers;
629 OpalMediaDataFunction m_mediaReadData;
631 OpalMediaDataFunction m_mediaWriteData;
633 OpalMediaDataType m_mediaDataHeader;
636 OpalMessageAvailableFunction m_messageAvailable;
640 const char * m_mediaOptions;
649 unsigned m_audioBufferTime;
652 unsigned m_manualAlerting;
658 OpalMediaTiming m_mediaTiming;
661 } OpalParamGeneral;
662
663
666 typedef struct OpalProductDescription {
667 const char * m_vendor;
670 const char * m_name;
673 const char * m_version;
676 unsigned m_t35CountryCode;
681 unsigned m_t35Extension;
686 unsigned m_manufacturerCode;
692 } OpalProductDescription;
693
694
698 typedef enum OpalUserInputModes {
699 OpalUserInputDefault,
700 OpalUserInputAsQ931,
701 OpalUserInputAsString,
702 OpalUserInputAsTone,
703 OpalUserInputAsRFC2833,
704 OpalUserInputInBand,
705 } OpalUserInputModes;
706
707
724 typedef struct OpalParamProtocol {
725 const char * m_prefix;
728 const char * m_userName;
731 const char * m_displayName;
733 OpalProductDescription m_product;
734 const char * m_interfaceAddresses;
742 OpalUserInputModes m_userInputMode;
745 const char * m_defaultOptions;
747 } OpalParamProtocol;
748
749
751 #define OPAL_MWI_EVENT_PACKAGE "message-summary"
752
754 #define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"
755
817 typedef struct OpalParamRegistration {
818 const char * m_protocol;
820 const char * m_identifier;
826 const char * m_hostName;
830 const char * m_authUserName;
831 const char * m_password;
832 const char * m_adminEntity;
835 unsigned m_timeToLive;
837 unsigned m_restoreTime;
840 const char * m_eventPackage;
848 } OpalParamRegistration;
849
850
854 typedef enum OpalRegistrationStates {
855 OpalRegisterSuccessful,
856 OpalRegisterRemoved,
860 OpalRegisterFailed,
862 OpalRegisterRetrying,
864 OpalRegisterRestored,
865 } OpalRegistrationStates;
866
867
871 typedef struct OpalStatusRegistration {
872 const char * m_protocol;
874 const char * m_serverName;
877 const char * m_error;
881 OpalRegistrationStates m_status;
882 OpalProductDescription m_product;
883 } OpalStatusRegistration;
884
885
922 typedef struct OpalParamSetUpCall {
923 const char * m_partyA;
937 const char * m_partyB;
949 const char * m_callToken;
954 const char * m_alertingType;
973 const char * m_protocolCallId;
975 OpalParamProtocol m_overrides;
978 } OpalParamSetUpCall;
979
980
984 typedef struct OpalStatusIncomingCall {
985 const char * m_callToken;
986 const char * m_localAddress;
987 const char * m_remoteAddress;
988 const char * m_remotePartyNumber;
989 const char * m_remoteDisplayName;
990 const char * m_calledAddress;
991 const char * m_calledPartyNumber;
992 OpalProductDescription m_product;
993 const char * m_alertingType;
1005 const char * m_protocolCallId;
1007 const char * m_referredByAddress;
1008 const char * m_redirectingNumber;
1009 } OpalStatusIncomingCall;
1010
1011
1020 typedef struct OpalParamAnswerCall {
1021 const char * m_callToken;
1022 OpalParamProtocol m_overrides;
1025 } OpalParamAnswerCall;
1026
1031 typedef enum OpalMediaStates {
1032 OpalMediaStateNoChange,
1033 OpalMediaStateOpen,
1035 OpalMediaStateClose,
1037 OpalMediaStatePause,
1039 OpalMediaStateResume
1041 } OpalMediaStates;
1042
1043
1050 typedef struct OpalStatusMediaStream {
1051 const char * m_callToken;
1052 const char * m_identifier;
1055 const char * m_type;
1060 const char * m_format;
1064 OpalMediaStates m_state;
1067 int m_volume;
1071 } OpalStatusMediaStream;
1072
1073
1076 typedef struct OpalParamSetUserData {
1077 const char * m_callToken;
1078 void * m_userData;
1079 } OpalParamSetUserData;
1080
1081
1087 typedef struct OpalStatusUserInput {
1088 const char * m_callToken;
1089 const char * m_userInput;
1090 unsigned m_duration;
1095 } OpalStatusUserInput, OpalParamUserInput;
1096
1097
1101 typedef struct OpalStatusMessageWaiting {
1102 const char * m_party;
1103 const char * m_type;
1104 const char * m_extraInfo;
1107 } OpalStatusMessageWaiting;
1108
1109
1114 typedef enum OpalLineAppearanceStates {
1115 OpalLineTerminated,
1116 OpalLineTrying,
1117 OpalLineProceeding,
1118 OpalLineRinging,
1119 OpalLineConnected,
1120 OpalLineSubcribed,
1121 OpalLineUnsubcribed,
1123 OpalLineIdle = OpalLineTerminated // Kept for backward compatibility
1124 } OpalLineAppearanceStates;
1125
1126
1130 typedef struct OpalStatusLineAppearance {
1131 const char * m_line;
1132 OpalLineAppearanceStates m_state;
1133 int m_appearance;
1136 const char * m_callId;
1140 const char * m_partyA;
1141 const char * m_partyB;
1142 } OpalStatusLineAppearance;
1143
1144
1148 typedef enum OpalVideoRecordMixMode {
1149 OpalSideBySideLetterbox,
1153 OpalSideBySideScaled,
1157 OpalStackedPillarbox,
1161 OpalStackedScaled,
1165 } OpalVideoRecordMixMode;
1166
1167
1170 typedef struct OpalParamRecording {
1171 const char * m_callToken;
1172 const char * m_file;
1174 unsigned m_channels;
1177 const char * m_audioFormat;
1181 const char * m_videoFormat;
1185 unsigned m_videoWidth;
1186 unsigned m_videoHeight;
1187 unsigned m_videoRate;
1188 OpalVideoRecordMixMode m_videoMixing;
1189 } OpalParamRecording;
1190
1191
1195 typedef struct OpalStatusTransferCall {
1196 const char * m_callToken;
1197 const char * m_protocolCallId;
1199 const char * m_result;
1214 const char * m_info;
1218 } OpalStatusTransferCall;
1219
1220
1224 typedef struct OpalStatusIVR {
1225 const char * m_callToken;
1226 const char * m_variables;
1231 } OpalStatusIVR;
1232
1233
1237 typedef struct OpalStatusCallCleared {
1238 const char * m_callToken;
1239 const char * m_reason;
1244 } OpalStatusCallCleared;
1245
1246
1251 typedef enum OpalCallEndReason {
1252 OpalCallEndedByLocalUser,
1253 OpalCallEndedByNoAccept,
1254 OpalCallEndedByAnswerDenied,
1255 OpalCallEndedByRemoteUser,
1256 OpalCallEndedByRefusal,
1257 OpalCallEndedByNoAnswer,
1258 OpalCallEndedByCallerAbort,
1259 OpalCallEndedByTransportFail,
1260 OpalCallEndedByConnectFail,
1261 OpalCallEndedByGatekeeper,
1262 OpalCallEndedByNoUser,
1263 OpalCallEndedByNoBandwidth,
1264 OpalCallEndedByCapabilityExchange,
1265 OpalCallEndedByCallForwarded,
1266 OpalCallEndedBySecurityDenial,
1267 OpalCallEndedByLocalBusy,
1268 OpalCallEndedByLocalCongestion,
1269 OpalCallEndedByRemoteBusy,
1270 OpalCallEndedByRemoteCongestion,
1271 OpalCallEndedByUnreachable,
1272 OpalCallEndedByNoEndPoint,
1273 OpalCallEndedByHostOffline,
1274 OpalCallEndedByTemporaryFailure,
1275 OpalCallEndedByQ931Cause,
1276 OpalCallEndedByDurationLimit,
1277 OpalCallEndedByInvalidConferenceID,
1278 OpalCallEndedByNoDialTone,
1279 OpalCallEndedByNoRingBackTone,
1280 OpalCallEndedByOutOfService,
1281 OpalCallEndedByAcceptingCallWaiting,
1282 OpalCallEndedWithQ931Code = 0x100
1283 } OpalCallEndReason;
1284
1285
1288 typedef struct OpalParamCallCleared {
1289 const char * m_callToken;
1290 OpalCallEndReason m_reason;
1292 } OpalParamCallCleared;
1293
1294
1298 struct OpalMessage {
1299 OpalMessageType m_type;
1300 union {
1301 const char * m_commandError;
1302 OpalParamGeneral m_general;
1303 OpalParamProtocol m_protocol;
1304 OpalParamRegistration m_registrationInfo;
1305 OpalStatusRegistration m_registrationStatus;
1306 OpalParamSetUpCall m_callSetUp;
1307 const char * m_callToken;
1308 OpalStatusIncomingCall m_incomingCall;
1309 OpalParamAnswerCall m_answerCall;
1310 OpalStatusUserInput m_userInput;
1311 OpalStatusMessageWaiting m_messageWaiting;
1312 OpalStatusLineAppearance m_lineAppearance;
1313 OpalStatusCallCleared m_callCleared;
1314 OpalParamCallCleared m_clearCall;
1315 OpalStatusMediaStream m_mediaStream;
1316 OpalParamSetUserData m_setUserData;
1317 OpalParamRecording m_recording;
1318 OpalStatusTransferCall m_transferStatus;
1319 OpalStatusIVR m_ivrStatus;
1320 } m_param;
1321 };
1322
1323
1324 #ifdef __cplusplus
1325 };
1326 #endif
1327
1328 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS)
1329
1331 class OpalMessagePtr
1332 {
1333 public:
1334 OpalMessagePtr(OpalMessageType type = OpalIndCommandError);
1335 ~OpalMessagePtr();
1336
1337 OpalMessageType GetType() const;
1338 void SetType(OpalMessageType type);
1339
1340 const char * GetCallToken() const;
1341 void SetCallToken(const char * token);
1342
1343 const char * GetCommandError() const;
1344
1345 OpalParamGeneral * GetGeneralParams() const;
1346 OpalParamProtocol * GetProtocolParams() const;
1347 OpalParamRegistration * GetRegistrationInfo() const;
1348 OpalStatusRegistration * GetRegistrationStatus() const;
1349 OpalParamSetUpCall * GetCallSetUp() const;
1350 OpalStatusIncomingCall * GetIncomingCall() const;
1351 OpalParamAnswerCall * GetAnswerCall() const;
1352 OpalStatusUserInput * GetUserInput() const;
1353 OpalStatusMessageWaiting * GetMessageWaiting() const;
1354 OpalStatusLineAppearance * GetLineAppearance() const;
1355 OpalStatusCallCleared * GetCallCleared() const;
1356 OpalParamCallCleared * GetClearCall() const;
1357 OpalStatusMediaStream * GetMediaStream() const;
1358 OpalParamSetUserData * GetSetUserData() const;
1359 OpalParamRecording * GetRecording() const;
1360 OpalStatusTransferCall * GetTransferStatus() const;
1361
1362 protected:
1363 OpalMessage * m_message;
1364
1365 private:
1366 OpalMessagePtr(const OpalMessagePtr &) { }
1367 void operator=(const OpalMessagePtr &) { }
1368
1369 friend class OpalContext;
1370 };
1371
1372
1373 #ifdef GetMessage
1374 #undef GetMessage
1375 #endif
1376 #ifdef SendMessage
1377 #undef SendMessage
1378 #endif
1379
1380
1388 class OpalContext
1389 {
1390 public:
1392 OpalContext();
1393
1395 virtual ~OpalContext();
1396
1399 unsigned Initialise(
1400 const char * options,
1401 unsigned version = OPAL_C_API_VERSION
1402 );
1403
1405 bool IsInitialised() const { return m_handle != NULL; }
1406
1408 void ShutDown();
1409
1411 bool GetMessage(
1412 OpalMessagePtr & message,
1413 unsigned timeout = 0
1414 );
1415
1417 bool SendMessage(
1418 const OpalMessagePtr & message,
1419 OpalMessagePtr & response
1420 );
1421
1422
1424 bool SetUpCall(
1425 OpalMessagePtr & response,
1426 const char * partyB,
1427 const char * partyA = NULL,
1428 const char * alertingType = NULL
1429 );
1430
1432 bool AnswerCall(
1433 const char * callToken
1434 );
1435
1437 bool ClearCall(
1438 const char * callToken,
1439 OpalCallEndReason reason = OpalCallEndedByLocalUser
1440 );
1441
1443 bool SendUserInput(
1444 const char * callToken,
1445 const char * userInput,
1446 unsigned duration = 0
1447 );
1448
1449 protected:
1450 OpalHandle m_handle;
1451 };
1452
1453 #endif
1454
1455 #endif // OPAL_OPAL_H
1456
1457