Lookup and authentication for websocket services

App instances can provide services on incoming appwebsocket connections that can be used by the PBX or other app instances. Those services are JSON APIs that are identified by a string. For ensuring the uniqueness, we recommend using the reverse domain name notation like "com.innovaphone.provisioning". See the documentation of AppWebsocket::AppWebsocketServiceInfo on how to publish services.

If you want to find and authenticate against one of those services you can use this library. After attaching it to the websocket connection from the PBX you can

File information

Filecommon/interface/services.h

Public functions CreateServicesApi

Classes IServicesApi
UServicesApi
IService

Examples Attaching to the websocket connection from the PBX
Lookup and authentication

Functions

Functions to initialize

extern class IServicesApi * CreateServicesApi(class UServicesApi * user, class IJsonApiConnection * conn);
CreateServicesApi
Creates an instance of the service API and attaches it to a IJsonApiConnection.

Parameters

class UServicesApi * userThe UServicesApi implementation that will handle the callbacks.
class IJsonApiConnection * connThe IJsonApiConnection instance that shall be used. It must be an appwebsocket connection from a PBX that offered the "Services" API in the PbxInfo message.

Return value

The actual IServicesApi object. The object is owned by the IJsonApiConnection and is deleted when the connection is closed. It must not be deleted by the application.

Classes

IServicesApi

class IServicesApi {
public:
    virtual ~IServicesApi() {};
    virtual class IService * GetService(const char * api) = 0;
    virtual class IAppWebsocketAuthenticator * CreateAuthenticator(class UAppWebsocketAuthenticator * user = 0) = 0;
};

Overview

This class provides lookup and authentication for services.

Public functions

GetService
Returns the first IService object for the given API ID.

Parameters

const char * apiThe ID of the API, typically in reverse domain name notation.

Return value

An IService object representing the first found service. If there is no matching service the return value will be NULL.

Remarks

The returned object is volatile. The application should not store a pointer to it but just use the contained values or copy them.
CreateAuthenticator
Creates an object that can handle the authentication against services. It can be passed to IAppWebsocketClient::Connect.

Parameters

class UAppWebsocketAuthenticator * userA pointer to the UAppWebsocketAuthenticator that uses the authentication. Pass 0, if used with IAppWebsocketClient::Connect.

Return value

The created UAppWebsocketAuthenticator object that will be used by IAppWebsocketClient::Connect.

UServicesApi

class UServicesApi {
public:
    virtual void ServicesApiUpdated(class IServicesApi * servicesApi) = 0;
    virtual void ServicesApiClosed(class IServicesApi * servicesApi) = 0;
};

Overview

Base class for applications that use the library.

Public functions

ServicesApiUpdated
Called if there are updates on the available services. This can happen if services appear, disappear or the details are changed.

Parameters

class IServicesApi * servicesApiA pointer to the source of the callback.
ServicesApiClosed
Called if the IServicesApi is closed. The application must not do any more function calls on it.

Parameters

class IServicesApi * servicesApiA pointer to the source of the callback.

Remarks

The application must not delete the IServicesApi. This is done by the IJsonApiConnection that owns the object.

IService

class IService {
public:
    virtual const char * GetName() = 0;
    virtual const char * GetTitle() = 0;
    virtual const char * GetWebsocketUrl() = 0;
    virtual const char * GetApiInfo() = 0;
    virtual class IService * GetNext() = 0;
};

Overview

This class provides the information about a single service and a pointer to the next service of the same type.

Public functions

GetName

Return value

The SIP URI of the app instance providing the service.
GetTitle

Return value

The display name of the app instance providing the service.
GetWebsocketUrl

Return value

The websocket URL of the service.
GetApiInfo

Return value

A string containing a JSON structure with further information about the service.
GetNext

Return value

Returns the next IService in the list or NULL if there are no more.

Code Example

Attaching to the websocket connection from the PBX

void MyAppwebsocketSession::AppWebsocketMessage(class json_io & msg, word base, const char * mt, const char * src)
{
    if (!strcmp(mt, "PbxInfo")) {
        servicesApi = CreateServicesApi(this, this);
        AppWebsocketMessageComplete();
    }
    else {
        AppWebsocketMessageComplete();
    }
}

Lookup and authentication

class IService * service = services.GetService("com.innovaphone.provisioning");
if (service) {
    appWebsocketClient->Connect(service->GetWebsocketUrl(), service->GetName(), servicesApi->CreateAuthenticator());
}