Initialization and Shutdown 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 in 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 beginning of the application.

    // Initialization process of Diarkis runtime
    // This method needs to be called only once at the application level before using any Diarkis feature.
    // In this sample, we initialize the runtime with the setting 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 Diarkis features. At this time, pass the UID (User ID) used to connect to the Diarkis server.

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

Initialization of Low-Level Communication Layer

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

    diarkis->SetupUdp();

Obtaining Connection Information for the Diarkis Server

Next, obtain the information needed to connect to the Diarkis server. (TODO) Want to lightly explain items like client key and server type. The included sample implements two patterns: obtaining connection information from an HTTP server within the Diarkis cluster and obtaining connection information via an API server (external server).

Pattern to Obtain Connection Information from an HTTP Server within the Diarkis Cluster

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

#if API_AUTH == 0
    // Access the HTTP server within the Diarkis cluster to get the server endpoint used for DirectMessage communication.
    // Depending on the communication method used, specify the appropriate server type to 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

Also, although not used in the sample

• DiarkisInterfaceBase::RequestEndpointAsync()

• DiarkisInterfaceBase::GetEndpointAsyncStatus()

• DiarkisInterfaceBase::GetAsyncEndpointResult()

can be used to obtain endpoint information asynchronously.

Pattern to Obtain Connection Information via an API Server (External Server)

Save the connection information obtained through some method like an API server (external server) in AuthInfo, and pass this information when actually connecting.

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

    // Below is sample code to connect to the UDP server using UDP connection information obtained via an API server (external server).
    // If you do not call GetEndpoint(), you need to set the connection information obtained via the API server.
    // The following is merely sample connection information and cannot be used to connect to the UDP server as is.
    std::string endpointString = "192.168.10.5:7100";
    std::string sidString = "a19c5dbb52de43e4a1fad47e5df166e0";
    std::string keyString = "495c0ca446704cb3ab37a8bd986c57a1";
    std::string ivString = "5b0ca9eb9de34df0b333eccd878d524f";
    std::string mackeyString = "88253f5c994a45bc9d9a6eb9ed502075";

    // Below is sample code for setting the endpoint and auth structure's sid, cred.key, cred.iv, cred.mac.
    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 connection information was obtained externally, pass the obtained information at this time. Also, after executing the connection process, check the connection status periodically to confirm whether the connection is complete, as it may take some time until the connection is actually established.

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

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

Initialization of Each Module

After the connection to the Diarkis server is complete, set up each module you want to use and perform the necessary communication processing 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.
    // From now on, access the functionalities of DirectMessage through the pointer obtained from DiarkisInterface.
    diarkis->SetupDirectMessage();

Disconnecting from the Diarkis Server

Call DiarkisInterfaceBase::Disconnect() to start the disconnection process from the Diarkis server. As with the connection, it may take some time until the disconnection is completed, so check the connection status after executing the disconnection process to confirm whether the disconnection is complete.

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

    // Although the disconnection process starts with the call to DiarkisInterface::Disconnect(), it may take some time until the disconnection is actually completed.
    // Check the state of the TCP/UDP connection to ensure a successful disconnection before proceeding to the termination process.
    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 execute the overall termination process of Diarkis. This process pairs with DiarkisInterfaceBase::DiarkisInit(), and like DiarkisInit, it should be called only once during the entire application lifecycle.

    // Termination process of Diarkis runtime
    // Once you have finished using Diarkis, call `DiarkisInterface::DiarkisDestroy()` only once, such as at the end of the application.
    DiarkisInterface::DiarkisDestroy();