# PBX API

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

## File information

File | common/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.