diff options
Diffstat (limited to 'src/kiro-client.h')
| -rw-r--r-- | src/kiro-client.h | 93 |
1 files changed, 92 insertions, 1 deletions
diff --git a/src/kiro-client.h b/src/kiro-client.h index 8e99877..9e9d3ef 100644 --- a/src/kiro-client.h +++ b/src/kiro-client.h @@ -70,20 +70,111 @@ struct _KiroClientClass { /* GObject and GType functions */ +/** + * kiro_client_get_type: (skip) + * Returns: GType of #KiroClient + */ GType kiro_client_get_type (void); +/** + * kiro_client_new - Creates a new #KiroClient + * Returns: (transfer full): A pointer to a new #KiroClient + * Description: + * Creates a new, unconnected #KiroClient and returns a pointer to it. + * See also: + * kiro_client_free, kiro_client_connect + */ KiroClient* kiro_client_new (void); +/** + * kiro_client_free - 'Destroys' the given #KiroClient + * @client: (transfer none): The #KiroClient that is to be freed + * Description: + * Transitions the #KiroServer through all necessary shutdown routines and + * frees the object memory. + * Note: + * The memory content that has been transfered from the server is + * automatically freed when calling this function. If you want to continue + * using the memory after freeing the #KiroClient, make sure to memcpy() it + * first, using the informations obtained from kiro_client_get_memory() and + * kiro_client_get_memory_size(). + * See also: + * kiro_client_new, kiro_client_connect + */ void kiro_client_free (KiroClient *client); /* client functions */ + +/** + * kiro_client_connect - Connect a #KiroClient to a Server + * @client: (transfer none): The #KiroClient to connect + * @dest_addr: (transfer none): The address of the target server + * @dest_port: (transfer none): The port of the target server + * Returns: + * 0 if the connection was successful, -1 in case of connection error + * Description: + * Connects the given #KiroClient to a KIRO server described by @dest_addr and + * @dest_port. + * Note: + * When building a connection to the server, memory for the transmission is + * created as well. + * See also: + * kiro_server_new + */ int kiro_client_connect (KiroClient *client, const char *dest_addr, const char *dest_port); +/** + * kiro_client_sync - Read data from the connected server + * @client: (transfer none): The #KiroServer to use sync on + * Returns: + * 0 if successful, -1 in case of synchronisation error + * Description: + * This synchronizes the client with the server, clining the memory + * provided by the server to the local client. The memory can be accessed by + * using kiro_client_get_memory(). + * Note: + * The server can send a 'reallocation' request to the client, forcing it to + * reallocate new memory with the next occurrence of kiro_client_sync(), + * freeing the old memory in the process. + *See also: + * kiro_client_get_memory, kiro_cient_connect + */ int kiro_client_sync (KiroClient *client); -void *kiro_client_get_memory (KiroClient *client); +/** + * kiro_client_get_memory - Return a pointer to the current client memory + * @client: (transfer none): The #KiroClient to get the memory from + * Returns: (transfer none): + * A pointer to the current memory of the client. + * Note: + * The server can instruct the client to reallocate memory on the next + * occurrence of kiro_client_sync(), freeing the old memory. Also, calling + * kiro_client_free() will free the client memory as well. If you need to + * make sure that the memory from the @client remains accessible after + * calling sync and/or free, you need to memcpy() the memory using the + * information from kiro_client_get_memory() and + * kiro_client_get_memory_size() first. + * The returned memory might under NO circumstances be freed by the user! + * See also: + * kiro_client_get_memory_size, kiro_client_sync + */ +void* kiro_client_get_memory (KiroClient *client); +/** + * kiro_client_get_memory_size - Return the client memory size in bytes + * @client: (transfer none): The #KiroClient to get the memory size of + * Returns: + * The size of the given #KiroClient memory in bytes + * Description: + * Returns the size of the allocated memory of @client, in bytes. + * Note: + * The server can instruct the client to reallocate memroy on the next + * occurrence of kiro_server_sync(), freeing the old memory. This might also + * effect the respective memory size. + * See also: + * kiro_client_get_memory, kiro_client_sync + */ size_t kiro_client_get_memory_size (KiroClient *client); G_END_DECLS |