NAME

on_client_connection_error - is invoked when the connection to the server app fails.

SYNOPSIS

#include <game-carrier/common.h>

typedef void (*OnClientConnectionError)(GCT_INTPTR conn_user, GCT_CSTR reason);

typedef struct on_client_connection_error {
    /* ... Some fields ... */
    OnClientConnectionError on_client_connection_error;
    /* ... Some fields ... */
}

Parameters:

  • conn_user GCT_INTPTR User data associated with the connection.
  • reason GCT_CSTR String value containing the error message.

RETURN VALUE

None.

DESCRIPTION

The on_client_connection_error event is a member of client_events struct. The on_client_connection_error event handler is invoked when the connection to the Game Carrier application fails. It is called after a successful invocation 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 reason parameter identifies a string value that contains an error description. It provides an arbitrary description for logging purposes only, without any standardized messages defined.

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

After the on_client_connection_error event is triggered, it is prohibited to call any API functions for that connection. To establish a new connection, you must call the gc_client_start again.

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_connect