How To Connect To Diarkis Cloud

This instruction is a walkthrough of how to make a real-time connection with Diarkis Cloud.

Obtaining The Connection EndPoints

Diarkis C# client needs TCP and/or UDP/RUDP endpoints. The endpoints are retrieved by an HTTP REST API of Diarkis Cloud. The HTTP API endpoint is the host address that you created when you deploy a Dairkis Cloud cluster. For more details please read here.

curl https://xxx.diarkis.io/auth/:userID -h "clientKey:zzz"

For a production-grade application, you must provide application server(s) independent of Diarkis Cloud to manage your client user data and other application-related data including the authentication of the user.

The HTTP REST API requires a user ID in its request URI to uniquely identify the requesting client. The user ID must be provided by the requesting client.

The HTTP REST API requires the Client Key in its request header. The Client Key is generated when you deploy a Diarkis Cloud cluster.

A successful request will have a response in JSON format similar to the example below:

{
  "TCP":"xxxxxx.diarkis.io:7200",
  "UDP":"yyyyyy.diarkis.io:7100",
  "sid":"9985a8943ce5467a8f9436b0a38a7a25",
  "encryptionKey":"cdca9e1b31bb4cf5ad4072a02fb7c0ad", 
  "encryptionIV":"1706e3f72e934d6c939b15cf436eb9e6",
  "encryptionMacKey":"f2a99106188d478fbe1537b6f2e071c8"
}

Call Update Method For Events

Diarkis TCP and UDP/RUDP clients need their Update method to be call every time it needs to dispatch events from network threads that is working in the background.

For Unity Game Engine, you must call in the Unity Update method:

// This is the Unity Update method - This is called on frame update
private void Update()
{
    if (diarkisUDPClient != null)
    {
        diarkisUDPClient.Update();
    }
    if (diarkisTCPClient != null)
    {
        diarkisTCPClient.Update();
    }
}

Make A UDP/RUDP Connection

Once you obtained the endpoint, you are now ready to make a connection to Diarkis Cloud. The example below shows how to make a connection with packet encryption keys:

NOTE: UDP does not have “connections” by design, but for the sake of convenience we use the term “connections” here.

int sendInterval = 200; // This is the interval in milliseconds to send packets. All packets that fall within this interval will be combined
int echoInterval = 5000; // The default is 5000 milliseconds
Diarkis.Udp udp = new Diarkis.Udp(sendInterval, echoInterval);
udp.SetClientKey(clientKey);
udp.SetEncryptionKeys(sid, key, iv, mackey);

// This event will raise when the connection is successfull
udp.OnConnect += HandleOnConnect;

// All network related errors will be caught here
udp.OnException += HandleOnException;

// Start the connection. This will raise either OnConnect or OnException event
udp.Connect(addr, port);

private void HandleOnConnect(bool reconnected)
{
    // reconnected will be true, if re-connected
    // Start your awesome real-time application here
}

private void HandleOnException(int code, string msg)
{
    // We handle error with network here...
}

How To terminate UDP Connection

The following example is to show how to terminate the UDP connection and its event listener:

// This event is raised when the client is disconnected
udp.OnDisconnect += HandleOnDisconnect;

udp.Disconnect();

private void HandleOnDisconnect(bool reconnecting)
{
    // reconnecting will be true, if Disconnect is invcoked by re-connection
}

Make A TCP Connection

Once you obtained the endpoint, you are now ready to make a connection to Diarkis Cloud. The example below shows how to make a connection with packet encryption keys:

int heartbeatInterval = 5000; // The default is 5000 milliseconds
Diarkis.Tcp tcp = new Diarkis.Tcp(heartbeatInterval);
tcp.SetClientKey(clientKey);
tcp.SetEncryptionKeys(sid, key, iv, mackey);

// This event will raise when the connection is successfull
tcp.OnConnect += HandleOnConnect;

// All network related errors will be caught here
tcp.OnException += HandleOnException;

// Start the connection. This will raise either OnConnect or OnException event
tcp.Connect(addr, port);

private void HandleOnConnect(bool reconnected)
{
    // reconnected will be true, if re-connected
    // Start your awesome real-time application here
}

private void HandleOnException(int code, string msg)
{
    // We handle error with network here...
}

How To terminate TCP Connection

The following example is to show how to terminate the TCP connection and its event listener:

// This event is raised when the client is disconnected
tcp.OnDisconnect += HandleOnDisconnect;

tcp.Disconnect();

private void HandleOnDisconnect(bool reconnecting)
{
    // reconnecting will be true, if Disconnect is invcoked by re-connection
}

Conclusion

Diarkis client offers secure real-time communications with Diarkis Cloud. It allows the developer to choose the type of real-time communication they need for their applications without changing API the interface.