This file contains a simplified API to the OPAL system. It provides a pure "C" language interface as will as a very simple C++ class and a contrained set of functions for "late binding". More...

#include <stdlib.h>

Include dependency graph for opal.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Data Structures
struct	OpalParamGeneral

struct	OpalProductDescription

struct	OpalParamProtocol

struct	OpalParamRegistration

struct	OpalStatusRegistration

struct	OpalMIME

struct	OpalParamSetUpCall

struct	OpalStatusIncomingCall

struct	OpalParamAnswerCall

struct	OpalStatusMediaStream

struct	OpalParamSetUserData

struct	OpalParamUserInput

struct	OpalStatusMessageWaiting

struct	OpalStatusLineAppearance

struct	OpalPresenceStatus

struct	OpalInstantMessage

struct	OpalParamRecording

struct	OpalStatusTransferCall

struct	OpalStatusIVR

struct	OpalProtocolMessage

struct	OpalStatusCallCleared

struct	OpalParamCallCleared

union	OpalMessageParam

struct	OpalMessage

class	OpalMessagePtr
	Wrapper around the OpalMessage structure. More...

class	OpalContext

Macros
#define	OPAL_EXPORT

#define	OPAL_C_API_VERSION 40
	Current API version. More...

#define	OPAL_INITIALISE_FUNCTION "OpalInitialise"

#define	OPAL_SHUTDOWN_FUNCTION "OpalShutDown"

#define	OPAL_GET_MESSAGE_FUNCTION "OpalGetMessage"

#define	OPAL_SEND_MESSAGE_FUNCTION "OpalSendMessage"

#define	OPAL_FREE_MESSAGE_FUNCTION "OpalFreeMessage"

#define	OPAL_PREFIX_H323 "h323"
	H.323 Protocol supported string for OpalInitialise() More...

#define	OPAL_PREFIX_H323S "h323s"
	Secure H.323 Protocol supported string for OpalInitialise() More...

#define	OPAL_PREFIX_SIP "sip"
	SIP Protocol supported string for OpalInitialise() More...

#define	OPAL_PREFIX_SIPS "sips"
	Secure SIP Protocol supported string for OpalInitialise() More...

#define	OPAL_PREFIX_SDP "sdp"
	SDP over HTTP (e.g. for WebRTC) supported string for OpalInitialise() More...

#define	OPAL_PREFIX_IAX2 "iax2"
	IAX2 Protocol supported string for OpalInitialise() More...

#define	OPAL_PREFIX_PCSS "pc"
	PC sound system supported string for OpalInitialise() More...

#define	OPAL_PREFIX_LOCAL "local"
	Local endpoint supported string for OpalInitialise() More...

#define	OPAL_PREFIX_POTS "pots"
	Plain Old Telephone System supported string for OpalInitialise() More...

#define	OPAL_PREFIX_PSTN "pstn"
	Public Switched Network supported string for OpalInitialise() More...

#define	OPAL_PREFIX_CAPI "isdn"
	ISDN (via CAPI) string for OpalInitialise() More...

#define	OPAL_PREFIX_FAX "fax"
	G.711 fax supported string for OpalInitialise() More...

#define	OPAL_PREFIX_T38 "t38"
	G.711 fax supported string for OpalInitialise() More...

#define	OPAL_PREFIX_IVR "ivr"
	Interactive Voice Response supported string for OpalInitialise() More...

#define	OPAL_PREFIX_MIXER "mcu"
	Mixer for conferencing. More...

#define	OPAL_PREFIX_IM "im"
	Interactive Voice Response supported string for OpalInitialise() More...

#define	OPAL_PREFIX_GST "gst"
	GStreamer supported string for OpalInitialise() More...

#define	OPAL_PREFIX_SKINNY "sccp"
	Cisco Skinny Client Control Protocol supported string for OpalInitialise() More...

#define	OPAL_PREFIX_LYNC "lync"
	Microsoft Lync (UCMA) supported string for OpalInitialise() More...

#define	OPAL_PREFIX_ALL

#define	OPAL_MWI_EVENT_PACKAGE "message-summary"
	Name of SIP event package for Message Waiting events. More...

#define	OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"
	Name of SIP even package fo rmonitoring call status. More...

#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)
	Initialise an OpalMessage for OpalCmdSetGeneralParameters, returns OpalParamGeneral*. More...

#define	OPALMSG_PROTO_PARAM(msg) OPALMSG_INIT(msg,OpalCmdSetProtocolParameters,m_protocol)
	Initialise an OpalMessage for OpalCmdSetProtocolParameters, returns OpalParamProtocol*. More...

#define	OPALMSG_REGISTRATION(msg) OPALMSG_INIT(msg,OpalCmdRegistration,m_registrationInfo)
	Initialise an OpalMessage for OpalCmdRegistration, returns OpalParamRegistration*. More...

#define	OPALMSG_SETUP_CALL(msg) OPALMSG_INIT(msg,OpalCmdSetUpCall,m_callSetUp)
	Initialise an OpalMessage for OpalCmdSetUpCall, returns OpalParamSetUpCall*. More...

#define	OPALMSG_TRANSFER(msg) OPALMSG_INIT(msg,OpalCmdTransferCall,m_callSetUp)
	Initialise an OpalMessage for OpalCmdTransferCall, returns OpalParamSetUpCall*. More...

#define	OPALMSG_ANSWER_CALL(msg) OPALMSG_INIT(msg,OpalCmdAnswerCall,m_answerCall)
	Initialise an OpalMessage for OpalCmdAnswerCall, returns OpalParamAnswerCall*. More...

#define	OPALMSG_CLEAR_CALL(msg) OPALMSG_INIT(msg,OpalCmdClearCall,m_clearCall)
	Initialise an OpalMessage for OpalCmdClearCall, returns OpalParamCallCleared*. More...

#define	OPALMSG_SET_USER_DATA(msg) OPALMSG_INIT(msg,OpalCmdSetUserData,m_setUserData)
	Initialise an OpalMessage for OpalCmdSetUserData, returns OpalParamSetUserData*. More...

#define	OPALMSG_START_RECORDING(msg) OPALMSG_INIT(msg,OpalCmdStartRecording,m_recording)
	Initialise an OpalMessage for OpalCmdStartRecording, returns OpalParamRecording*. More...

Typedefs
typedef struct OpalHandleStruct *	OpalHandle
	Handle to initialised OPAL instance. More...

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

typedef void(OPAL_EXPORT *	OpalShutDownFunction )(OpalHandle opal)

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

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

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

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

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

Enumerations
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, OpalMessageTypeCount }

enum	OpalSilenceDetectMode { OpalSilenceDetectNoChange, OpalSilenceDetectDisabled, OpalSilenceDetectFixed, OpalSilenceDetectAdaptive }

enum	OpalEchoCancelMode { OpalEchoCancelNoChange, OpalEchoCancelDisabled, OpalEchoCancelEnabled }

enum	OpalMediaDataType { OpalMediaDataNoChange, OpalMediaDataPayloadOnly, OpalMediaDataWithHeader }

enum	OpalMediaTiming { OpalMediaTimingNoChange, OpalMediaTimingSynchronous, OpalMediaTimingAsynchronous, OpalMediaTimingSimulated }

enum	OpalUserInputModes { OpalUserInputDefault, OpalUserInputAsQ931, OpalUserInputAsString, OpalUserInputAsTone, OpalUserInputAsRFC2833, OpalUserInputInBand }

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

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

enum	OpalLineAppearanceStates { OpalLineTerminated, OpalLineTrying, OpalLineProceeding, OpalLineRinging, OpalLineConnected, OpalLineSubcribed, OpalLineUnsubcribed, OpalLineIdle = OpalLineTerminated }

enum	OpalPresenceStates { OpalPresenceAuthRequest = -100, OpalUnknownPresentity = -4, OpalPresenceError, OpalPresenceForbidden, OpalPresenceNone, OpalPresenceUnchanged, OpalPresenceAvailable, OpalPresenceUnavailable }

enum	OpalVideoRecordMixMode { OpalSideBySideLetterbox, OpalSideBySideScaled, OpalStackedPillarbox, OpalStackedScaled }

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 }

Functions
OpalHandle OPAL_EXPORT	OpalInitialise (unsigned version, const char options)

void OPAL_EXPORT	OpalShutDown (OpalHandle opal)

OpalMessage *OPAL_EXPORT	OpalGetMessage (OpalHandle opal, unsigned timeout)

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

void OPAL_EXPORT	OpalFreeMessage (OpalMessage *message)

Detailed Description

This file contains a simplified API to the OPAL system. It provides a pure "C" language interface as will as a very simple C++ class and a contrained set of functions for "late binding".

It should be noted that the simplified API, is sill not very simple. There are complexities invoved that cannot be avoided. However, this API does remove some issues with the full API such as multi-threading and advanced C++ concepts.

The other major feature of this API is the ability to be easily "late bound" using Windows LoadLibrary() or Unix dlopen() at run time. You may look at the sample code in opal/samples/c_api/main.c for an example of how to do late binding.

Late binding also allows for easier integration of OPAL fucntionality to interpreted languages such as Java, Perl etc. Systems like "swig" may be used to produce interface files for such languages.

To make the above easier, there are only four functions: OpalInitialise(), OpalShutDown(), OpalGetMessage() and OpalSendMessage(). All commands to OPAL and indications back from OPAL are done through the latter two functions.

This API also provides a basic C++ class OpalContext, which may be used for C++ programmers that do not wish to learn the large number of classes in the full API. At the cost of minimal extensibility and control.

Macro Definition Documentation

#define OPAL_C_API_VERSION 40

Current API version.

#define OPAL_EXPORT

#define OPAL_FREE_MESSAGE_FUNCTION "OpalFreeMessage"

String representation of the OpalFreeMessage() which may be used for late binding to the library.

#define OPAL_GET_MESSAGE_FUNCTION "OpalGetMessage"

String representation of the OpalGetMessage() which may be used for late binding to the library.

#define OPAL_INITIALISE_FUNCTION "OpalInitialise"

String representation of the OpalIntialise() which may be used for late binding to the library.

#define OPAL_LINE_APPEARANCE_EVENT_PACKAGE "dialog;sla;ma"

Name of SIP even package fo rmonitoring call status.

#define OPAL_MWI_EVENT_PACKAGE "message-summary"

Name of SIP event package for Message Waiting events.

#define OPAL_PREFIX_ALL

Value:

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

#define OPAL_PREFIX_CAPI "isdn"

ISDN (via CAPI) string for OpalInitialise()

#define OPAL_PREFIX_FAX "fax"

G.711 fax supported string for OpalInitialise()

#define OPAL_PREFIX_GST "gst"

GStreamer supported string for OpalInitialise()

#define OPAL_PREFIX_H323 "h323"

H.323 Protocol supported string for OpalInitialise()

#define OPAL_PREFIX_H323S "h323s"

Secure H.323 Protocol supported string for OpalInitialise()

#define OPAL_PREFIX_IAX2 "iax2"

IAX2 Protocol supported string for OpalInitialise()

#define OPAL_PREFIX_IM "im"

Interactive Voice Response supported string for OpalInitialise()

#define OPAL_PREFIX_IVR "ivr"

Interactive Voice Response supported string for OpalInitialise()

#define OPAL_PREFIX_LOCAL "local"

Local endpoint supported string for OpalInitialise()

#define OPAL_PREFIX_LYNC "lync"

Microsoft Lync (UCMA) supported string for OpalInitialise()

#define OPAL_PREFIX_MIXER "mcu"

Mixer for conferencing.

#define OPAL_PREFIX_PCSS "pc"

PC sound system supported string for OpalInitialise()

#define OPAL_PREFIX_POTS "pots"

Plain Old Telephone System supported string for OpalInitialise()

#define OPAL_PREFIX_PSTN "pstn"

Public Switched Network supported string for OpalInitialise()

#define OPAL_PREFIX_SDP "sdp"

SDP over HTTP (e.g. for WebRTC) supported string for OpalInitialise()

#define OPAL_PREFIX_SIP "sip"

SIP Protocol supported string for OpalInitialise()

#define OPAL_PREFIX_SIPS "sips"

Secure SIP Protocol supported string for OpalInitialise()

#define OPAL_PREFIX_SKINNY "sccp"

Cisco Skinny Client Control Protocol supported string for OpalInitialise()

#define OPAL_PREFIX_T38 "t38"

G.711 fax supported string for OpalInitialise()

#define OPAL_SEND_MESSAGE_FUNCTION "OpalSendMessage"

Typedef representation of the pointer to the OpalSendMessage() function which may be used for late binding to the library.

#define OPAL_SHUTDOWN_FUNCTION "OpalShutDown"

String representation of the OpalShutDown() which may be used for late binding to the library.

#define OPALMSG_ANSWER_CALL ( msg ) OPALMSG_INIT(msg,OpalCmdAnswerCall,m_answerCall)

Initialise an OpalMessage for OpalCmdAnswerCall, returns OpalParamAnswerCall*.

#define OPALMSG_CLEAR_CALL ( msg ) OPALMSG_INIT(msg,OpalCmdClearCall,m_clearCall)

Initialise an OpalMessage for OpalCmdClearCall, returns OpalParamCallCleared*.

#define OPALMSG_GENERAL_PARAM ( msg ) OPALMSG_INIT(msg,OpalCmdSetGeneralParameters,m_general)

Initialise an OpalMessage for OpalCmdSetGeneralParameters, returns OpalParamGeneral*.

#define OPALMSG_INIT	(	msg,
		type,
		field
	)	(memset(&(msg), 0, sizeof(msg)),(msg).m_type=type,&(msg).m_param.field)

#define OPALMSG_PROTO_PARAM ( msg ) OPALMSG_INIT(msg,OpalCmdSetProtocolParameters,m_protocol)

Initialise an OpalMessage for OpalCmdSetProtocolParameters, returns OpalParamProtocol*.

#define OPALMSG_REGISTRATION ( msg ) OPALMSG_INIT(msg,OpalCmdRegistration,m_registrationInfo)

Initialise an OpalMessage for OpalCmdRegistration, returns OpalParamRegistration*.

#define OPALMSG_SET_USER_DATA ( msg ) OPALMSG_INIT(msg,OpalCmdSetUserData,m_setUserData)

Initialise an OpalMessage for OpalCmdSetUserData, returns OpalParamSetUserData*.

#define OPALMSG_SETUP_CALL ( msg ) OPALMSG_INIT(msg,OpalCmdSetUpCall,m_callSetUp)

Initialise an OpalMessage for OpalCmdSetUpCall, returns OpalParamSetUpCall*.

#define OPALMSG_START_RECORDING ( msg ) OPALMSG_INIT(msg,OpalCmdStartRecording,m_recording)

Initialise an OpalMessage for OpalCmdStartRecording, returns OpalParamRecording*.

#define OPALMSG_TRANSFER ( msg ) OPALMSG_INIT(msg,OpalCmdTransferCall,m_callSetUp)

Initialise an OpalMessage for OpalCmdTransferCall, returns OpalParamSetUpCall*.

Typedef Documentation

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

Typedef representation of the pointer to the OpalFreeMessage() function which may be used for late binding to the library.

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

Typedef representation of the pointer to the OpalGetMessage() function which may be used for late binding to the library.

typedef struct OpalHandleStruct* OpalHandle

Handle to initialised OPAL instance.

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

Typedef representation of the pointer to the OpalIntialise() function which may be used for late binding to the library.

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

Function for reading/writing media data. The m_mediaReadData and m_mediaWriteData memebers of OpalParamGeneral are the mechanism by which an application can be sent the raw media for a call.

This requires the inclusion of the OPAL_PREFIX_LOCAL ("local") or OPAL_PREFIX_PCSS ("pc") in the OpalInitialise() call. If the latter is used the m_pcssMediaOverride in OpalParamGeneral must also be set for the specific media you wish th callback to apply to. For the local endpoint all media is sent to the callback.

Note that incoming calls are sent to the local endpoints in order they are specified in OpalInitialise, so make sure OPAL_PREFIX_LOCAL is the first, or only entry, in the list to OpalInitialise() for it to be selected as the default is for OPAL_PREFIX_PCSS to be used.

The "write" function, which is taking data from a remote and providing it to the "C" application for writing, should not be assumed to have a one to one correspondence with RTP packets. The OPAL jiter buffer may insert "silence" data for missing or too late packets. In this case the function is called with the size parameter equal to zero. It is up to the application what it does in that circumstance.

if format is "YUV420P" then data will point to four 32 bit integers being the x, y, width and height of the image, following by the YUV planar pixel data.

Note that this function will be called in the context of different threads so the user must take care of any mutex and synchonisation issues.

Returns size of data actually read or written, or -1 if there is an error and the media stream should be shut down.

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

Function called when a message event becomes available. This function is called before the message is queued for the GetMessage() function.

A return value of zero indicates that the message is not to be passed on to the GetMessage(). A non-zero value will pass the message on.

Note that this function will be called in the context of different threads so the user must take care of any mutex and synchonisation issues. If the user subsequently uses the GetMessage() then the message will have been serialised so that there are no multi-threading issues.

A simple use case would be for this function to send a signal or message to the applications main thread and then return a non-zero value. The main thread would then wake up and get the message using GetMessage.

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

String representation of the OpalSendMessage() which may be used for late binding to the library.

typedef void(OPAL_EXPORT * OpalShutDownFunction)(OpalHandle opal)

Typedef representation of the pointer to the OpalShutDown() function which may be used for late binding to the library.

Enumeration Type Documentation

enum OpalCallEndReason

Type code for the reasons a call was ended.

Enumerator
OpalCallEndedByLocalUser	Local endpoint application cleared call.
OpalCallEndedByNoAccept	Local endpoint did not accept call OnIncomingCall()=false.
OpalCallEndedByAnswerDenied	Local endpoint declined to answer call.
OpalCallEndedByRemoteUser	Remote endpoint application cleared call.
OpalCallEndedByRefusal	Remote endpoint refused call.
OpalCallEndedByNoAnswer	Remote endpoint did not answer in required time.
OpalCallEndedByCallerAbort	Remote endpoint stopped calling.
OpalCallEndedByTransportFail	Transport error cleared call.
OpalCallEndedByConnectFail	Transport connection failed to establish call.
OpalCallEndedByGatekeeper	Gatekeeper has cleared call.
OpalCallEndedByNoUser	Call failed as could not find user (in GK)
OpalCallEndedByNoBandwidth	Call failed as could not get enough bandwidth.
OpalCallEndedByCapabilityExchange	Could not find common capabilities.
OpalCallEndedByCallForwarded	Call was forwarded using FACILITY message.
OpalCallEndedBySecurityDenial	Call failed a security check and was ended.
OpalCallEndedByLocalBusy	Local endpoint busy.
OpalCallEndedByLocalCongestion	Local endpoint congested.
OpalCallEndedByRemoteBusy	Remote endpoint busy.
OpalCallEndedByRemoteCongestion	Remote endpoint congested.
OpalCallEndedByUnreachable	Could not reach the remote party.
OpalCallEndedByNoEndPoint	The remote party is not running an endpoint.
OpalCallEndedByHostOffline	The remote party host off line.
OpalCallEndedByTemporaryFailure	The remote failed temporarily app may retry.
OpalCallEndedByQ931Cause	The remote ended the call with Q.931 cause code in MS byte.
OpalCallEndedByDurationLimit	Call cleared due to an enforced duration limit.
OpalCallEndedByInvalidConferenceID	Call cleared due to invalid conference ID.
OpalCallEndedByNoDialTone	Call cleared due to missing dial tone.
OpalCallEndedByNoRingBackTone	Call cleared due to missing ringback tone.
OpalCallEndedByOutOfService	Call cleared because the line is out of service,.
OpalCallEndedByAcceptingCallWaiting	Call cleared because another call is answered.
OpalCallEndedByGkAdmissionFailed	Call cleared because gatekeeper admission request failed.
OpalCallEndedByMediaFailed	Call cleared due to loss of media flow.
OpalCallEndedByCallCompletedElsewhere	Call cleared because it was answered by another extension.
OpalCallEndedByCertificateAuthority	When using TLS, the remote certifcate was not authenticated.
OpalCallEndedByIllegalAddress	Destination Address format was incorrect format.
OpalCallEndedByCustomCode	End call with custom protocol specific code (e.g. SIP)

enum OpalEchoCancelMode

Type code the echo cancellation algorithm modes. This is used by the OpalCmdSetGeneralParameters command in the OpalParamGeneral structure.

Enumerator
OpalEchoCancelNoChange	No change to the echo cancellation mode.
OpalEchoCancelDisabled	Indicate the echo cancellation is disabled
OpalEchoCancelEnabled	Indicate the echo cancellation is enabled

enum OpalLineAppearanceStates

Type code for media stream status/control. This is used by the OpalIndMediaStream indication and OpalCmdMediaStream command in the OpalStatusMediaStream structure.

Enumerator
OpalLineTerminated	Line has ended a call.
OpalLineTrying	Line has been siezed.
OpalLineProceeding	Line is trying to make a call.
OpalLineRinging	Line is ringing.
OpalLineConnected	Line is connected.
OpalLineSubcribed	Line appearance subscription successful.
OpalLineUnsubcribed	Line appearance unsubscription successful.
OpalLineIdle

enum OpalMediaDataType

Type code the media data call back functions data type. This is used by the OpalCmdSetGeneralParameters command in the OpalParamGeneral structure.

This controls if the whole RTP data frame or just the paylaod part is passed to the read/write function.

Default is OpalMediaDataPayloadOnly.

Enumerator
OpalMediaDataNoChange	No change to the media data type.
OpalMediaDataPayloadOnly	Indicate only the RTP payload is passed to the read/write function
OpalMediaDataWithHeader	Indicate the whole RTP frame including header is passed to the read/write function

enum OpalMediaStates

Type code for media stream status/control. This is used by the OpalIndMediaStream indication and OpalCmdMediaStream command in the OpalStatusMediaStream structure.

Enumerator
OpalMediaStateNoChange	No change to the media stream state.
OpalMediaStateOpen	Media stream has been opened when indication, or is to be opened when a command.
OpalMediaStateClose	Media stream has been closed when indication, or is to be closed when a command.
OpalMediaStatePause	Media stream has been paused when indication, or is to be paused when a command.
OpalMediaStateResume	Media stream has been paused when indication, or is to be paused when a command.

enum OpalMediaTiming

Timing mode for the media data call back functions data type. This is used by the OpalCmdSetGeneralParameters command in the OpalParamGeneral structure.

This controls if the read/write function is in control of the real time aspects of the media flow. If synchronous then the read/write function is expected to handle the real time "pacing" of the read or written data.

Note this is important both for reads and writes. For example in synchronous mode you cannot simply read from a file and send, or you will likely overrun the remotes buffers. Similarly for writing to a file, the correct operation of the OPAL jitter buffer is dependent on it not being drained too fast by the "write" function.

If marked as asynchroous then the OPAL stack itself will take care of the timing and things like read/write to a disk file will work correctly.

Enumerator
OpalMediaTimingNoChange	No change to the media data type.
OpalMediaTimingSynchronous	Indicate the read/write function is going to handle all real time aspects of the media flow.
OpalMediaTimingAsynchronous	Indicate the read/write function does not require real time aspects of the media flow.
OpalMediaTimingSimulated	Indicate the read/write function does not handle the real time aspects of the media flow and they must be simulated by the OPAL library.

enum OpalMessageType

Type code for messages defined by OpalMessage.

Enumerator
OpalIndCommandError	An error occurred during a command. This is only returned by OpalSendMessage(). The details of the error are shown in the OpalMessage::m_commandError field.
OpalCmdSetGeneralParameters	Set general parameters command. This configures global settings in OPAL. See the OpalParamGeneral structure for more information.
OpalCmdSetProtocolParameters	Set protocol parameters command. This configures settings in OPAL that may be different for each protocol, e.g. SIP & H.323. See the OpalParamProtocol structure for more information.
OpalCmdRegistration	Register/Unregister command. This initiates a registration or unregistration operation with a protocol dependent server. Currently only for H.323 and SIP. See the OpalParamRegistration structure for more information.
OpalIndRegistration	Status of registration indication. After the OpalCmdRegistration has initiated a registration, this indication will be returned by the OpalGetMessage() function when the status of the registration changes, e.g. successful registration or communications failure etc. See the OpalStatusRegistration structure for more information.
OpalCmdSetUpCall	Set up a call command. This starts the outgoing call process. The OpalIndAlerting, OpalIndEstablished and OpalIndCallCleared messages are returned by OpalGetMessage() to indicate the call progress. See the OpalParamSetUpCall structure for more information.
OpalIndIncomingCall	Incoming call indication. This is returned by the OpalGetMessage() function at any time after listeners are set up via the OpalCmdSetProtocolParameters command. See the OpalStatusIncomingCall structure for more information.
OpalCmdAnswerCall	Answer call command. After a OpalIndIncomingCall is returned by the OpalGetMessage() function, an application maye indicate that the call is to be answered with this message. The OpalMessage m_callToken field is set to the token returned in OpalIndIncomingCall.
OpalCmdClearCall	Hang Up call command. After a OpalCmdSetUpCall command is executed or a OpalIndIncomingCall indication is received then this may be used to "hang up" the call. The OpalIndCallCleared is subsequently returned in the OpalGetMessage() when the call has completed its hang up operation. See OpalParamCallCleared structure for more information.
OpalIndAlerting	Remote is alerting indication. This message is returned in the OpalGetMessage() function when the underlying protocol states the remote telephone is "ringing". See the OpalParamSetUpCall structure for more information.
OpalIndEstablished	Call is established indication. This message is returned in the OpalGetMessage() function when the remote or local endpont has "answered" the call and there is media flowing. See the OpalParamSetUpCall structure for more information.
OpalIndUserInput	User input indication. This message is returned in the OpalGetMessage() function when, during a call, user indications (aka DTMF tones) are received. See the OpalStatusUserInput structure for more information.
OpalIndCallCleared	Call is cleared indication. This message is returned in the OpalGetMessage() function when the call has completed. The OpalMessage m_callToken field indicates which call cleared.
OpalCmdHoldCall	Place call in a hold state. The OpalMessage m_callToken field is set to the token returned in OpalIndIncomingCall.
OpalCmdRetrieveCall	Retrieve call from hold state. The OpalMessage m_callToken field is set to the token for the call.
OpalCmdTransferCall	Transfer a call to another party. This starts the outgoing call process for the other party. See the OpalParamSetUpCall structure for more information.
OpalCmdUserInput	User input command. This sends specified user input to the remote connection. See the OpalStatusUserInput structure for more information.
OpalIndMessageWaiting	Message Waiting indication. This message is returned in the OpalGetMessage() function when an MWI is received on any of the supported protocols.
OpalIndMediaStream	A media stream has started/stopped. This message is returned in the OpalGetMessage() function when a media stream is started or stopped. See the OpalStatusMediaStream structure for more information.
OpalCmdMediaStream	Execute control on a media stream. See the OpalStatusMediaStream structure for more information.
OpalCmdSetUserData	Set the user data field associated with a call
OpalIndLineAppearance	Line Appearance indication. This message is returned in the OpalGetMessage() function when any of the supported protocols indicate that the state of a "line" has changed, e.g. free, busy, on hold etc.
OpalCmdStartRecording	Start recording an active call. See the OpalParamRecording structure for more information.
OpalCmdStopRecording	Stop recording an active call. Only the m_callToken field of the OpalMessage union is used.
OpalIndProceeding	Call has been accepted by remote. This message is returned in the OpalGetMessage() function when the underlying protocol states the remote endpoint acknowledged that it will route the call. This is distinct from OpalIndAlerting in that it is not known at this time if anything is ringing. This indication may be used to distinguish between "transport" level error, in which case another host may be tried, and that the responsibility for finalising the call has moved "upstream". See the OpalParamSetUpCall structure for more information.
OpalCmdAlerting	Send an indication to the remote that we are "ringing". The OpalMessage m_callToken field indicates which call is alerting.
OpalIndOnHold	Indicate a call has been placed on hold by remote. This message is returned in the OpalGetMessage() function.
OpalIndOffHold	Indicate a call has been retrieved from hold by remote. This message is returned in the OpalGetMessage() function.
OpalIndTransferCall	Status of transfer operation that is under way. This message is returned in the OpalGetMessage() function. See the OpalStatusTransferCall structure for more information.
OpalIndCompletedIVR	Indicates completion of the IVR (VXML) script. This message is returned in the OpalGetMessage() function. See the OpalStatusIVR structure for more information.
OpalCmdAuthorisePresence	Permit or deny authority for the remote presentity to view the presence state of a local presentity. See the OpalPresenceStatus structure for more information.
OpalCmdSubscribePresence	Subscribe to the change in presence state for a presentity. See the OpalPresenceStatus structure for more information.
OpalCmdSetLocalPresence	Set, and publish, the local presence state. See the OpalPresenceStatus structure for more information.
OpalIndPresenceChange	Indicates a change the the presence state for a given presentity. This message is returned in the OpalGetMessage() function. See the OpalPresenceStatus structure for more information.
OpalCmdSendIM	Send an Instant Message. See the OpalInstantMessage structure for more information.
OpalIndReceiveIM	Indicates receipt of an instant message. This message is returned in the OpalGetMessage() function. See the OpalInstantMessage structure for more information.
OpalIndSentIM	Get indication of the disposition of a sent instant message. This message is returned in the OpalGetMessage() function. See the OpalInstantMessage structure for more information.
OpalIndProtocolMessage	Get indication of protocol specific messages. See the OpalProtocolMessage structure for more information.
OpalMessageTypeCount

enum OpalPresenceStates

Type code for presence states. This is used by the OpalPresenceStatus structure.

Enumerator
OpalPresenceAuthRequest	Authorisation to view a users state is required.
OpalUnknownPresentity	Presentity does not exist.
OpalPresenceError	Something bad happened.
OpalPresenceForbidden	Access to presence information was specifically forbidden.
OpalPresenceNone	No presence status - not the same as Unavailable or Away.
OpalPresenceUnchanged	State has not changed from last time.
OpalPresenceAvailable	User has a presence and is available to be contacted.
OpalPresenceUnavailable	User has a presence, but is cannot be contacted.

enum OpalRegistrationStates

Type code for media stream status/control. This is used by the OpalIndRegistration indication in the OpalStatusRegistration structure.

Enumerator
OpalRegisterSuccessful	Successfully registered.
OpalRegisterRemoved	Successfully unregistered. Note that the m_error field may be non-null if an error occurred during unregistration, however the unregistration will "complete" as far as the local endpoint is concerned and no more registration retries are made.
OpalRegisterFailed	Registration has failed. The m_error field of the OpalStatusRegistration structure will contain more details.
OpalRegisterRetrying	Registrar/Gatekeeper has gone offline and a failed retry has been executed.
OpalRegisterRestored	Registration has been restored after a succesfull retry.

enum OpalSilenceDetectMode

Type code the silence detect algorithm modes. This is used by the OpalCmdSetGeneralParameters command in the OpalParamGeneral structure.

Enumerator
OpalSilenceDetectNoChange	No change to the silence detect mode.
OpalSilenceDetectDisabled	Indicate silence detect is disabled
OpalSilenceDetectFixed	Indicate silence detect uses a fixed threshold
OpalSilenceDetectAdaptive	Indicate silence detect uses an adaptive threashold

enum OpalUserInputModes

Type code for controlling the mode in which user input (DTMF) is sent. This is used by the OpalCmdSetProtocolParameters command in the OpalParamProtocol structure.

Enumerator
OpalUserInputDefault	Default mode for protocol.
OpalUserInputAsQ931	Use Q.931 Information Elements (H.323 only)
OpalUserInputAsString	Use arbitrary strings (H.245 string, or INFO dtmf)
OpalUserInputAsTone	Use DTMF specific names (H.245 signal, or INFO dtmf-relay)
OpalUserInputAsRFC2833	Use RFC 2833 for DTMF only.
OpalUserInputInBand	Use in-band generated audio tones for DTMF.

enum OpalVideoRecordMixMode

Type of mixing for video when recording. This is used by the OpalCmdStartRecording command in the OpalParamRecording structure.

Enumerator
OpalSideBySideLetterbox	Two images side by side with black bars top and bottom. It is expected that the input frames and output are all the same aspect ratio, e.g. 4:3. Works well if inputs are QCIF and output is CIF for example.
OpalSideBySideScaled	Two images side by side, scaled to fit halves of output frame. It is expected that the output frame be double the width of the input data to maintain aspect ratio. e.g. for CIF inputs, output would be 704x288.
OpalStackedPillarbox	Two images, one on top of the other with black bars down the sides. It is expected that the input frames and output are all the same aspect ratio, e.g. 4:3. Works well if inputs are QCIF and output is CIF for example.
OpalStackedScaled	Two images, one on top of the other, scaled to fit halves of output frame. It is expected that the output frame be double the height of the input data to maintain aspect ratio. e.g. for CIF inputs, output would be 352x576.

Function Documentation

void OPAL_EXPORT OpalFreeMessage ( OpalMessage * message )

Free memeory in message the OPAL system has sent. The parameter must be the message returned by OpalGetMessage() or OpalSendMessage().

OpalMessage* OPAL_EXPORT OpalGetMessage	(	OpalHandle	opal,
		unsigned	timeout
	)

Get a message from the OPAL system. The first parameter must be the handle returned by OpalInitialise(). The second parameter is a timeout in milliseconds. NULL is returned if a timeout occurs. A value of UINT_MAX will wait forever for a message.

The returned message must be disposed of by a call to OpalFreeMessage().

The OPAL system will serialise all messages returned from this function to avoid any multi-threading issues. If the application wishes to avoid even this small delay, there is a callback function that may be configured that is not thread safe but may be used to get the messages as soon as they are generated. See OpalCmdSetGeneralParameters.

Note if OpalShutDown() is called from a different thread then this function will break from its block and return NULL.

Example: OpalMessage * message;

while ((message = OpalGetMessage(hOPAL, timeout)) != NULL) { switch (message->m_type) { case OpalIndRegistration : HandleRegistration(message); break; case OpalIndIncomingCall : Ring(message); break; case OpalIndCallCleared : HandleHangUp(message); break; } OpalFreeMessage(message); }

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

Initialise the OPAL system, returning a "handle" to the system that must be used in other calls to OPAL.

The version parameter indicates the version of the API being used by the caller. It should always be set to the constant OPAL_C_API_VERSION. On return the library will indicate the API version it supports, if it is lower than that provided by the application.

The C string options are space separated tokens indicating various options to be enabled, for example the protocols to be available. NULL or an empty string will load all available protocols. The current protocol tokens are: sip sips h323 h323s iax2 pc local pots pstn ivr The above protocols are in priority order, so if a protocol is not explicitly in the address, then the first one of the opposite "category" s used. There are two categories, network protocols (sip, h323, iax & pstn) and non-network protocols (pc, local, pots & ivr).

Additional options are in similar form to command line arguments:

-t or –trace

Enable trace log. Multiple instances increase the trace level.

-l or –trace-level X

Enable trace log and set level to X.

-o or –output "name"

Set the filename for trace log output.

-l or –trace-option X

Enable trace log option, use +X or -X to add/remove option where X is one of:

block	PTrace::Block constructs in output
time	time since prgram start
date	date and time
gmt	Date/time is in UTC
thread	thread name and identifier
level	log level
file	source file name and line number
object	PObject pointer
context	context identifier
daily	rotate output file daily
hour	rotate output file hourly
minute	rotate output file every minute
append	append to output file, otherwise overwrites <perm>	file permission similar to unix chmod, but starts with +/- and only has one combination at a time, e.g. +uw is user write, +or is other read, etc

-c or –config "dir"

Configuration file or directory.

-p or –plugin "dir"

Plugin module directory.

-m or –manaufacturer "str"

Manufacturer name for application.

-n or –name "str"

Product name for application.

-M or –major X

Major version number.

-N or –minor X

Minor version number.

-R or –status X

Code status ("alpha", "beta" or "release").

-B or –build X

Build/patch number.

It should also be noted that there must not be spaces around the '=' sign in the above options.

If NULL is returned then an initialisation error occurred. This can only really occur if the user specifies prefixes which are not supported by the library.

Example: OpalHandle hOPAL; unsigned version;

version = OPAL_C_API_VERSION; if ((hOPAL = OpalInitialise(&version, OPAL_PREFIX_H323 " " OPAL_PREFIX_SIP " " OPAL_PREFIX_IAX2 " " OPAL_PREFIX_PCSS " TraceLevel=4")) == NULL) { fputs("Could not initialise OPAL\n", stderr); return false; }

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

Send a message to the OPAL system. The first parameter must be the handle returned by OpalInitialise(). The second parameter is a constructed message which is a command to the OPAL system.

Within the command message, generally a NULL or empty string, or zero value for integral types, indicates the particular parameter is to be ignored. Documentation on individiual messages will indicate which are mandatory.

The return value is another message which will have a type of OpalIndCommandError if an error occurs. The OpalMessage::m_commandError field will contain a string indicating the error that occurred.

If successful, the the type of the message is the same as the command type. The message fields in the return will generally be set to the previous value for the field, where relevant. For example in the OpalCmdSetGeneralParameters command the OpalParamGeneral::m_natServer would contain the STUN server name prior to the command.

A NULL is only returned if the either OpalHandle or OpalMessage parameters is NULL.

The returned message must be disposed of by a call to OpalFreeMessage().

Example: void SendCommand(OpalMessage * command) { OpalMessage * response; if ((response = OpalSendMessage(hOPAL, command)) == NULL) { puts("OPAL not initialised."); else if (response->m_type != OpalIndCommandError) HandleResponse(response); else if (response->m_param.m_commandError == NULL || *response->m_param.m_commandError == '\0') puts("OPAL error."); else printf("OPAL error: %s\n", response->m_param.m_commandError);

OpalFreeMessage(response); }

void OPAL_EXPORT OpalShutDown ( OpalHandle opal )

Shut down and clean up all resource used by the OPAL system. The parameter must be the handle returned by OpalInitialise().

Example: OpalShutDown(hOPAL);

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

Typedef Documentation

Enumeration Type Documentation

Function Documentation