OPAL  Version 3.10.10
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: 27795 $
30  * $Author: rjongbloed $
31  * $Date: 2012-06-07 22:49:21 -0500 (Thu, 07 Jun 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 27
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 
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 {
415 // Always add new messages to ethe end to maintain backward compatibility
418 
419 
423 typedef enum OpalSilenceDetectMode {
429 
430 
434 typedef enum 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 
486  const OpalMessage * message
487 );
488 
489 
497 typedef enum OpalMediaDataType {
504 
505 
523 typedef enum OpalMediaTiming {
533 
534 
567 typedef struct OpalParamGeneral {
568  const char * m_audioRecordDevice;
569  const char * m_audioPlayerDevice;
570  const char * m_videoInputDevice;
571  const char * m_videoOutputDevice;
572  const char * m_videoPreviewDevice;
573  const char * m_mediaOrder;
576  const char * m_mediaMask;
579  const char * m_autoRxMedia;
583  const char * m_autoTxMedia;
587  const char * m_natRouter;
589  const char * m_stunServer;
591  unsigned m_tcpPortBase;
593  unsigned m_tcpPortMax;
595  unsigned m_udpPortBase;
597  unsigned m_udpPortMax;
599  unsigned m_rtpPortBase;
601  unsigned m_rtpPortMax;
607  unsigned m_minAudioJitter;
611  unsigned m_maxAudioJitter;
620  unsigned m_signalDeadband;
622  unsigned m_silenceDeadband;
629  unsigned m_audioBuffers;
643  const char * m_mediaOptions;
652  unsigned m_audioBufferTime;
655  unsigned m_manualAlerting;
669 
670 
673 typedef struct OpalProductDescription {
674  const char * m_vendor;
677  const char * m_name;
680  const char * m_version;
683  unsigned m_t35CountryCode;
688  unsigned m_t35Extension;
700 
701 
705 typedef enum OpalUserInputModes {
713 
714 
731 typedef struct OpalParamProtocol {
732  const char * m_prefix;
735  const char * m_userName;
738  const char * m_displayName;
741  const char * m_interfaceAddresses;
752  const char * m_defaultOptions;
755 
756 
758 #define OPAL_MWI_EVENT_PACKAGE "message-summary"
759 
761 #define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"
762 
824 typedef struct OpalParamRegistration {
825  const char * m_protocol;
827  const char * m_identifier;
833  const char * m_hostName;
837  const char * m_authUserName;
838  const char * m_password;
839  const char * m_adminEntity;
842  unsigned m_timeToLive;
844  unsigned m_restoreTime;
847  const char * m_eventPackage;
856 
857 
873 
874 
878 typedef struct OpalStatusRegistration {
879  const char * m_protocol;
881  const char * m_serverName;
884  const char * m_error;
891 
892 
929 typedef struct OpalParamSetUpCall {
930  const char * m_partyA;
944  const char * m_partyB;
956  const char * m_callToken;
961  const char * m_alertingType;
980  const char * m_protocolCallId;
986 
987 
991 typedef struct OpalStatusIncomingCall {
992  const char * m_callToken;
993  const char * m_localAddress;
994  const char * m_remoteAddress;
995  const char * m_remotePartyNumber;
996  const char * m_remoteDisplayName;
997  const char * m_calledAddress;
998  const char * m_calledPartyNumber;
1000  const char * m_alertingType;
1012  const char * m_protocolCallId;
1014  const char * m_referredByAddress;
1015  const char * m_redirectingNumber;
1017 
1018 
1027 typedef struct OpalParamAnswerCall {
1028  const char * m_callToken;
1033 
1038 typedef enum OpalMediaStates {
1048 } OpalMediaStates;
1049 
1050 
1057 typedef struct OpalStatusMediaStream {
1058  const char * m_callToken;
1059  const char * m_identifier;
1062  const char * m_type;
1067  const char * m_format;
1074  int m_volume;
1079 
1080 
1083 typedef struct OpalParamSetUserData {
1084  const char * m_callToken;
1085  void * m_userData;
1087 
1088 
1094 typedef struct OpalStatusUserInput {
1095  const char * m_callToken;
1096  const char * m_userInput;
1097  unsigned m_duration;
1102 } OpalStatusUserInput, OpalParamUserInput;
1103 
1104 
1109  const char * m_party;
1110  const char * m_type;
1111  const char * m_extraInfo;
1115 
1116 
1130  OpalLineIdle = OpalLineTerminated // Kept for backward compatibility
1132 
1133 
1138  const char * m_line;
1143  const char * m_callId;
1147  const char * m_partyA;
1148  const char * m_partyB;
1150 
1151 
1173 
1174 
1177 typedef struct OpalParamRecording {
1178  const char * m_callToken;
1179  const char * m_file;
1181  unsigned m_channels;
1184  const char * m_audioFormat;
1188  const char * m_videoFormat;
1192  unsigned m_videoWidth;
1193  unsigned m_videoHeight;
1194  unsigned m_videoRate;
1197 
1198 
1202 typedef struct OpalStatusTransferCall {
1203  const char * m_callToken;
1204  const char * m_protocolCallId;
1206  const char * m_result;
1221  const char * m_info;
1226 
1227 
1231 typedef struct OpalStatusIVR {
1232  const char * m_callToken;
1233  const char * m_variables;
1238 } OpalStatusIVR;
1239 
1240 
1244 typedef struct OpalStatusCallCleared {
1245  const char * m_callToken;
1246  const char * m_reason;
1252 
1253 
1258 typedef enum OpalCallEndReason {
1291 
1292 
1295 typedef struct OpalParamCallCleared {
1296  const char * m_callToken;
1300 
1301 
1305 struct OpalMessage {
1307  union {
1308  const char * m_commandError;
1314  const char * m_callToken;
1317  OpalStatusUserInput m_userInput;
1327  } m_param;
1328 };
1329 
1330 
1331 #ifdef __cplusplus
1332 };
1333 #endif
1334 
1335 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS)
1336 
1339 {
1340  public:
1342  ~OpalMessagePtr();
1343 
1344  OpalMessageType GetType() const;
1345  void SetType(OpalMessageType type);
1346 
1347  const char * GetCallToken() const;
1348  void SetCallToken(const char * token);
1349 
1350  const char * GetCommandError() const;
1351 
1356  OpalParamSetUpCall * GetCallSetUp() const;
1359  OpalStatusUserInput * GetUserInput() const;
1366  OpalParamRecording * GetRecording() const;
1368 
1369  protected:
1371 
1372  private:
1373  OpalMessagePtr(const OpalMessagePtr &) { }
1374  void operator=(const OpalMessagePtr &) { }
1375 
1376  friend class OpalContext;
1377 };
1378 
1379 
1380 #ifdef GetMessage
1381 #undef GetMessage
1382 #endif
1383 #ifdef SendMessage
1384 #undef SendMessage
1385 #endif
1386 
1387 
1396 {
1397  public:
1399  OpalContext();
1400 
1402  virtual ~OpalContext();
1403 
1406  unsigned Initialise(
1407  const char * options,
1408  unsigned version = OPAL_C_API_VERSION
1409  );
1410 
1412  bool IsInitialised() const { return m_handle != NULL; }
1413 
1415  void ShutDown();
1416 
1418  bool GetMessage(
1419  OpalMessagePtr & message,
1420  unsigned timeout = 0
1421  );
1422 
1424  bool SendMessage(
1425  const OpalMessagePtr & message,
1426  OpalMessagePtr & response
1427  );
1428 
1429 
1431  bool SetUpCall(
1432  OpalMessagePtr & response,
1433  const char * partyB,
1434  const char * partyA = NULL,
1435  const char * alertingType = NULL
1436  );
1437 
1439  bool AnswerCall(
1440  const char * callToken
1441  );
1442 
1444  bool ClearCall(
1445  const char * callToken,
1447  );
1448 
1450  bool SendUserInput(
1451  const char * callToken,
1452  const char * userInput,
1453  unsigned duration = 0
1454  );
1455 
1456  protected:
1458 };
1459 
1460 #endif
1461 
1462 #endif // OPAL_OPAL_H
1463 
1464