# Establishing An Active Session

This method establishes a client session with a game server and returns a descriptor representing a handle to the client session that was established with the server. This handle can be used to send and receive messages to and from the server using other methods in the API.

To terminate the session refer to the description of the [gc_client_stop](https://hackmd.io/@vldsg/B1wdk7nZ3) method.

## Method

intptr_t gc_client_start(
    intptr_t user,
    int proto,
    const char * host,
    int port,
    const char * app_name,
    struct client_events * events);

| Parameter | Data Type | Supported Values | Default Value | Description |
|------------------------|-----------|------------------------------------------------|---------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name | intptr_t | - | - | A unique identifier of the server to connect to. |
| proto | int | **0** - SSL WebSocket. **1** - WebSocket | 0 | When this parameter is set to 0, this method will use the secure(SSL) WebSocket protocol. Otherwise, when set to 1, an unencrypted version of WebSocket is used. |
| * host | char | - | - | Fully qualified domain name(FQDN) of the game server, for instance https://yourgame.server.com. |
| port | int | - | - | Set the port number to establish the connection. The port number must be set during the configuration of the game server. |
| * app_name | char | - | - | Specify the unique application name. This parameter is used to distinguish the app you want to connect to from other apps running on the server. |
| client_events * events | struct | Refer to the [client_events struct](https://hackmd.io/@vldsg/ryfNobnZn) description. | - | The client_events struct dictates the behavior of the method in such networking phases as connection, disconnection, connection error and other. |

## Return Value

Returns an **intptr_t** value which represents a handle to the client session that was established with the server.

> **_NOTE:_** The **intptr_t** value is also represented as the **client_id** parameter across other APIs that interact with the server. For instance, those methods can be responsible for [terminating an active session](https://hackmd.io/NSPOiO8HS2eL4oyC_7dvpQ) or [sending a message to the server](https://hackmd.io/J0ICo1SHSoaJb9AeZH4FdQ), in both cases the **client_id** parameter is required to identify an active session.

## Example

> GPT Generated Output

This code initializes the **client_events_t** struct with the event handlers and calls **gc_client_start** with the appropriate parameters to establish a session with the game server. It then waits for the user to manually terminate the session before exiting the program.

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

int main() {
    // Initialize the events struct
    client_events_t events = {
        .on_client_connect = on_client_connect,
        .on_client_disconnect = on_client_disconnect,
        .on_client_connection_error = on_client_connection_error,
        .on_client_message = on_client_message,
        .on_client_message_sent = on_client_message_sent,
        .on_client_timer = on_client_timer
    };

    // Call gc_client_start with the appropriate parameters
    intptr_t user = 12345;
    int proto = 0;
    const char* host = "https://yourgame.server.com";
    int port = 1234;
    const char* app_name = "my_app_name";
    intptr_t session = gc_client_start(user, proto, host, port, app_name, &events);

    // Check if session was established successfully
    if (session == 0) {
        printf("Failed to establish session\n");
        return 1;
    }

    // Wait for the user to manually terminate the session
    printf("Press any key to terminate session\n");
    getchar();

    return 0;
}