OPAL  Version 3.10.4
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 
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 {
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;
604  unsigned m_minAudioJitter;
608  unsigned m_maxAudioJitter;
617  unsigned m_signalDeadband;
619  unsigned m_silenceDeadband;
626  unsigned m_audioBuffers;
640  const char * m_mediaOptions;
649  unsigned m_audioBufferTime;
652  unsigned m_manualAlerting;
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;
693 
694 
698 typedef enum OpalUserInputModes {
706 
707 
724 typedef struct OpalParamProtocol {
725  const char * m_prefix;
728  const char * m_userName;
731  const char * m_displayName;
734  const char * m_interfaceAddresses;
745  const char * m_defaultOptions;
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;
849 
850 
866 
867 
871 typedef struct OpalStatusRegistration {
872  const char * m_protocol;
874  const char * m_serverName;
877  const char * m_error;
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;
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;
993  const char * m_alertingType;
1005  const char * m_protocolCallId;
1007  const char * m_referredByAddress;
1008  const char * m_redirectingNumber;
1010 
1011 
1020 typedef struct OpalParamAnswerCall {
1021  const char * m_callToken;
1026 
1031 typedef enum OpalMediaStates {
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;
1067  int m_volume;
1072 
1073 
1076 typedef struct OpalParamSetUserData {
1077  const char * m_callToken;
1078  void * m_userData;
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 
1102  const char * m_party;
1103  const char * m_type;
1104  const char * m_extraInfo;
1108 
1109 
1123  OpalLineIdle = OpalLineTerminated // Kept for backward compatibility
1125 
1126 
1131  const char * m_line;
1136  const char * m_callId;
1140  const char * m_partyA;
1141  const char * m_partyB;
1143 
1144 
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;
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;
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;
1245 
1246 
1251 typedef enum OpalCallEndReason {
1284 
1285 
1288 typedef struct OpalParamCallCleared {
1289  const char * m_callToken;
1293 
1294 
1298 struct OpalMessage {
1300  union {
1301  const char * m_commandError;
1307  const char * m_callToken;
1310  OpalStatusUserInput m_userInput;
1320  } m_param;
1321 };
1322 
1323 
1324 #ifdef __cplusplus
1325 };
1326 #endif
1327 
1328 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS)
1329 
1332 {
1333  public:
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 
1349  OpalParamSetUpCall * GetCallSetUp() const;
1352  OpalStatusUserInput * GetUserInput() const;
1359  OpalParamRecording * GetRecording() const;
1361 
1362  protected:
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 
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,
1440  );
1441 
1443  bool SendUserInput(
1444  const char * callToken,
1445  const char * userInput,
1446  unsigned duration = 0
1447  );
1448 
1449  protected:
1451 };
1452 
1453 #endif
1454 
1455 #endif // OPAL_OPAL_H
1456 
1457