NAME

on_client_message - event is triggered when a message is received from the application.

SYNOPSIS

#include <game-carrier/common.h>

typedef void (*OnClientMessage)(GCT_INTPTR conn_user, GCT_PTR data, GCT_SIZE len);

typedef struct on_client_message {
    /* ... Some fields ... */
    OnClientMessage on_client_message;
    /* ... Some fields ... */
}

Parameters:

  • conn_user GCT_INTPTR User data associated with the connection.
  • data GCT_PTR A pointer to the received message.
  • len GCT_SIZE The length of the received message in bytes.

RETURN VALUE

None.

DESCRIPTION

The on_client_message event is a member of the client_events struct. It is triggered when a message is received from a Game Carrier application.

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 msg parameter represents a pointer to the received message. The message data is deallocated from memory after the event is called. Therefore, if it is needed to use the message data beyond the event, it is necessary to copy it.

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

In Passive and Hybrid modes, the on_client_message 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.

The on_client_message may be called only for established connections. It means that on_client_connect event had been received for the connection and on_client_disconnect event had not been received yet.

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, on_client_connect