NAME

gc_client_set_timer - schedules a timed event for a connection.

SYNOPSIS

#include <game-carrier/client.h>

GC_CLIENT_API
GCT_INT gc_client_set_timer(
    GCT_INTPTR client_handle,
    GCT_INT ms);

Parameters:

  • client_handle GCT_INTPTR The client connection handle.
  • ms GCT_INT Identifies the timer interval in milliseconds.

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_set_timer is used to schedule a timed event for a connection established with the Game Carrier server application. It allows you to set a timer interval in milliseconds, after which the on_client_timer event will be triggered.

The client_handle parameter represents the client connection handle, which is used to identify a specific connection for which the timer event is being scheduled. The handle is returned after the successful connection establishing in on_client_connect event.

The ms parameter is used to specify the timer interval in milliseconds. It determines the duration after which the timer event will be triggered for the specified client connection.

This function should be called following a successful receipt of the on_client_connect event.

You can use gc_client_set_timer to schedule events or actions that need to occur after a specific time interval. For example, you might use it to periodically send a heartbeat message to the server or to check for updates at regular intervals.

When the connection is still established and the timer expires, the on_client_timer event will be triggered. Each connection supports only one timer. If a new timer is set by the game, the old timer will be automatically canceled. Please note that the timer does not have a high resolution, making it unsuitable for precise timing purposes.

In Passive and Hybrid modes, the event will be called in the same thread as the gc_clients_service call, and the timer will also be invoked within the context of the gc_clients_service call.

However, in Active mode, the event may be triggered in an arbitrary thread.

Refer to the description of the gc_clients_init function to learn more about supported modes.

If you are dealing with server-to-server interactions, the corresponding function is s2sSetTimer.

EXAMPLE

#include <game-carrier/client.h>

#include <stdio.h>

#define GAME_CLIENT 1
#define TIMER_DURATION  1000

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;
        gc_client_set_timer(game_conn, TIMER_DURATION);
        return;
    }

    printf("??? Connected to the 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_set_timer(game_conn, GC_CANCEL_TIMER);
        gc_client_stop(game_conn);
        return;
    }

    printf("??? Received message from an unknown server: %s\n", (char*)data);
}

void on_client_timer(GCT_INTPTR conn_user)
{
    if (conn_user == GAME_CLIENT) {
        fprintf(stderr, "Timer expired, no answer in time!\n");
        gc_client_stop(game_conn);
        return;
    }

    fprintf(stderr, "??? Timer has expired for an unknown connection\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_timer = on_client_timer;

    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_timer, on_client_connect