PBX API

IPbxApi is a task-oriented interface that allows app services to access PBX data and functionality.

File information

Filecommon/interface/pbx.h

Public functions CreatePbxApi

Classes IPbxApi
IPbxApiPresenceSubscription
IPbxApiPresence

Functions

Functions to initialize

extern class IPbxApi * CreatePbxApi(class IJsonApiConnection * conn);
CreatePbxApi
This function creates a IPbxApi object that will be connected to a given IJsonApiConnection, typically an AppWebsocket.

Return value

The IPbxApi instance. The object is owned by the IJsonApiConnection and is deleted automatically when the connection is closed. So the application should never delete it.

Classes

IPbxApi

class IPbxApi {
public:
    virtual ~IPbxApi() {};
    virtual class ITask * CreateSetPresence(const char * guid, const char * sip, const char * contact, const char * activity, const char * note) = 0;
    virtual class IPbxApiPresenceSubscription * CreatePresenceSubscription(const char * sip, const char * num, const char * sourceSip = 0) = 0;
    virtual class IPbxApiTaskGetNodeInfo * CreateGetNodeInfo(const char * pbx, const char * domain) = 0;
};

Overview

The interface of the PBX API. It provides functions to create several tasks that can be used to communicate with the PBX.

Public functions

CreateSetPresence
Creates an ITask that sets the presence for a given contact of a given user.

Parameters

const char * guid The GUID of the affected user object. (guid or sip must be specified)
const char * sip The SIP URI of the affected user object. (guid or sip must be specified)
const char * contact The contact string of the presence (e.g. tel:)
const char * activity A SIP activity string (e.g. away, busy, lunch, vacation, dnd, ...). If not set the activity will be displayed as "available".
const char * note A free text describing details about the activity.

Return value

An ITask object that implements the presence change.
CreatePresenceSubscription
Creates a presence subscription for a given SIP URI or phone number.

Parameters

const char * sip The SIP URI of the monitored user. (sip or num must be specified)
const char * number The phone number of the monitored user. (sip or num must be specified)
const char * sourceSip Can be specified if the monitoring should be done on behalf of a specific user. Otherwise the subscription is done on behalf of the app object of the app instance.

Return value

An IPbxApiPresenceSubscription object that implements the presence subscription.
CreateGetNodeInfo
Creates an ITask that retrieves some node configuration info.

Parameters

const char * pbx The pbx argument as received within a PbxInfo message.
const char * domain The domain argument as received within a PbxInfo message.

Return value

An IPbxApiTaskGetNodeInfo object.

IPbxApiPresenceSubscription

class IPbxApiPresenceSubscription : public ITask {
public:
    virtual ~IPbxApiPresenceSubscription() {}
    virtual void Start(class UTask * user) = 0;
    virtual void Stop() = 0;
    virtual bool IsUp() = 0;
    virtual const char * GetSip() = 0;
    virtual const char * GetDn() = 0;
    virtual const char * GetNum() = 0;
    virtual const char * GetEmail() = 0;
    virtual class IPbxApiPresence * GetPresence() = 0;
};

Overview

This class implements a presence subscription using the ITask interface. It produces a TaskProgress callback on each update with one of the following values:
PBX_API_PROGRESS_SUBSCIPTION
The state of the presence subscription changed. This could be if the presence subscription goes up or down or if the remote endpoint information changed.
PBX_API_PROGRESS_PRESENCE
The presence information has changed.

Public functions

Start
Starts the presence subscription. The specified UTask will get the TaskProgress callback on any changes or TaskFailed on a fatal error.

Parameters

class UTask * user The UTask object that shall receive the callbacks.
Stop
Stops the presence subscription. The UTask will get the TaskComplete callback, when the presence subscription has terminated.
IsUp
Tells if the presence monitor is up or down. All the other info is just available, if the presence monitor is up.

Return value

true if the presence monitor is up. false if it is down.
GetSip

Return value

The SIP URI of the monitored endpoint.
GetCn

Return value

The common name of the monitored endpoint.
GetDn

Return value

The display name of the monitored endpoint.
GetNum

Return value

The phone number of the monitored endpoint.
GetEmail

Return value

The email address of the monitored endpoint.
GetPresence

Return value

A pointer to an IPbxApiPresence object that contains the list of presence entries, or null if there are none.

IPbxApiPresence

class IPbxApiPresence {
public:
    virtual const char * GetContact() = 0;
    virtual const char * GetStatus() = 0;
    virtual const char * GetActivity() = 0;
    virtual const char * GetNote() = 0;
    virtual class IPbxApiPresence * GetNext() = 0;
};

Overview

The user can have a list of presence entries that consist of a contact ("tel:"), a status ("open" or "closed"), an activity ("away", "busy", etc) and a note. The IPbxApiPresence object represents a single entry with a pointer to the next entry in the list. Please note that object is volatile. The application should not store any pointers to it but copy the needed information.

Public functions

GetContact

Return value

The contact string of the presence entry (e.g. "tel:") or NULL.
GetStatus

Return value

The status string of the presence entry ("open", "closed") or NULL.
GetActivity

Return value

The activity string of the presence entry ("away", "busy", etc) or NULL.
GetNote

Return value

The note string of the presence entry or NULL.
GetNext

Return value

The next IPbxApiPresence object in the list or NULL if there is none.

IPbxApiTaskGetNodeInfo

class IPbxApiTaskGetNodeInfo : public ITask {
public:
	virtual const char * GetName() = 0;
	virtual const char * GetPrefixIntl() = 0;
	virtual const char * GetPrefixNtl() = 0;
	virtual const char * GetPrefixSubs() = 0;
	virtual const char * GetAreaCode() = 0;	
	virtual const char * GetCountryCode() = 0;
};

Overview

A PBX node's configuration can be read upon completion.

Public functions

GetName

Return value

The node's name.
GetPrefixIntl

Return value

The node's prefix for international numbers.
GetPrefixNtl

Return value

The node's prefix for national numbers.
GetPrefixSubs

Return value

The node's prefix for subscriber numbers.
GetAreaCode

Return value

The node's configured area code, e.g. 30 for Berlin.
GetCountryCode

Return value

The node's configured country code, e.g. 49 for germany.