OPAL  Version 3.10.4
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: 26939 $
00030  * $Author: rjongbloed $
00031  * $Date: 2012-02-07 01:17:49 -0600 (Tue, 07 Feb 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 26
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"    ///< H.323 Protocol supported string for OpalInitialise()
00301 #define OPAL_PREFIX_SIP   "sip"     ///< SIP Protocol supported string for OpalInitialise()
00302 #define OPAL_PREFIX_IAX2  "iax2"    ///< IAX2 Protocol supported string for OpalInitialise()
00303 #define OPAL_PREFIX_PCSS  "pc"      ///< PC sound system supported string for OpalInitialise()
00304 #define OPAL_PREFIX_LOCAL "local"   ///< Local endpoint supported string for OpalInitialise()
00305 #define OPAL_PREFIX_POTS  "pots"    ///< Plain Old Telephone System supported string for OpalInitialise()
00306 #define OPAL_PREFIX_PSTN  "pstn"    ///< Public Switched Network supported string for OpalInitialise()
00307 #define OPAL_PREFIX_IVR   "ivr"     ///< Interactive Voice Response supported string for OpalInitialise()
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 } OpalMediaTiming;
00530 
00531 
00564 typedef struct OpalParamGeneral {
00565   const char * m_audioRecordDevice;   
00566   const char * m_audioPlayerDevice;   
00567   const char * m_videoInputDevice;    
00568   const char * m_videoOutputDevice;   
00569   const char * m_videoPreviewDevice;  
00570   const char * m_mediaOrder;          
00573   const char * m_mediaMask;           
00576   const char * m_autoRxMedia;         
00580   const char * m_autoTxMedia;         
00584   const char * m_natRouter;           
00586   const char * m_stunServer;          
00588   unsigned     m_tcpPortBase;         
00590   unsigned     m_tcpPortMax;          
00592   unsigned     m_udpPortBase;         
00594   unsigned     m_udpPortMax;          
00596   unsigned     m_rtpPortBase;         
00598   unsigned     m_rtpPortMax;          
00600   unsigned     m_rtpTypeOfService;    
00602   unsigned     m_rtpMaxPayloadSize;   
00604   unsigned     m_minAudioJitter;      
00608   unsigned     m_maxAudioJitter;      
00612   OpalSilenceDetectMode m_silenceDetectMode; 
00615   unsigned     m_silenceThreshold;    
00617   unsigned     m_signalDeadband;      
00619   unsigned     m_silenceDeadband;     
00621   unsigned     m_silenceAdaptPeriod;  
00624   OpalEchoCancelMode m_echoCancellation; 
00626   unsigned     m_audioBuffers;        
00629   OpalMediaDataFunction m_mediaReadData;   
00631   OpalMediaDataFunction m_mediaWriteData;  
00633   OpalMediaDataType     m_mediaDataHeader; 
00636   OpalMessageAvailableFunction m_messageAvailable; 
00640   const char * m_mediaOptions;        
00649   unsigned     m_audioBufferTime;     
00652   unsigned m_manualAlerting;          
00658   OpalMediaTiming m_mediaTiming;      
00661 } OpalParamGeneral;
00662 
00663 
00666 typedef struct OpalProductDescription {
00667   const char * m_vendor;              
00670   const char * m_name;                
00673   const char * m_version;             
00676   unsigned     m_t35CountryCode;      
00681   unsigned     m_t35Extension;        
00686   unsigned     m_manufacturerCode;    
00692 } OpalProductDescription;
00693 
00694 
00698 typedef enum OpalUserInputModes {
00699   OpalUserInputDefault,   
00700   OpalUserInputAsQ931,    
00701   OpalUserInputAsString,  
00702   OpalUserInputAsTone,    
00703   OpalUserInputAsRFC2833, 
00704   OpalUserInputInBand,    
00705 } OpalUserInputModes;
00706 
00707 
00724 typedef struct OpalParamProtocol {
00725   const char * m_prefix;              
00728   const char * m_userName;            
00731   const char * m_displayName;         
00733   OpalProductDescription m_product;   
00734   const char * m_interfaceAddresses;  
00742   OpalUserInputModes m_userInputMode; 
00745   const char * m_defaultOptions;      
00747 } OpalParamProtocol;
00748 
00749 
00751 #define OPAL_MWI_EVENT_PACKAGE             "message-summary"
00752 
00754 #define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"
00755 
00817 typedef struct OpalParamRegistration {
00818   const char * m_protocol;      
00820   const char * m_identifier;    
00826   const char * m_hostName;      
00830   const char * m_authUserName;  
00831   const char * m_password;      
00832   const char * m_adminEntity;   
00835   unsigned     m_timeToLive;    
00837   unsigned     m_restoreTime;   
00840   const char * m_eventPackage;  
00848 } OpalParamRegistration;
00849 
00850 
00854 typedef enum OpalRegistrationStates {
00855   OpalRegisterSuccessful,   
00856   OpalRegisterRemoved,      
00860   OpalRegisterFailed,       
00862   OpalRegisterRetrying,     
00864   OpalRegisterRestored,     
00865 } OpalRegistrationStates;
00866 
00867 
00871 typedef struct OpalStatusRegistration {
00872   const char * m_protocol;    
00874   const char * m_serverName;  
00877   const char * m_error;       
00881   OpalRegistrationStates m_status; 
00882   OpalProductDescription m_product; 
00883 } OpalStatusRegistration;
00884 
00885 
00922 typedef struct OpalParamSetUpCall {
00923   const char * m_partyA;      
00937   const char * m_partyB;      
00949   const char * m_callToken;   
00954   const char * m_alertingType;
00973   const char * m_protocolCallId;  
00975   OpalParamProtocol m_overrides;  
00978 } OpalParamSetUpCall;
00979 
00980 
00984 typedef struct OpalStatusIncomingCall {
00985   const char * m_callToken;         
00986   const char * m_localAddress;      
00987   const char * m_remoteAddress;     
00988   const char * m_remotePartyNumber; 
00989   const char * m_remoteDisplayName; 
00990   const char * m_calledAddress;     
00991   const char * m_calledPartyNumber; 
00992   OpalProductDescription m_product; 
00993   const char * m_alertingType;
01005   const char * m_protocolCallId;  
01007   const char * m_referredByAddress; 
01008   const char * m_redirectingNumber; 
01009 } OpalStatusIncomingCall;
01010 
01011 
01020 typedef struct OpalParamAnswerCall {
01021   const char * m_callToken;       
01022   OpalParamProtocol m_overrides;  
01025 } OpalParamAnswerCall;
01026 
01031 typedef enum OpalMediaStates {
01032   OpalMediaStateNoChange,   
01033   OpalMediaStateOpen,       
01035   OpalMediaStateClose,      
01037   OpalMediaStatePause,      
01039   OpalMediaStateResume      
01041 } OpalMediaStates;
01042 
01043 
01050 typedef struct OpalStatusMediaStream {
01051   const char    * m_callToken;   
01052   const char    * m_identifier;  
01055   const char    * m_type;        
01060   const char    * m_format;      
01064   OpalMediaStates m_state;       
01067   int             m_volume;      
01071 } OpalStatusMediaStream;
01072 
01073 
01076 typedef struct OpalParamSetUserData {
01077   const char    * m_callToken;   
01078   void *        m_userData;      
01079 } OpalParamSetUserData;
01080 
01081 
01087 typedef struct OpalStatusUserInput {
01088   const char * m_callToken;   
01089   const char * m_userInput;   
01090   unsigned     m_duration;    
01095 } OpalStatusUserInput, OpalParamUserInput;
01096 
01097 
01101 typedef struct OpalStatusMessageWaiting {
01102   const char * m_party;     
01103   const char * m_type;      
01104   const char * m_extraInfo; 
01107 } OpalStatusMessageWaiting;
01108 
01109 
01114 typedef enum OpalLineAppearanceStates {
01115   OpalLineTerminated,  
01116   OpalLineTrying,      
01117   OpalLineProceeding,  
01118   OpalLineRinging,     
01119   OpalLineConnected,   
01120   OpalLineSubcribed,   
01121   OpalLineUnsubcribed, 
01123   OpalLineIdle = OpalLineTerminated // Kept for backward compatibility
01124 } OpalLineAppearanceStates;
01125 
01126 
01130 typedef struct OpalStatusLineAppearance {
01131   const char *             m_line;       
01132   OpalLineAppearanceStates m_state;      
01133   int                      m_appearance; 
01136   const char *             m_callId;     
01140   const char *             m_partyA;     
01141   const char *             m_partyB;     
01142 } OpalStatusLineAppearance;
01143 
01144 
01148 typedef enum OpalVideoRecordMixMode {
01149   OpalSideBySideLetterbox, 
01153   OpalSideBySideScaled,    
01157   OpalStackedPillarbox,    
01161   OpalStackedScaled,       
01165 } OpalVideoRecordMixMode;
01166 
01167 
01170 typedef struct OpalParamRecording {
01171   const char * m_callToken;  
01172   const char * m_file;       
01174   unsigned     m_channels;   
01177   const char * m_audioFormat; 
01181   const char * m_videoFormat; 
01185   unsigned     m_videoWidth;  
01186   unsigned     m_videoHeight; 
01187   unsigned     m_videoRate;   
01188   OpalVideoRecordMixMode m_videoMixing; 
01189 } OpalParamRecording;
01190 
01191 
01195 typedef struct OpalStatusTransferCall {
01196   const char * m_callToken;       
01197   const char * m_protocolCallId;  
01199   const char * m_result;          
01214   const char * m_info;    
01218 } OpalStatusTransferCall;
01219 
01220 
01224 typedef struct OpalStatusIVR {
01225   const char * m_callToken;   
01226   const char * m_variables;   
01231 } OpalStatusIVR;
01232 
01233 
01237 typedef struct OpalStatusCallCleared {
01238   const char * m_callToken;   
01239   const char * m_reason;      
01244 } OpalStatusCallCleared;
01245 
01246 
01251 typedef enum OpalCallEndReason {
01252   OpalCallEndedByLocalUser,         
01253   OpalCallEndedByNoAccept,          
01254   OpalCallEndedByAnswerDenied,      
01255   OpalCallEndedByRemoteUser,        
01256   OpalCallEndedByRefusal,           
01257   OpalCallEndedByNoAnswer,          
01258   OpalCallEndedByCallerAbort,       
01259   OpalCallEndedByTransportFail,     
01260   OpalCallEndedByConnectFail,       
01261   OpalCallEndedByGatekeeper,        
01262   OpalCallEndedByNoUser,            
01263   OpalCallEndedByNoBandwidth,       
01264   OpalCallEndedByCapabilityExchange,
01265   OpalCallEndedByCallForwarded,     
01266   OpalCallEndedBySecurityDenial,    
01267   OpalCallEndedByLocalBusy,         
01268   OpalCallEndedByLocalCongestion,   
01269   OpalCallEndedByRemoteBusy,        
01270   OpalCallEndedByRemoteCongestion,  
01271   OpalCallEndedByUnreachable,       
01272   OpalCallEndedByNoEndPoint,        
01273   OpalCallEndedByHostOffline,       
01274   OpalCallEndedByTemporaryFailure,  
01275   OpalCallEndedByQ931Cause,         
01276   OpalCallEndedByDurationLimit,     
01277   OpalCallEndedByInvalidConferenceID, 
01278   OpalCallEndedByNoDialTone,        
01279   OpalCallEndedByNoRingBackTone,    
01280   OpalCallEndedByOutOfService,      
01281   OpalCallEndedByAcceptingCallWaiting, 
01282   OpalCallEndedWithQ931Code = 0x100  
01283 } OpalCallEndReason;
01284 
01285 
01288 typedef struct OpalParamCallCleared {
01289   const char      * m_callToken;  
01290   OpalCallEndReason m_reason;     
01292 } OpalParamCallCleared;
01293 
01294 
01298 struct OpalMessage {
01299   OpalMessageType m_type;   
01300   union {
01301     const char *             m_commandError;       
01302     OpalParamGeneral         m_general;            
01303     OpalParamProtocol        m_protocol;           
01304     OpalParamRegistration    m_registrationInfo;   
01305     OpalStatusRegistration   m_registrationStatus; 
01306     OpalParamSetUpCall       m_callSetUp;          
01307     const char *             m_callToken;          
01308     OpalStatusIncomingCall   m_incomingCall;       
01309     OpalParamAnswerCall      m_answerCall;         
01310     OpalStatusUserInput      m_userInput;          
01311     OpalStatusMessageWaiting m_messageWaiting;     
01312     OpalStatusLineAppearance m_lineAppearance;     
01313     OpalStatusCallCleared    m_callCleared;        
01314     OpalParamCallCleared     m_clearCall;          
01315     OpalStatusMediaStream    m_mediaStream;        
01316     OpalParamSetUserData     m_setUserData;        
01317     OpalParamRecording       m_recording;          
01318     OpalStatusTransferCall   m_transferStatus;     
01319     OpalStatusIVR            m_ivrStatus;          
01320   } m_param;
01321 };
01322 
01323 
01324 #ifdef __cplusplus
01325 };
01326 #endif
01327 
01328 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS)
01329 
01331 class OpalMessagePtr
01332 {
01333   public:
01334     OpalMessagePtr(OpalMessageType type = OpalIndCommandError);
01335     ~OpalMessagePtr();
01336 
01337     OpalMessageType GetType() const;
01338     void SetType(OpalMessageType type);
01339 
01340     const char               * GetCallToken() const;          
01341     void                       SetCallToken(const char * token);
01342 
01343     const char               * GetCommandError() const;       
01344 
01345     OpalParamGeneral         * GetGeneralParams() const;      
01346     OpalParamProtocol        * GetProtocolParams() const;     
01347     OpalParamRegistration    * GetRegistrationInfo() const;   
01348     OpalStatusRegistration   * GetRegistrationStatus() const; 
01349     OpalParamSetUpCall       * GetCallSetUp() const;          
01350     OpalStatusIncomingCall   * GetIncomingCall() const;       
01351     OpalParamAnswerCall      * GetAnswerCall() const;         
01352     OpalStatusUserInput      * GetUserInput() const;          
01353     OpalStatusMessageWaiting * GetMessageWaiting() const;     
01354     OpalStatusLineAppearance * GetLineAppearance() const;     
01355     OpalStatusCallCleared    * GetCallCleared() const;        
01356     OpalParamCallCleared     * GetClearCall() const;          
01357     OpalStatusMediaStream    * GetMediaStream() const;        
01358     OpalParamSetUserData     * GetSetUserData() const;        
01359     OpalParamRecording       * GetRecording() const;          
01360     OpalStatusTransferCall   * GetTransferStatus() const;     
01361 
01362   protected:
01363     OpalMessage * m_message;
01364 
01365   private:
01366     OpalMessagePtr(const OpalMessagePtr &) { }
01367     void operator=(const OpalMessagePtr &) { }
01368 
01369   friend class OpalContext;
01370 };
01371 
01372 
01373 #ifdef GetMessage
01374 #undef GetMessage
01375 #endif
01376 #ifdef SendMessage
01377 #undef SendMessage
01378 #endif
01379 
01380 
01388 class OpalContext
01389 {
01390   public:
01392     OpalContext();
01393 
01395     virtual ~OpalContext();
01396 
01399     unsigned Initialise(
01400       const char * options,  
01401       unsigned version = OPAL_C_API_VERSION 
01402     );
01403 
01405     bool IsInitialised() const { return m_handle != NULL; }
01406 
01408     void ShutDown();
01409 
01411     bool GetMessage(
01412       OpalMessagePtr & message,
01413       unsigned timeout = 0
01414     );
01415 
01417     bool SendMessage(
01418       const OpalMessagePtr & message,  
01419       OpalMessagePtr & response        
01420     );
01421 
01422 
01424     bool SetUpCall(
01425       OpalMessagePtr & response,       
01426       const char * partyB,             
01427       const char * partyA = NULL,      
01428       const char * alertingType = NULL 
01429     );
01430 
01432     bool AnswerCall(
01433       const char * callToken           
01434     );
01435 
01437     bool ClearCall(
01438       const char * callToken,          
01439       OpalCallEndReason reason = OpalCallEndedByLocalUser  
01440     );
01441 
01443     bool SendUserInput(
01444       const char * callToken,     
01445       const char * userInput,     
01446       unsigned     duration = 0   
01447     );
01448 
01449   protected:
01450     OpalHandle m_handle;
01451 };
01452 
01453 #endif
01454 
01455 #endif // OPAL_OPAL_H
01456 
01457