1 /*
2 * SysDB - src/include/utils/proto.h
3 * Copyright (C) 2013 Sebastian 'tokkee' Harl <sh@tokkee.org>
4 * All rights reserved.
5 *
6 * Redistribution and use in source and binary forms, with or without
7 * modification, are permitted provided that the following conditions
8 * are met:
9 * 1. Redistributions of source code must retain the above copyright
10 * notice, this list of conditions and the following disclaimer.
11 * 2. Redistributions in binary form must reproduce the above copyright
12 * notice, this list of conditions and the following disclaimer in the
13 * documentation and/or other materials provided with the distribution.
14 *
15 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
16 * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
17 * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
18 * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR
19 * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
20 * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
21 * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
22 * OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
23 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
24 * OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
25 * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
26 */
28 #ifndef SDB_UTILS_PROTO_H
29 #define SDB_UTILS_PROTO_H 1
31 #include "core/data.h"
33 #include <stdint.h>
34 #include <unistd.h>
36 #ifdef __cplusplus
37 extern "C" {
38 #endif
40 /*
41 * sdb_proto_host, sdb_proto_service, sdb_proto_metric:
42 * Protocol-specific representations of the basic information of stored
43 * objects.
44 */
45 typedef struct {
46 sdb_time_t last_update;
47 const char *name;
48 } sdb_proto_host_t;
49 #define SDB_PROTO_HOST_INIT { 0, NULL }
51 typedef struct {
52 sdb_time_t last_update;
53 const char *hostname;
54 const char *name;
55 } sdb_proto_service_t;
56 #define SDB_PROTO_SERVICE_INIT { 0, NULL, NULL }
58 typedef struct {
59 sdb_time_t last_update;
60 const char *hostname;
61 const char *name;
62 const char *store_type; /* optional */
63 const char *store_id; /* optional */
64 sdb_time_t store_last_update; /* optional */
65 } sdb_proto_metric_t;
66 #define SDB_PROTO_METRIC_INIT { 0, NULL, NULL, NULL, NULL, 0 }
68 typedef struct {
69 sdb_time_t last_update;
70 int parent_type;
71 const char *hostname; /* optional */
72 const char *parent;
73 const char *key;
74 sdb_data_t value;
75 } sdb_proto_attribute_t;
76 #define SDB_PROTO_ATTRIBUTE_INIT { 0, 0, NULL, NULL, NULL, SDB_DATA_INIT }
78 /*
79 * sdb_proto_marshal:
80 * Encode the message into the wire format by adding an appropriate header.
81 * The encoded message is written to buf which has to be large enough to store
82 * the header (64 bits) and the entire message.
83 *
84 * Returns:
85 * - The number of bytes of the full encoded message on success. The function
86 * does not write more than 'buf_len' bytes. If the output was truncated
87 * then the return value is the number of bytes which would have been
88 * written if enough space had been available.
89 * - a negative value on error
90 */
91 ssize_t
92 sdb_proto_marshal(char *buf, size_t buf_len, uint32_t code,
93 uint32_t msg_len, const char *msg);
95 /*
96 * sdb_proto_marshal_int32:
97 * Encode the 32-bit integer into the wire format and write it to buf.
98 *
99 * Returns:
100 * - The number of bytes of the encoded value on success. The function does
101 * not write more than 'buf_len' bytes. If the output was truncated then
102 * the return value is the number of bytes which would have been written if
103 * enough space had been available.
104 * - a negative value else
105 */
106 ssize_t
107 sdb_proto_marshal_int32(char *buf, size_t buf_len, uint32_t v);
109 /*
110 * sdb_proto_marshal_data:
111 * Encode a datum into the wire format and write it to buf.
112 *
113 * Returns:
114 * - The number of bytes of the full encoded datum on success. The function
115 * does not write more than 'buf_len' bytes. If the output was truncated
116 * then the return value is the number of bytes which would have been
117 * written if enough space had been available.
118 * - a negative value else
119 */
120 ssize_t
121 sdb_proto_marshal_data(char *buf, size_t buf_len, const sdb_data_t *datum);
123 /*
124 * sdb_proto_marshal_host, sdb_proto_marshal_service,
125 * sdb_proto_marshal_metric, sdb_proto_marshal_attribute:
126 * Encode the basic information of a stored object into the wire format and
127 * write it to buf. These functions are similar to the sdb_store_<type>
128 * functions. See their documentation for details about the arguments.
129 *
130 * Returns:
131 * - The number of bytes of the full encoded datum on success. The function
132 * does not write more than 'buf_len' bytes. If the output was truncated
133 * then the return value is the number of bytes which would have been
134 * written if enough space had been available.
135 * - a negative value else
136 */
137 ssize_t
138 sdb_proto_marshal_host(char *buf, size_t buf_len,
139 const sdb_proto_host_t *host);
140 ssize_t
141 sdb_proto_marshal_service(char *buf, size_t buf_len,
142 const sdb_proto_service_t *svc);
143 ssize_t
144 sdb_proto_marshal_metric(char *buf, size_t buf_len,
145 const sdb_proto_metric_t *metric);
146 ssize_t
147 sdb_proto_marshal_attribute(char *buf, size_t buf_len,
148 const sdb_proto_attribute_t *attr);
150 /*
151 * sdb_proto_unmarshal_header:
152 * Read and decode a message header from the specified string.
153 *
154 * Returns:
155 * - the number of bytes read on success
156 * - a negative value else
157 */
158 ssize_t
159 sdb_proto_unmarshal_header(const char *buf, size_t buf_len,
160 uint32_t *code, uint32_t *msg_len);
162 /*
163 * sdb_proto_unmarshal_int32:
164 * Read and decode a 32-bit integer from the specified string.
165 *
166 * Returns:
167 * - the number of bytes read on success
168 * - a negative value else
169 */
170 ssize_t
171 sdb_proto_unmarshal_int32(const char *buf, size_t buf_len, uint32_t *v);
173 /*
174 * sdb_proto_unmarshal_data:
175 * Read and decode a datum from the specified string. The datum's data will be
176 * allocated dynamically if necessary and will have to be free'd using
177 * sdb_data_free_datum.
178 *
179 * Returns:
180 * - the number of bytes read on success
181 * - a negative value else
182 */
183 ssize_t
184 sdb_proto_unmarshal_data(const char *buf, size_t len, sdb_data_t *datum);
186 /*
187 * sdb_proto_unmarshal_host, sdb_proto_unmarshal_service,
188 * sdb_proto_unmarshal_metric, sdb_proto_unmarshal_attribute:
189 * Read and decode a host, service, metric, or attribute object from the
190 * specified string.
191 *
192 * Returns:
193 * - the number of bytes read on success
194 * - a negative value else
195 */
196 ssize_t
197 sdb_proto_unmarshal_host(const char *buf, size_t len,
198 sdb_proto_host_t *host);
199 ssize_t
200 sdb_proto_unmarshal_service(const char *buf, size_t len,
201 sdb_proto_service_t *svc);
202 ssize_t
203 sdb_proto_unmarshal_metric(const char *buf, size_t len,
204 sdb_proto_metric_t *metric);
205 ssize_t
206 sdb_proto_unmarshal_attribute(const char *buf, size_t len,
207 sdb_proto_attribute_t *attr);
209 #ifdef __cplusplus
210 } /* extern "C" */
211 #endif
213 #endif /* ! SDB_UTILS_PROTO_H */
215 /* vim: set tw=78 sw=4 ts=4 noexpandtab : */