# API Websocket Client

This interface is used for internal modules of the myApps launcher. It is not needed by app developers.

The ApiWebsocketClient connects to an ApiRelay instance that is usually also a local service. It allows implementing API providers and API consumers that can interact with the apps running in myApps. The websocket protocol is used for the connection.

## File information

File | common/lib/apiwebsocket_client.h
Classes | ApiWebsocketClient ApiProvider ApiConsumer

# Classes

## ApiWebsocketClient

    class ApiWebsocketClient : public UWebsocketClient, public UTimer {
        ...
    public:
        ApiWebsocketClient(class IIoMux * const iomux, class ISocketProvider * const tcp, class ISocketProvider * const tls, class IDns * const dns, class IInstanceLog * const log, const char * uri, const char * pwd, const char * dn);
        virtual ~ApiWebsocketClient();
        bool ApiWebsocketClientIsConnected();
        void ApiWebsocketClientClose();
        virtual void ApiWebsocketClientCloseComplete() = 0;
        virtual void ApiWebsocketClientConnected() {};
        virtual void ApiWebsocketClientDisconnected() {};
    };

Base class for websocket sessions to the ApiRelay of the myApps launcher.

### ApiWebsocketClient

Contructor function.

Parameters

  const char * uri | The websocket URI of the api relay service.
  const char * pwd | The password for authenticating to the api relay service.
  const char * dn | The display name that shall be used for API providers.

### ApiWebsocketClientIsConnected

Return value
  Returns true if the connection to the api relay is up. False otherwise.

### ApiWebsocketClientClose

Shall be called to close the connection and all attached API providers and consumers. The application will get the `ApiWebsocketClientCloseComplete` callback when this is done.

### ApiWebsocketClientCloseComplete

Will be called after the connection and all attached API providers and consumers have been closed. Applications that use the library should not exit before this callback is received.

### ApiWebsocketClientConnected

Called if the connection went up.

### ApiWebsocketClientDisconnected

Called if the connection went down.

## ApiProvider

    class ApiProvider : public btree, public UIoExec {
        ...
    protected:
        void ApiProviderClosed();
        ...
    public:
        ApiProvider(class ApiWebsocketClient * const client, const char * api);
        void ApiProviderSend(const char * client, const char * consumer, const char * src, class json_io & msg, word base, char * buffer);
        void ApiProviderUpdate(class json_io & json, word base, char * buffer);
        virtual void ApiProviderRecv(const char * client, const char * consumer, const char * src, class json_io & msg, word base) = 0;
        virtual void ApiProviderConsumerClosed(const char * client, const char * consumer) {}
        virtual void ApiProviderClose() { ApiProviderClosed(); }
        virtual void ApiProviderConnected() {}
        virtual void ApiProviderDisconnected() {}
    };

Base class for client API providers. An ApiProvider is attached during creation to an ApiWebsocketClient. It is deleted by the ApiWebsocketClient. So the application doesn't need to keep a reference to it.

### ApiProvider

Contructor function.

Parameters

  class ApiWebsocketClient * const client | The ApiWebsocketClient instance to be used by the provider.
  const char * api | The name of the API that is implemented by this class (e.g. com.innovaphone.search).

### ApiProviderSend

This function is used for sending ApiResult messages. The parameters client, consumer and src should be echoed from the corresponding ApiRequest message received using `ApiProviderRecv`.

Parameters

  const char * client | The opaque client ID from the API request.
  const char * consumer | The opaque consumer ID from the API request.
  const char * src | The opaque source ID from the API request.
  class json_io & msg | A JSON structure containing an API request.
  word base | The reference pointing to the base of the message inside the JSON structure.
  char * buffer | A buffer that is big enough to contain the whole encoded message.

### ApiProviderUpdate

This function is used for sending a new ApiModel to the client.

Parameters

  class json_io & msg | A JSON structure containing the new API model.
  word base | The reference pointing to the base of the message inside the JSON structure.
  char * buffer | A buffer that is big enough to contain the whole encoded message.

### ApiProviderRecv

This callback is called when an ApiRequest is received. ApiResults should be sent using the `ApiProviderSend` function. The extra parameters (client, consumer and src) must be echoed back in the response.

Parameters

  const char * client | The opaque client ID. Must be echoed back in the API response.
  const char * consumer | The opaque consumer ID. Must be echoed back in the API response.
  const char * src | The opaque source ID chosen be the consumer. Must be echoed back in the API response.
  class json_io & msg | A JSON structure containing an API request.
  word base | The reference pointing to the base of the message inside the JSON structure.

### ApiProviderConsumerClosed

This callback is called when an API consumer has been closed. This can be used to cancel any open API requests or subscriptions done by that consumer.

Parameters

  const char * client | The ID of the client.
  const char * consumer | The ID of the consumer.

### ApiProviderClose

This callback is called before the object is deleted by the AppWebsocketClient. Subclasses should stop any activities and then call `ApiProviderClosed()`.

### ApiProviderConnected

Called when the provider is connected to the api relay.

### ApiProviderDisconnected

Called when the provider is disconnected from the api relay.

### ApiProviderClosed

This function should be called after the `ApiProviderClose()` callback, when the implementing class has stopped any activities.

## ApiConsumer

    class ApiConsumer : public btree, public UIoExec {
        ....
    protected:
        void ApiConsumerClosed();
        ...
    public:
        ApiConsumer(class ApiWebsocketClient * const client, const char * api);
        void ApiConsumerSend(const char * provider, const char * src, class json_io & msg, word base, char * buffer);
        virtual void ApiConsumerRecv(const char * provider, const char * src, class json_io & msg, word base) {};
        virtual void ApiConsumerUpdate(class json_io & model, word base) {};
        virtual void ApiConsumerClose() { ApiConsumerClosed(); }
        virtual void ApiConsumerConnected() {}
        virtual void ApiConsumerDisconnected() {}
    };

Base class for client API consumers. An ApiConsumer is attached during creation to an ApiWebsocketClient. It is deleted by the ApiWebsocketClient. So the application doesn't need to keep a reference to it.

### ApiConsumer

Contructor function.

Parameters

  class ApiWebsocketClient * const client | The ApiWebsocketClient instance to be used by the consumer.
  const char * api | The name of the API that is used by this class (e.g. com.innovaphone.search).

### ApiConsumerSend

Call this function to send an ApiRequst message to the specified provider.

Parameters

  const char * provider | Can be one of the following: The ID of the provider. "*" to broadcast the request to all providers. NULL to let the client choose the provider based on user settings or by asking the user.
  const char * src | An optional source ID that shall be mirrored back in the API result.
  class json_io & msg | A JSON structure containing an API request.
  word base | The reference pointing to the base of the message inside the JSON structure.
  char * buffer | A buffer that is big enough to contain the whole encoded message.

### ApiConsumerRecv

This function is called when an ApiResult message is received.

Parameters

  const char * provider | The provider ID.
  const char * src | The source ID that was sent with the corresponding API request.
  class json_io & msg | A JSON structure containing an API result.
  word base | The reference pointing to the base of the message inside the JSON structure.

### ApiConsumerUpdate

This function is called when the API model has changed.

Parameters

  class json_io & msg | A JSON structure containing the new API model.
  word base | The reference pointing to the base of the message inside the JSON structure.

### ApiConsumerClose

This callback is called before the object is deleted by the AppWebsocketClient. Subclasses should stop any activities and then call `ApiConsumerClosed()`.

### ApiConsumerConnected

Called when the consumer is connected to the api relay.

### ApiConsumerDisconnected

Called when the consumer is disconnected from the api relay.

### ApiConsumerClosed

This function should be called after the `ApiConsumerClose()` callback, when the implementing class has stopped any activities.