1#ifndef VRTQL_MSG_DECLARE
2#define VRTQL_MSG_DECLARE
3
4#include "websocket.h"
5
6#ifdef __cplusplus
7extern "C" {
8#endif
9
10typedef enum
11{
12 VM_MPACK_FORMAT,
13 VM_JSON_FORMAT
14} vrtql_msg_format_t;
15
16typedef enum
17{
18 VM_MSG_VALID = (1 << 1),
19 VM_MSG_PRIORITY = (1 << 2),
20 VM_MSG_OUT_OF_BAND = (1 << 3)
21} vrtql_msg_state_t;
22
23/**
24 * @defgroup MessageFunctions
25 *
26 * @brief Functions that manage VRTQL messages
27 *
28 */
29
30/**
31 * @brief Represents a message with routing, headers, and content.
32 *
33 * @ingroup MessageFunctions
34 */
35typedef struct vrtql_msg
36{
37 vws_kvs* routing; /**< A map storing routing information. */
38 vws_kvs* headers; /**< A map storing header fields. */
39
40 vws_buffer* content; /**< Buffer for the message content. */
41 uint64_t flags; /**< Message state flags */
42 vrtql_msg_format_t format; /**< Message format */
43 void* data; /**< User-defined data */
44
45} vrtql_msg;
46
47/**
48 * @brief Creates a new vrtql_msg instance.
49 * @return A pointer to the new vrtql_msg instance.
50 *
51 * @ingroup MessageFunctions
52 */
53vrtql_msg* vrtql_msg_new();
54
55/**
56 * @brief Frees a vrtql_msg instance.
57 * @param msg The vrtql_msg instance to be freed.
58 *
59 * @ingroup MessageFunctions
60 */
61void vrtql_msg_free(vrtql_msg* msg);
62
63/**
64 * @brief Dumps/traces a message to JSON format
65 * @param msg The message
66 *
67 * @ingroup MessageFunctions
68 */
69void vrtql_msg_dump(vrtql_msg* m);
70
71/**
72 * @brief Gets a header value by key.
73 * @param msg The vrtql_msg instance.
74 * @param key The header key.
75 * @return The header value. Returns NULL if the key doesn't exist.
76 *
77 * @ingroup MessageFunctions
78 */
79cstr vrtql_msg_get_header(vrtql_msg* msg, cstr key);
80
81/**
82 * @brief Sets a header key-value pair.
83 * @param msg The vrtql_msg instance.
84 * @param key The header key.
85 * @param value The header value.
86 *
87 * @ingroup MessageFunctions
88 */
89void vrtql_msg_set_header(vrtql_msg* msg, cstr key, cstr value);
90
91/**
92 * @brief Removes a header key-value pair.
93 * @param msg The vrtql_msg instance.
94 * @param key The header key to be removed.
95 *
96 * @ingroup MessageFunctions
97 */
98void vrtql_msg_clear_header(vrtql_msg* msg, cstr key);
99
100/**
101 * @brief Gets a routing value by key.
102 * @param msg The vrtql_msg instance.
103 * @param key The routing key.
104 * @return The routing value. Returns NULL if the key doesn't exist.
105 *
106 * @ingroup MessageFunctions
107 */
108cstr vrtql_msg_get_routing(vrtql_msg* msg, cstr key);
109
110/**
111 * @brief Sets a routing key-value pair.
112 * @param msg The vrtql_msg instance.
113 * @param key The routing key.
114 * @param value The routing value.
115 *
116 * @ingroup MessageFunctions
117 */
118void vrtql_msg_set_routing(vrtql_msg* msg, cstr key, cstr value);
119
120/**
121 * @brief Removes a routing key-value pair.
122 * @param msg The vrtql_msg instance.
123 * @param key The routing key to be removed.
124 *
125 * @ingroup MessageFunctions
126 */
127void vrtql_msg_clear_routing(vrtql_msg* msg, cstr key);
128
129/**
130 * @brief Gets the content of the message.
131 * @param msg The vrtql_msg instance.
132 * @return The content of the message. Returns NULL if no content is set.
133 *
134 * @ingroup MessageFunctions
135 */
136cstr vrtql_msg_get_content(vrtql_msg* msg);
137
138/**
139 * @brief Gets the size of the content.
140 * @param msg The vrtql_msg instance.
141 * @return The size of the content in bytes.
142 *
143 * @ingroup MessageFunctions
144 */
145size_t vrtql_msg_get_content_size(vrtql_msg* msg);
146
147/**
148 * @brief Sets the content of the message from a string.
149 * @param msg The vrtql_msg instance.
150 * @param value The content to be set.
151 *
152 * @ingroup MessageFunctions
153 */
154void vrtql_msg_set_content(vrtql_msg* msg, cstr value);
155
156/**
157 * @brief Sets the content of the message from a binary data.
158 * @param msg The vrtql_msg instance.
159 * @param value The content to be set.
160 * @param size The size of the content in bytes.
161 *
162 * @ingroup MessageFunctions
163 */
164void vrtql_msg_set_content_binary(vrtql_msg* msg, cstr value, size_t size);
165
166/**
167 * @brief Clears the content of the message.
168 * @param msg The vrtql_msg instance.
169 *
170 * @ingroup MessageFunctions
171 */
172void vrtql_msg_clear_content(vrtql_msg* msg);
173
174/**
175 * @brief Serializes a vrtql_msg instance to a buffer.
176 * @param msg The vrtql_msg instance.
177 * @return A buffer containing the serialized message.
178 *
179 * @ingroup MessageFunctions
180 */
181vws_buffer* vrtql_msg_serialize(vrtql_msg* msg);
182
183/**
184 * @brief Deserializes a buffer to a vrtql_msg instance.
185 * @param msg The vrtql_msg instance.
186 * @param data The buffer containing the serialized message.
187 * @param length The length of the buffer in bytes.
188 * @return true on success, false on failure.
189 *
190 * @ingroup MessageFunctions
191 */
192bool vrtql_msg_deserialize(vrtql_msg* msg, ucstr data, size_t length);
193
194/**
195 * @brief Sends a message via a websocket connection. Does not take ownership of
196 * message. Caller is still responsible for freeing message. This is to allow
197 * reuse of messages.
198 *
199 * @param c The connection.
200 * @param string The data to send.
201 * @param size The size of the data in bytes.
202 * @return Returns the number of bytes sent or -1 on error. In the case of
203 * error, check vws.e for details, especially for VE_SOCKET.
204 *
205 * @ingroup MessageFunctions
206 */
207ssize_t vrtql_msg_send(vws_cnx* c, vrtql_msg* msg);
208
209/**
210 * @brief Receives a message from the connection.
211 *
212 * @param c The connection.
213 * @return Returns the most recent message or NULL if the socket timed out
214 * without receiving a full message. In the case of NULL, You should also
215 * check for socket error (vws.e.code == VE_SOCKET or
216 * vws_cnx_is_connected()).
217 *
218 * @ingroup MessageFunctions
219 */
220vrtql_msg* vrtql_msg_recv(vws_cnx* c);
221
222#ifdef __cplusplus
223}
224#endif
225
226#endif /* VRTQL_MSG_DECLARE */
227