Initialization and Termination of Diarkis Module

This page introduces part of the code from the directmessage_simple sample to explain the overall flow when using the Diarkis Module. The actual source code of the sample is located at samples\directmessage_simple\directmessage_simple.cpp.

Initialization of Diarkis Runtime Library and Diarkis Module

First, call DiarkisInterfaceBase::DiarkisInit() to initialize the Diarkis Runtime Library and Diarkis Module. This process must be executed only once at the very start across the entire application.

    // Initialization process of Diarkis Runtime
    // Must be called once across the entire application before using Diarkis functionalities.
    // In this sample, we initialize the runtime with settings to output logs to a file.
    DiarkisInterface::DiarkisInit(uid, LogOutType::FILE_OUT, true, nullptr);

Creating an Instance of DiarkisInterfaceBase

Next, create an instance of a class that inherits from DiarkisInterfaceBase to connect to the Diarkis server and use various functionalities of Diarkis. At this time, pass the UID (User ID) used to connect to the Diarkis server.

    // Create a class that inherits DiarkisInterface to access all functions of Diarkis.
    diarkis = Diarkis::DiarkisAllocShared<DiarkisInterfaceDirectMessageSimple>(uid);

Initialization of Low-Level Communication Layer

After creating an instance of DiarkisInterfaceBase, set up TCP/UDP communication used for communicating with the Diarkis server.

    diarkis->SetupUdp();

Obtaining Connection Information to Diarkis Server

Next, obtain the information required to connect to the Diarkis server. (TODO) Want to briefly explain client keys and server types, etc. In the accompanying sample, two patterns are implemented: obtaining connection information from the HTTP server within the Diarkis cluster and obtaining it via an API server (external server).

Pattern for Obtaining Connection Information from HTTP Server within Diarkis Cluster

Use DiarkisInterfaceBase::GetEndpoint() to obtain the connection information. The obtained connection information is automatically stored within DiarkisInterfaceBase and is used when connecting.

#if API_AUTH == 0
    // Access the HTTP server in the Diarkis cluster to obtain the server endpoint used for DirectMessage communication.
    // Depending on the method used for communication, specify the appropriate server type and obtain the endpoint from the server.
    if (diarkis->GetEndpoint(host.c_str(), clientKey.c_str(), serverType.c_str(), endpoint, 256) == false)
    {
        DiarkisUtils::Print("Failed to get %s endpoint: host=%s uid=%s clientKey=%s", serverType.c_str(), host.c_str(), uid.c_str(), clientKey.c_str());
        DiarkisInterface::DiarkisDestroy();
        return 1;
    }

    DiarkisUtils::Print("Endpoint: %s", endpoint);
    DiarkisUtils::Print("UID     : %s\n", uid.c_str());
#endif // API_AUTH

Although not used in the sample,

• DiarkisInterfaceBase::RequestEndpointAsync()

• DiarkisInterfaceBase::GetEndpointAsyncStatus()

• DiarkisInterfaceBase::GetAsyncEndpointResult()

can also be used to obtain endpoint information asynchronously.

Pattern for Obtaining Connection Information via API Server (External Server)

Save the connection information obtained by some method, such as an API server (external server), into AuthInfo and pass this information during the actual connection process.

#if API_AUTH
    struct AuthInfo auth;
    // diarkis->GetAuthInfo(&auth);

    // Below is sample code for using UDP connection information obtained via an API server (external server) to connect to the UDP server.
    // If `GetEndpoint()` is not called, it is necessary to set the connection information obtained via the API server.
    // The following is merely sample connection information, so you cannot connect to the UDP server with this exact code.
    std::string endpointString = "192.168.10.5:7100";
    std::string sidString = "a19c5dbb52de43e4a1fad47e5df166e0";
    std::string keyString = "495c0ca446704cb3ab37a8bd986c57a1";
    std::string ivString = "5b0ca9eb9de34df0b333eccd878d524f";
    std::string mackeyString = "88253f5c994a45bc9d9a6eb9ed502075";

    // The following is sample code for setting the endpoint and the sid, cred.key, cred.iv, cred.mac of the auth struct.
    strcpy(endpoint, endpointString.c_str());
    HexadecimalStringToByteArray(sidString.c_str(), auth.sid, DIARKIS_AUTHKEY_LEN);
    HexadecimalStringToByteArray(keyString.c_str(), auth.cred.key, DIARKIS_AUTHKEY_LEN);
    HexadecimalStringToByteArray(ivString.c_str(), auth.cred.iv, DIARKIS_AUTHKEY_LEN);
    HexadecimalStringToByteArray(mackeyString.c_str(), auth.cred.mac, DIARKIS_AUTHKEY_LEN);
#endif // API_AUTH

Connecting to Diarkis Server

If the connection information was obtained externally, pass the obtained information at this timing. Also, since it can take some time for the connection to complete after executing the connection process, periodically check the connection status to see if the connection has completed.

    // Connect to the endpoint obtained via HTTP access and establish communication with the Diarkis server.
    // In this sample, we use TCP/UDP sockets to connect to the Diarkis server.
    bool connectResult = false;
#if API_AUTH == 0
    connectResult = diarkis->ConnectUdp(endpoint);
#else
    connectResult = diarkis->ConnectUdp(endpoint, serverType.c_str(), &auth);
#endif

    // Although the connection process starts with the call to DiarkisInterface::ConnectUdp/Tcp(), it may take some time to actually complete the connection.
    // To ensure a successful connection, check the state of the TCP/UDP connection.
    while (!diarkis->GetUdpBase()->IsConnected())
    {
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }

Initialization for Each Module

After completing the connection to the Diarkis server, set up the modules you wish to use and perform the necessary communication processes for the application.

    // Initialize the DirectMessage module managed within DiarkisInterface.
    // Allocate an instance of the DirectMessage module and associate it with the TCP/UDP module used for communication.
    // Henceforth, access DirectMessage functions by obtaining the pointer of the DirectMessage module from DiarkisInterface.
    diarkis->SetupDirectMessage();

Disconnecting from Diarkis Server

By calling DiarkisInterfaceBase::Disconnect(), the process of disconnecting from the Diarkis server begins. As with the connection, since it can take time for the disconnection to be completed, check the connection status after executing the disconnection process to see if it is completed.

    // Disconnect from the Diarkis server
    diarkis->Disconnect();

    // Although the disconnection process starts with the call to DiarkisInterface::Disconnect(), it may take some time to actually complete the disconnection.
    // To proceed to the termination process after ensuring disconnection, check the state of the TCP/UDP connection.
    while (diarkis->GetUdpBase()->IsConnected() == true)
    {
        std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }

Releasing Used Instances

Once the disconnection from the Diarkis server is complete and DiarkisInterfaceBase is no longer needed, release the instance.

    diarkis = nullptr;

Termination Process

At the end of the application, call DiarkisInterfaceBase::DiarkisDestroy() to perform the overall termination process of Diarkis. This process complements DiarkisInterfaceBase::DiarkisInit() and, like DiarkisInit, should be called just once during the entire application lifecycle.

    // Termination process of the Diarkis Runtime
    // After finishing using Diarkis, ensure to call DiarkisInterface::DiarkisDestroy() once, for instance, during application termination.
    DiarkisInterface::DiarkisDestroy();