opal.h

Go to the documentation of this file.

/*
 * opal.h
 *
 * "C" language interface for OPAL
 *
 * Open Phone Abstraction Library (OPAL)
 *
 * Copyright (c) 2008 Vox Lucida
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Open Phone Abstraction Library.
 *
 * The Initial Developer of the Original Code is Vox Lucida (Robert Jongbloed)
 *
 * This code was initially written with the assisance of funding from
 * Stonevoice. http://www.stonevoice.com.
 *
 * Contributor(s): ______________________________________.
 *
 * $Revision: 22553 $
 * $Author: csoutheren $
 * $Date: 2009-05-07 08:56:06 +0000 (Thu, 07 May 2009) $
 */

#ifndef OPAL_OPAL_H
#define OPAL_OPAL_H

#ifdef __cplusplus
extern "C" {
#endif

#ifdef _WIN32
  #define OPAL_EXPORT __stdcall
#else
  #define OPAL_EXPORT
#endif

typedef struct OpalHandleStruct * OpalHandle;

typedef struct OpalMessage OpalMessage;


#define OPAL_C_API_VERSION 18



OpalHandle OPAL_EXPORT OpalInitialise(unsigned * version, const char * options);

#define OPAL_INITIALISE_FUNCTION   "OpalInitialise"

typedef OpalHandle (OPAL_EXPORT *OpalInitialiseFunction)(unsigned * version, const char * options);



void OPAL_EXPORT OpalShutDown(OpalHandle opal);

#define OPAL_SHUTDOWN_FUNCTION     "OpalShutDown"

typedef void (OPAL_EXPORT *OpalShutDownFunction)(OpalHandle opal);



OpalMessage * OPAL_EXPORT OpalGetMessage(OpalHandle opal, unsigned timeout);

#define OPAL_GET_MESSAGE_FUNCTION  "OpalGetMessage"

typedef OpalMessage * (OPAL_EXPORT *OpalGetMessageFunction)(OpalHandle opal, unsigned timeout);



OpalMessage * OPAL_EXPORT OpalSendMessage(OpalHandle opal, const OpalMessage * message);

typedef OpalMessage * (OPAL_EXPORT *OpalSendMessageFunction)(OpalHandle opal, const OpalMessage * message);

#define OPAL_SEND_MESSAGE_FUNCTION "OpalSendMessage"



void OPAL_EXPORT OpalFreeMessage(OpalMessage * message);

#define OPAL_FREE_MESSAGE_FUNCTION "OpalFreeMessage"

typedef void (OPAL_EXPORT *OpalFreeMessageFunction)(OpalMessage * message);



#define OPAL_PREFIX_H323  "h323"
#define OPAL_PREFIX_SIP   "sip"
#define OPAL_PREFIX_IAX2  "iax2"
#define OPAL_PREFIX_PCSS  "pc"
#define OPAL_PREFIX_LOCAL "local"
#define OPAL_PREFIX_POTS  "pots"
#define OPAL_PREFIX_PSTN  "pstn"
#define OPAL_PREFIX_IVR   "ivr"

#define OPAL_PREFIX_ALL OPAL_PREFIX_H323  " " \
                        OPAL_PREFIX_SIP   " " \
                        OPAL_PREFIX_IAX2  " " \
                        OPAL_PREFIX_PCSS  " " \
                        OPAL_PREFIX_LOCAL " " \
                        OPAL_PREFIX_POTS  " " \
                        OPAL_PREFIX_PSTN  " " \
                        OPAL_PREFIX_IVR


typedef enum OpalMessageType {
  OpalIndCommandError,          
  OpalCmdSetGeneralParameters,  
  OpalCmdSetProtocolParameters, 
  OpalCmdRegistration,          
  OpalIndRegistration,          
  OpalCmdSetUpCall,             
  OpalIndIncomingCall,          
  OpalCmdAnswerCall,            
  OpalCmdClearCall,             
  OpalIndAlerting,              
  OpalIndEstablished,           
  OpalIndUserInput,             
  OpalIndCallCleared,           
  OpalCmdHoldCall,              
  OpalCmdRetrieveCall,          
  OpalCmdTransferCall,          
  OpalCmdUserInput,             
  OpalIndMessageWaiting,        
  OpalIndMediaStream,           
  OpalCmdMediaStream,           
  OpalCmdSetUserData,           
  OpalIndLineAppearance,        
  OpalCmdStartRecording,        
  OpalCmdStopRecording,         
  OpalIndProceeding,            
  OpalMessageTypeCount
} OpalMessageType;


typedef enum OpalSilenceDetectMode {
  OpalSilenceDetectNoChange,  
  OpalSilenceDetectDisabled,  
  OpalSilenceDetectFixed,     
  OpalSilenceDetectAdaptive   
} OpalSilenceDetectMode;


typedef enum OpalEchoCancelMode {
  OpalEchoCancelNoChange,   
  OpalEchoCancelDisabled,   
  OpalEchoCancelEnabled     
} OpalEchoCancelMode;


typedef int (*OpalMediaDataFunction)(
  const char * token,   
  const char * stream,  
  const char * format,  
  void * userData,      
  void * data,          
  int size              
);


typedef int (*OpalMessageAvailableFunction)(
  const OpalMessage * message  
);


typedef enum OpalMediaDataType {
  OpalMediaDataNoChange,      
  OpalMediaDataPayloadOnly,   
  OpalMediaDataWithHeader     
} OpalMediaDataType;


typedef struct OpalParamGeneral {
  const char * m_audioRecordDevice;   
  const char * m_audioPlayerDevice;   
  const char * m_videoInputDevice;    
  const char * m_videoOutputDevice;   
  const char * m_videoPreviewDevice;  
  const char * m_mediaOrder;          
  const char * m_mediaMask;           
  const char * m_autoRxMedia;         
  const char * m_autoTxMedia;         
  const char * m_natRouter;           
  const char * m_stunServer;          
  unsigned     m_tcpPortBase;         
  unsigned     m_tcpPortMax;          
  unsigned     m_udpPortBase;         
  unsigned     m_udpPortMax;          
  unsigned     m_rtpPortBase;         
  unsigned     m_rtpPortMax;          
  unsigned     m_rtpTypeOfService;    
  unsigned     m_rtpMaxPayloadSize;   
  unsigned     m_minAudioJitter;      
  unsigned     m_maxAudioJitter;      
  OpalSilenceDetectMode m_silenceDetectMode; 
  unsigned     m_silenceThreshold;    
  unsigned     m_signalDeadband;      
  unsigned     m_silenceDeadband;     
  unsigned     m_silenceAdaptPeriod;  
  OpalEchoCancelMode m_echoCancellation; 
  unsigned     m_audioBuffers;        
  OpalMediaDataFunction m_mediaReadData;   
  OpalMediaDataFunction m_mediaWriteData;  
  OpalMediaDataType     m_mediaDataHeader; 
  OpalMessageAvailableFunction m_messageAvailable; 
  const char * m_mediaOptions;        
} OpalParamGeneral;


typedef struct OpalProductDescription {
  const char * m_vendor;              
  const char * m_name;                
  const char * m_version;             
  unsigned     m_t35CountryCode;      
  unsigned     m_t35Extension;        
  unsigned     m_manufacturerCode;    
} OpalProductDescription;


typedef struct OpalParamProtocol {
  const char * m_prefix;              
  const char * m_userName;            
  const char * m_displayName;         
  OpalProductDescription m_product;   
  const char * m_interfaceAddresses;  
} OpalParamProtocol;


#define OPAL_MWI_EVENT_PACKAGE             "message-summary"
#define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"

typedef struct OpalParamRegistration {
  const char * m_protocol;      
  const char * m_identifier;    
  const char * m_hostName;      
  const char * m_authUserName;  
  const char * m_password;      
  const char * m_adminEntity;   
  unsigned     m_timeToLive;    
  unsigned     m_restoreTime;   
  const char * m_eventPackage;  
} OpalParamRegistration;


typedef enum OpalRegistrationStates {
  OpalRegisterSuccessful,   
  OpalRegisterRemoved,      
  OpalRegisterFailed,       
  OpalRegisterRetrying,     
  OpalRegisterRestored,     
} OpalRegistrationStates;


typedef struct OpalStatusRegistration {
  const char * m_protocol;    
  const char * m_serverName;  
  const char * m_error;       
  OpalRegistrationStates m_status; 
  OpalProductDescription m_product; 
} OpalStatusRegistration;


typedef struct OpalParamSetUpCall {
  const char * m_partyA;      
  const char * m_partyB;      
  const char * m_callToken;   
  const char * m_alertingType;
  const char * m_protocolCallId;  
} OpalParamSetUpCall;


typedef struct OpalStatusIncomingCall {
  const char * m_callToken;         
  const char * m_localAddress;      
  const char * m_remoteAddress;     
  const char * m_remotePartyNumber; 
  const char * m_remoteDisplayName; 
  const char * m_calledAddress;     
  const char * m_calledPartyNumber; 
  OpalProductDescription m_product; 
  const char * m_alertingType;
  const char * m_protocolCallId;  
} OpalStatusIncomingCall;


typedef enum OpalMediaStates {
  OpalMediaStateNoChange,   
  OpalMediaStateOpen,       
  OpalMediaStateClose,      
  OpalMediaStatePause,      
  OpalMediaStateResume      
} OpalMediaStates;


typedef struct OpalStatusMediaStream {
  const char    * m_callToken;   
  const char    * m_identifier;  
  const char    * m_type;        
  const char    * m_format;      
  OpalMediaStates m_state;       
} OpalStatusMediaStream;


typedef struct OpalParamSetUserData {
  const char    * m_callToken;   
  void *        m_userData;      
} OpalParamSetUserData;


typedef struct OpalStatusUserInput {
  const char * m_callToken;   
  const char * m_userInput;   
  unsigned     m_duration;    
} OpalStatusUserInput;


typedef struct OpalStatusMessageWaiting {
  const char * m_party;     
  const char * m_type;      
  const char * m_extraInfo; 
} OpalStatusMessageWaiting;


typedef enum OpalLineAppearanceStates {
  OpalLineTerminated,  
  OpalLineTrying,      
  OpalLineProceeding,  
  OpalLineRinging,     
  OpalLineConnected,   
  OpalLineSubcribed,   
  OpalLineUnsubcribed, 
  OpalLineIdle = OpalLineTerminated // Kept for backward compatibility
} OpalLineAppearanceStates;


typedef struct OpalStatusLineAppearance {
  const char *             m_line;       
  OpalLineAppearanceStates m_state;      
  int                      m_appearance; 
  const char *             m_callId;     
  const char *             m_partyA;     
  const char *             m_partyB;     
} OpalStatusLineAppearance;


typedef struct OpalParamRecording {
  const char * m_callToken;  
  const char * m_file;       
  unsigned     m_channels;   
} OpalParamRecording;


typedef struct OpalStatusCallCleared {
  const char * m_callToken;   
  const char * m_reason;      
} OpalStatusCallCleared;


typedef enum OpalCallEndReason {
  OpalCallEndedByLocalUser,         
  OpalCallEndedByNoAccept,          
  OpalCallEndedByAnswerDenied,      
  OpalCallEndedByRemoteUser,        
  OpalCallEndedByRefusal,           
  OpalCallEndedByNoAnswer,          
  OpalCallEndedByCallerAbort,       
  OpalCallEndedByTransportFail,     
  OpalCallEndedByConnectFail,       
  OpalCallEndedByGatekeeper,        
  OpalCallEndedByNoUser,            
  OpalCallEndedByNoBandwidth,       
  OpalCallEndedByCapabilityExchange,
  OpalCallEndedByCallForwarded,     
  OpalCallEndedBySecurityDenial,    
  OpalCallEndedByLocalBusy,         
  OpalCallEndedByLocalCongestion,   
  OpalCallEndedByRemoteBusy,        
  OpalCallEndedByRemoteCongestion,  
  OpalCallEndedByUnreachable,       
  OpalCallEndedByNoEndPoint,        
  OpalCallEndedByHostOffline,       
  OpalCallEndedByTemporaryFailure,  
  OpalCallEndedByQ931Cause,         
  OpalCallEndedByDurationLimit,     
  OpalCallEndedByInvalidConferenceID, 
  OpalCallEndedByNoDialTone,        
  OpalCallEndedByNoRingBackTone,    
  OpalCallEndedByOutOfService,      
  OpalCallEndedByAcceptingCallWaiting, 
  OpalCallEndedWithQ931Code = 0x100  
} OpalCallEndReason;


typedef struct OpalParamCallCleared {
  const char      * m_callToken;  
  OpalCallEndReason m_reason;     
} OpalParamCallCleared;


struct OpalMessage {
  OpalMessageType m_type;   
  union {
    const char *             m_commandError;       
    OpalParamGeneral         m_general;            
    OpalParamProtocol        m_protocol;           
    OpalParamRegistration    m_registrationInfo;   
    OpalStatusRegistration   m_registrationStatus; 
    OpalParamSetUpCall       m_callSetUp;          
    const char *             m_callToken;          
    OpalStatusIncomingCall   m_incomingCall;       
    OpalStatusUserInput      m_userInput;          
    OpalStatusMessageWaiting m_messageWaiting;     
    OpalStatusLineAppearance m_lineAppearance;     
    OpalStatusCallCleared    m_callCleared;        
    OpalParamCallCleared     m_clearCall;          
    OpalStatusMediaStream    m_mediaStream;        
    OpalParamSetUserData     m_setUserData;        
    OpalParamRecording       m_recording;          
  } m_param;
};


#ifdef __cplusplus
};
#endif

#endif // OPAL_OPAL_H

---