diff options
| -rw-r--r-- | ssh/tomsg_clientlib.h | 39 |
1 files changed, 37 insertions, 2 deletions
diff --git a/ssh/tomsg_clientlib.h b/ssh/tomsg_clientlib.h index f560728..58ad4d4 100644 --- a/ssh/tomsg_clientlib.h +++ b/ssh/tomsg_clientlib.h @@ -5,6 +5,14 @@ #include <stdint.h> +// This is a fairly low-level client library for the tomsg protocol. No state +// is kept; the API just allows for sending commands and receiving responses +// and push messages from the server. +// Use tomsg_connect() to connect, then wait for messages by poll(2)'ing on the +// file descriptor returned by tomsg_poll_fd(). To send a command, use +// functions like tomsg_register(), tomsg_send(), etc. + + struct tomsg_client; enum tomsg_retval { @@ -22,16 +30,25 @@ enum tomsg_retval { TOMSG_ERR_MEMORY, // Error allocating memory }; +// Returns reference to internal static buffer. const char* tomsg_strerror(enum tomsg_retval code); +// If successful, stores a new connection structure in 'client' and returns +// TOMSG_OK. On error, stores NULL in 'client' and returns an error code. enum tomsg_retval tomsg_connect( const char *hostname, int port, struct tomsg_client **client // output ); -// Will also free the client structure +// Close the connection. This also frees the client structure. Note that even +// in case of an error, you must still call this function to prevent a memory +// leak. void tomsg_close(struct tomsg_client *client); +// Returns a file descriptor that can be listened for read-ready events (using +// e.g. select(2) or poll(2)). Whenever it becomes ready for reading, you +// should call tomsg_next_event(). If the connection was already closed +// internally due to an error, returns -1. int tomsg_poll_fd(const struct tomsg_client *client); enum tomsg_event_type { @@ -116,6 +133,11 @@ struct tomsg_event { }; }; +// Free the fields in the event structure corresponding to the event type set. +// The structure memory may be re-used for a different event afterwards. Note +// that, despite the name, the fields are not actually set to NULL -- they +// couldn't be, since the structure is passed by value (to indicate ownership +// transfer). void tomsg_event_nullify(struct tomsg_event event); // Will return TOMSG_ERR_AGAIN if no events are available at present. In that @@ -127,27 +149,35 @@ enum tomsg_retval tomsg_next_event( struct tomsg_event *event // output ); +// Send a register command to the server. enum tomsg_retval tomsg_register( struct tomsg_client *client, const char *username, const char *password ); +// Send a login command to the server. enum tomsg_retval tomsg_login( struct tomsg_client *client, const char *username, const char *password ); +// Send a logout command to the server. enum tomsg_retval tomsg_logout(struct tomsg_client *client); +// Send a list_rooms command to the server. enum tomsg_retval tomsg_list_rooms(struct tomsg_client *client); +// Send a list_members command to the server. enum tomsg_retval tomsg_list_members(struct tomsg_client *client, const char *room_name); +// Send a create_room command to the server. enum tomsg_retval tomsg_create_room(struct tomsg_client *client); +// Send an invite command to the server. enum tomsg_retval tomsg_invite( struct tomsg_client *client, const char *room_name, const char *username); +// Send a send command to the server. // If 'tag' is not NULL, will write the message request tag to the referenced // location. This tag will also be given in the TOMSG_EV_SEND response, so that // the response can be linked to the original message. @@ -156,13 +186,18 @@ enum tomsg_retval tomsg_send( int64_t *tag // output ); -// pass -1 to 'before_msgid' to return the latest 'count' +// Send a history command to the server. +// Pass -1 to 'before_msgid' to return the latest 'count' instead messages +// before that id. enum tomsg_retval tomsg_history( struct tomsg_client *client, const char *room_name, int64_t count, int64_t before_msgid); +// Send a ping command to the server. enum tomsg_retval tomsg_ping(struct tomsg_client *client); +// Send an is_online command to the server. enum tomsg_retval tomsg_is_online(struct tomsg_client *client, const char *username); +// Send a user_active command to the server. enum tomsg_retval tomsg_user_active(struct tomsg_client *client, bool active); |