NAME

gc_client_add_message - allows sending a message to the server application.

SYNOPSIS

#include <game-carrier/client.h>

GC_CLIENT_API
void gc_client_add_message(
    GCT_INTPTR client_handle,
    GCT_PTR data,
    GCT_INT len,
    GCT_INTPTR cookie);

Parameters:

  • client_handle GCT_INTPTR The client connection handle.
  • data GCT_PTR Message data to be sent to the server application.
  • len GCT_INT The length of the message being sent in bytes.
  • cookie GCT_INTPTR User data assocaited with the message.

RETURN VALUE

None.

DESCRIPTION

The gc_client_add_message function is used to send a message to the Game Carrier server application.

The client_handle parameter represents the client connection handle, which is used to identify the active client session to which the message should be sent. Basically, this handle allows the function to determine the appropriate client session for message delivery. The handle is returned after a successful connection is established in the on_client_connect event.

The msg parameter specifies the message data to be sent to the Game Carrier server application.

The len parameter indicates the length of the message data being sent in bytes.

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 gc_client_add_message function should be called after receiving a on_client_connect event.

In Passive mode, there will be no attempts to send a message until the game calls gc_clients_service in the same thread where the gc_clients_service was initially called. In other modes, the message will be sent immediately.

After the message is queued for sending, the on_client_message_sent event will be triggered. This event does not indicate that the message has been delivered to the application. It only means that the message has been handed over to the operating system.

In case of server to server the analogeous function is s2sAddMessage.

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