LIBEMQ
libemq - is an open source client library for the EagleMQ written in C.
It has been designed to be light on memory usage, high performance, and provide full access to server side methods.
Methods
Common methods
emq_client *emq_tcp_connect(const char *addr, int port);
Connect to the EagleMQ server via TCP protocol.
| № | Name | Description |
| 1 | addr | the server IP |
| 2 | port | the server port |
Return: emq_client on success, NULL on error.
emq_client *emq_unix_connect(const char *path);
Connect to the EagleMQ server via unix domain socket.
| № | Name | Description |
| 1 | path | the path to unix domain socket |
Return: emq_client on success, NULL on error.
void emq_disconnect(emq_client *client);
Disconnects the client from the server and removes the connection context.
| № | Name | Description |
| 1 | client | the context of a client connection |
void emq_noack_enable(emq_client *client);
Enable noack mode.
When enabled, the server does not respond to commands status messages and the result is always EMQ_STATUS_OK. Using this option is useful for performance. Also, it should be used to send commands if you are subscribed to the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
void emq_noack_disable(emq_client *client);
Disable noack mode.
| № | Name | Description |
| 1 | client | the context of a client connection |
int emq_process(emq_client *client);
Processing of all server events.
| № | Name | Description |
| 1 | client | the context of a client connection |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
void emq_list_rewind(emq_list *list, emq_list_iterator *iter);
Initialize the list iterator.
| № | Name | Direction | Description |
| 1 | list | in | the list |
| 2 | iter | out | the list iterator |
emq_list_node *emq_list_next(emq_list_iterator *iter);
Gets the next value list.
| № | Name | Description |
| 1 | iter | the list iterator |
Return: emq_list_node.
void emq_list_release(emq_list *list);
Delete list.
| № | Name | Description |
| 1 | list | the list |
char *emq_last_error(emq_client *client);
Description of the last error client.
| № | Name | Description |
| 1 | client | the context of a client connection |
Return: description of the error.
int emq_version(void);
Returns the version libemq.
Return: version libemq.
Messages methods
emq_msg *emq_msg_create(void *data, size_t size, int zero_copy);
Create a new message.
| № | Name | Description |
| 1 | data | the message data |
| 2 | size | the message size |
| 3 | zero_copy | flag to use zero copy (EMQ_ZEROCOPY_ON, EMQ_ZEROCOPY_OFF) |
Return: new message.
emq_msg *emq_msg_copy(emq_msg *msg);
Copy the message.
| № | Name | Description |
| 1 | msg | the message |
Return: copy of the message.
void emq_msg_expire(emq_msg *msg, emq_time time);
Set expiration time for message.
| № | Name | Description |
| 1 | msg | the message |
| 2 | time | the time (in miliseconds) |
void *emq_msg_data(emq_msg *msg);
Get the message data.
| № | Name | Description |
| 1 | msg | the message |
Return: message data.
size_t emq_msg_size(emq_msg *msg);
Get the message size.
| № | Name | Description |
| 1 | msg | the message |
Return: size of the message.
emq_tag emq_msg_tag(emq_msg *msg);
Get tag of the message.
| № | Name | Description |
| 1 | msg | the message |
Return: tag of the message.
void emq_msg_release(emq_msg *msg)
Delete the message.
| № | Name | Description |
| 1 | msg | the message |
Basic methods
int emq_auth(emq_client *client, const char *name, const char *password);
Client authentication on the server.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the user name |
| 3 | password | the user password |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_ping(emq_client *client);
Ping server. Used to check the server status.
| № | Name | Description |
| 1 | client | the context of a client connection |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_stat(emq_client *client, emq_status *status);
Get server statistics.
| № | Name | Direction | Description |
| 1 | client | in | the context of a client connection |
| 2 | status | out | the server statistics |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_save(emq_client *client, uint8_t async);
Saving data to disk.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | async | Saving mode (0 - synchronously save, 1 - asynchronously save) |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_flush(emq_client *client, uint32_t flags);
Deleting the data on the server.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | flags | flags to delete the data from the server (EMQ_FLUSH_ALL, EMQ_FLUSH_USER, EMQ_FLUSH_QUEUE, EMQ_FLUSH_CHANNEL) |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
User methods
int emq_user_create(emq_client *client, const char *name, const char *password, emq_perm perm);
Create a new user.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the user name |
| 3 | password | the user password |
| 4 | perm | the user permissions (see Table 1) |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
emq_list *emq_user_list(emq_client *client);
Get a list of all users.
| № | Name | Description |
| 1 | client | the context of a client connection |
Return: list of users.
int emq_user_rename(emq_client *client, const char *from, const char *to);
Rename the user.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | from | the old user name |
| 3 | to | the new user name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_user_set_perm(emq_client *client, const char *name, emq_perm perm);
Set permissions to the user.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the user name |
| 3 | perm | the user permissions (see Table 1) |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_user_delete(emq_client *client, const char *name);
Delete the user.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the user name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
Table 1. Description of user permissions
| № | Name | Command | Description |
| 1 | EMQ_QUEUE_PERM |
.queue_create .queue_declare .queue_exist .queue_list .queue_rename .queue_size .queue_push .queue_get .queue_pop .queue_confirm .queue_subscribe .queue_unsubscribe .queue_purge .queue_delete |
The ability to perform all the commands associated with queues |
| 2 | EMQ_ROUTE_PERM |
.route_create .route_exist .route_list .route_keys .route_rename .route_bind .route_unbind .route_push .route_delete |
The ability to perform all the commands associated with routes |
| 3 | EMQ_CHANNEL_PERM |
.channel_create .channel_exist .channel_list .channel_rename .channel_publish .channel_subscribe .channel_psubscribe .channel_unsubscribe .channel_punsubscribe .channel_delete |
The ability to perform all the commands associated with channel |
| 4 | EMQ_ADMIN_PERM | - | The ability to perform all the commands on the server (including the commands for working with users) |
| 5 | EMQ_NOT_CHANGE_PERM | - | If a user is created with the flag, then it can not be removed |
| 6 | EMQ_QUEUE_CREATE_PERM | .queue_create | Permission to create queues |
| 7 | EMQ_QUEUE_DECLARE_PERM | .queue_declare | Permission to declare the queue |
| 8 | EMQ_QUEUE_EXIST_PERM | .queue_exist | Permission to check the existence of the queue |
| 9 | EMQ_QUEUE_LIST_PERM | .queue_list | Permission to get a list of queues |
| 10 | EMQ_QUEUE_RENAME_PERM | .queue_rename | Permission to rename the queue |
| 11 | EMQ_QUEUE_SIZE_PERM | .queue_size | Permission to get the size of the queue |
| 12 | EMQ_QUEUE_PUSH_PERM | .queue_push | Permission to push messages to the queue |
| 13 | EMQ_QUEUE_GET_PERM | .queue_get | Permission to get messages from the queue |
| 14 | EMQ_QUEUE_POP_PERM | .queue_pop | Permission to pop messages from the queue |
| 15 | EMQ_QUEUE_CONFIRM_PERM | .queue_confirm | Permission to confirm delivery for the message |
| 16 | EMQ_QUEUE_SUBSCRIBE_PERM | .queue_subscribe | Permission to subscribe to the queue |
| 17 | EMQ_QUEUE_UNSUBSCRIBE_PERM | .queue_unsubscribe | Permission to unsubscribe from the queue |
| 18 | EMQ_QUEUE_PURGE_PERM | .queue_purge | Permission to delete all messages from the queue |
| 19 | EMQ_QUEUE_DELETE_PERM | .queue_delete | Permission to delete queue |
| 20 | EMQ_ROUTE_CREATE_PERM | .route_create | Permission to create route |
| 21 | EMQ_ROUTE_EXIST_PERM | .route_exist | Permission to check the existence of the route |
| 22 | EMQ_ROUTE_LIST_PERM | .route_list | Permission to get a list of routes |
| 23 | EMQ_ROUTE_KEYS_PERM | .route_keys | Permission to get a list of route keys |
| 24 | EMQ_ROUTE_RENAME_PERM | .route_rename | Permission to rename the route |
| 25 | EMQ_ROUTE_BIND_PERM | .route_bind | Permission to bind route with the queue |
| 26 | EMQ_ROUTE_UNBIND_PERM | .route_unbind | Permission to unbind route from the queue |
| 27 | EMQ_ROUTE_PUSH_PERM | .route_push | Permission to push messages to the route |
| 28 | EMQ_ROUTE_DELETE_PERM | .route_delete | Permission to delete route |
| 29 | EMQ_CHANNEL_CREATE_PERM | .channel_create | Permission to create channel |
| 30 | EMQ_CHANNEL_EXIST_PERM | .channel_exist | Permission to check the existence of the channel |
| 31 | EMQ_CHANNEL_LIST_PERM | .channel_list | Permission to get a list of channels |
| 32 | EMQ_CHANNEL_RENAME_PERM | .channel_rename | Permission to rename the channel |
| 33 | EMQ_CHANNEL_PUBLISH_PERM | .channel_publish | Permission to publish message to the channel |
| 34 | EMQ_CHANNEL_SUBSCRIBE_PERM | .channel_subscribe | Permission to subscribe to the channel by topic |
| 35 | EMQ_CHANNEL_PSUBSCRIBE_PERM | .channel_psubscribe | Permission to subscribe to the channel by pattern |
| 36 | EMQ_CHANNEL_UNSUBSCRIBE_PERM | .channel_unsubscribe | Permission to unsubscribe from channel by topic |
| 37 | EMQ_CHANNEL_PUNSUBSCRIBE_PERM | .channel_punsubscribe | Permission to unsubscribe from channel by pattern |
| 38 | EMQ_CHANNEL_DELETE_PERM | .channel_delete | Permission to delete channel |
Queue methods
int emq_queue_create(emq_client *client, const char *name, uint32_t max_msg, uint32_t max_msg_size, uint32_t flags);
Create the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
| 3 | max_msg | the maximum number of messages |
| 4 | max_msg_size | the maximum message size |
| 5 | flags | flags to create a queue (EMQ_QUEUE_NONE, EMQ_QUEUE_AUTODELETE, EMQ_QUEUE_FORCE_PUSH, EMQ_QUEUE_ROUND_ROBIN, EMQ_QUEUE_DURABLE) |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_queue_declare(emq_client *client, const char *name);
Declare the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_queue_exist(emq_client *client, const char *name);
Check the queue of existence.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
Return: Value greater than 0 if the queue exists.
emq_list *emq_queue_list(emq_client *client);
Get a list of queues.
| № | Name | Description |
| 1 | client | the context of a client connection |
Return: list of queues.
int emq_queue_rename(emq_client *client, const char *from, const char *to);
Rename the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | from | the old queue name |
| 3 | to | the new queue name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
size_t emq_queue_size(emq_client *client, const char *name);
Get the number of elements in the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
Return: number of elements in the queue.
int emq_queue_push(emq_client *client, const char *name, emq_msg *msg);
Push a message to the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
| 3 | msg | the message |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
emq_msg *emq_queue_get(emq_client *client, const char *name);
Get a message from the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
Return: message on success, NULL on error.
emq_msg *emq_queue_pop(emq_client *client, const char *name, uint32_t timeout);
Pop a message from the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
| 3 | timeout | the timeout for wait confirm delivery |
Return: message on success, NULL on error.
int emq_queue_confirm(emq_client *client, const char *name, emq_tag tag);
Confirm delivery message.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
| 3 | tag | the message tag |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_queue_subscribe(emq_client *client, const char *name, uint32_t flags, emq_msg_callback *callback);
Subscribe to the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
| 3 | flags | flags subscription (EMQ_QUEUE_SUBSCRIBE_MSG, EMQ_QUEUE_SUBSCRIBE_NOTIFY) |
| 4 | callback | callback to the event subscription |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_queue_unsubscribe(emq_client *client, const char *name);
Unsubscribe from the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_queue_purge(emq_client *client, const char *name);
Purge the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_queue_delete(emq_client *client, const char *name);
Delete the queue.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the queue name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
Route methods
int emq_route_create(emq_client *client, const char *name, uint32_t flags);
Create the route.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the route name |
| 3 | flags | flags to create a route (EMQ_ROUTE_NONE, EMQ_ROUTE_AUTODELETE, EMQ_ROUTE_ROUND_ROBIN, EMQ_ROUTE_DURABLE) |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_route_exist(emq_client *client, const char *name);
Check the route of existence.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the route name |
Return: Value greater than 0 if the route exists.
emq_list *emq_route_list(emq_client *client);
Get a list of route.
| № | Name | Description |
| 1 | client | the context of a client connection |
Return: list of routes.
int emq_route_rename(emq_client *client, const char *from, const char *to);
Rename the route.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | from | the old route name |
| 3 | to | the new route name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
emq_list *emq_route_keys(emq_client *client, const char *name);
Get a list of route keys.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the route name |
Return: list of route keys.
int emq_route_bind(emq_client *client, const char *name, const char *queue, const char *key);
Bind the route with queue by key.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the route name |
| 3 | queue | the queue name |
| 4 | key | the key |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_route_unbind(emq_client *client, const char *name, const char *queue, const char *key);
Unbind the route from queue by a key.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the route name |
| 3 | queue | the queue name |
| 4 | key | the key |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_route_push(emq_client *client, const char *name, const char *key, emq_msg *msg);
Push a message to the route.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the route name |
| 3 | key | the key |
| 4 | msg | the message |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_route_delete(emq_client *client, const char *name);
Delete the route.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the route name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
Channel methods
int emq_channel_create(emq_client *client, const char *name, uint32_t flags);
Create the channel.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the channel name |
| 3 | flags | flags to create a channel (EMQ_CHANNEL_NONE, EMQ_CHANNEL_AUTODELETE, EMQ_CHANNEL_ROUND_ROBIN, EMQ_CHANNEL_DURABLE) |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_channel_exist(emq_client *client, const char *name);
Check the channel of existence.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the channel name |
Return: Value greater than 0 if the channel exists.
emq_list *emq_channel_list(emq_client *client);
Get a list of channels.
| № | Name | Description |
| 1 | client | the context of a client connection |
Return: list of channels.
int emq_channel_rename(emq_client *client, const char *from, const char *to);
Rename the channel.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | from | the old channel name |
| 3 | to | the new channel name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_channel_publish(emq_client *client, const char *name, const char *topic, emq_msg *msg);
Publish a message to the channel.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the channel name |
| 3 | topic | the channel topic |
| 4 | msg | the message |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_channel_subscribe(emq_client *client, const char *name, const char *topic, emq_msg_callback *callback);
Subscribe to the channel by topic.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the channel name |
| 3 | topic | the channel topic |
| 4 | callback | callback to the event subscription |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_channel_psubscribe(emq_client *client, const char *name, const char *pattern, emq_msg_callback *callback);
Subscribe to the channel by pattern.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the channel name |
| 3 | pattern | the channel pattern |
| 4 | callback | callback to the event subscription |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_channel_unsubscribe(emq_client *client, const char *name, const char *topic);
Unsubscribe from the channel by topic.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the channel name |
| 3 | topic | the channel topic |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_channel_punsubscribe(emq_client *client, const char *name, const char *pattern);
Unsubscribe from the channel by pattern.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the channel name |
| 3 | pattern | the channel pattern |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
int emq_channel_delete(emq_client *client, const char *name);
Delete the channel.
| № | Name | Description |
| 1 | client | the context of a client connection |
| 2 | name | the channel name |
Return: EMQ_STATUS_OK on success, EMQ_STATUS_ERR on error.
Author
libemq has written by Stanislav Yakush([email protected]) and is released under the BSD license.
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent