opal.h File Reference

Go to the source code of this file.

Classes

struct  OpalParamGeneral
struct  OpalParamProtocol
struct  OpalParamRegistration
struct  OpalStatusRegistration
struct  OpalParamSetUpCall
struct  OpalStatusIncomingCall
struct  OpalStatusUserInput
struct  OpalStatusCallCleared
struct  OpalMessage

Defines

#define OPAL_EXPORT
#define OPAL_C_API_VERSION   "1"
#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_PC   "pc"
#define OPAL_PREFIX_H323   "h323"
#define OPAL_PREFIX_SIP   "sip"
#define OPAL_PREFIX_IAX2   "iax2"
#define OPAL_PREFIX_POTS   "pots"
#define OPAL_PREFIX_PSTN   "pstn"
#define OPAL_PREFIX_IVR   "ivr"
#define OPAL_PREFIX_ALL

Typedefs

typedef OpalHandleStruct * OpalHandle
typedef OpalHandle(OPAL_EXPORT *) OpalInitialiseFunction (const char *prefixes)
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)

Enumerations

enum  OpalMessageType {
  OpalIndCommandError, OpalCmdSetGeneralParameters, OpalCmdSetProtocolParameters, OpalCmdRegistration,
  OpalIndRegistration, OpalCmdSetUpCall, OpalIndIncomingCall, OpalCmdAnswerCall,
  OpalCmdClearCall, OpalIndAlerting, OpalIndEstablished, OpalIndUserInput,
  OpalIndCallCleared, OpalCmdHoldCall, OpalCmdRetrieveCall, OpalCmdTransferCall,
  OpalMessageTypeCount
}

Functions

OpalHandle OPAL_EXPORT OpalInitialise (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   "1"

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

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

Value:

#define OPAL_PREFIX_H323   "h323"

#define OPAL_PREFIX_IAX2   "iax2"

#define OPAL_PREFIX_IVR   "ivr"

#define OPAL_PREFIX_PC   "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

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 OpalHandleStruct* OpalHandle

typedef OpalHandle(OPAL_EXPORT *) OpalInitialiseFunction(const char *prefixes)

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

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 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 OpalMessage m_callToken field is set to the token returned in OpalCmdSetUpCall or OpalIndIncomingCall. The OpalIndCallCleared is returned in the OpalGetMessage() when the call has completed its hang up operation.
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.
OpalMessageTypeCount 


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

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

OpalHandle OPAL_EXPORT OpalInitialise ( const char *  options  ) 

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

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:

pc sip sips h323 h323s iax2 pots pstn ivr

Additional options are:

Version=1 API version of caller, the stack will use structures based on this version of the API. TraceLevel=1 Level for tracing. TraceFile=name Set the filename for trace output. Note "name" cannot contain any spaces.

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.

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

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


Generated on Fri Mar 7 07:36:40 2008 for OPAL by  doxygen 1.5.1