diff options
Diffstat (limited to 'src/cynagora.h')
| -rw-r--r-- | src/cynagora.h | 280 |
1 files changed, 181 insertions, 99 deletions
diff --git a/src/cynagora.h b/src/cynagora.h index b77c0f4..aff1720 100644 --- a/src/cynagora.h +++ b/src/cynagora.h @@ -21,19 +21,24 @@ /******************************************************************************/ /******************************************************************************/ +/******************************************************************************/ +/* COMMON PART - types and functions common to check/admin/agent clients */ +/******************************************************************************/ typedef struct cynagora cynagora_t; typedef enum cynagora_type cynagora_type_t; typedef struct cynagora_key cynagora_key_t; -typedef struct cynagora_value cynagora_value_t; /** * type of the client interface */ -enum cynagora_type { +enum cynagora_type +{ /** type for checking permissions */ cynagora_Check, + /** type for adminstration */ cynagora_Admin, + /** type for handling agents */ cynagora_Agent }; @@ -41,7 +46,8 @@ enum cynagora_type { /** * Describes a query key */ -struct cynagora_key { +struct cynagora_key +{ /** client item of the key */ const char *client; /** session item of the key */ @@ -53,34 +59,12 @@ struct cynagora_key { }; /** - * Describes the value associated to a key - */ -struct cynagora_value { - /** the associated value */ - const char *value; - /** the expiration in seconds since epoch, negative to avoid cache */ - time_t expire; -}; - -/** - * Callback for enumeration of items (admin) - * The function is called for each entry matching the selection key - * with the key and the associated value for that entry - * - * @see cynagora_get - */ -typedef void cynagora_get_cb_t( - void *closure, - const cynagora_key_t *key, - const cynagora_value_t *value); - -/** - * Callback for receiving asynchronousely the replies to the queries + * Callback for receiving asynchronously the replies to the queries * Receives: * closure: the closure given to cynagora_async_check * status: 0 if forbidden * 1 if granted - * -ECANCELED if cancelled + * -ECANCELED if canceled */ typedef void cynagora_async_check_cb_t( void *closure, @@ -88,10 +72,10 @@ typedef void cynagora_async_check_cb_t( /** * Callback for managing the connection in an external loop - * + * * That callback receives epoll_ctl operations, a file descriptor number and * a mask of expected events. - * + * * @see epoll_ctl */ typedef int cynagora_async_ctl_cb_t( @@ -103,16 +87,16 @@ typedef int cynagora_async_ctl_cb_t( /** * Create a client to the permission server cynagora * The client is created but not connected. The connection is made on need. - * + * * @param cynagora pointer to the handle of the opened client * @param type type of the client to open - * @param cache_size requested cache size + * @param cache_size requested cache size (no cache if 0) * @param socketspec specification of the socket to connect to or NULL for * using the default - * + * * @return 0 in case of success and in that case *cynagora is filled * a negative -errno value and *cynara is set to NULL - * + * * @see cynagora_destroy, cynagora_cache_resize */ extern @@ -126,9 +110,9 @@ cynagora_create( /** * Destroy the client handler and release its memory - * + * * @param cynagora the client handler to close - * + * * @see cynagora_create */ extern @@ -140,7 +124,7 @@ cynagora_destroy( /** * Ask the client to disconnect from the server. * The client will reconnect if needed. - * + * * @param cynagora the client handler */ extern @@ -150,10 +134,40 @@ cynagora_disconnect( ); /** + * Set the asynchronous control function + * + * @param cynagora the handler of the client + * @param controlcb + * @param closure + * + * @return 0 in case of success or a negative -errno value + */ +extern +int +cynagora_async_setup( + cynagora_t *cynagora, + cynagora_async_ctl_cb_t *controlcb, + void *closure +); + +/** + * Process the inputs of the client + * + * @param cynagora the handler of the client + * + * @return 0 in case of success or a negative -errno value + */ +extern +int +cynagora_async_process( + cynagora_t *cynagora +); + +/** * Clear the cache - * + * * @param cynagora the client handler - * + * * @see cynagora_cache_resize */ extern @@ -164,12 +178,12 @@ cynagora_cache_clear( /** * Resize the cache - * + * * @param cynagora the client handler * @param size new expected cache - * + * * @return 0 on success or -ENOMEM if out of memory - * + * * @see cynagora_cache_clear, cynagora_create */ extern @@ -181,12 +195,12 @@ cynagora_cache_resize( /** * Check a key against the cache - * + * * @param cynagora the client handler * @param key the key to check - * + * * @return 0 if forbidden, 1 if authorize, -ENOENT if cache miss - * + * * @see cynagora_check */ extern @@ -199,13 +213,13 @@ cynagora_cache_check( /** * Query the permission database for the key (synchronous) * Allows agent resolution. - * + * * @param cynagora the client handler * @param key the key to check - * + * * @return 0 if permission forbidden, 1 if permission granted * or if error a negative -errno value - * + * * @see cynagora_test, cynagora_cache_check */ extern @@ -218,11 +232,11 @@ cynagora_check( /** * Query the permission database for the key (synchronous) * Avoids agent resolution. - * + * * @param cynagora the client handler * @param key - * @return - * + * @return + * * @see cynagora_check */ extern @@ -233,13 +247,63 @@ cynagora_test( ); /** + * Check the key asynchronousely (async) + * + * @param cynagora the handler of the client + * @param key the key to query + * @param simple if zero allows agent process else if not 0 forbids it + * @param callback the callback to call on reply + * @param closure a closure for the callback + * + * @return 0 in case of success or a negative -errno value + */ +extern +int +cynagora_async_check( + cynagora_t *cynagora, + const cynagora_key_t *key, + int simple, + cynagora_async_check_cb_t *callback, + void *closure +); + +/******************************************************************************/ +/* ADMIN PART - types and functions specific to admin clients */ +/******************************************************************************/ + +/** + * Describes the value associated to a key + */ +struct cynagora_value +{ + /** the associated value */ + const char *value; + /** the expiration in seconds since epoch, negative to avoid cache */ + time_t expire; +}; +typedef struct cynagora_value cynagora_value_t; + +/** + * Callback for enumeration of items (admin) + * The function is called for each entry matching the selection key + * with the key and the associated value for that entry + * + * @see cynagora_get + */ +typedef void cynagora_get_cb_t( + void *closure, + const cynagora_key_t *key, + const cynagora_value_t *value); + + +/** * List any value of the permission database that matches the key (admin, synchronous) - * + * * @param cynagora the client handler * @param key the selection key * @param callback the callback for receiving items * @param closure closure of the callback - * + * * @return 0 in case of success or a negative -errno value */ extern @@ -253,11 +317,11 @@ cynagora_get( /** * Query or set the logging of requests (admin, synchronous) - * + * * @param cynagora the client handler * @param on should set on * @param off should set off - * + * * @return 0 if not logging, 1 if logging or a negative -errno value */ extern @@ -270,13 +334,13 @@ cynagora_log( /** * Enter cancelable section for modifying database (admin, synchronous) - * + * * @param cynagora the handler of the client - * + * * @return 0 in case of success or a negative -errno value * -EPERM if not a admin client * -EINPROGRESS if already entered - * + * * @see cynagora_leave, cynagora_set, cynagora_drop */ extern @@ -287,15 +351,15 @@ cynagora_enter( /** * Leave cancelable section for modifying database (admin, synchronous) - * + * * @param cynagora the handler of the client * @param commit if zero, cancel the modifications in progress otherwise if * not zero, commit the changes - * + * * @return 0 in case of success or a negative -errno value * -EPERM if not a admin client * -ECANCELED if not entered - * + * * @see cynagora_enter, cynagora_set, cynagora_drop */ extern @@ -308,15 +372,15 @@ cynagora_leave( /** * Set a rule (either create or change it) (admin, synchronous) * This call requires to have entered the cancelable section. - * + * * @param cynagora the handler of the client * @param key the key to set * @param value the value to set to the key - * + * * @return 0 in case of success or a negative -errno value * -EPERM if not a admin client * -ECANCELED if not entered - * + * * @see cynagora_enter, cynagora_leave, cynagora_drop */ extern @@ -330,14 +394,14 @@ cynagora_set( /** * Drop items matching the key selector (admin, synchronous) * This call requires to have entered the cancelable section. - * + * * @param cynagora the handler of the client * @param key Filter of the keys to drop - * + * * @return 0 in case of success or a negative -errno value * -EPERM if not a admin client * -ECANCELED if not entered - * + * * @see cynagora_enter, cynagora_leave, cynagora_set */ extern @@ -347,53 +411,71 @@ cynagora_drop( const cynagora_key_t *key ); + +/******************************************************************************/ +/* AGENT PART - types and functions specific to agent clients */ +/******************************************************************************/ + +/** structure representing an agent query from cynagora server */ +struct cynagora_query +{ + /** name of the queried agent */ + const char *name; + + /** value associated to the matching rule */ + const char *value; + + /** key of the query */ + cynagora_key_t key; +}; +typedef struct cynagora_query cynagora_query_t; + +/** callback receiving agent queries */ +typedef int (cynagora_agent_cb_t)( + void *closure, + cynagora_query_t *query); + /** - * Set the asynchronous control function - * - * @param cynagora the handler of the client - * @param controlcb - * @param closure - * - * @return 0 in case of success or a negative -errno value + * Check if the given name is a valid agent name + * + * @param name name to check + * @return 0 when invalid or 1 if valid */ extern int -cynagora_async_setup( - cynagora_t *cynagora, - cynagora_async_ctl_cb_t *controlcb, - void *closure +cynagora_agent_is_valid_name( + const char *name ); /** - * Process the inputs of the client - * - * @param cynagora the handler of the client - * - * @return 0 in case of success or a negative -errno value + * Create an agent of a given name + * + * @param cynagora the client + * @param name name of the agent to create + * @param agentcb callback that will treat queries for the agent + * @param closure closure for the callback + * @return 0 on success */ extern int -cynagora_async_process( - cynagora_t *cynagora +cynagora_agent_create( + cynagora_t *cynagora, + const char *name, + cynagora_agent_cb_t *agentcb, + void *closure ); /** - * Check the key asynchronousely (async) - * - * @param cynagora the handler of the client - * @param key the key to query - * @param simple if zero allows agent process else if not 0 forbids it - * @param callback the callback to call on reply - * @param closure a closure for the callback - * - * @return 0 in case of success or a negative -errno value + * Reply to the query. After calling that function, the query is not more + * valid (removed from memory). + * + * @param query the query to reply + * @param value the value that the agent wants to reply to the query + * @return 0 on success or a negative error code */ extern int -cynagora_async_check( - cynagora_t *cynagora, - const cynagora_key_t *key, - int simple, - cynagora_async_check_cb_t *callback, - void *closure +cynagora_agent_reply( + cynagora_query_t *query, + cynagora_value_t *value ); |