C API Basic Functions

Basic Functions

Introduction

This section describes basic function that are intended for connection to verse server and user authentication. When you want to use verse library in your code, then you have to include appropriate header file:

#include <verse.h>

When you want to send some command to the verse server, then you have to call 'vrs_send_ command. Example:

int my_session_id, ret;
ret = vrs_send_connect_request("localhost", "12345", 0, &my_session_id);

When we want to be notified about received command, then we have to do two things. Call periodically vrs_callback_update function:

/* Never ending loop */
while(1) {
  vrs_callback_update(my_session_id);
  sleep(1);
}

and we have to register two basic callback functions (vrs_register_receive_user_authenticate, vrs_register_receive_connect_accept and vrs_register_receive_connect_terminate). When these three callback functions are not registered, then you can not connect to verse server.

The verse library uses concept of callback functions. These callback functions are registered with vrs_register_receive_ functions that has one argument: pointer at your callback function. This callback function is called, when corresponding command is received (not immediately, but when vrs_callback_update is called). Example of callback function and registration of callback function:

void cb_receive_connect_terminate(const uint8_t session_id,
    const uint8_t error_code)
{
    printf("session_id: %d, exited with error code: %d\n",
        session_id, error_code);
    exit(EXIT_SUCCESS);
}

int main(void)
{
    /* Registration of callback function, that is called,
       when connection with server is closed */
    vrs_register_receive_connect_terminate(cb_receive_connect_terminate);
}

Connection and User Authentication

Before you connect to Verse server, you can set some optional information about your Verse client (name and version number). These information will be visible to other users in special info node then. This information can be set only once. Setting these information after connecting to Verse server is useless, because this information is negotiated only during handshake with Verse server.

int vrs_set_client_info(char *name, char *version);

You can connect to Verse server with following function:

int32_t vrs_send_connect_request(const char *hostname,
    const char *service,
    const uint16_t flags,
    uint8_t *session_id);

Parameter hostaneme could be hostname or IP address of server. service is port number or service name defined in /etc/services. This function set up session_id, which is unique ID of session. This ID is used in other callback function.

The argument flags could be set to following bits ():

#define VRS_DGRAM_SEC_NONE      1   /* No security at datagram connection */
#define VRS_DGRAM_SEC_DTLS      2   /* DTLS at datagram connection */
#define VRS_TP_UDP              4   /* Transport protocol: UDP*/
#define VRS_TP_TCP              8   /* Transport protocol: TCP */
#define VRS_NO_CMD_CMPR         16  /* No command compression */

void vrs_register_receive_user_authenticate(
    void (*func)(const uint8_t session_id,
    const char *username,
    const uint8_t auth_methods_count,
    const uint8_t *methods))

This function is used for registration a callback function, which is called, when user is asked for password. When username has zero length (this callback function is called at the first time), then client is asked by server only for username and client has to send only username in following function call:

int32_t vrs_send_user_authenticate(const uint8_t session_id,
    const char *username,
    const uint8_t auth_type,
    const uint8_t data_length,
    const char *data)

Supported authentication types are:

• VRS_UA_METHOD_NONE = 1
• VRS_UA_METHOD_PASSWORD = 2

void vrs_register_receive_connect_accept(
    void (*cb_connect_accept)(const uint8_t session_id,
    const uint32_t user_id,
    const uint32_t avatar_id));

This function is used for registering cb_connect_accept() callback function. cb_connect_accept() is executed, when handshake between client and server is finished and new communication thread is created. session_id unambiguously identify connection corresponding connection request, because it is the same value as value returned by vrs_send_connect_request(). user_id is unique user ID. avatar_id is unique ID of avatar node, which represents client application at server.

int32_t vrs_send_connect_terminate(const uint8_t session_id,
    const char error_num);

This function is called from main thread to terminate connection.

void vrs_register_receive_connect_terminate(
    void (*cb_connect_terminate)(const uint8_t session_id,
    const uint8_t error_code));

This function is used for registering cb_connect_terminate() callback function. cb_connect_terminate() is executed, when teardown between client and server is finished or, when connection to the server is lost, or handshake was not finished for some reason. This reason is stored in error_code and it could have following values:

 #define VRS_CONN_TERM_RESERVED      0 /* Reserved code */
 #define VRS_CONN_TERM_HOST_UNKNOWN  1 /* Host could not be found */
 #define VRS_CONN_TERM_HOST_DOWN     2 /* Host is not accessible */
 #define VRS_CONN_TERM_SERVER_DOWN   3 /* Server isn't running */
 #define VRS_CONN_TERM_AUTH_FAILED   4 /* Bad username or password */
 #define VRS_CONN_TERM_TIMEOUT       5 /* Connection timed out */
 #define VRS_CONN_TERM_ERROR         6 /* Connection was broken */
 #define VRS_CONN_TERM_CLIENT        7 /* Connection terminated by client */
 #define VRS_CONN_TERM_SERVER        8 /* Connection terminated by server */

int32_t vrs_callback_update(uint8_t session_id);

This function is called from main application thread. When this function is called and there are some system or node commands in queue, then appropriate callback functions are executed.

char *vrs_strerror(const int32_t error_num);

Some functions called from main thread can return some int32_t variable with error number. This function could be used to get the string of the error. (Not fully implemented yet)

Following function could be used to set current FPS of client application. This value is then negotiated with Verse server and Verse server will send with negotiated FPS rate (higher rate of sending then negotiated FPS would be useless).

int32_t vrs_send_fps(const uint8_t session_id,
    const uint8_t prio,
    const float fps);

When you want to see more debug messages, then you can adjust it with following function:

int32_t vrs_set_debug_level(uint8_t debug_level);

The parameter debug_level could have following values:

VRS_PRINT_NONE, VRS_PRINT_INFO, VRS_PRINT_ERROR, VRS_PRINT_WARNING, VRS_PRINT_DEBUG_MSG:

Client should be able to set maximal size of outgoing queue and it should be able to get information about current maximal size of outgoing queue and free space in outgoing queue. It is important, when client want to 'upload' big data to Verse server. Client should not send everything in one step (put everything to outgoing queue). Default size of outgoing queue is 1MB. Client should be able to control maximal size of incoming queue due to Flow Control.

Call following function to get parameters of session:

int32_t vrs_get(const uint8_t session_id,
    const uint8_t param);

Previous function can set some parameters of session. The param can have following values:

#define VRS_SESSION_IN_QUEUE_MAX_SIZE     1
#define VRS_SESSION_IN_QUEUE_FREE_SPACE   2
#define VRS_SESSION_OUT_QUEUE_MAX_SIZE    3
#define VRS_SESSION_OUT_QUEUE_FREE_SPACE  4

It is possible to set maximal size of incoming and outgoing queue using following function. It will be possible to set other parametrs of session in the future.

int32_t vrs_set(const uint8_t session_id,
    const uint8_t param,
    const uint32_t value);

Previous function can be used for setting some parameters of session. The param can have following values:

#define VRS_SESSION_IN_QUEUE_MAX_SIZE    1
#define VRS_SESSION_OUT_QUEUE_MAX_SIZE   3