NAME

on_client_message_sent - event is triggered when a message is delivered to the operating system.

SYNOPSIS

#include <game-carrier/common.h>

typedef void (*OnClientMessageSent)(GCT_INTPTR conn_user, GCT_INTPTR cookie, GCT_SIZE len, int status);

typedef struct on_client_message_sent {
    /* ... Some fields ... */
    OnClientMessageSent on_client_message_sent;
    /* ... Some fields ... */
}

Parameters:

  • conn_user GCT_INTPTR User data associated with the connection.
  • cookie GCT_INTPTR A pointer to the user data.
  • len GCT_SIZE The length of the received message in bytes.
  • status int The error code of the write operation.

RETURN VALUE

None.

DESCRIPTION

The on_client_message_sent event is a member of the client_events struct. It is triggered when a message is successfully delivered to the operating system. However, it does not guarantee that the server application will receive the message. This event occurs after invoking the gc_client_add_message function.

The conn_user parameter represents the user-defined data that is associated with a connection. This data is passed to all event handlers that are defined in the client_events struct. This parameter allows the user to find their own connection-related data. It could be a pointer to a structure allocated before creation a connection, or an index in some container. If the user has created multiple connections, they could use different conn_user values for each connection and then use that value in the event handlers to determine which connection the event is associated with.

The cookie parameter allows associating the user-specific data with the message and can be utilized for custom handling or identification purposes when the on_client_message_sent event is triggered.

The len parameter ndicates the length of the received message in bytes.

The status parameter represents the error code of the write operation. A value of 0 indicates that there is no error. Typically, it corresponds to one of the standard values that can be stored in the errno variable.

It is guaranteed that every gc_client_add_message call will be followed by the corresponding on_client_message_sent event.

In Passive and Hybrid modes, the on_client_message_sent event is called in the same thread from gc_clients_service call. While in Active mode, the event may be triggered in an arbitrary thread.

EXAMPLE

#include <game-carrier/client.h>

#include <stdio.h>
#include <string.h>

/**
 * The example below connects to a server,
 * waits for a message and then it disconnects.
 **/

#define GAME_CLIENT   1
#define MAGIC_COOKIE 42

int mode = GC_MODE_HYBRID;
GCT_INTPTR game_conn;

int finished = 0;

void on_client_connect(GCT_INTPTR conn_user, GCT_INTPTR handle)
{
    if (conn_user == GAME_CLIENT) {
        printf("Connected to the game server\n");
        game_conn = handle;
        char * msg = "Hello!";
        gc_client_add_message(game_conn, msg, strlen(msg), MAGIC_COOKIE);
        return;
    }

    printf("??? Connected to an unknown server\n");
}

void on_client_connection_error(GCT_INTPTR conn_user, GCT_CSTR reason)
{
    ++finished;

    if (conn_user == GAME_CLIENT) {
        fprintf(stderr, "Failed connecting to the game server: %s\n", reason);
        return;
    }

    fprintf(stderr, "??? Failed connecting to the unknown server: %s\n", reason);
}

void on_client_disconnect(GCT_INTPTR conn_user)
{
    ++finished;

    if (conn_user == GAME_CLIENT) {
        printf("Disconnected from the game server.\n");
        return;
    }

    printf("??? Unknown connection has been disconnected from the game server");
}

void on_client_message(
    GCT_INTPTR conn_user, GCT_PTR data, GCT_SIZE len)
{
    if (conn_user == GAME_CLIENT) {
        printf("Received message from the game server: %s\n", (char*)data);
        gc_client_stop(game_conn);
        return;
    }

    printf("??? Received message from an unknown server: %s\n", (char*)data);
}

void on_client_message_sent(
    GCT_INTPTR conn_user,
    GCT_INTPTR cookie,
    GCT_SIZE len,
    GCT_INT status)
{
    if (conn_user != GAME_CLIENT) {
        fprintf(stderr, "??? Unknown message sent\n");
        return;
    }

    if (cookie != MAGIC_COOKIE) {
        fprintf(stderr, "??? Unexpected cookie received: " PRId64, cookie);
        return;
    }

    if (status != 0) {
        fprintf(stderr, "Failed to send message, error code is %d\n", status);
        return;
    }

    printf("Message sent OK\n");
}

int main(int argc, char * argv[])
{
    ClientEvents events;
    events.on_client_connect = on_client_connect;
    events.on_client_connection_error = on_client_connection_error;
    events.on_client_disconnect = on_client_disconnect;
    events.on_client_message = on_client_message;

    int ret = gc_clients_init(mode);
    if (ret != 0) {
        fprintf(stderr, "Failed to initialize the Game Carrier client library\n");
        return 1;
    }

    int status = gc_client_start(GAME_CLIENT, GC_PROTOCOL_WSS, "game.example.com", 7681, "game", &events);
    if (status != 0) {
        fprintf(stderr, "Failed to connect to the game server\n");
        return 1;
    }

    /* Wait Loop */
    while (finished != 1) {

        /* Perform related game activity, like drawing a new frame */
        draw_new_frame();

        /* Handling network */
        if (mode == GC_MODE_PASSIVE || mode == GC_MODE_HYBRID) {
            gc_clients_service();
        }
     }

    gc_clients_cleanup();
    return 0;
}

SEE ALSO

gc_client_start, gc_client_add_message