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 connection handle. This value can be passed to all API functions, such as gc_client_add_message.

In Passive and Hybrid modes, the on_client_connect 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_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 gc_client_add_message, gc_client_set_timer, gc_client_stop.

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/client.h>

#include <stdio.h>

#define GAME_CLIENT 1
#define LOBBY_CLIENT 2

int mode = GC_MODE_HYBRID;
GCT_INTPTR game_conn, lobby_conn;

/**
 * Counter for finished client sessions.
 * We have two sessions: game and lobby.
 * The application will be closed when both sessions are finished.
 **/

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;
        gc_client_stop(game_conn);
        return;
    }

    if (conn_user == LOBBY_CLIENT) {
        printf("Connected to the lobby server\n");
        lobby_conn = handle;
        gc_client_stop(lobby_conn);
        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 to connect to the game server: %s\n", reason);
        return;
    }

    if (conn_user == LOBBY_CLIENT) {
        fprintf(stderr, "Failed to connect to the lobby server: %s\n", reason);
        return;
    }

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

 void on_client_disconnect(GCT_INTPTR conn_user)
 {
     ++finished;
 }

 int main(int argc, char * argv[])
 {
     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;

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

     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;
     }

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

     // Wait Loop //
     while (finished != 2) {

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

         // Handling the 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_connection_error, on_client_disconnect