gc_client

NAME

gc_client_start - establishes a session with the application.

SYNOPSIS

#include <game-carrier/client.h>

GC_CLIENT_API
GCT_INT gc_client_start(
    GCT_INTPTR conn_user,
    GCT_INT proto,
    GCT_CSTR host,
    GCT_INT port,
    GCT_CSTR app_name,
    struct client_events * events);

Parameters:

conn_user GCT_INTPTR User data associated with a connection.
proto GCT_INT WebSocket protocol version.
host GCT_CSTR Domain name or IP address of the server.
port GCT_INT Server port number.
app_name GCT_CSTR Application name.
events pointer to the client_events struct.

RETURN VALUE

Returns 0 if the operation is successful.

Standard errno codes like EINVAL or ENOMEM are returned if creation/allocation fails.

DESCRIPTION

The gc_client_start function establishes a client session with a Game Carrier server application and returns an error code where 0 means success.

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.

When proto parameter is set to GC_PROTOCOL_WSS, this method will use the WebSocket Secure(WSS) protocol. Otherwise, when set to GC_PROTOCOL_WS (1), an unencrypted version of WebSocket is used.

The host parameter represents the fully qualified domain name(FQDN) of the game server, for instance "https://yourgame.server.com", or an IP address string.

The port parameter specifies the port number to establish the connection with the server. The port number must be set during the configuration of the game server.

The app_name parameter specifies the unique application name. This parameter is used to distinguish the app you want to connect to from other apps running on the server. By passing NULL to this parameter, you instruct the function to connect to a default application associated with a specific host/port configuration set in the server’s config file.

The events parameter specifies the pointer to the client_events struct.

You must invoke this function only if the gc_clients_init was invoked beforehand.

If gc_client_start fails and returns a nonzero error code, no events will occur. On the other hand, if gc_client_start succeeds (returns 0), the on_client_connect or on_client_connection_error event will be called subsequently.

The connection descriptor representing a handle to the client session that has established will be received in on_client_connect event. This handle is represented as the client_handle parameter in other library functions.

In Passive mode, connections are not established until the gc_clients_service is called.

In Hybrid mode, connections are immediately established, but notifications about connection status or errors are only sent when gc_clients_service is called.

In Active mode, connections are immediately established, and notifications about connection status or errors are delivered immediately, however, this may occur in an arbitrary thread.

In case of server to server connection the analogeous function is s2sCreate.

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

NAME

SYNOPSIS

RETURN VALUE

DESCRIPTION

EXAMPLE

SEE ALSO