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.