OPAL Version 3.10.2
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: 26246 $
00030  * $Author: rjongbloed $
00031  * $Date: 2011-07-25 22:42:23 -0500 (Mon, 25 Jul 2011) $
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 25
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;  
00976 } OpalParamSetUpCall;
00977 
00978 
00982 typedef struct OpalStatusIncomingCall {
00983   const char * m_callToken;         
00984   const char * m_localAddress;      
00985   const char * m_remoteAddress;     
00986   const char * m_remotePartyNumber; 
00987   const char * m_remoteDisplayName; 
00988   const char * m_calledAddress;     
00989   const char * m_calledPartyNumber; 
00990   OpalProductDescription m_product; 
00991   const char * m_alertingType;
01003   const char * m_protocolCallId;  
01005   const char * m_referredByAddress; 
01006   const char * m_redirectingNumber; 
01007 } OpalStatusIncomingCall;
01008 
01009 
01014 typedef enum OpalMediaStates {
01015   OpalMediaStateNoChange,   
01016   OpalMediaStateOpen,       
01018   OpalMediaStateClose,      
01020   OpalMediaStatePause,      
01022   OpalMediaStateResume      
01024 } OpalMediaStates;
01025 
01026 
01033 typedef struct OpalStatusMediaStream {
01034   const char    * m_callToken;   
01035   const char    * m_identifier;  
01038   const char    * m_type;        
01043   const char    * m_format;      
01047   OpalMediaStates m_state;       
01050   int             m_volume;      
01054 } OpalStatusMediaStream;
01055 
01056 
01059 typedef struct OpalParamSetUserData {
01060   const char    * m_callToken;   
01061   void *        m_userData;      
01062 } OpalParamSetUserData;
01063 
01064 
01070 typedef struct OpalStatusUserInput {
01071   const char * m_callToken;   
01072   const char * m_userInput;   
01073   unsigned     m_duration;    
01078 } OpalStatusUserInput, OpalParamUserInput;
01079 
01080 
01084 typedef struct OpalStatusMessageWaiting {
01085   const char * m_party;     
01086   const char * m_type;      
01087   const char * m_extraInfo; 
01090 } OpalStatusMessageWaiting;
01091 
01092 
01097 typedef enum OpalLineAppearanceStates {
01098   OpalLineTerminated,  
01099   OpalLineTrying,      
01100   OpalLineProceeding,  
01101   OpalLineRinging,     
01102   OpalLineConnected,   
01103   OpalLineSubcribed,   
01104   OpalLineUnsubcribed, 
01106   OpalLineIdle = OpalLineTerminated // Kept for backward compatibility
01107 } OpalLineAppearanceStates;
01108 
01109 
01113 typedef struct OpalStatusLineAppearance {
01114   const char *             m_line;       
01115   OpalLineAppearanceStates m_state;      
01116   int                      m_appearance; 
01119   const char *             m_callId;     
01123   const char *             m_partyA;     
01124   const char *             m_partyB;     
01125 } OpalStatusLineAppearance;
01126 
01127 
01131 typedef enum OpalVideoRecordMixMode {
01132   OpalSideBySideLetterbox, 
01136   OpalSideBySideScaled,    
01140   OpalStackedPillarbox,    
01144   OpalStackedScaled,       
01148 } OpalVideoRecordMixMode;
01149 
01150 
01153 typedef struct OpalParamRecording {
01154   const char * m_callToken;  
01155   const char * m_file;       
01157   unsigned     m_channels;   
01160   const char * m_audioFormat; 
01164   const char * m_videoFormat; 
01168   unsigned     m_videoWidth;  
01169   unsigned     m_videoHeight; 
01170   unsigned     m_videoRate;   
01171   OpalVideoRecordMixMode m_videoMixing; 
01172 } OpalParamRecording;
01173 
01174 
01178 typedef struct OpalStatusTransferCall {
01179   const char * m_callToken;       
01180   const char * m_protocolCallId;  
01182   const char * m_result;          
01197   const char * m_info;    
01201 } OpalStatusTransferCall;
01202 
01203 
01207 typedef struct OpalStatusIVR {
01208   const char * m_callToken;   
01209   const char * m_variables;   
01214 } OpalStatusIVR;
01215 
01216 
01220 typedef struct OpalStatusCallCleared {
01221   const char * m_callToken;   
01222   const char * m_reason;      
01227 } OpalStatusCallCleared;
01228 
01229 
01234 typedef enum OpalCallEndReason {
01235   OpalCallEndedByLocalUser,         
01236   OpalCallEndedByNoAccept,          
01237   OpalCallEndedByAnswerDenied,      
01238   OpalCallEndedByRemoteUser,        
01239   OpalCallEndedByRefusal,           
01240   OpalCallEndedByNoAnswer,          
01241   OpalCallEndedByCallerAbort,       
01242   OpalCallEndedByTransportFail,     
01243   OpalCallEndedByConnectFail,       
01244   OpalCallEndedByGatekeeper,        
01245   OpalCallEndedByNoUser,            
01246   OpalCallEndedByNoBandwidth,       
01247   OpalCallEndedByCapabilityExchange,
01248   OpalCallEndedByCallForwarded,     
01249   OpalCallEndedBySecurityDenial,    
01250   OpalCallEndedByLocalBusy,         
01251   OpalCallEndedByLocalCongestion,   
01252   OpalCallEndedByRemoteBusy,        
01253   OpalCallEndedByRemoteCongestion,  
01254   OpalCallEndedByUnreachable,       
01255   OpalCallEndedByNoEndPoint,        
01256   OpalCallEndedByHostOffline,       
01257   OpalCallEndedByTemporaryFailure,  
01258   OpalCallEndedByQ931Cause,         
01259   OpalCallEndedByDurationLimit,     
01260   OpalCallEndedByInvalidConferenceID, 
01261   OpalCallEndedByNoDialTone,        
01262   OpalCallEndedByNoRingBackTone,    
01263   OpalCallEndedByOutOfService,      
01264   OpalCallEndedByAcceptingCallWaiting, 
01265   OpalCallEndedWithQ931Code = 0x100  
01266 } OpalCallEndReason;
01267 
01268 
01271 typedef struct OpalParamCallCleared {
01272   const char      * m_callToken;  
01273   OpalCallEndReason m_reason;     
01275 } OpalParamCallCleared;
01276 
01277 
01281 struct OpalMessage {
01282   OpalMessageType m_type;   
01283   union {
01284     const char *             m_commandError;       
01285     OpalParamGeneral         m_general;            
01286     OpalParamProtocol        m_protocol;           
01287     OpalParamRegistration    m_registrationInfo;   
01288     OpalStatusRegistration   m_registrationStatus; 
01289     OpalParamSetUpCall       m_callSetUp;          
01290     const char *             m_callToken;          
01291     OpalStatusIncomingCall   m_incomingCall;       
01292     OpalStatusUserInput      m_userInput;          
01293     OpalStatusMessageWaiting m_messageWaiting;     
01294     OpalStatusLineAppearance m_lineAppearance;     
01295     OpalStatusCallCleared    m_callCleared;        
01296     OpalParamCallCleared     m_clearCall;          
01297     OpalStatusMediaStream    m_mediaStream;        
01298     OpalParamSetUserData     m_setUserData;        
01299     OpalParamRecording       m_recording;          
01300     OpalStatusTransferCall   m_transferStatus;     
01301     OpalStatusIVR            m_ivrStatus;          
01302   } m_param;
01303 };
01304 
01305 
01306 #ifdef __cplusplus
01307 };
01308 #endif
01309 
01310 #if defined(__cplusplus) || defined(DOC_PLUS_PLUS)
01311 
01313 class OpalMessagePtr
01314 {
01315   public:
01316     OpalMessagePtr(OpalMessageType type = OpalIndCommandError);
01317     ~OpalMessagePtr();
01318 
01319     OpalMessageType GetType() const;
01320     void SetType(OpalMessageType type);
01321 
01322     const char               * GetCallToken() const;          
01323     void                       SetCallToken(const char * token);
01324 
01325     const char               * GetCommandError() const;       
01326 
01327     OpalParamGeneral         * GetGeneralParams() const;      
01328     OpalParamProtocol        * GetProtocolParams() const;     
01329     OpalParamRegistration    * GetRegistrationInfo() const;   
01330     OpalStatusRegistration   * GetRegistrationStatus() const; 
01331     OpalParamSetUpCall       * GetCallSetUp() const;          
01332     OpalStatusIncomingCall   * GetIncomingCall() const;       
01333     OpalStatusUserInput      * GetUserInput() const;          
01334     OpalStatusMessageWaiting * GetMessageWaiting() const;     
01335     OpalStatusLineAppearance * GetLineAppearance() const;     
01336     OpalStatusCallCleared    * GetCallCleared() const;        
01337     OpalParamCallCleared     * GetClearCall() const;          
01338     OpalStatusMediaStream    * GetMediaStream() const;        
01339     OpalParamSetUserData     * GetSetUserData() const;        
01340     OpalParamRecording       * GetRecording() const;          
01341     OpalStatusTransferCall   * GetTransferStatus() const;     
01342 
01343   protected:
01344     OpalMessage * m_message;
01345 
01346   private:
01347     OpalMessagePtr(const OpalMessagePtr &) { }
01348     void operator=(const OpalMessagePtr &) { }
01349 
01350   friend class OpalContext;
01351 };
01352 
01353 
01354 #ifdef GetMessage
01355 #undef GetMessage
01356 #endif
01357 #ifdef SendMessage
01358 #undef SendMessage
01359 #endif
01360 
01361 
01369 class OpalContext
01370 {
01371   public:
01373     OpalContext();
01374 
01376     virtual ~OpalContext();
01377 
01380     unsigned Initialise(
01381       const char * options,  
01382       unsigned version = OPAL_C_API_VERSION 
01383     );
01384 
01386     bool IsInitialised() const { return m_handle != NULL; }
01387 
01389     void ShutDown();
01390 
01392     bool GetMessage(
01393       OpalMessagePtr & message,
01394       unsigned timeout = 0
01395     );
01396 
01398     bool SendMessage(
01399       const OpalMessagePtr & message,  
01400       OpalMessagePtr & response        
01401     );
01402 
01403 
01405     bool SetUpCall(
01406       OpalMessagePtr & response,       
01407       const char * partyB,             
01408       const char * partyA = NULL,      
01409       const char * alertingType = NULL 
01410     );
01411 
01413     bool AnswerCall(
01414       const char * callToken           
01415     );
01416 
01418     bool ClearCall(
01419       const char * callToken,          
01420       OpalCallEndReason reason = OpalCallEndedByLocalUser  
01421     );
01422 
01424     bool SendUserInput(
01425       const char * callToken,     
01426       const char * userInput,     
01427       unsigned     duration = 0   
01428     );
01429 
01430   protected:
01431     OpalHandle m_handle;
01432 };
01433 
01434 #endif
01435 
01436 #endif // OPAL_OPAL_H
01437 
01438