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 

Generated on 14 Aug 2013 for OPAL by  doxygen 1.4.7