# 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

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

  class UAppWebsocketAuthenticator * user | A 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 * 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());
    }