NAME

gc_client_stop - closes a specific active connection.

SYNOPSIS

#include <game-carrier/client.h>

GC_CLIENT_API
void gc_client_stop(
    GCT_INTPTR client_handle);

Parameters:

  • client_handle GCT_INTPTR The client connection handle.

RETURN VALUE

None.

DESCRIPTION

The gc_client_stop function closes a specific active connection established with the Game Carrier server application. It must be called only after successful receiving on_client_connect event.

The client_handle parameter represents the client connection handle, which is used to identify a specific connection that must be closed. The handle is returned after a successful connection is established in the on_client_connect event.

After calling gc_client_stop function all messages, added by the gc_client_add_message function, will be sent. At the same time, it will not process any new messages.

There is a possibility of receiving on_client_message events after the successful gc_client_stop call. It happens when a message is received and queued up to be processed by the application, but at that moment the application hasn’t had a chance to handle it yet. In that case, the message will still be processed and the on_client_message event will be triggered, even if gc_client_stop has been called and the connection is being closed.

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

EXAMPLE

#include <game-carrier/client.h>

#include <stdio.h>
#include <string.h>

/**
 * The example below connects to a server,
 * waits for a message and then it disconnects.
 **/

#define GAME_CLIENT   1
#define MAGIC_COOKIE 42

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;
        char * msg = "Hello!";
        gc_client_add_message(game_conn, msg, strlen(msg), MAGIC_COOKIE);
        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 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_stop(game_conn);
        return;
    }

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

void on_client_message_sent(
    GCT_INTPTR conn_user,
    GCT_INTPTR cookie,
    GCT_SIZE len,
    GCT_INT status)
{
    if (conn_user != GAME_CLIENT) {
        fprintf(stderr, "??? Unknown message sent\n");
        return;
    }

    if (cookie != MAGIC_COOKIE) {
        fprintf(stderr, "??? Unexpected cookie received: " PRId64, cookie);
        return;
    }

    if (status != 0) {
        fprintf(stderr, "Failed to send message, error code is %d\n", status);
        return;
    }

    printf("Message sent OK\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_message = on_client_message;

    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_connect, on_client_disconnect