GUAC-1389: Document client process map manipulation functions.

This commit is contained in:
Michael Jumper 2016-03-02 15:34:39 -08:00
parent d595d96304
commit 26bdd9bc38
2 changed files with 81 additions and 14 deletions

View File

@ -32,7 +32,13 @@
#include <string.h>
/**
* Returns a hash code based on the connection ID of the given client.
* Returns a hash code based on the given connection ID.
*
* @param str
* The string containing the connection ID.
*
* @return
* A reasonably well-distributed hash code for the given string.
*/
static unsigned int __guacd_client_hash(const char* str) {
@ -48,10 +54,22 @@ static unsigned int __guacd_client_hash(const char* str) {
}
/**
* Locates the bucket corresponding to the hash code indicated by the give id.
* Each bucket is an instance of guac_common_list.
* Locates the bucket corresponding to the hash code indicated by the given id,
* where the hash code is dictated by __guacd_client_hash(). Each bucket is an
* instance of guac_common_list.
*
* @param map
* The map to retrieve the hash bucket from.
*
* @param id
* The ID whose hash code determines the bucket being retrieved.
*
* @return
* The bucket corresponding to the hash code for the given ID, represented
* by a guac_common_list.
*/
static guac_common_list* __guacd_proc_find_bucket(guacd_proc_map* map, const char* id) {
static guac_common_list* __guacd_proc_find_bucket(guacd_proc_map* map,
const char* id) {
const int index = __guacd_client_hash(id) % GUACD_PROC_MAP_BUCKETS;
return map->__buckets[index];
@ -59,11 +77,24 @@ static guac_common_list* __guacd_proc_find_bucket(guacd_proc_map* map, const cha
}
/**
* Given a list of guacd_proc instances, returns the
* guacd_proc having the guac_client with the given ID, or NULL if no
* such client is stored.
* Given a bucket of guacd_proc instances, returns the guacd_proc having the
* guac_client with the given ID, or NULL if no such client is stored.
*
* @param bucket
* The bucket of guacd_proc instances to search, represented as a
* guac_common_list.
*
* @param id
* The ID of the guac_client whose corresponding guacd_proc instance should
* be located within the bucket.
*
* @return
* The guac_common_list_element containing the guacd_proc instance
* corresponding to the guac_client having the given ID, or NULL of no such
* element exists.
*/
static guac_common_list_element* __guacd_proc_find(guac_common_list* bucket, const char* id) {
static guac_common_list_element* __guacd_proc_find(guac_common_list* bucket,
const char* id) {
guac_common_list_element* current = bucket->head;

View File

@ -50,27 +50,63 @@ typedef struct guacd_proc_map {
} guacd_proc_map;
/**
* Allocates a new client process map, which persists for the life of guacd.
* Allocates a new client process map. There is intended to be exactly one
* process map instance, which persists for the life of guacd.
*
* @return
* A newly-allocated client process map.
*/
guacd_proc_map* guacd_proc_map_alloc();
/**
* Adds the given process to the client process map. On success, zero is returned. If
* adding the client fails (due to lack of space, or duplicate ID), a non-zero
* value is returned instead. The client process is stored by the connection ID
* of the underlying guac_client.
* Adds the given process to the client process map. On success, zero is
* returned. If adding the client fails (due to lack of space, or duplicate
* ID), a non-zero value is returned instead. The client process is stored by
* the connection ID of the underlying guac_client.
*
* @param map
* The map in which the given client process should be stored.
*
* @param proc
* The client process to store in the given map.
*
* @return
* Zero if the process was successfully stored in the map, or non-zero if
* storing the process fails for any reason.
*/
int guacd_proc_map_add(guacd_proc_map* map, guacd_proc* proc);
/**
* Retrieves the client process having the client with the given ID, or NULL if
* no such process is stored.
*
* @param map
* The map from which to retrieve the process associated with the client
* having the given ID.
*
* @param id
* The ID of the client whose process should be retrieved.
*
* @return
* The process associated with the client having the given ID, or NULL if
* no such process exists.
*/
guacd_proc* guacd_proc_map_retrieve(guacd_proc_map* map, const char* id);
/**
* Removes the client process having the client with the given ID, returning
* the corresponding process. If no such process exists, NULL is returned.
*
* @param map
* The map from which to remove the process associated with the client
* having the given ID.
*
* @param id
* The ID of the client whose process should be removed.
*
* @return
* The process associated with the client having the given ID which has now
* been removed from the given map, or NULL if no such process exists.
*/
guacd_proc* guacd_proc_map_remove(guacd_proc_map* map, const char* id);