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
- get the available services and their websocket URLs for a given service id.
- get an authentication for a service from the PBX.
File information
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 * user | The UServicesApi implementation that will handle the callbacks. |
| class IJsonApiConnection * conn | The 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 * api | The 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
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 * servicesApi | A 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 * servicesApi | A 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());
}