Appwebsocket client

The appwebsocket client is used to establish a websocket connection to an app with the appwebsocket authentication protocol.
You can enable automatic reconnecting with exponential backoff by setting the autoReconnect flag in the Connect call.

File information

Logging

Classes

class IAppWebsocketClient {
public:
    static IAppWebsocketClient * Create(class IIoMux * const iomux,
                                        class UAppWebsocketClient * const user,
                                        class ISocketProvider * const tcpSocketProvider,
                                        class ISocketProvider * const tlsSocketProvider,
                                        class IDns * const dns,
                                        class IInstanceLog * const log);

    void Connect(const char * websocketUri, const char * password, const char * app, const char * domain, const char * sip, const char * guid, const char * dn, bool autoReconnect = false);
    void Connect(const char * websocketUri, const char * app, class IAppWebsocketAuthenticator * authenticator, bool autoReconnect = false);
    void MessageComplete();
    void MessageSend(class json_io & msg, char * buffer);
    void MessageSendText(const char * buffer);
    void Encrypt(const char * seed, const char * data, char * out, size_t outLen);
    void Decrypt(const char * seed, const char * data, char * out, size_t outLen);
    void Hash(const char * seed, const char * data, char * out, size_t outLen);
    void Close();
};

Public functions

This function creates a new instance of IAppWebsocketClient.

Parameters

class IIoMux * const iomux	A pointer to the IIoMux class.
class UAppWebsocketClient * const user	A pointer to the UAppWebsocketClient class which will receive the callbacks.
class ISocketProvider * const tcpSocketProvider	A pointer to the ISocketProvider class for TCP sockets.
class ISocketProvider * const tlsSocketProvider	A pointer to the ISocketProvider class for TLS sockets.
class IDns * const dns	A pointer to the IDns class. Can be a nullptr.
IInstanceLog * log	An IInstanceLog pointer to the logging interface.

This function connects to the given endpoint.

Parameters

const char *websocketUri	The websocket URI, e.g. wss://mydomain.com/websocket/uri
const char *password
const char *app
const char *domain
const char *sip
const char *guid
const char *dn
bool autoReconnect	Default false. If true, the client tries to reconnect with an exponential backoff to avoid request flooding. The minimum reconnection timeout is 1s and the maximum 60s. The timeout is just resetted to minimum timeout again after a successfull login.

Remarks autoReconnect

With autoReconnect enabled, you might get multiple AppWebsocketClientConnectComplete callbacks for every successfull connect. Instead of receiving a AppWebsocketClientClose, you'll get an AppWebsocketClientDisconnected callback, so that your application knows that the client is currently disconnected.

This function connects to the given endpoint.

Parameters

const char *websocketUri	The websocket URI, e.g. wss://mydomain.com/websocket/uri
const char *app
class IAppWebsocketAuthenticator * const authenticator	A pointer to the IAppWebsocketAuthenticator class.
bool autoReconnect	Default false. If true, the client tries to reconnect with an exponential backoff to avoid request flooding. The minimum reconnection timeout is 1s and the maximum 60s. The timeout is just resetted to minimum timeout again after a successfull login.

Remarks

See the remarks of the previous Connect overload too.
If you set autoReconnect, the reconnect mechanism just works as long as the authenticator object is valid. This object might be closed due to configuration changes or connection issues between the PBX and another App object.
In such a case you might get an AppWebsocketClientClosed callback even if you didn't call Close yourself.

Call this function to receive the next message.

This function sends a JSON message.

Parameters

class json_io &msg	A json_io class which contains the message JSON.
char *buffer	A buffer which will be used to encode the message into. Must be big enough to avoid buffer overflows!

This function sends a text message.

Parameters

const char *buffer

The buffer which will be sent.

Closes the appwebsocket client connection. This also disables automatic reconnecting.

class UAppWebsocketClient {
public:
    virtual void AppWebsocketClientConnectComplete(class IAppWebsocketClient * appWebsocketClient) = 0;
    virtual void AppWebsocketClientMessage(class IAppWebsocketClient * appWebsocketClient, class json_io & msg, word base, const char * mt, const char * src) = 0;
    virtual void AppWebsocketClientSendResult(class IAppWebsocketClient * appWebsocketClient) = 0;
    virtual void AppWebsocketClientClosed(class IAppWebsocketClient * appWebsocketClient) = 0;
    virtual void AppWebsocketClientDisconnected(class IAppWebsocketClient * appWebsocketClient) {};
};

Overview

Public functions

Code Example

class Test : public UAppWebsocketClient {
    class IAppWebsocketClient * awsClient;
    void AppWebsocketClientConnectComplete(class IAppWebsocketClient * appWebsocketClient) override;
    void AppWebsocketClientMessage(class IAppWebsocketClient * appWebsocketClient, class json_io & msg, word base, const char * mt, const char * src) override;
    void AppWebsocketClientSendResult(class IAppWebsocketClient * appWebsocketClient) override;
    void AppWebsocketClientClosed(class IAppWebsocketClient * appWebsocketClient) override;
    
public:
    Test(class IIoMux * const iomux,
          class ISocketProvider * const tcpSocketProvider,
          class ISocketProvider * const tlsSocketProvider,
          class IDns * const dns,
          class IInstanceLog * const log);
};
    
Test::Test(class IIoMux * const iomux,
          class ISocketProvider * const tcpSocketProvider,
          class ISocketProvider * const tlsSocketProvider,
          class IDns * const dns,
          class IInstanceLog * const log)
{
    this->awsClient = IAppWebsocketClient::Create(iomux, this, tcpSocketProvider, tlsSocketProvider, dns, log);
    this->awsClient->Connect("wss://mydomain.com/websocket/uri", "myapp", "mydomain.com", "sip", "...", "DN");
}

void Test::AppWebsocketClientConnectComplete(class IAppWebsocketClient * appWebsocketClient) 
{
    char buffer[1024];
    class json_io json(buffer);
    word base = json.add_object(JSON_ID_ROOT, nullptr);
    json.add_string(base, "mt", "SendHello");
    this->awsClient->MessageSend(json, buffer);
    this->awsClient->MessageComplete();
}

void Test::AppWebsocketClientMessage(class IAppWebsocketClient * appWebsocketClient, class json_io & msg, word base, const char * mt, const char * src) 
{
    debug->printf("Test::AppWebsocketClientMessage received mt:%s", mt);
    this->awsClient->Close();
}

void Test::AppWebsocketClientSendResult(class IAppWebsocketClient * appWebsocketClient) 
{
    debug->printf("Test::AppWebsocketClientSendResult message sent");
}

void Test::AppWebsocketClientClosed(class IAppWebsocketClient * appWebsocketClient) 
{
    debug->printf("Test::AppWebsocketClientClosed");
    delete this->awsClient;
    this->awsClient = nullptr;
    // do other cleanup, e.g. call TryClose()
}