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): ______________________________________.
 */

#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 40



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

#if _WIN32
  #define OPAL_INITIALISE_FUNCTION MAKEINTRESOURCE(1)
#else
  #define OPAL_INITIALISE_FUNCTION "OpalInitialise"
#endif


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



extern void OPAL_EXPORT OpalShutDown(OpalHandle opal);

#if _WIN32
  #define OPAL_SHUTDOWN_FUNCTION MAKEINTRESOURCE(2)
#else
  #define OPAL_SHUTDOWN_FUNCTION "OpalShutDown"
#endif

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



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

#if _WIN32
  #define OPAL_GET_MESSAGE_FUNCTION MAKEINTRESOURCE(3)
#else
  #define OPAL_GET_MESSAGE_FUNCTION "OpalGetMessage"
#endif

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



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

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

#if _WIN32
  #define OPAL_SEND_MESSAGE_FUNCTION MAKEINTRESOURCE(4)
#else
  #define OPAL_SEND_MESSAGE_FUNCTION "OpalSendMessage"
#endif



extern void OPAL_EXPORT OpalFreeMessage(OpalMessage * message);

#if _WIN32
  #define OPAL_FREE_MESSAGE_FUNCTION MAKEINTRESOURCE(5)
#else
  #define OPAL_FREE_MESSAGE_FUNCTION "OpalFreeMessage"
#endif

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



#define OPAL_PREFIX_H323   "h323"   
#define OPAL_PREFIX_H323S  "h323s"  
#define OPAL_PREFIX_SIP    "sip"    
#define OPAL_PREFIX_SIPS   "sips"   
#define OPAL_PREFIX_SDP    "sdp"    
#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_CAPI   "isdn"   
#define OPAL_PREFIX_FAX    "fax"    
#define OPAL_PREFIX_T38    "t38"    
#define OPAL_PREFIX_IVR    "ivr"    
#define OPAL_PREFIX_MIXER  "mcu"    
#define OPAL_PREFIX_IM     "im"     
#define OPAL_PREFIX_GST    "gst"    
#define OPAL_PREFIX_SKINNY "sccp"   
#define OPAL_PREFIX_LYNC   "lync"   

#define OPAL_PREFIX_ALL OPAL_PREFIX_SIP    " " \
                        OPAL_PREFIX_SIPS   " " \
                        OPAL_PREFIX_H323   " " \
                        OPAL_PREFIX_H323S  " " \
                        OPAL_PREFIX_IAX2   " " \
                        OPAL_PREFIX_SDP    " " \
                        OPAL_PREFIX_SKINNY " " \
                        OPAL_PREFIX_LYNC   " " \
                        OPAL_PREFIX_PCSS   " " \
                        OPAL_PREFIX_LOCAL  " " \
                        OPAL_PREFIX_GST    " " \
                        OPAL_PREFIX_POTS   " " \
                        OPAL_PREFIX_PSTN   " " \
                        OPAL_PREFIX_FAX    " " \
                        OPAL_PREFIX_T38    " " \
                        OPAL_PREFIX_IVR    " " \
                        OPAL_PREFIX_MIXER  " " \
                        OPAL_PREFIX_IM


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,          
  OpalCmdAuthorisePresence,     
  OpalCmdSubscribePresence,     
  OpalCmdSetLocalPresence,      
  OpalIndPresenceChange,        
  OpalCmdSendIM,                
  OpalIndReceiveIM,             
  OpalIndSentIM,                
  OpalIndProtocolMessage,       
// 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,  
  OpalMediaTimingSimulated      
} 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_natMethod;           
  const char * m_natServer;           
  unsigned     m_tcpPortBase;         
  unsigned     m_tcpPortMax;          
  unsigned     m_udpPortBase;         
  unsigned     m_udpPortMax;          
  unsigned     m_rtpPortBase;         
  unsigned     m_rtpPortMax;          
  unsigned     m_rtpTypeOfService;    
  unsigned     m_rtpMaxPayloadSize;   
  int          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;      
  OpalMediaTiming m_videoSourceTiming;
  const char * m_pcssMediaOverride;   
  unsigned m_noMediaTimeout;          
  const char * m_caFiles;             
  const char * m_certificate;         
  const char * m_privateKey;          
  unsigned m_autoCreateCertificate;   
} 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;      
  const char * m_mediaCryptoSuites;   
  const char * m_allMediaCryptoSuites;
  unsigned m_maxSizeUDP;              
  const char * m_protocolMessageIdentifiers; 
} 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;  
  const char * m_attributes;    
} 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 OpalMIME
{
  const char * m_type;      
  unsigned     m_length;    
  const char * m_data;      
} OpalMIME;


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;  
  unsigned     m_extraCount; 
  const OpalMIME * m_extras; 
} 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; 
  unsigned     m_extraCount; 
  const OpalMIME * m_extras; 
  const char * m_remoteIdentity; 
  const char * m_supportedFeatures; 
} OpalStatusIncomingCall;


typedef struct OpalParamAnswerCall {
  const char * m_callToken;       
  OpalParamProtocol m_overrides;  
  unsigned m_withMedia;           
} 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;      
  const char    * m_watermark;   
} 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 OpalPresenceStates {
  OpalPresenceAuthRequest = -100, 
  OpalUnknownPresentity = -4,     
  OpalPresenceError,              
  OpalPresenceForbidden,          
  OpalPresenceNone,               
  OpalPresenceUnchanged,          
  OpalPresenceAvailable,          
  OpalPresenceUnavailable         
} OpalPresenceStates;


typedef struct OpalPresenceStatus {
  const char *       m_entity;    
  const char *       m_target;    
  const char *       m_service;   
  const char *       m_contact;   
  const char *       m_capabilities;
  OpalPresenceStates m_state;     
  const char *       m_activities;
  const char *       m_note;      
  const char *       m_infoType;  
  const char *       m_infoData;  
} OpalPresenceStatus;


typedef struct OpalInstantMessage {
  const char *  m_from;      
  const char *  m_to;        
  const char *  m_host;      
  const char *  m_conversationId; 
  const char *  m_textBody;  
  unsigned      m_bodyCount; 
  const char ** m_mimeType;  
  const char ** m_bodies;    
  unsigned      m_messageId; 
  const char *  m_htmlBody;  
  const OpalMIME * m_bodyData; 
} OpalInstantMessage;


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; 
  unsigned     m_audioBufferSize; 
} 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 OpalProtocolMessage {
  const char * m_protocol;   
  const char * m_callToken;  
  const char * m_identifier; 
  const void * m_payload;    
  unsigned     m_size;       
  unsigned     m_extraCount; 
  const OpalMIME * m_extras; 
} OpalProtocolMessage;


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,   
    OpalCallEndedByGkAdmissionFailed,      
    OpalCallEndedByMediaFailed,            
    OpalCallEndedByCallCompletedElsewhere, 
    OpalCallEndedByCertificateAuthority,   
    OpalCallEndedByIllegalAddress,         
    OpalCallEndedByCustomCode              
} OpalCallEndReason;


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


union OpalMessageParam {
  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;          
  OpalPresenceStatus       m_presenceStatus;     
  OpalInstantMessage       m_instantMessage;     
  OpalProtocolMessage      m_protocolMessage;    
};


struct OpalMessage {
  OpalMessageType m_type;   
  union OpalMessageParam m_param;   
};


#define OPALMSG_INIT(msg,type,field) (memset(&(msg), 0, sizeof(msg)),(msg).m_type=type,&(msg).m_param.field)
  
#define OPALMSG_GENERAL_PARAM(msg) OPALMSG_INIT(msg,OpalCmdSetGeneralParameters,m_general)
  
#define OPALMSG_PROTO_PARAM(msg) OPALMSG_INIT(msg,OpalCmdSetProtocolParameters,m_protocol)
  
#define OPALMSG_REGISTRATION(msg) OPALMSG_INIT(msg,OpalCmdRegistration,m_registrationInfo)
  
#define OPALMSG_SETUP_CALL(msg) OPALMSG_INIT(msg,OpalCmdSetUpCall,m_callSetUp)
  
#define OPALMSG_TRANSFER(msg) OPALMSG_INIT(msg,OpalCmdTransferCall,m_callSetUp)
  
#define OPALMSG_ANSWER_CALL(msg) OPALMSG_INIT(msg,OpalCmdAnswerCall,m_answerCall)
  
#define OPALMSG_CLEAR_CALL(msg) OPALMSG_INIT(msg,OpalCmdClearCall,m_clearCall)

#define OPALMSG_SET_USER_DATA(msg) OPALMSG_INIT(msg,OpalCmdSetUserData,m_setUserData)
  
#define OPALMSG_START_RECORDING(msg) OPALMSG_INIT(msg,OpalCmdStartRecording,m_recording)
  
  
#ifdef __cplusplus
};
#endif

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

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

    OpalMessageType GetType() const;
    OpalMessagePtr & SetType(OpalMessageType type);

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

    const char               * GetCommandError() const;       

    OpalParamGeneral         * GetGeneralParams() const;      
    OpalParamProtocol        * GetProtocolParams() const;     
    OpalParamRegistration    * GetRegistrationParams() 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;     
    OpalPresenceStatus       * GetPresenceStatus() const;     
    OpalInstantMessage       * GetInstantMessage() const;     

#ifndef SWIG
    operator OpalParamGeneral         *() const { return GetGeneralParams(); }
    operator OpalParamProtocol        *() const { return GetProtocolParams(); }
    operator OpalParamRegistration    *() const { return GetRegistrationParams(); }
    operator OpalStatusRegistration   *() const { return GetRegistrationStatus(); }
    operator OpalParamSetUpCall       *() const { return GetCallSetUp(); }
    operator OpalStatusIncomingCall   *() const { return GetIncomingCall(); }
    operator OpalParamAnswerCall      *() const { return GetAnswerCall(); }
    operator OpalStatusUserInput      *() const { return GetUserInput(); }
    operator OpalStatusMessageWaiting *() const { return GetMessageWaiting(); }
    operator OpalStatusLineAppearance *() const { return GetLineAppearance(); }
    operator OpalStatusCallCleared    *() const { return GetCallCleared(); }
    operator OpalParamCallCleared     *() const { return GetClearCall(); }
    operator OpalStatusMediaStream    *() const { return GetMediaStream(); }
    operator OpalParamSetUserData     *() const { return GetSetUserData(); }
    operator OpalParamRecording       *() const { return GetRecording(); }
    operator OpalStatusTransferCall   *() const { return GetTransferStatus(); }
    operator OpalPresenceStatus       *() const { return GetPresenceStatus(); }
    operator OpalInstantMessage       *() const { return GetInstantMessage(); }
#endif // SWIG

  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  
    );
    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   
    );

#ifndef SWIG
    // Windows API compatibility
    __inline bool GetMessageA(
      OpalMessagePtr & message,
      unsigned timeout = 0
    ) { return GetMessage(message, timeout); }
    __inline bool GetMessageW(
      OpalMessagePtr & message,
      unsigned timeout = 0
    ) { return GetMessage(message, timeout); }
    __inline bool SendMessageA(
      const OpalMessagePtr & message
    ) { return SendMessage(message); }
    __inline bool SendMessageA(
      const OpalMessagePtr & message,
      OpalMessagePtr & response
    ) { return SendMessage(message, response); }
    __inline bool SendMessageW(
      const OpalMessagePtr & message
    ) { return SendMessage(message); }
    __inline bool SendMessageW(
      const OpalMessagePtr & message,
      OpalMessagePtr & response
    ) { return SendMessage(message, response); }
#endif // SWIG

  protected:
    OpalHandle m_handle;
};

#endif // defined(__cplusplus)

#endif // OPAL_OPAL_H