From 8f1c3c3135cc40aef3129446fc01bdec9d7a9be5 Mon Sep 17 00:00:00 2001 From: Francois Gouget Date: Wed, 30 Nov 2016 09:00:00 +0100 Subject: [PATCH] udscs: Improve the udscs API documentation Document what happens whenever passing a NULL server or connection pointer is allowed. Make it clear that only pathname Unix domain sockets are supported. Also document when no_types and the type_to_string array are used and what for. Signed-off-by: Francois Gouget --- src/udscs.h | 62 +++++++++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 50 insertions(+), 12 deletions(-) diff --git a/src/udscs.h b/src/udscs.h index 6e960f8..6160568 100644 --- a/src/udscs.h +++ b/src/udscs.h @@ -57,33 +57,55 @@ typedef void (*udscs_read_callback)(struct udscs_connection **connp, */ typedef void (*udscs_disconnect_callback)(struct udscs_connection *conn); -/* Connect to a unix domain socket named name. */ +/* Connect to the unix domain socket specified by socketname. + * Only sockets bound to a pathname are supported. + * + * If debug is true then the events on this connection will be traced. + * This includes the incoming and outgoing message names. So when debug is true + * no_types must be set to the value of the highest valid message id + 1, + * and type_to_string must point to a string array of size no_types for + * converting the message ids to their names. + */ struct udscs_connection *udscs_connect(const char *socketname, udscs_read_callback read_callback, udscs_disconnect_callback disconnect_callback, const char * const type_to_string[], int no_types, int debug); -/* The contents of connp will be made NULL. */ +/* Close the connection, releases the corresponding resources and + * sets *connp to NULL. + * + * Does nothing if *connp is NULL. + */ void udscs_destroy_connection(struct udscs_connection **connp); +/* Given a udscs client, fill the fd_sets pointed to by readfds and + * writefds for select() usage. + * Return value: value of the highest fd + 1 or -1 if conn is NULL + */ int udscs_client_fill_fds(struct udscs_connection *conn, fd_set *readfds, fd_set *writefds); -/* Note the connection may be destroyed (when disconnected) by this call - * in this case the disconnect calllback will get called before the - * destruction and the contents of connp will be made NULL. +/* Handle any events flagged by select for the given udscs client. + * Note that upon disconnection this will call the disconnect callback + * and then destroy the connection which will set *connp to NULL. + * + * Does nothing if *connp is NULL. */ void udscs_client_handle_fds(struct udscs_connection **connp, fd_set *readfds, fd_set *writefds); /* Queue a message for delivery to the client connected through conn. - * Returns 0 on success -1 on error (only happens when malloc fails). + * Return value: 0 on success -1 on error (only happens when malloc fails). */ int udscs_write(struct udscs_connection *conn, uint32_t type, uint32_t arg1, uint32_t arg2, const uint8_t *data, uint32_t size); -/* To associate per connection data with a connection. */ +/* Associates the specified user data with the connection. */ void udscs_set_user_data(struct udscs_connection *conn, void *data); + +/* Return value: the connection's associated user data, + * NULL if conn is NULL. + */ void *udscs_get_user_data(struct udscs_connection *conn); @@ -98,13 +120,27 @@ struct udscs_server; */ typedef void (*udscs_connect_callback)(struct udscs_connection *conn); -/* Create a unix domain socket named name and start listening on it. */ +/* Create the unix domain socket specified by socketname and + * start listening on it. + * Only sockets bound to a pathname are supported. + * + * If debug is true then the events on this socket and related individual + * connections will be traced. + * This includes the incoming and outgoing message names. So when debug is true + * no_types must be set to the value of the highest valid message id + 1, + * and type_to_string must point to a string array of size no_types for + * converting the message ids to their names. + */ struct udscs_server *udscs_create_server(const char *socketname, udscs_connect_callback connect_callback, udscs_read_callback read_callback, udscs_disconnect_callback disconnect_callback, const char * const type_to_string[], int no_types, int debug); +/* Close all the server's connections and releases the corresponding + * resources. + * Does nothing if server is NULL. + */ void udscs_destroy_server(struct udscs_server *server); /* Like udscs_write, but then send the message to all clients connected to @@ -122,19 +158,21 @@ typedef int (*udscs_for_all_clients_callback)(struct udscs_connection **connp, /* Call func for all clients connected to the server, passing through * priv to all func calls. Returns the total of the return values from all - * calls to func. + * calls to func or 0 if server is NULL. */ int udscs_server_for_all_clients(struct udscs_server *server, udscs_for_all_clients_callback func, void *priv); -/* Given an udscs server or client fill the fd_sets pointed to by readfds and +/* Given a udscs server, fill the fd_sets pointed to by readfds and * writefds for select() usage. - * Return value: value of the highest fd + 1 + * Return value: value of the highest fd + 1 or -1 if server is NULL */ int udscs_server_fill_fds(struct udscs_server *server, fd_set *readfds, fd_set *writefds); -/* Handle any events flagged by select for the given udscs server or client. */ +/* Handle any events flagged by select for the given udscs server. + * Does nothing if server is NULL. + */ void udscs_server_handle_fds(struct udscs_server *server, fd_set *readfds, fd_set *writefds); -- 2.11.4.GIT