d9/deb/opal_8h_source.html

/*

 * 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: 29938 $

 * $Author: rjongbloed $

 * $Date: 2013-06-13 12:19:41 +1000 (Thu, 13 Jun 2013) $

 */


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


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_FAX   "fax"

#define OPAL_PREFIX_T38   "t38"

#define OPAL_PREFIX_IVR   "ivr"

#define OPAL_PREFIX_IM    "im"


#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_FAX  " " \

                        OPAL_PREFIX_T38  " " \

                        OPAL_PREFIX_IVR  " " \

                        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,

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

  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;

  OpalMediaTiming m_videoSourceTiming;

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

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

  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;

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

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

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

    OpalPresenceStatus       m_presenceStatus;

    OpalInstantMessage       m_instantMessage;


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

    OpalPresenceStatus       * GetPresenceStatus() const;

    OpalInstantMessage       * GetInstantMessage() 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