NAME

connectionClose - closes the connection with the client.

SYNOPSIS

#include <game-carrier/server.h>

typedef GCT_INT (GC_CORE_API *ConnectionClose)(
    GCT_INTPTR conn_handle,
    GCT_INT reason);

typedef struct connectionClose {
    /* ... Some fields ... */
    ConnectionClose connectionClose;
    /* ... Some fields ... */
}

Parameters:

• conn_handle GCT_INTPTR Unique identifier of the connection.
• reason GCT_INT Reason for disconnecting a connection.

RETURN VALUE

Returns 0 if the invocation is successful.

Returns an error code, such as EINVAL, if the function is called with invalid or incorrect arguments.

DESCRIPTION

The connectionClose function is utilized on the server side to correctly close a connection. It allows the server to terminate the connection in a controlled manner, ensuring that all necessary steps are taken to properly conclude the communication session. By invoking this function, the server initiates the process of closing the connection, freeing up any associated resources, and terminating the established network link between the server and the client.

The conn_handle parameter represents the connection handle that was previously passed to the on_connect call. It serves as a reference to the specific connection that triggered the event.

The reason parameter identifies the reason for disconnecting a connection. It can take on one of the following constants: GC_CLOSE_REASON_NORMAL (0) - This constant is used to correctly close a connection. It ensures that all messages in the queue will be delivered, and any pending operations will be completed before the connection is closed. GC_CLOSE_REASON_DROP (1) - This constant is used to drop a connection. It causes all messages in the queue to be discarded, and any pending operations to be aborted, before closing the connection.

EXAMPLE

#include <game-carrier/server.h>

#include <stdlib.h>

static struct core_api api;

struct connection_data {
    GCT_INTPTR conn_handle;
    /* user data associated with connection */
};

GC_ADAPTER_EVENT
GCT_INT adapter_initialize(
    GCT_INT id,
    struct core_api * core_api,
    GCT_CPTR load_path)
{
    api = *core_api;
    return 0;
}

GC_ADAPTER_EVENT
GCT_INTPTR on_connect(
    GCT_INT app_id,
    GCT_INTPTR conn_handle,
    GCT_INT pid,
    GCT_CSTR rip,
    GCT_INT rport,
    GCT_CSTR lip,
    GCT_INT lport,
    GCT_CSTR udata)
{
    struct connection_data * data = malloc(sizeof(struct connection_data));
    /* No memory, failed */
    if (data == NULL) {
        return GC_DROP_CONNECTION;
    }

    data->conn_handle = conn_handle;
    /* initialize other fields */
    return (GCT_INTPTR)data;
}

GC_ADAPTER_EVENT
void on_disconnect(
    GCT_INTPTR conn_user)
{
    struct connection_data * data = (struct connection_data *)conn_user;
    /* Deallocate user connection data */
    free(data);
}

void close_connection(struct connection_data * data)
{
    api.connectionClose(data->conn_handle, GC_CLOSE_REASON_NORMAL);
}

SEE ALSO

on_connect, on_disconnect, gc_close_reason