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: 26939 $
 * $Author: rjongbloed $
 * $Date: 2012-02-07 01:17:49 -0600 (Tue, 07 Feb 2012) $
 */

#ifndef OPAL_OPAL_H
#define OPAL_OPAL_H

#include <stdlib.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 26



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,            
  OpalCmdAlerting,              
  OpalIndOnHold,                
  OpalIndOffHold,               
  OpalIndTransferCall,          
  OpalIndCompletedIVR,          
// Always add new messages to ethe end to maintain backward compatibility
  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 enum OpalMediaTiming {
  OpalMediaTimingNoChange,      
  OpalMediaTimingSynchronous,   
  OpalMediaTimingAsynchronous   
} OpalMediaTiming;


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;        
  unsigned     m_audioBufferTime;     
  unsigned m_manualAlerting;          
  OpalMediaTiming m_mediaTiming;      
} 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 enum OpalUserInputModes {
  OpalUserInputDefault,   
  OpalUserInputAsQ931,    
  OpalUserInputAsString,  
  OpalUserInputAsTone,    
  OpalUserInputAsRFC2833, 
  OpalUserInputInBand,    
} OpalUserInputModes;


typedef struct OpalParamProtocol {
  const char * m_prefix;              
  const char * m_userName;            
  const char * m_displayName;         
  OpalProductDescription m_product;   
  const char * m_interfaceAddresses;  
  OpalUserInputModes m_userInputMode; 
  const char * m_defaultOptions;      
} 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;  
  OpalParamProtocol m_overrides;  
} 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;  
  const char * m_referredByAddress; 
  const char * m_redirectingNumber; 
} OpalStatusIncomingCall;


typedef struct OpalParamAnswerCall {
  const char * m_callToken;       
  OpalParamProtocol m_overrides;  
} OpalParamAnswerCall;

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;       
  int             m_volume;      
} 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, OpalParamUserInput;


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 enum OpalVideoRecordMixMode {
  OpalSideBySideLetterbox, 
  OpalSideBySideScaled,    
  OpalStackedPillarbox,    
  OpalStackedScaled,       
} OpalVideoRecordMixMode;


typedef struct OpalParamRecording {
  const char * m_callToken;  
  const char * m_file;       
  unsigned     m_channels;   
  const char * m_audioFormat; 
  const char * m_videoFormat; 
  unsigned     m_videoWidth;  
  unsigned     m_videoHeight; 
  unsigned     m_videoRate;   
  OpalVideoRecordMixMode m_videoMixing; 
} OpalParamRecording;


typedef struct OpalStatusTransferCall {
  const char * m_callToken;       
  const char * m_protocolCallId;  
  const char * m_result;          
  const char * m_info;    
} OpalStatusTransferCall;


typedef struct OpalStatusIVR {
  const char * m_callToken;   
  const char * m_variables;   
} OpalStatusIVR;


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;       
    OpalParamAnswerCall      m_answerCall;         
    OpalStatusUserInput      m_userInput;          
    OpalStatusMessageWaiting m_messageWaiting;     
    OpalStatusLineAppearance m_lineAppearance;     
    OpalStatusCallCleared    m_callCleared;        
    OpalParamCallCleared     m_clearCall;          
    OpalStatusMediaStream    m_mediaStream;        
    OpalParamSetUserData     m_setUserData;        
    OpalParamRecording       m_recording;          
    OpalStatusTransferCall   m_transferStatus;     
    OpalStatusIVR            m_ivrStatus;          
  } m_param;
};


#ifdef __cplusplus
};
#endif

#if defined(__cplusplus) || defined(DOC_PLUS_PLUS)

class OpalMessagePtr
{
  public:
    OpalMessagePtr(OpalMessageType type = OpalIndCommandError);
    ~OpalMessagePtr();

    OpalMessageType GetType() const;
    void SetType(OpalMessageType type);

    const char               * GetCallToken() const;          
    void                       SetCallToken(const char * token);

    const char               * GetCommandError() const;       

    OpalParamGeneral         * GetGeneralParams() const;      
    OpalParamProtocol        * GetProtocolParams() const;     
    OpalParamRegistration    * GetRegistrationInfo() const;   
    OpalStatusRegistration   * GetRegistrationStatus() const; 
    OpalParamSetUpCall       * GetCallSetUp() const;          
    OpalStatusIncomingCall   * GetIncomingCall() const;       
    OpalParamAnswerCall      * GetAnswerCall() const;         
    OpalStatusUserInput      * GetUserInput() const;          
    OpalStatusMessageWaiting * GetMessageWaiting() const;     
    OpalStatusLineAppearance * GetLineAppearance() const;     
    OpalStatusCallCleared    * GetCallCleared() const;        
    OpalParamCallCleared     * GetClearCall() const;          
    OpalStatusMediaStream    * GetMediaStream() const;        
    OpalParamSetUserData     * GetSetUserData() const;        
    OpalParamRecording       * GetRecording() const;          
    OpalStatusTransferCall   * GetTransferStatus() const;     

  protected:
    OpalMessage * m_message;

  private:
    OpalMessagePtr(const OpalMessagePtr &) { }
    void operator=(const OpalMessagePtr &) { }

  friend class OpalContext;
};


#ifdef GetMessage
#undef GetMessage
#endif
#ifdef SendMessage
#undef SendMessage
#endif


class OpalContext
{
  public:
    OpalContext();

    virtual ~OpalContext();

    unsigned Initialise(
      const char * options,  
      unsigned version = OPAL_C_API_VERSION 
    );

    bool IsInitialised() const { return m_handle != NULL; }

    void ShutDown();

    bool GetMessage(
      OpalMessagePtr & message,
      unsigned timeout = 0
    );

    bool SendMessage(
      const OpalMessagePtr & message,  
      OpalMessagePtr & response        
    );


    bool SetUpCall(
      OpalMessagePtr & response,       
      const char * partyB,             
      const char * partyA = NULL,      
      const char * alertingType = NULL 
    );

    bool AnswerCall(
      const char * callToken           
    );

    bool ClearCall(
      const char * callToken,          
      OpalCallEndReason reason = OpalCallEndedByLocalUser  
    );

    bool SendUserInput(
      const char * callToken,     
      const char * userInput,     
      unsigned     duration = 0   
    );

  protected:
    OpalHandle m_handle;
};

#endif

#endif // OPAL_OPAL_H