aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
-rw-r--r--ssh/tomsg_clientlib.h39
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);