NAME

on_client_connect - event gets triggered when a connection is established with the server application.

SYNOPSIS

#include <game-carrier/common.h>

typedef void (*OnClientConnect)(GCT_INTPTR conn_user, GCT_INTPTR handle);

typedef struct on_client_connect {
    /* ... Some fields ... */
    OnClientConnect on_client_connect;
    /* ... Some fields ... */
}

Parameters:

  • conn_user GCT_INTPTR User data associated with a connection.
  • handle GCT_INTPTR Connection handler to use in API.

RETURN VALUE

None.

DESCRIPTION

The on_client_connect event is a member of client_events struct. It is triggered upon establishing a connection to the Game Carrier application, following a successful call of the gc_client_start 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 handle parameter represents a server-to-server connection handle. This value can be passed to all API functions, such as s2sAddMessage.

The on_client_connect event serves as the initial event for a specific connection, guaranteeing that only one of the events on_client_connect or on_client_connection_error will be triggered when a connection attempt is made.

Subsequently, the established connection can generate events such as on_client_message, on_client_message_sent, on_client_timer, and on_client_disconnect.

Only when the connection is established, you can utilize such functions as s2sAddMessage, s2sSetTimer, s2sDestroy.

During normal execution, it is guaranteed that the on_client_disconnect event will be always called after the on_client_connect event, providing a reliable sequence of events.

EXAMPLE

#include <game-carrier/server.h>

#include <stdio.h>

static struct core_api api;

#define STAT_SERVER 1
#define CACHE_SERVER 2

GCT_INT adapter_id;
GCT_INTPTR s2s_stat_handle, s2s_cache_handle;

GC_ADAPTER_EVENT
GCT_INT adapter_initialize(
    GCT_INT id,
    struct core_api * core_api,
    GCT_CPTR load_path)
{
    adapter_id = id;
    api = *core_api;
}

void on_client_connect(GCT_INTPTR conn_user, GCT_INTPTR handle)
{
    if (conn_user == STAT_SERVER) {
        api.logMessage(GCL_NOTICE, "Connected to the stat server");
        s2s_stat_handle = handle;
        api.s2sDestroy(s2s_stat_handle);
        return;
    }

    if (conn_user == CACHE_SERVER) {
        api.logMessage(GCL_NOTICE, "Connected to the cache server");
        s2s_cache_handle = handle;
        api.s2sDestroy(s2s_cache_handle);
        return;
    }

    api.logMessage(GCL_ERR, "??? Connected to an unknown server");
}

void on_client_connection_error(GCT_INTPTR conn_user, GCT_CSTR reason)
{
    char buf[256];

    if (conn_user == STAT_SERVER) {
        snprintf(buf, sizeof(buf), "Failed to connect to the stat server: %s.", reason);
        api.logMessage(GCL_ERR, buf);
        return;
    }

    if (conn_user == CACHE_SERVER) {
        snprintf(buf, sizeof(buf), "Failed to connect to the cache server: %s", reason);
        api.logMessage(GCL_ERR, buf);
        return;
    }

    snprintf(buf, sizeof(buf), "??? Failed to connect to an unknown server: %s", reason);
    api.logMessage(GCL_ERR, buf);
}

void on_client_disconnect(GCT_INTPTR conn_user)
{
    if (conn_user == STAT_SERVER) {
        api.logMessage(GCL_NOTICE, "Disconect from stat server");
        return;
    }

    if (conn_user == CACHE_SERVER) {
        api.logMessage(GCL_NOTICE, "Disconect from cache server");
        return;
    }

    api.logMessage(GCL_ERR, "??? Disconect from unknown server");
}

GC_ADAPTER_EVENT
void application_start(GCT_INT app_id)
{
    int status;

    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;

    status = api.s2sCreate(adapter_id, STAT_SERVER, GC_PROTOCOL_WSS, "stat.example.com", 7681, "stat", &events);
    if (status != 0) {
        api.logMessage(GCL_ERR, "Failed to connect to the game server.");
    }

    status = api.s2sCreate(adapter_id, CACHE_SERVER, GC_PROTOCOL_WSS, "cache.example.com", 7681, "cache", &events);
    if (status != 0) {
        api.logMessage(GCL_ERR, "Failed to connect to the lobby server.");
    }
}

SEE ALSO

s2sCreate, on_client_connection_error, on_client_disconnect