trilogy_w_prepared_statements 2.2.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/LICENSE +22 -0
- data/README.md +80 -0
- data/Rakefile +22 -0
- data/ext/trilogy-ruby/cast.c +277 -0
- data/ext/trilogy-ruby/cext.c +1048 -0
- data/ext/trilogy-ruby/extconf.rb +17 -0
- data/ext/trilogy-ruby/inc/trilogy/blocking.h +281 -0
- data/ext/trilogy-ruby/inc/trilogy/buffer.h +64 -0
- data/ext/trilogy-ruby/inc/trilogy/builder.h +165 -0
- data/ext/trilogy-ruby/inc/trilogy/charset.h +277 -0
- data/ext/trilogy-ruby/inc/trilogy/client.h +760 -0
- data/ext/trilogy-ruby/inc/trilogy/error.h +44 -0
- data/ext/trilogy-ruby/inc/trilogy/packet_parser.h +34 -0
- data/ext/trilogy-ruby/inc/trilogy/protocol.h +1014 -0
- data/ext/trilogy-ruby/inc/trilogy/reader.h +216 -0
- data/ext/trilogy-ruby/inc/trilogy/socket.h +111 -0
- data/ext/trilogy-ruby/inc/trilogy/vendor/curl_hostcheck.h +29 -0
- data/ext/trilogy-ruby/inc/trilogy/vendor/openssl_hostname_validation.h +51 -0
- data/ext/trilogy-ruby/inc/trilogy.h +8 -0
- data/ext/trilogy-ruby/src/blocking.c +358 -0
- data/ext/trilogy-ruby/src/buffer.c +60 -0
- data/ext/trilogy-ruby/src/builder.c +236 -0
- data/ext/trilogy-ruby/src/charset.c +212 -0
- data/ext/trilogy-ruby/src/client.c +903 -0
- data/ext/trilogy-ruby/src/error.c +17 -0
- data/ext/trilogy-ruby/src/packet_parser.c +140 -0
- data/ext/trilogy-ruby/src/protocol.c +1175 -0
- data/ext/trilogy-ruby/src/reader.c +282 -0
- data/ext/trilogy-ruby/src/socket.c +623 -0
- data/ext/trilogy-ruby/src/vendor/curl_hostcheck.c +206 -0
- data/ext/trilogy-ruby/src/vendor/openssl_hostname_validation.c +175 -0
- data/ext/trilogy-ruby/trilogy-ruby.h +37 -0
- data/lib/trilogy/version.rb +3 -0
- data/lib/trilogy.rb +61 -0
- data/trilogy.gemspec +27 -0
- metadata +107 -0
@@ -0,0 +1,17 @@
|
|
1
|
+
require "mkmf"
|
2
|
+
|
3
|
+
# concatenate trilogy library sources to allow the compiler to optimise across
|
4
|
+
# source files
|
5
|
+
File.binwrite("trilogy.c",
|
6
|
+
Dir["#{__dir__}/src/**/*.c"].map { |src| File.binread(src) }.join)
|
7
|
+
|
8
|
+
$objs = %w[trilogy.o cast.o cext.o]
|
9
|
+
$CFLAGS << " -I #{__dir__}/inc -std=gnu99"
|
10
|
+
|
11
|
+
dir_config("openssl")
|
12
|
+
|
13
|
+
have_library("crypto", "CRYPTO_malloc")
|
14
|
+
have_library("ssl", "SSL_new")
|
15
|
+
have_func("rb_interned_str", "ruby.h")
|
16
|
+
|
17
|
+
create_makefile "trilogy/cext"
|
@@ -0,0 +1,281 @@
|
|
1
|
+
#ifndef TRILOGY_BLOCKING_H
|
2
|
+
#define TRILOGY_BLOCKING_H
|
3
|
+
|
4
|
+
#include "client.h"
|
5
|
+
|
6
|
+
/* Trilogy Blocking Client API
|
7
|
+
*
|
8
|
+
* This API is a set of high level functions for issuing commands to the MySQL-compatible
|
9
|
+
* server. Being just a simple wrapper around the non-blocking API - each call
|
10
|
+
* will block until a full request and response cycle has completed, or an error
|
11
|
+
* occurs.
|
12
|
+
*
|
13
|
+
* The trilogy_init function from client.h should be used to initialize a
|
14
|
+
* trilogy_conn_t struct. While trilogy_free should be used to ensure any internal
|
15
|
+
* buffers are freed.
|
16
|
+
*
|
17
|
+
* Applications requiring finer-grained control over I/O should use the
|
18
|
+
* non-blocking API in client.h
|
19
|
+
*/
|
20
|
+
|
21
|
+
/* trilogy_connect - Establish a connection to a MySQL-compatible server
|
22
|
+
*
|
23
|
+
* conn - A pre-initialized trilogy_conn_t pointer.
|
24
|
+
* opts - Connection options for where to connect to.
|
25
|
+
*
|
26
|
+
* Return values
|
27
|
+
* TRILOGY_OK - Connected and authenticated successfully.
|
28
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
29
|
+
* TRILOGY_CLOSED_CONNECTION - The connection was severed during
|
30
|
+
* authentication. TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing
|
31
|
+
* a network packet.
|
32
|
+
*/
|
33
|
+
int trilogy_connect(trilogy_conn_t *conn, const trilogy_sockopt_t *opts);
|
34
|
+
|
35
|
+
/* trilogy_connect_sock - Establish a connection to a MySQL-compatible server with an
|
36
|
+
* - existing socket.
|
37
|
+
*
|
38
|
+
* conn - A pre-initialized trilogy_conn_t pointer.
|
39
|
+
* sock - A connected socket.
|
40
|
+
*
|
41
|
+
* Return values
|
42
|
+
* TRILOGY_OK - Connected and authenticated successfully.
|
43
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
44
|
+
* TRILOGY_CLOSED_CONNECTION - The connection was severed during
|
45
|
+
* authentication. TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing
|
46
|
+
* a network packet.
|
47
|
+
*/
|
48
|
+
int trilogy_connect_sock(trilogy_conn_t *conn, trilogy_sock_t *sock);
|
49
|
+
|
50
|
+
/* trilogy_change_db - Change the default database for a connection.
|
51
|
+
*
|
52
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected
|
53
|
+
* trilogy_conn_t is undefined. name - Name of the database to set as default.
|
54
|
+
* name_len - Length of the database name string in bytes.
|
55
|
+
*
|
56
|
+
* Return values
|
57
|
+
* TRILOGY_OK - The change db command completed successfully.
|
58
|
+
* TRILOGY_ERR - The server returned an error.
|
59
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
60
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
61
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
62
|
+
* packet.
|
63
|
+
*/
|
64
|
+
int trilogy_change_db(trilogy_conn_t *conn, const char *name, size_t name_len);
|
65
|
+
|
66
|
+
/* trilogy_query - Send and execute a query.
|
67
|
+
*
|
68
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected
|
69
|
+
* trilogy_conn_t is undefined.
|
70
|
+
* query - The query string to be sent to the server.
|
71
|
+
* query_len - Length of the query string in bytes.
|
72
|
+
* column_count_out - Out parameter; The number of columns in the result set.
|
73
|
+
*
|
74
|
+
* Return values
|
75
|
+
* TRILOGY_OK - The query completed successfully and there are
|
76
|
+
* no results to be read. TRILOGY_HAVE_RESULTS - The query completed
|
77
|
+
* successfully and there are results to be read. The caller must then call
|
78
|
+
* trilogy_read_full_column to read all column info
|
79
|
+
* packets, then trilogy_read_full_row until all rows
|
80
|
+
* have been read.
|
81
|
+
* TRILOGY_ERR - The server returned an error.
|
82
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
83
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
84
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
85
|
+
* packet.
|
86
|
+
*/
|
87
|
+
int trilogy_query(trilogy_conn_t *conn, const char *query, size_t query_len, uint64_t *column_count_out);
|
88
|
+
|
89
|
+
/* trilogy_read_full_column - Read a column from the result set.
|
90
|
+
*
|
91
|
+
* This should be called after issuing a query that has results. For example:
|
92
|
+
* an INSERT query won't have a result set.
|
93
|
+
*
|
94
|
+
* Calling this function at any other time during the connection lifecycle is
|
95
|
+
* undefined.
|
96
|
+
*
|
97
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected
|
98
|
+
* trilogy_conn_t is undefined.
|
99
|
+
* column_out - Out parameter; A pointer to a pre-allocated trilogy_column_t,
|
100
|
+
* which will be filled out by this function.
|
101
|
+
*
|
102
|
+
* Return values
|
103
|
+
* TRILOGY_OK - The column was successfully read.
|
104
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
105
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
106
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
107
|
+
* packet.
|
108
|
+
*/
|
109
|
+
int trilogy_read_full_column(trilogy_conn_t *conn, trilogy_column_t *column_out);
|
110
|
+
|
111
|
+
/* trilogy_read_full_row - Read a row from the result set.
|
112
|
+
*
|
113
|
+
* This should only be called after reading all of the columns from a result
|
114
|
+
* set.
|
115
|
+
*
|
116
|
+
* Calling this function at any other time during the connection lifecycle is
|
117
|
+
* undefined.
|
118
|
+
*
|
119
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected
|
120
|
+
* trilogy_conn_t is undefined.
|
121
|
+
* values_out - Out parameter; A pointer to a pre-allocated trilogy_value_t, which
|
122
|
+
* will be filled out by this function. It should be allocated with
|
123
|
+
* enough space to hold a trilogy_value_t pointer for each column.
|
124
|
+
* Something like: `(sizeof(trilogy_value_t) * column_count)`.
|
125
|
+
*
|
126
|
+
* Return values
|
127
|
+
* TRILOGY_OK - The row was successfully read.
|
128
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
129
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
130
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
131
|
+
* packet.
|
132
|
+
*/
|
133
|
+
int trilogy_read_full_row(trilogy_conn_t *conn, trilogy_value_t *values_out);
|
134
|
+
|
135
|
+
/* trilogy_ping - Send a ping command to the server.
|
136
|
+
*
|
137
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected trilogy_conn_t
|
138
|
+
* is undefined.
|
139
|
+
*
|
140
|
+
* Return values
|
141
|
+
* TRILOGY_OK - The ping command completed successfully.
|
142
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
143
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
144
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
145
|
+
* packet.
|
146
|
+
*/
|
147
|
+
int trilogy_ping(trilogy_conn_t *conn);
|
148
|
+
|
149
|
+
/* trilogy_close - Send a quit command to the server.
|
150
|
+
*
|
151
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected trilogy_conn_t
|
152
|
+
* is undefined.
|
153
|
+
*
|
154
|
+
* Return values
|
155
|
+
* TRILOGY_OK - The quit command was completed successfully.
|
156
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
157
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
158
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
159
|
+
* packet.
|
160
|
+
*/
|
161
|
+
int trilogy_close(trilogy_conn_t *conn);
|
162
|
+
|
163
|
+
/* trilogy_stmt_prepare - Send a prepared statement prepare command to the server.
|
164
|
+
*
|
165
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected trilogy_conn_t is
|
166
|
+
* undefined.
|
167
|
+
* stmt - A pointer to the buffer containing the statement to prepare.
|
168
|
+
* stmt_len - The length of the data buffer.
|
169
|
+
* stmt_out - A pointer to a pre-allocated trilogy_stmt_t.
|
170
|
+
*
|
171
|
+
* Return values:
|
172
|
+
* TRILOGY_OK - The prepare command was successfully sent to the server.
|
173
|
+
* TRILOGY_UNEXPECTED_PACKET - The response packet wasn't what was expected.
|
174
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
175
|
+
* packet.
|
176
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
177
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
178
|
+
*/
|
179
|
+
int trilogy_stmt_prepare(trilogy_conn_t *conn, const char *stmt, size_t stmt_len, trilogy_stmt_t *stmt_out);
|
180
|
+
|
181
|
+
/* trilogy_stmt_execute - Send a prepared statement execute command to the server.
|
182
|
+
*
|
183
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected trilogy_conn_t is
|
184
|
+
* undefined.
|
185
|
+
* stmt - Pointer to a valid trilogy_stmt_t, representing the prepared statement you're
|
186
|
+
* requesting to execute.
|
187
|
+
* flags - The flags (TRILOGY_STMT_FLAGS_t) to be used with this execute command packet.
|
188
|
+
* binds - Pointer to an array of trilogy_binary_value_t's. The array size should
|
189
|
+
* match that of `trilogy_stmt_t.column_count`.
|
190
|
+
* column_count_out - Out parameter; A pointer to a pre-allocated uint64_t. Represents the
|
191
|
+
* number of columns in the response.
|
192
|
+
*
|
193
|
+
* Return values:
|
194
|
+
* TRILOGY_OK - The execute command was successfully sent to the server.
|
195
|
+
* TRILOGY_UNEXPECTED_PACKET - The response packet wasn't what was expected.
|
196
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
197
|
+
* packet.
|
198
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
199
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
200
|
+
*/
|
201
|
+
int trilogy_stmt_execute(trilogy_conn_t *conn, trilogy_stmt_t *stmt, uint8_t flags, trilogy_binary_value_t *binds,
|
202
|
+
uint64_t *column_count_out);
|
203
|
+
|
204
|
+
/* trilogy_stmt_bind_data - Send a prepared statement bind long data command to the server.
|
205
|
+
*
|
206
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected trilogy_conn_t is
|
207
|
+
* undefined.
|
208
|
+
* stmt - Pointer to a valid trilogy_stmt_t, representing the prepared statement for which
|
209
|
+
* to bind the supplied parameter data to.
|
210
|
+
* param_num - The parameter index for which the supplied data should be bound to.
|
211
|
+
* data - A pointer to the buffer containing the data to be bound.
|
212
|
+
* data_len - The length of the data buffer.
|
213
|
+
*
|
214
|
+
* Return values:
|
215
|
+
* TRILOGY_OK - The bind data command was successfully sent to the server.
|
216
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
217
|
+
*/
|
218
|
+
int trilogy_stmt_bind_data(trilogy_conn_t *conn, trilogy_stmt_t *stmt, uint16_t param_num, uint8_t *data,
|
219
|
+
size_t data_len);
|
220
|
+
|
221
|
+
/* trilogy_stmt_read_full_row - Read a row from the prepared statement execute response.
|
222
|
+
*
|
223
|
+
* This should only be called after a sucessful call to trilogy_stmt_execute.
|
224
|
+
* You should continue calling this until TRILOGY_EOF is returned. Denoting the end
|
225
|
+
* of the result set.
|
226
|
+
*
|
227
|
+
* conn - A pre-initialized trilogy_conn_t pointer. It can also be connected but
|
228
|
+
* a disconnected trilogy_conn_t will also return TRILOGY_OK.
|
229
|
+
* stmt - Pointer to a valid trilogy_stmt_t, representing the prepared statement you're
|
230
|
+
* requesting to execute.
|
231
|
+
* columns - The list of columns from the prepared statement.
|
232
|
+
* column_count - The number of columns in prepared statement.
|
233
|
+
* values_out - Out parameter; A pointer to a pre-allocated array of
|
234
|
+
* trilogy_binary_value_t's. There must be enough space to fit all of the
|
235
|
+
* values. This can be computed with:
|
236
|
+
* `(sizeof(trilogy_binary_value_t) * column_count)`.
|
237
|
+
*
|
238
|
+
* Return values:
|
239
|
+
* TRILOGY_OK - The prepare command response successfully read from
|
240
|
+
* the server.
|
241
|
+
* TRILOGY_EOF - There are no more rows to read from the result set.
|
242
|
+
* TRILOGY_UNEXPECTED_PACKET - The response packet wasn't what was expected.
|
243
|
+
* TRILOGY_PROTOCOL_VIOLATION - Invalid length parsed for a TIME/DATETIME/TIMESTAMP value.
|
244
|
+
* TRILOGY_UNKNOWN_TYPE - An unsupported or unknown MySQL type was seen.
|
245
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
246
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
247
|
+
*/
|
248
|
+
int trilogy_stmt_read_full_row(trilogy_conn_t *conn, trilogy_stmt_t *stmt, trilogy_column_packet_t *columns,
|
249
|
+
trilogy_binary_value_t *values_out);
|
250
|
+
|
251
|
+
/* trilogy_stmt_reset - Send a prepared statement reset command to the server.
|
252
|
+
*
|
253
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected trilogy_conn_t is
|
254
|
+
* undefined.
|
255
|
+
* stmt - Pointer to a valid trilogy_stmt_t, representing the prepared statement you're
|
256
|
+
* requesting to reset.
|
257
|
+
*
|
258
|
+
* Return values:
|
259
|
+
* TRILOGY_OK - The reset command was successfully sent to the server.
|
260
|
+
* TRILOGY_UNEXPECTED_PACKET - The response packet wasn't what was expected.
|
261
|
+
* TRILOGY_PROTOCOL_VIOLATION - An error occurred while processing a network
|
262
|
+
* packet.
|
263
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
264
|
+
* TRILOGY_CLOSED_CONNECTION - The connection is closed.
|
265
|
+
*/
|
266
|
+
int trilogy_stmt_reset(trilogy_conn_t *conn, trilogy_stmt_t *stmt);
|
267
|
+
|
268
|
+
/* trilogy_stmt_close_send - Send a prepared statement close command to the server.
|
269
|
+
*
|
270
|
+
* conn - A connected trilogy_conn_t pointer. Using a disconnected trilogy_conn_t is
|
271
|
+
* undefined.
|
272
|
+
* stmt - Pointer to a valid trilogy_stmt_t, representing the prepared statement you're
|
273
|
+
* requesting to close.
|
274
|
+
*
|
275
|
+
* Return values:
|
276
|
+
* TRILOGY_OK - The close command was successfully sent to the server.
|
277
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
278
|
+
*/
|
279
|
+
int trilogy_stmt_close(trilogy_conn_t *conn, trilogy_stmt_t *stmt);
|
280
|
+
|
281
|
+
#endif
|
@@ -0,0 +1,64 @@
|
|
1
|
+
#ifndef TRILOGY_BUFFER_H
|
2
|
+
#define TRILOGY_BUFFER_H
|
3
|
+
|
4
|
+
#include <stddef.h>
|
5
|
+
#include <stdint.h>
|
6
|
+
|
7
|
+
/* trilogy_buffer_t - A convenience type used for wrapping a reusable chunk of
|
8
|
+
* memory.
|
9
|
+
*/
|
10
|
+
typedef struct {
|
11
|
+
size_t len;
|
12
|
+
size_t cap;
|
13
|
+
uint8_t *buff;
|
14
|
+
} trilogy_buffer_t;
|
15
|
+
|
16
|
+
/* trilogy_buffer_init - Initialize an trilogy_buffer_t and pre-allocate
|
17
|
+
* `initial_capacity` bytes.
|
18
|
+
*
|
19
|
+
* buffer - A pointer to an allocated, uninitialized trilogy_buffer_t.
|
20
|
+
* initial_capacity - The initial capacity for the buffer.
|
21
|
+
*
|
22
|
+
* Return values:
|
23
|
+
* TRILOGY_OK - The buffer was initialized.
|
24
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
25
|
+
*/
|
26
|
+
int trilogy_buffer_init(trilogy_buffer_t *buffer, size_t initial_capacity);
|
27
|
+
|
28
|
+
/* trilogy_buffer_expand - Make sure there is at least `needed` bytes available in
|
29
|
+
* the underlying buffer, resizing it to be larger if necessary.
|
30
|
+
*
|
31
|
+
* buffer - A pre-initialized trilogy_buffer_t pointer.
|
32
|
+
* needed - The amount of space requested to be available in the buffer after
|
33
|
+
* after this call returns.
|
34
|
+
*
|
35
|
+
* Return values:
|
36
|
+
* TRILOGY_OK - The buffer is guaranteed to have at least `needed` bytes of
|
37
|
+
* space available.
|
38
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
39
|
+
* TRILOGY_TYPE_OVERFLOW - The amount of buffer spaced needed is larger than the
|
40
|
+
* what can be represented by `size_t`.
|
41
|
+
*/
|
42
|
+
int trilogy_buffer_expand(trilogy_buffer_t *buffer, size_t needed);
|
43
|
+
|
44
|
+
/* trilogy_buffer_putc - Appends a byte to the buffer, resizing the underlying
|
45
|
+
* allocation if necessary.
|
46
|
+
*
|
47
|
+
* buffer - A pointer to a pre-initialized trilogy_buffer_t.
|
48
|
+
* c - The byte to append to the buffer.
|
49
|
+
*
|
50
|
+
* Return values:
|
51
|
+
* TRILOGY_OK - The character was appended to the buffer
|
52
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
53
|
+
*/
|
54
|
+
int trilogy_buffer_putc(trilogy_buffer_t *buffer, uint8_t c);
|
55
|
+
|
56
|
+
/* trilogy_buffer_free - Free an trilogy_buffer_t's underlying storage. The buffer
|
57
|
+
* must be re-initialized with trilogy_buffer_init if it is to be reused. Any
|
58
|
+
* operations performed on an unintialized or freed buffer are undefined.
|
59
|
+
*
|
60
|
+
* buffer - An initialized trilogy_buffer_t.
|
61
|
+
*/
|
62
|
+
void trilogy_buffer_free(trilogy_buffer_t *buffer);
|
63
|
+
|
64
|
+
#endif
|
@@ -0,0 +1,165 @@
|
|
1
|
+
#ifndef TRILOGY_BUILDER_H
|
2
|
+
#define TRILOGY_BUILDER_H
|
3
|
+
|
4
|
+
#include <stddef.h>
|
5
|
+
#include <stdint.h>
|
6
|
+
|
7
|
+
#include "trilogy/buffer.h"
|
8
|
+
|
9
|
+
/* Trilogy Packet Builder API
|
10
|
+
*
|
11
|
+
* The builder API is used for building protocol packet buffers.
|
12
|
+
*/
|
13
|
+
|
14
|
+
/* trilogy_builder_t - The builder API's instance type.
|
15
|
+
*/
|
16
|
+
typedef struct {
|
17
|
+
trilogy_buffer_t *buffer;
|
18
|
+
size_t header_offset;
|
19
|
+
uint32_t fragment_length;
|
20
|
+
uint8_t seq;
|
21
|
+
} trilogy_builder_t;
|
22
|
+
|
23
|
+
/* trilogy_builder_init - Initialize a pre-allocated trilogy_builder_t
|
24
|
+
*
|
25
|
+
* builder - A pre-allocated trilogy_builder_t pointer
|
26
|
+
* buffer - A pre-initialized trilogy_buffer_t pointer
|
27
|
+
* seq - The initial sequence number for the packet to be built. This is
|
28
|
+
* the initial number because the builder API will automatically
|
29
|
+
* split buffers that are larger than TRILOGY_MAX_PACKET_LEN into
|
30
|
+
* multiple packets and increment the sequence number in each packet
|
31
|
+
* following the initial.
|
32
|
+
*
|
33
|
+
* Return values:
|
34
|
+
* TRILOGY_OK - The builder was successfully initialized.
|
35
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
36
|
+
*/
|
37
|
+
int trilogy_builder_init(trilogy_builder_t *builder, trilogy_buffer_t *buffer, uint8_t seq);
|
38
|
+
|
39
|
+
/* trilogy_builder_finalize - Finalize internal buffer state, ensuring all of the
|
40
|
+
* packets inside are valid and ready for use over the wire.
|
41
|
+
*
|
42
|
+
* builder - A pre-initialized trilogy_builder_t pointer.
|
43
|
+
*
|
44
|
+
* Returns nothing.
|
45
|
+
*/
|
46
|
+
void trilogy_builder_finalize(trilogy_builder_t *builder);
|
47
|
+
|
48
|
+
/* trilogy_builder_write_uint8 - Append an unsigned 8-bit integer to the packet
|
49
|
+
* buffer.
|
50
|
+
*
|
51
|
+
* builder - A pre-initialized trilogy_builder_t pointer.
|
52
|
+
* val - The value to append to the buffer.
|
53
|
+
*
|
54
|
+
* Return values:
|
55
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
56
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
57
|
+
*/
|
58
|
+
int trilogy_builder_write_uint8(trilogy_builder_t *builder, uint8_t val);
|
59
|
+
|
60
|
+
/* trilogy_builder_write_uint16 - Append an unsigned 16-bit integer to the packet
|
61
|
+
* buffer.
|
62
|
+
*
|
63
|
+
* builder - A pre-initialized trilogy_builder_t pointer.
|
64
|
+
* val - The value to append to the buffer.
|
65
|
+
*
|
66
|
+
* Return values:
|
67
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
68
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
69
|
+
*/
|
70
|
+
int trilogy_builder_write_uint16(trilogy_builder_t *builder, uint16_t val);
|
71
|
+
|
72
|
+
/* trilogy_builder_write_uint24 - Append an unsigned 24-bit integer to the packet
|
73
|
+
* buffer.
|
74
|
+
*
|
75
|
+
* builder - A pre-initialized trilogy_builder_t pointer.
|
76
|
+
* val - The value to append to the buffer.
|
77
|
+
*
|
78
|
+
* Return values:
|
79
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
80
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
81
|
+
*/
|
82
|
+
int trilogy_builder_write_uint24(trilogy_builder_t *builder, uint32_t val);
|
83
|
+
|
84
|
+
/* trilogy_builder_write_uint32 - Append an unsigned 32-bit integer to the packet
|
85
|
+
* buffer.
|
86
|
+
*
|
87
|
+
* builder - A pre-initialized trilogy_builder_t pointer
|
88
|
+
* val - The value to append to the buffer
|
89
|
+
*
|
90
|
+
* Return values:
|
91
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
92
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
93
|
+
*/
|
94
|
+
int trilogy_builder_write_uint32(trilogy_builder_t *builder, uint32_t val);
|
95
|
+
|
96
|
+
/* trilogy_builder_write_uint64 - Append an unsigned 64-bit integer to the packet
|
97
|
+
* buffer.
|
98
|
+
*
|
99
|
+
* builder - A pre-initialized trilogy_builder_t pointer
|
100
|
+
* val - The value to append to the buffer
|
101
|
+
*
|
102
|
+
* Return values:
|
103
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
104
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
105
|
+
*/
|
106
|
+
int trilogy_builder_write_uint64(trilogy_builder_t *builder, uint64_t val);
|
107
|
+
|
108
|
+
int trilogy_builder_write_float(trilogy_builder_t *builder, float val);
|
109
|
+
|
110
|
+
int trilogy_builder_write_double(trilogy_builder_t *builder, double val);
|
111
|
+
|
112
|
+
/* trilogy_builder_write_lenenc - Append a length-encoded integer to the packet
|
113
|
+
* buffer.
|
114
|
+
*
|
115
|
+
* The actual number of bytes appended to the buffer depends on the value passed
|
116
|
+
* in.
|
117
|
+
*
|
118
|
+
* builder - A pre-initialized trilogy_builder_t pointer
|
119
|
+
* val - The value to append to the buffer
|
120
|
+
*
|
121
|
+
* Return values:
|
122
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
123
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
124
|
+
*/
|
125
|
+
int trilogy_builder_write_lenenc(trilogy_builder_t *builder, uint64_t val);
|
126
|
+
|
127
|
+
/* trilogy_builder_write_buffer - Append opaque bytes to the packet buffer.
|
128
|
+
*
|
129
|
+
* builder - A pre-initialized trilogy_builder_t pointer
|
130
|
+
* data - A pointer to the opaque data to be appended
|
131
|
+
* len - The number of bytes to append from the location in memory the
|
132
|
+
* `data` parameter points to.
|
133
|
+
*
|
134
|
+
* Return values:
|
135
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
136
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
137
|
+
*/
|
138
|
+
int trilogy_builder_write_buffer(trilogy_builder_t *builder, const void *data, size_t len);
|
139
|
+
|
140
|
+
/* trilogy_builder_write_lenenc_buffer - Append opaque bytes to the packet buffer,
|
141
|
+
* prepended by its length as a length-encoded integer.
|
142
|
+
*
|
143
|
+
* builder - A pre-initialized trilogy_builder_t pointer
|
144
|
+
* data - A pointer to the opaque data to be appended
|
145
|
+
* len - The number of bytes to append from the location in memory the
|
146
|
+
* `data` parameter points to.
|
147
|
+
*
|
148
|
+
* Return values:
|
149
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
150
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
151
|
+
*/
|
152
|
+
int trilogy_builder_write_lenenc_buffer(trilogy_builder_t *builder, const void *data, size_t len);
|
153
|
+
|
154
|
+
/* trilogy_builder_write_string - Append a C-string to the packet buffer.
|
155
|
+
*
|
156
|
+
* builder - A pre-initialized trilogy_builder_t pointer
|
157
|
+
* data - A pointer to the C-string to append
|
158
|
+
*
|
159
|
+
* Return values:
|
160
|
+
* TRILOGY_OK - The value was appended to the packet buffer.
|
161
|
+
* TRILOGY_SYSERR - A system error occurred, check errno.
|
162
|
+
*/
|
163
|
+
int trilogy_builder_write_string(trilogy_builder_t *builder, const char *data);
|
164
|
+
|
165
|
+
#endif
|