# opal.h

Go to the documentation of this file.

    00001 /*
    00002  * opal.h
    00003  *
    00004  * "C" language interface for OPAL
    00005  *
    00006  * Open Phone Abstraction Library (OPAL)
    00007  *
    00008  * Copyright (c) 2008 Vox Lucida
    00009  *
    00010  * The contents of this file are subject to the Mozilla Public License
    00011  * Version 1.0 (the "License"); you may not use this file except in
    00012  * compliance with the License. You may obtain a copy of the License at
    00013  * http://www.mozilla.org/MPL/
    00014  *
    00015  * Software distributed under the License is distributed on an "AS IS"
    00016  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
    00017  * the License for the specific language governing rights and limitations
    00018  * under the License.
    00019  *
    00020  * The Original Code is Open Phone Abstraction Library.
    00021  *
    00022  * The Initial Developer of the Original Code is Vox Lucida (Robert Jongbloed)
    00023  *
    00024  * This code was initially written with the assisance of funding from
    00025  * Stonevoice. http://www.stonevoice.com.
    00026  *
    00027  * Contributor(s): ______________________________________.
    00028  *
    00029  * $Revision: 20987 $
    00030  * $Author: rjongbloed $
    00031  * $Date: 2008-09-15 12:32:43 +0000 (Mon, 15 Sep 2008) $
    00032  */
    00033
    00034 #ifndef __OPAL_H
    00035 #define __OPAL_H
    00036
    00037 #ifdef __cplusplus
    00038 extern "C" {
    00039 #endif
    00040
    00047 #ifdef _WIN32
    00048   #define OPAL_EXPORT __stdcall
    00049 #else
    00050   #define OPAL_EXPORT
    00051 #endif
    00052
    00053 typedef struct OpalHandleStruct * OpalHandle;
    00054
    00055 typedef struct OpalMessage OpalMessage;
    00056
    00057
    00058 #define OPAL_C_API_VERSION 11
    00059
    00060
    00062
    00095 OpalHandle OPAL_EXPORT OpalInitialise(unsigned * version, const char * options);
    00096
    00100 #define OPAL_INITIALISE_FUNCTION   "OpalInitialise"
    00101
    00105 typedef OpalHandle (OPAL_EXPORT *OpalInitialiseFunction)(unsigned * version, const char * options);
    00106
    00107
    00109
    00113 void OPAL_EXPORT OpalShutDown(OpalHandle opal);
    00114
    00118 #define OPAL_SHUTDOWN_FUNCTION     "OpalShutDown"
    00119
    00123 typedef void (OPAL_EXPORT *OpalShutDownFunction)(OpalHandle opal);
    00124
    00125
    00127
    00138 OpalMessage * OPAL_EXPORT OpalGetMessage(OpalHandle opal, unsigned timeout);
    00139
    00143 #define OPAL_GET_MESSAGE_FUNCTION  "OpalGetMessage"
    00144
    00148 typedef OpalMessage * (OPAL_EXPORT *OpalGetMessageFunction)(OpalHandle opal, unsigned timeout);
    00149
    00150
    00152
    00175 OpalMessage * OPAL_EXPORT OpalSendMessage(OpalHandle opal, const OpalMessage * message);
    00176
    00180 typedef OpalMessage * (OPAL_EXPORT *OpalSendMessageFunction)(OpalHandle opal, const OpalMessage * message);
    00181
    00185 #define OPAL_SEND_MESSAGE_FUNCTION "OpalSendMessage"
    00186
    00187
    00189
    00193 void OPAL_EXPORT OpalFreeMessage(OpalMessage * message);
    00194
    00198 #define OPAL_FREE_MESSAGE_FUNCTION "OpalFreeMessage"
    00199
    00203 typedef void (OPAL_EXPORT *OpalFreeMessageFunction)(OpalMessage * message);
    00204
    00205
    00207
    00208 #define OPAL_PREFIX_H323  "h323"
    00209 #define OPAL_PREFIX_SIP   "sip"
    00210 #define OPAL_PREFIX_IAX2  "iax2"
    00211 #define OPAL_PREFIX_PCSS  "pc"
    00212 #define OPAL_PREFIX_LOCAL "local"
    00213 #define OPAL_PREFIX_POTS  "pots"
    00214 #define OPAL_PREFIX_PSTN  "pstn"
    00215 #define OPAL_PREFIX_IVR   "ivr"
    00216
    00217 #define OPAL_PREFIX_ALL OPAL_PREFIX_H323  " " \
    00218                         OPAL_PREFIX_SIP   " " \
    00219                         OPAL_PREFIX_IAX2  " " \
    00220                         OPAL_PREFIX_PCSS  " " \
    00221                         OPAL_PREFIX_LOCAL " " \
    00222                         OPAL_PREFIX_POTS  " " \
    00223                         OPAL_PREFIX_PSTN  " " \
    00224                         OPAL_PREFIX_IVR
    00225
    00226
    00229 typedef enum OpalMessageType {
    00230   OpalIndCommandError,
    00233   OpalCmdSetGeneralParameters,
    00235   OpalCmdSetProtocolParameters,
    00238   OpalCmdRegistration,
    00242   OpalIndRegistration,
    00247   OpalCmdSetUpCall,
    00251   OpalIndIncomingCall,
    00254   OpalCmdAnswerCall,
    00258   OpalCmdClearCall,
    00263   OpalIndAlerting,
    00267   OpalIndEstablished,
    00271   OpalIndUserInput,
    00274   OpalIndCallCleared,
    00277   OpalCmdHoldCall,
    00279   OpalCmdRetrieveCall,
    00281   OpalCmdTransferCall,
    00284   OpalCmdUserInput,
    00286   OpalIndMessageWaiting,
    00290   OpalIndMediaStream,
    00293   OpalCmdMediaStream,
    00296   OpalCmdSetUserData,
    00298   OpalMessageTypeCount
    00299 } OpalMessageType;
    00300
    00301
    00305 typedef enum OpalSilenceDetectMode {
    00306   OpalSilenceDetectNoChange,
    00307   OpalSilenceDetectDisabled,
    00308   OpalSilenceDetectFixed,
    00309   OpalSilenceDetectAdaptive
    00310 } OpalSilenceDetectMode;
    00311
    00312
    00316 typedef enum OpalEchoCancelMode {
    00317   OpalEchoCancelNoChange,
    00318   OpalEchoCancelDisabled,
    00319   OpalEchoCancelEnabled
    00320 } OpalEchoCancelMode;
    00321
    00322
    00330 typedef int (*OpalMediaDataFunction)(
    00331   const char * token,
    00333   const char * stream,
    00337   const char * format,
    00338   void * userData,
    00339   void * data,
    00340   int size
    00341 );
    00342
    00343
    00360 typedef int (*OpalMessageAvailableFunction)(
    00361   const OpalMessage * message
    00362 );
    00363
    00364
    00368 typedef enum OpalMediaDataType {
    00369   OpalMediaDataNoChange,
    00370   OpalMediaDataPayloadOnly,
    00372   OpalMediaDataWithHeader
    00374 } OpalMediaDataType;
    00375
    00376
    00380 typedef struct OpalParamGeneral {
    00381   const char * m_audioRecordDevice;
    00382   const char * m_audioPlayerDevice;
    00383   const char * m_videoInputDevice;
    00384   const char * m_videoOutputDevice;
    00385   const char * m_videoPreviewDevice;
    00386   const char * m_mediaOrder;
    00389   const char * m_mediaMask;
    00392   const char * m_autoRxMedia;
    00394   const char * m_autoTxMedia;
    00396   const char * m_natRouter;
    00398   const char * m_stunServer;
    00400   unsigned     m_tcpPortBase;
    00402   unsigned     m_tcpPortMax;
    00404   unsigned     m_udpPortBase;
    00406   unsigned     m_udpPortMax;
    00408   unsigned     m_rtpPortBase;
    00410   unsigned     m_rtpPortMax;
    00412   unsigned     m_rtpTypeOfService;
    00414   unsigned     m_rtpMaxPayloadSize;
    00416   unsigned     m_minAudioJitter;
    00420   unsigned     m_maxAudioJitter;
    00424   OpalSilenceDetectMode m_silenceDetectMode;
    00427   unsigned     m_silenceThreshold;
    00429   unsigned     m_signalDeadband;
    00431   unsigned     m_silenceDeadband;
    00433   unsigned     m_silenceAdaptPeriod;
    00436   OpalEchoCancelMode m_echoCancellation;
    00438   unsigned     m_audioBuffers;
    00439   OpalMediaDataFunction m_mediaReadData;
    00441   OpalMediaDataFunction m_mediaWriteData;
    00443   OpalMediaDataType     m_mediaDataHeader;
    00446   OpalMessageAvailableFunction m_messageAvailable;
    00450 } OpalParamGeneral;
    00451
    00452
    00455 typedef struct OpalProductDescription {
    00456   const char * m_vendor;
    00459   const char * m_name;
    00462   const char * m_version;
    00465   unsigned     m_t35CountryCode;
    00470   unsigned     m_t35Extension;
    00475   unsigned     m_manufacturerCode;
    00481 } OpalProductDescription;
    00482
    00483
    00487 typedef struct OpalParamProtocol {
    00488   const char * m_prefix;
    00491   const char * m_userName;
    00494   const char * m_displayName;
    00496   OpalProductDescription m_product;
    00497   const char * m_interfaceAddresses;
    00502 } OpalParamProtocol;
    00503
    00504
    00508 typedef struct OpalParamRegistration {
    00509   const char * m_protocol;
    00511   const char * m_identifier;
    00517   const char * m_hostName;
    00520   const char * m_authUserName;
    00521   const char * m_password;
    00522   const char * m_adminEntity;
    00525   unsigned     m_timeToLive;
    00527   unsigned     m_restoreTime;
    00530   unsigned     m_messageWaiting;
    00535 } OpalParamRegistration;
    00536
    00537
    00541 typedef enum OpalRegistrationStates {
    00542   OpalRegisterSuccessful,
    00543   OpalRegisterRemoved,
    00547   OpalRegisterFailed,
    00549   OpalRegisterRetrying,
    00551   OpalRegisterRestored,
    00552 } OpalRegistrationStates;
    00553
    00554
    00558 typedef struct OpalStatusRegistration {
    00559   const char * m_protocol;
    00561   const char * m_serverName;
    00564   const char * m_error;
    00568   OpalRegistrationStates m_status;
    00569   OpalProductDescription m_product;
    00570 } OpalStatusRegistration;
    00571
    00572
    00585 typedef struct OpalParamSetUpCall {
    00586   const char * m_partyA;
    00600   const char * m_partyB;
    00612   const char * m_callToken;
    00617 } OpalParamSetUpCall;
    00618
    00619
    00623 typedef struct OpalStatusIncomingCall {
    00624   const char * m_callToken;
    00625   const char * m_localAddress;
    00626   const char * m_remoteAddress;
    00627   const char * m_remotePartyNumber;
    00628   const char * m_remoteDisplayName;
    00629   const char * m_calledAddress;
    00630   const char * m_calledPartyNumber;
    00631   OpalProductDescription m_product;
    00632 } OpalStatusIncomingCall;
    00633
    00634
    00639 typedef enum OpalMediaStates {
    00640   OpalMediaStateNoChange,
    00641   OpalMediaStateOpen,
    00643   OpalMediaStateClose,
    00645   OpalMediaStatePause,
    00647   OpalMediaStateResume
    00649 } OpalMediaStates;
    00650
    00651
    00658 typedef struct OpalStatusMediaStream {
    00659   const char    * m_callToken;
    00660   const char    * m_identifier;
    00663   const char    * m_type;
    00668   const char    * m_format;
    00672   OpalMediaStates m_state;
    00675 } OpalStatusMediaStream;
    00676
    00677
    00680 typedef struct OpalParamSetUserData {
    00681   const char    * m_callToken;
    00682   void *        m_userData;
    00683 } OpalParamSetUserData;
    00684
    00685
    00691 typedef struct OpalStatusUserInput {
    00692   const char * m_callToken;
    00693   const char * m_userInput;
    00694   unsigned     m_duration;
    00699 } OpalStatusUserInput;
    00700
    00701
    00705 typedef struct OpalStatusMessageWaiting {
    00706   const char * m_party;
    00707   const char * m_type;
    00708   const char * m_extraInfo;
    00711 } OpalStatusMessageWaiting;
    00712
    00713
    00717 typedef struct OpalStatusCallCleared {
    00718   const char * m_callToken;
    00719   const char * m_reason;
    00724 } OpalStatusCallCleared;
    00725
    00726
    00731 typedef enum OpalCallEndReason {
    00732   OpalCallEndedByLocalUser,
    00733   OpalCallEndedByNoAccept,
    00734   OpalCallEndedByAnswerDenied,
    00735   OpalCallEndedByRemoteUser,
    00736   OpalCallEndedByRefusal,
    00737   OpalCallEndedByNoAnswer,
    00738   OpalCallEndedByCallerAbort,
    00739   OpalCallEndedByTransportFail,
    00740   OpalCallEndedByConnectFail,
    00741   OpalCallEndedByGatekeeper,
    00742   OpalCallEndedByNoUser,
    00743   OpalCallEndedByNoBandwidth,
    00744   OpalCallEndedByCapabilityExchange,
    00745   OpalCallEndedByCallForwarded,
    00746   OpalCallEndedBySecurityDenial,
    00747   OpalCallEndedByLocalBusy,
    00748   OpalCallEndedByLocalCongestion,
    00749   OpalCallEndedByRemoteBusy,
    00750   OpalCallEndedByRemoteCongestion,
    00751   OpalCallEndedByUnreachable,
    00752   OpalCallEndedByNoEndPoint,
    00753   OpalCallEndedByHostOffline,
    00754   OpalCallEndedByTemporaryFailure,
    00755   OpalCallEndedByQ931Cause,
    00756   OpalCallEndedByDurationLimit,
    00757   OpalCallEndedByInvalidConferenceID,
    00758   OpalCallEndedByNoDialTone,
    00759   OpalCallEndedByNoRingBackTone,
    00760   OpalCallEndedByOutOfService,
    00761   OpalCallEndedByAcceptingCallWaiting,
    00762   OpalCallEndedWithQ931Code = 0x100
    00763 } OpalCallEndReason;
    00764
    00765
    00768 typedef struct OpalParamCallCleared {
    00769   const char      * m_callToken;
    00770   OpalCallEndReason m_reason;
    00772 } OpalParamCallCleared;
    00773
    00774
    00778 struct OpalMessage {
    00779   OpalMessageType m_type;
    00780   union {
    00781     const char *             m_commandError;
    00782     OpalParamGeneral         m_general;
    00783     OpalParamProtocol        m_protocol;
    00784     OpalParamRegistration    m_registrationInfo;
    00785     OpalStatusRegistration   m_registrationStatus;
    00786     OpalParamSetUpCall       m_callSetUp;
    00787     const char *             m_callToken;
    00788     OpalStatusIncomingCall   m_incomingCall;
    00789     OpalStatusUserInput      m_userInput;
    00790     OpalStatusMessageWaiting m_messageWaiting;
    00791     OpalStatusCallCleared    m_callCleared;
    00792     OpalParamCallCleared     m_clearCall;
    00793     OpalStatusMediaStream    m_mediaStream;
    00794     OpalParamSetUserData     m_setUserData;
    00795   } m_param;
    00796 };
    00797
    00798
    00799 #ifdef __cplusplus
    00800 };
    00801 #endif
    00802
    00803 #endif // __OPAL_H
    00804
    00805