# 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: 27795 $
    00030  * $Author: rjongbloed $
    00031  * $Date: 2012-06-07 22:49:21 -0500 (Thu, 07 Jun 2012) $
    00032  */
    00033
    00034 #ifndef OPAL_OPAL_H
    00035 #define OPAL_OPAL_H
    00036
    00037 #include <stdlib.h>
    00038
    00039
    00040 #ifdef __cplusplus
    00041 extern "C" {
    00042 #endif
    00043
    00070 #ifdef _WIN32
    00071   #define OPAL_EXPORT __stdcall
    00072 #else
    00073   #define OPAL_EXPORT
    00074 #endif
    00075
    00077 typedef struct OpalHandleStruct * OpalHandle;
    00078
    00079
    00080 typedef struct OpalMessage OpalMessage;
    00081
    00083 #define OPAL_C_API_VERSION 27
    00084
    00085
    00087
    00138 OpalHandle OPAL_EXPORT OpalInitialise(unsigned * version, const char * options);
    00139
    00143 #define OPAL_INITIALISE_FUNCTION   "OpalInitialise"
    00144
    00148 typedef OpalHandle (OPAL_EXPORT *OpalInitialiseFunction)(unsigned * version, const char * options);
    00149
    00150
    00152
    00161 void OPAL_EXPORT OpalShutDown(OpalHandle opal);
    00162
    00166 #define OPAL_SHUTDOWN_FUNCTION     "OpalShutDown"
    00167
    00171 typedef void (OPAL_EXPORT *OpalShutDownFunction)(OpalHandle opal);
    00172
    00173
    00175
    00212 OpalMessage * OPAL_EXPORT OpalGetMessage(OpalHandle opal, unsigned timeout);
    00213
    00217 #define OPAL_GET_MESSAGE_FUNCTION  "OpalGetMessage"
    00218
    00222 typedef OpalMessage * (OPAL_EXPORT *OpalGetMessageFunction)(OpalHandle opal, unsigned timeout);
    00223
    00224
    00226
    00267 OpalMessage * OPAL_EXPORT OpalSendMessage(OpalHandle opal, const OpalMessage * message);
    00268
    00272 typedef OpalMessage * (OPAL_EXPORT *OpalSendMessageFunction)(OpalHandle opal, const OpalMessage * message);
    00273
    00277 #define OPAL_SEND_MESSAGE_FUNCTION "OpalSendMessage"
    00278
    00279
    00281
    00285 void OPAL_EXPORT OpalFreeMessage(OpalMessage * message);
    00286
    00290 #define OPAL_FREE_MESSAGE_FUNCTION "OpalFreeMessage"
    00291
    00295 typedef void (OPAL_EXPORT *OpalFreeMessageFunction)(OpalMessage * message);
    00296
    00297
    00299
    00300 #define OPAL_PREFIX_H323  "h323"
    00301 #define OPAL_PREFIX_SIP   "sip"
    00302 #define OPAL_PREFIX_IAX2  "iax2"
    00303 #define OPAL_PREFIX_PCSS  "pc"
    00304 #define OPAL_PREFIX_LOCAL "local"
    00305 #define OPAL_PREFIX_POTS  "pots"
    00306 #define OPAL_PREFIX_PSTN  "pstn"
    00307 #define OPAL_PREFIX_IVR   "ivr"
    00308
    00309 #define OPAL_PREFIX_ALL OPAL_PREFIX_H323  " " \
    00310                         OPAL_PREFIX_SIP   " " \
    00311                         OPAL_PREFIX_IAX2  " " \
    00312                         OPAL_PREFIX_PCSS  " " \
    00313                         OPAL_PREFIX_LOCAL " " \
    00314                         OPAL_PREFIX_POTS  " " \
    00315                         OPAL_PREFIX_PSTN  " " \
    00316                         OPAL_PREFIX_IVR
    00317
    00318
    00321 typedef enum OpalMessageType {
    00322   OpalIndCommandError,
    00325   OpalCmdSetGeneralParameters,
    00327   OpalCmdSetProtocolParameters,
    00330   OpalCmdRegistration,
    00334   OpalIndRegistration,
    00339   OpalCmdSetUpCall,
    00343   OpalIndIncomingCall,
    00346   OpalCmdAnswerCall,
    00350   OpalCmdClearCall,
    00355   OpalIndAlerting,
    00359   OpalIndEstablished,
    00363   OpalIndUserInput,
    00366   OpalIndCallCleared,
    00369   OpalCmdHoldCall,
    00371   OpalCmdRetrieveCall,
    00373   OpalCmdTransferCall,
    00376   OpalCmdUserInput,
    00378   OpalIndMessageWaiting,
    00381   OpalIndMediaStream,
    00384   OpalCmdMediaStream,
    00386   OpalCmdSetUserData,
    00387   OpalIndLineAppearance,
    00390   OpalCmdStartRecording,
    00392   OpalCmdStopRecording,
    00394   OpalIndProceeding,
    00402   OpalCmdAlerting,
    00404   OpalIndOnHold,
    00406   OpalIndOffHold,
    00408   OpalIndTransferCall,
    00411   OpalIndCompletedIVR,
    00415 // Always add new messages to ethe end to maintain backward compatibility
    00416   OpalMessageTypeCount
    00417 } OpalMessageType;
    00418
    00419
    00423 typedef enum OpalSilenceDetectMode {
    00424   OpalSilenceDetectNoChange,
    00425   OpalSilenceDetectDisabled,
    00426   OpalSilenceDetectFixed,
    00427   OpalSilenceDetectAdaptive
    00428 } OpalSilenceDetectMode;
    00429
    00430
    00434 typedef enum OpalEchoCancelMode {
    00435   OpalEchoCancelNoChange,
    00436   OpalEchoCancelDisabled,
    00437   OpalEchoCancelEnabled
    00438 } OpalEchoCancelMode;
    00439
    00440
    00455 typedef int (*OpalMediaDataFunction)(
    00456   const char * token,
    00458   const char * stream,
    00462   const char * format,
    00463   void * userData,
    00464   void * data,
    00465   int size
    00466 );
    00467
    00468
    00485 typedef int (*OpalMessageAvailableFunction)(
    00486   const OpalMessage * message
    00487 );
    00488
    00489
    00497 typedef enum OpalMediaDataType {
    00498   OpalMediaDataNoChange,
    00499   OpalMediaDataPayloadOnly,
    00501   OpalMediaDataWithHeader
    00503 } OpalMediaDataType;
    00504
    00505
    00523 typedef enum OpalMediaTiming {
    00524   OpalMediaTimingNoChange,
    00525   OpalMediaTimingSynchronous,
    00527   OpalMediaTimingAsynchronous,
    00529   OpalMediaTimingSimulated
    00532 } OpalMediaTiming;
    00533
    00534
    00567 typedef struct OpalParamGeneral {
    00568   const char * m_audioRecordDevice;
    00569   const char * m_audioPlayerDevice;
    00570   const char * m_videoInputDevice;
    00571   const char * m_videoOutputDevice;
    00572   const char * m_videoPreviewDevice;
    00573   const char * m_mediaOrder;
    00576   const char * m_mediaMask;
    00579   const char * m_autoRxMedia;
    00583   const char * m_autoTxMedia;
    00587   const char * m_natRouter;
    00589   const char * m_stunServer;
    00591   unsigned     m_tcpPortBase;
    00593   unsigned     m_tcpPortMax;
    00595   unsigned     m_udpPortBase;
    00597   unsigned     m_udpPortMax;
    00599   unsigned     m_rtpPortBase;
    00601   unsigned     m_rtpPortMax;
    00603   unsigned     m_rtpTypeOfService;
    00605   unsigned     m_rtpMaxPayloadSize;
    00607   unsigned     m_minAudioJitter;
    00611   unsigned     m_maxAudioJitter;
    00615   OpalSilenceDetectMode m_silenceDetectMode;
    00618   unsigned     m_silenceThreshold;
    00620   unsigned     m_signalDeadband;
    00622   unsigned     m_silenceDeadband;
    00624   unsigned     m_silenceAdaptPeriod;
    00627   OpalEchoCancelMode m_echoCancellation;
    00629   unsigned     m_audioBuffers;
    00632   OpalMediaDataFunction m_mediaReadData;
    00634   OpalMediaDataFunction m_mediaWriteData;
    00636   OpalMediaDataType     m_mediaDataHeader;
    00639   OpalMessageAvailableFunction m_messageAvailable;
    00643   const char * m_mediaOptions;
    00652   unsigned     m_audioBufferTime;
    00655   unsigned m_manualAlerting;
    00661   OpalMediaTiming m_mediaTiming;
    00665   OpalMediaTiming m_videoSourceTiming;
    00668 } OpalParamGeneral;
    00669
    00670
    00673 typedef struct OpalProductDescription {
    00674   const char * m_vendor;
    00677   const char * m_name;
    00680   const char * m_version;
    00683   unsigned     m_t35CountryCode;
    00688   unsigned     m_t35Extension;
    00693   unsigned     m_manufacturerCode;
    00699 } OpalProductDescription;
    00700
    00701
    00705 typedef enum OpalUserInputModes {
    00706   OpalUserInputDefault,
    00707   OpalUserInputAsQ931,
    00708   OpalUserInputAsString,
    00709   OpalUserInputAsTone,
    00710   OpalUserInputAsRFC2833,
    00711   OpalUserInputInBand,
    00712 } OpalUserInputModes;
    00713
    00714
    00731 typedef struct OpalParamProtocol {
    00732   const char * m_prefix;
    00735   const char * m_userName;
    00738   const char * m_displayName;
    00740   OpalProductDescription m_product;
    00741   const char * m_interfaceAddresses;
    00749   OpalUserInputModes m_userInputMode;
    00752   const char * m_defaultOptions;
    00754 } OpalParamProtocol;
    00755
    00756
    00758 #define OPAL_MWI_EVENT_PACKAGE             "message-summary"
    00759
    00761 #define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"
    00762
    00824 typedef struct OpalParamRegistration {
    00825   const char * m_protocol;
    00827   const char * m_identifier;
    00833   const char * m_hostName;
    00837   const char * m_authUserName;
    00838   const char * m_password;
    00839   const char * m_adminEntity;
    00842   unsigned     m_timeToLive;
    00844   unsigned     m_restoreTime;
    00847   const char * m_eventPackage;
    00855 } OpalParamRegistration;
    00856
    00857
    00861 typedef enum OpalRegistrationStates {
    00862   OpalRegisterSuccessful,
    00863   OpalRegisterRemoved,
    00867   OpalRegisterFailed,
    00869   OpalRegisterRetrying,
    00871   OpalRegisterRestored,
    00872 } OpalRegistrationStates;
    00873
    00874
    00878 typedef struct OpalStatusRegistration {
    00879   const char * m_protocol;
    00881   const char * m_serverName;
    00884   const char * m_error;
    00888   OpalRegistrationStates m_status;
    00889   OpalProductDescription m_product;
    00890 } OpalStatusRegistration;
    00891
    00892
    00929 typedef struct OpalParamSetUpCall {
    00930   const char * m_partyA;
    00944   const char * m_partyB;
    00956   const char * m_callToken;
    00961   const char * m_alertingType;
    00980   const char * m_protocolCallId;
    00982   OpalParamProtocol m_overrides;
    00985 } OpalParamSetUpCall;
    00986
    00987
    00991 typedef struct OpalStatusIncomingCall {
    00992   const char * m_callToken;
    00993   const char * m_localAddress;
    00994   const char * m_remoteAddress;
    00995   const char * m_remotePartyNumber;
    00996   const char * m_remoteDisplayName;
    00997   const char * m_calledAddress;
    00998   const char * m_calledPartyNumber;
    00999   OpalProductDescription m_product;
    01000   const char * m_alertingType;
    01012   const char * m_protocolCallId;
    01014   const char * m_referredByAddress;
    01015   const char * m_redirectingNumber;
    01016 } OpalStatusIncomingCall;
    01017
    01018
    01027 typedef struct OpalParamAnswerCall {
    01028   const char * m_callToken;
    01029   OpalParamProtocol m_overrides;
    01032 } OpalParamAnswerCall;
    01033
    01038 typedef enum OpalMediaStates {
    01039   OpalMediaStateNoChange,
    01040   OpalMediaStateOpen,
    01042   OpalMediaStateClose,
    01044   OpalMediaStatePause,
    01046   OpalMediaStateResume
    01048 } OpalMediaStates;
    01049
    01050
    01057 typedef struct OpalStatusMediaStream {
    01058   const char    * m_callToken;
    01059   const char    * m_identifier;
    01062   const char    * m_type;
    01067   const char    * m_format;
    01071   OpalMediaStates m_state;
    01074   int             m_volume;
    01078 } OpalStatusMediaStream;
    01079
    01080
    01083 typedef struct OpalParamSetUserData {
    01084   const char    * m_callToken;
    01085   void *        m_userData;
    01086 } OpalParamSetUserData;
    01087
    01088
    01094 typedef struct OpalStatusUserInput {
    01095   const char * m_callToken;
    01096   const char * m_userInput;
    01097   unsigned     m_duration;
    01102 } OpalStatusUserInput, OpalParamUserInput;
    01103
    01104
    01108 typedef struct OpalStatusMessageWaiting {
    01109   const char * m_party;
    01110   const char * m_type;
    01111   const char * m_extraInfo;
    01114 } OpalStatusMessageWaiting;
    01115
    01116
    01121 typedef enum OpalLineAppearanceStates {
    01122   OpalLineTerminated,
    01123   OpalLineTrying,
    01124   OpalLineProceeding,
    01125   OpalLineRinging,
    01126   OpalLineConnected,
    01127   OpalLineSubcribed,
    01128   OpalLineUnsubcribed,
    01130   OpalLineIdle = OpalLineTerminated // Kept for backward compatibility
    01131 } OpalLineAppearanceStates;
    01132
    01133
    01137 typedef struct OpalStatusLineAppearance {
    01138   const char *             m_line;
    01139   OpalLineAppearanceStates m_state;
    01140   int                      m_appearance;
    01143   const char *             m_callId;
    01147   const char *             m_partyA;
    01148   const char *             m_partyB;
    01149 } OpalStatusLineAppearance;
    01150
    01151
    01155 typedef enum OpalVideoRecordMixMode {
    01156   OpalSideBySideLetterbox,
    01160   OpalSideBySideScaled,
    01164   OpalStackedPillarbox,
    01168   OpalStackedScaled,
    01172 } OpalVideoRecordMixMode;
    01173
    01174
    01177 typedef struct OpalParamRecording {
    01178   const char * m_callToken;
    01179   const char * m_file;
    01181   unsigned     m_channels;
    01184   const char * m_audioFormat;
    01188   const char * m_videoFormat;
    01192   unsigned     m_videoWidth;
    01193   unsigned     m_videoHeight;
    01194   unsigned     m_videoRate;
    01195   OpalVideoRecordMixMode m_videoMixing;
    01196 } OpalParamRecording;
    01197
    01198
    01202 typedef struct OpalStatusTransferCall {
    01203   const char * m_callToken;
    01204   const char * m_protocolCallId;
    01206   const char * m_result;
    01221   const char * m_info;
    01225 } OpalStatusTransferCall;
    01226
    01227
    01231 typedef struct OpalStatusIVR {
    01232   const char * m_callToken;
    01233   const char * m_variables;
    01238 } OpalStatusIVR;
    01239
    01240
    01244 typedef struct OpalStatusCallCleared {
    01245   const char * m_callToken;
    01246   const char * m_reason;
    01251 } OpalStatusCallCleared;
    01252
    01253
    01258 typedef enum OpalCallEndReason {
    01259   OpalCallEndedByLocalUser,
    01260   OpalCallEndedByNoAccept,
    01261   OpalCallEndedByAnswerDenied,
    01262   OpalCallEndedByRemoteUser,
    01263   OpalCallEndedByRefusal,
    01264   OpalCallEndedByNoAnswer,
    01265   OpalCallEndedByCallerAbort,
    01266   OpalCallEndedByTransportFail,
    01267   OpalCallEndedByConnectFail,
    01268   OpalCallEndedByGatekeeper,
    01269   OpalCallEndedByNoUser,
    01270   OpalCallEndedByNoBandwidth,
    01271   OpalCallEndedByCapabilityExchange,
    01272   OpalCallEndedByCallForwarded,
    01273   OpalCallEndedBySecurityDenial,
    01274   OpalCallEndedByLocalBusy,
    01275   OpalCallEndedByLocalCongestion,
    01276   OpalCallEndedByRemoteBusy,
    01277   OpalCallEndedByRemoteCongestion,
    01278   OpalCallEndedByUnreachable,
    01279   OpalCallEndedByNoEndPoint,
    01280   OpalCallEndedByHostOffline,
    01281   OpalCallEndedByTemporaryFailure,
    01282   OpalCallEndedByQ931Cause,
    01283   OpalCallEndedByDurationLimit,
    01284   OpalCallEndedByInvalidConferenceID,
    01285   OpalCallEndedByNoDialTone,
    01286   OpalCallEndedByNoRingBackTone,
    01287   OpalCallEndedByOutOfService,
    01288   OpalCallEndedByAcceptingCallWaiting,
    01289   OpalCallEndedWithQ931Code = 0x100
    01290 } OpalCallEndReason;
    01291
    01292
    01295 typedef struct OpalParamCallCleared {
    01296   const char      * m_callToken;
    01297   OpalCallEndReason m_reason;
    01299 } OpalParamCallCleared;
    01300
    01301
    01305 struct OpalMessage {
    01306   OpalMessageType m_type;
    01307   union {
    01308     const char *             m_commandError;
    01309     OpalParamGeneral         m_general;
    01310     OpalParamProtocol        m_protocol;
    01311     OpalParamRegistration    m_registrationInfo;
    01312     OpalStatusRegistration   m_registrationStatus;
    01313     OpalParamSetUpCall       m_callSetUp;
    01314     const char *             m_callToken;
    01315     OpalStatusIncomingCall   m_incomingCall;
    01316     OpalParamAnswerCall      m_answerCall;
    01317     OpalStatusUserInput      m_userInput;
    01318     OpalStatusMessageWaiting m_messageWaiting;
    01319     OpalStatusLineAppearance m_lineAppearance;
    01320     OpalStatusCallCleared    m_callCleared;
    01321     OpalParamCallCleared     m_clearCall;
    01322     OpalStatusMediaStream    m_mediaStream;
    01323     OpalParamSetUserData     m_setUserData;
    01324     OpalParamRecording       m_recording;
    01325     OpalStatusTransferCall   m_transferStatus;
    01326     OpalStatusIVR            m_ivrStatus;
    01327   } m_param;
    01328 };
    01329
    01330
    01331 #ifdef __cplusplus
    01332 };
    01333 #endif
    01334
    01335 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS)
    01336
    01338 class OpalMessagePtr
    01339 {
    01340   public:
    01341     OpalMessagePtr(OpalMessageType type = OpalIndCommandError);
    01342     ~OpalMessagePtr();
    01343
    01344     OpalMessageType GetType() const;
    01345     void SetType(OpalMessageType type);
    01346
    01347     const char               * GetCallToken() const;
    01348     void                       SetCallToken(const char * token);
    01349
    01350     const char               * GetCommandError() const;
    01351
    01352     OpalParamGeneral         * GetGeneralParams() const;
    01353     OpalParamProtocol        * GetProtocolParams() const;
    01354     OpalParamRegistration    * GetRegistrationInfo() const;
    01355     OpalStatusRegistration   * GetRegistrationStatus() const;
    01356     OpalParamSetUpCall       * GetCallSetUp() const;
    01357     OpalStatusIncomingCall   * GetIncomingCall() const;
    01358     OpalParamAnswerCall      * GetAnswerCall() const;
    01359     OpalStatusUserInput      * GetUserInput() const;
    01360     OpalStatusMessageWaiting * GetMessageWaiting() const;
    01361     OpalStatusLineAppearance * GetLineAppearance() const;
    01362     OpalStatusCallCleared    * GetCallCleared() const;
    01363     OpalParamCallCleared     * GetClearCall() const;
    01364     OpalStatusMediaStream    * GetMediaStream() const;
    01365     OpalParamSetUserData     * GetSetUserData() const;
    01366     OpalParamRecording       * GetRecording() const;
    01367     OpalStatusTransferCall   * GetTransferStatus() const;
    01368
    01369   protected:
    01370     OpalMessage * m_message;
    01371
    01372   private:
    01373     OpalMessagePtr(const OpalMessagePtr &) { }
    01374     void operator=(const OpalMessagePtr &) { }
    01375
    01376   friend class OpalContext;
    01377 };
    01378
    01379
    01380 #ifdef GetMessage
    01381 #undef GetMessage
    01382 #endif
    01383 #ifdef SendMessage
    01384 #undef SendMessage
    01385 #endif
    01386
    01387
    01395 class OpalContext
    01396 {
    01397   public:
    01399     OpalContext();
    01400
    01402     virtual ~OpalContext();
    01403
    01406     unsigned Initialise(
    01407       const char * options,
    01408       unsigned version = OPAL_C_API_VERSION
    01409     );
    01410
    01412     bool IsInitialised() const { return m_handle != NULL; }
    01413
    01415     void ShutDown();
    01416
    01418     bool GetMessage(
    01419       OpalMessagePtr & message,
    01420       unsigned timeout = 0
    01421     );
    01422
    01424     bool SendMessage(
    01425       const OpalMessagePtr & message,
    01426       OpalMessagePtr & response
    01427     );
    01428
    01429
    01431     bool SetUpCall(
    01432       OpalMessagePtr & response,
    01433       const char * partyB,
    01434       const char * partyA = NULL,
    01435       const char * alertingType = NULL
    01436     );
    01437
    01439     bool AnswerCall(
    01440       const char * callToken
    01441     );
    01442
    01444     bool ClearCall(
    01445       const char * callToken,
    01446       OpalCallEndReason reason = OpalCallEndedByLocalUser
    01447     );
    01448
    01450     bool SendUserInput(
    01451       const char * callToken,
    01452       const char * userInput,
    01453       unsigned     duration = 0
    01454     );
    01455
    01456   protected:
    01457     OpalHandle m_handle;
    01458 };
    01459
    01460 #endif
    01461
    01462 #endif // OPAL_OPAL_H
    01463
    01464