opal.h File Reference

Go to the source code of this file.

Classes

struct  OpalParamGeneral
struct  OpalProductDescription
struct  OpalParamProtocol
struct  OpalParamRegistration
struct  OpalStatusRegistration
struct  OpalParamSetUpCall
struct  OpalStatusIncomingCall
struct  OpalStatusMediaStream
struct  OpalParamSetUserData
struct  OpalStatusUserInput
struct  OpalStatusMessageWaiting
struct  OpalStatusLineAppearance
struct  OpalParamRecording
struct  OpalStatusCallCleared
struct  OpalParamCallCleared
struct  OpalMessage

Defines

#define OPAL_EXPORT
#define OPAL_C_API_VERSION   18
#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"
#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
#define OPAL_MWI_EVENT_PACKAGE   "message-summary"
#define OPAL_LINE_APPEARANCE_EVENT_PACKAGE   "dialog;sla;ma"

Typedefs

typedef struct OpalHandleStruct * OpalHandle
typedef struct OpalMessage OpalMessage
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 enum OpalMessageType OpalMessageType
typedef enum OpalSilenceDetectMode OpalSilenceDetectMode
typedef enum OpalEchoCancelMode 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 OpalMediaDataType
typedef struct OpalParamGeneral OpalParamGeneral
typedef struct
OpalProductDescription 
OpalProductDescription
typedef struct OpalParamProtocol OpalParamProtocol
typedef struct
OpalParamRegistration 
OpalParamRegistration
typedef enum OpalRegistrationStates OpalRegistrationStates
typedef struct
OpalStatusRegistration 
OpalStatusRegistration
typedef struct OpalParamSetUpCall OpalParamSetUpCall
typedef struct
OpalStatusIncomingCall 
OpalStatusIncomingCall
typedef enum OpalMediaStates OpalMediaStates
typedef struct
OpalStatusMediaStream 
OpalStatusMediaStream
typedef struct OpalParamSetUserData OpalParamSetUserData
typedef struct OpalStatusUserInput OpalStatusUserInput
typedef struct
OpalStatusMessageWaiting 
OpalStatusMessageWaiting
typedef enum
OpalLineAppearanceStates 
OpalLineAppearanceStates
typedef struct
OpalStatusLineAppearance 
OpalStatusLineAppearance
typedef struct OpalParamRecording OpalParamRecording
typedef struct
OpalStatusCallCleared 
OpalStatusCallCleared
typedef enum OpalCallEndReason OpalCallEndReason
typedef struct OpalParamCallCleared OpalParamCallCleared

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, OpalMessageTypeCount
}
enum  OpalSilenceDetectMode { OpalSilenceDetectNoChange, OpalSilenceDetectDisabled, OpalSilenceDetectFixed, OpalSilenceDetectAdaptive }
enum  OpalEchoCancelMode { OpalEchoCancelNoChange, OpalEchoCancelDisabled, OpalEchoCancelEnabled }
enum  OpalMediaDataType { OpalMediaDataNoChange, OpalMediaDataPayloadOnly, OpalMediaDataWithHeader }
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  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
}

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)

Define Documentation

#define OPAL_C_API_VERSION   18
#define OPAL_EXPORT

/file opal.h This file contains an API for accessing the OPAL system via "C" language interface. A contrained set of functions are declared which allows the library 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.

#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"
#define OPAL_MWI_EVENT_PACKAGE   "message-summary"
#define OPAL_PREFIX_ALL
#define OPAL_PREFIX_H323   "h323"
#define OPAL_PREFIX_IAX2   "iax2"
#define OPAL_PREFIX_IVR   "ivr"
#define OPAL_PREFIX_LOCAL   "local"
#define OPAL_PREFIX_PCSS   "pc"
#define OPAL_PREFIX_POTS   "pots"
#define OPAL_PREFIX_PSTN   "pstn"
#define OPAL_PREFIX_SIP   "sip"
#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.


Typedef Documentation

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

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

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

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

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

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

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.

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

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

typedef struct OpalMessage OpalMessage
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.

Type code for messages defined by OpalMessage.

Call clearance information for the OpalCmdClearCall command.

General parameters for the OpalCmdSetGeneralParameters command. This is only passed to and returned from the OpalSendMessage() function.

Example: OpalMessage command; OpalMessage * response;

memset(&command, 0, sizeof(command)); command.m_type = OpalCmdSetGeneralParameters; command.m_param.m_general.m_stunServer = "stun.voxgratia.org"; command.m_param.m_general.m_mediaMask = "RFC4175*"; response = OpalSendMessage(hOPAL, &command);

Protocol parameters for the OpalCmdSetProtocolParameters command. This is only passed to and returned from the OpalSendMessage() function.

Example: OpalMessage command; OpalMessage * response;

memset(&command, 0, sizeof(command)); command.m_type = OpalCmdSetProtocolParameters; command.m_param.m_protocol.m_userName = "robertj"; command.m_param.m_protocol.m_displayName = "Robert Jongbloed"; command.m_param.m_protocol.m_interfaceAddresses = "*"; response = OpalSendMessage(hOPAL, &command);

Call recording information for the OpalCmdStartRecording command.

Registration parameters for the OpalCmdRegistration command. This is only passed to and returned from the OpalSendMessage() function.

Example: OpalMessage command; OpalMessage * response;

H.323 register with gatekeeper memset(&command, 0, sizeof(command)); command.m_type = OpalCmdRegistration; command.m_param.m_registrationInfo.m_protocol = "h323"; command.m_param.m_registrationInfo.m_identifier = "31415"; command.m_param.m_registrationInfo.m_hostName = gk.voxgratia.org; command.m_param.m_registrationInfo.m_password = "secret"; command.m_param.m_registrationInfo.m_timeToLive = 300; response = OpalSendMessage(hOPAL, &command); if (response != NULL && response->m_type == OpalCmdRegistration) m_AddressOfRecord = response->m_param.m_registrationInfo.m_identifier

SIP register with regstrar/proxy memset(&command, 0, sizeof(command)); command.m_type = OpalCmdRegistration; command.m_param.m_registrationInfo.m_protocol = "sip"; command.m_param.m_registrationInfo.m_identifier = "rjongbloed@ekiga.net"; command.m_param.m_registrationInfo.m_password = "secret"; command.m_param.m_registrationInfo.m_timeToLive = 300; response = OpalSendMessage(hOPAL, &command); if (response != NULL && response->m_type == OpalCmdRegistration) m_AddressOfRecord = response->m_param.m_registrationInfo.m_identifier

unREGISTER memset(&command, 0, sizeof(command)); command.m_type = OpalCmdRegistration; command.m_param.m_registrationInfo.m_protocol = "sip"; command.m_param.m_registrationInfo.m_identifier = m_AddressOfRecord; command.m_param.m_registrationInfo.m_timeToLive = 0; response = OpalSendMessage(hOPAL, &command);

Set event package so do SUBSCRIBE memset(&command, 0, sizeof(command)); command.m_type = OpalCmdRegistration; command.m_param.m_registrationInfo.m_protocol = "sip"; command.m_param.m_registrationInfo.m_identifier = "2012@pbx.local"; command.m_param.m_registrationInfo.m_hostName = "sa@pbx.local"; command.m_param.m_registrationInfo.m_eventPackage = OPAL_LINE_APPEARANCE_EVENT_PACKAGE; command.m_param.m_registrationInfo.m_timeToLive = 300; response = OpalSendMessage(hOPAL, &command); if (response != NULL && response->m_type == OpalCmdRegistration) m_AddressOfRecord = response->m_param.m_registrationInfo.m_identifier

unSUBSCRIBE memset(&command, 0, sizeof(command)); command.m_type = OpalCmdRegistration; command.m_param.m_registrationInfo.m_protocol = "sip"; command.m_param.m_registrationInfo.m_identifier = m_AddressOfRecord; command.m_param.m_registrationInfo.m_eventPackage = OPAL_LINE_APPEARANCE_EVENT_PACKAGE; command.m_param.m_registrationInfo.m_timeToLive = 0; response = OpalSendMessage(hOPAL, &command);

Set up call parameters for several command and indication messages.

When establishing a new call via the OpalCmdSetUpCall command, the m_partyA and m_partyB fields indicate the parties to connect.

For OpalCmdTransferCall, m_partyA indicates the connection to be transferred and m_partyB is the party to be transferred to. If the call transfer is successful then a OpalIndCallCleared message will be received clearing the local call.

For OpalIndAlerting and OpalIndEstablished indications the three fields are set to the data for the call in progress.

Example: OpalMessage command; OpalMessage * response;

memset(&command, 0, sizeof(command)); command.m_type = OpalCmdSetUpCall; command.m_param.m_callSetUp.m_partyB = "h323:10.0.1.11"; response = OpalSendMessage(hOPAL, &command);

memset(&command, 0, sizeof(command)); command.m_type = OpalCmdSetUpCall; command.m_param.m_callSetUp.m_partyA = "pots:LINE1"; command.m_param.m_callSetUp.m_partyB = "sip:10.0.1.11"; response = OpalSendMessage(hOPAL, &command); callToken = strdup(response->m_param.m_callSetUp.m_callToken);

memset(&command, 0, sizeof(command)); command.m_type = OpalCmdTransferCall; command.m_param.m_callSetUp.m_callToken = callToken; command.m_param.m_callSetUp.m_partyB = "sip:10.0.1.12"; response = OpalSendMessage(hOPAL, &command);

Assign a user data field to a call

Product description variables.

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

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.

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

Call clearance information for the OpalIndCallCleared indication. This is only returned from the OpalGetMessage() function.

Incoming call information for the OpalIndIncomingCall indication. This is only returned from the OpalGetMessage() function.

Line Appearance information for the OpalIndLineAppearance indication. This is only returned from the OpalGetMessage() function.

Media stream information for the OpalIndMediaStream indication and OpalCmdMediaStream command.

This is may be returned from the OpalGetMessage() function or provided to the OpalSendMessage() function.

Message Waiting information for the OpalIndMessageWaiting indication. This is only returned from the OpalGetMessage() function.

Registration status for the OpalIndRegistration indication. This is only returned from the OpalGetMessage() function.

User input information for the OpalIndUserInput indication.

This is may be returned from the OpalGetMessage() function or provided to the OpalSendMessage() function.


Enumeration Type Documentation

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

Enumerator:
OpalCallEndedByLocalUser 
OpalCallEndedByNoAccept 

Local endpoint application cleared call.

OpalCallEndedByAnswerDenied 

Local endpoint did not accept call OnIncomingCall()=PFalse.

OpalCallEndedByRemoteUser 

Local endpoint declined to answer call.

OpalCallEndedByRefusal 

Remote endpoint application cleared call.

OpalCallEndedByNoAnswer 

Remote endpoint refused call.

OpalCallEndedByCallerAbort 

Remote endpoint did not answer in required time.

OpalCallEndedByTransportFail 

Remote endpoint stopped calling.

OpalCallEndedByConnectFail 

Transport error cleared call.

OpalCallEndedByGatekeeper 

Transport connection failed to establish call.

OpalCallEndedByNoUser 

Gatekeeper has cleared call.

OpalCallEndedByNoBandwidth 

Call failed as could not find user (in GK).

OpalCallEndedByCapabilityExchange 

Call failed as could not get enough bandwidth.

OpalCallEndedByCallForwarded 

Could not find common capabilities.

OpalCallEndedBySecurityDenial 

Call was forwarded using FACILITY message.

OpalCallEndedByLocalBusy 

Call failed a security check and was ended.

OpalCallEndedByLocalCongestion 

Local endpoint busy.

OpalCallEndedByRemoteBusy 

Local endpoint congested.

OpalCallEndedByRemoteCongestion 

Remote endpoint busy.

OpalCallEndedByUnreachable 

Remote endpoint congested.

OpalCallEndedByNoEndPoint 

Could not reach the remote party.

OpalCallEndedByHostOffline 

The remote party is not running an endpoint.

OpalCallEndedByTemporaryFailure 

The remote party host off line.

OpalCallEndedByQ931Cause 

The remote failed temporarily app may retry.

OpalCallEndedByDurationLimit 

The remote ended the call with unmapped Q.931 cause code.

OpalCallEndedByInvalidConferenceID 

Call cleared due to an enforced duration limit.

OpalCallEndedByNoDialTone 

Call cleared due to invalid conference ID.

OpalCallEndedByNoRingBackTone 

Call cleared due to missing dial tone.

OpalCallEndedByOutOfService 

Call cleared due to missing ringback tone.

OpalCallEndedByAcceptingCallWaiting 

Call cleared because the line is out of service,.

OpalCallEndedWithQ931Code 

Call cleared because another call is answered.

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

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 

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

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

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.

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 returned in OpalIndIncomingCall.

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.

OpalMessageTypeCount 

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.

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


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; } FreeMessageFunction(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:

TraceLevel=1 Level for tracing. TraceAppend Append to the trace file. TraceFile="name" Set the filename for trace output. Note quotes are required if spaces are in filename. 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_stunServer 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 == '') puts("OPAL error."); else printf("OPAL error: %s\n", response->m_param.m_commandError);

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

Generated on Tue Jun 15 00:28:42 2010 for OPAL by  doxygen 1.6.3