1 /**
2 * collectd - src/utils_cmds.h
3 * Copyright (C) 2016 Sebastian 'tokkee' Harl
4 *
5 * Permission is hereby granted, free of charge, to any person obtaining a
6 * copy of this software and associated documentation files (the "Software"),
7 * to deal in the Software without restriction, including without limitation
8 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
9 * and/or sell copies of the Software, and to permit persons to whom the
10 * Software is furnished to do so, subject to the following conditions:
11 *
12 * The above copyright notice and this permission notice shall be included in
13 * all copies or substantial portions of the Software.
14 *
15 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
20 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
21 * DEALINGS IN THE SOFTWARE.
22 *
23 * Authors:
24 * Sebastian 'tokkee' Harl <sh at tokkee.org>
25 **/
27 #ifndef UTILS_CMDS_H
28 #define UTILS_CMDS_H 1
30 #include "plugin.h"
32 #include <stdarg.h>
34 typedef enum {
35 CMD_UNKNOWN = 0,
36 CMD_FLUSH = 1,
37 CMD_LISTVAL = 2,
38 CMD_PUTVAL = 3,
39 } cmd_type_t;
40 #define CMD_TO_STRING(type) \
41 ((type) == CMD_FLUSH) ? "FLUSH" \
42 : ((type) == CMD_LISTVAL) ? "LISTVAL" \
43 : ((type) == CMD_PUTVAL) ? "PUTVAL" \
44 : "UNKNOWN"
46 typedef struct {
47 double timeout;
49 char **plugins;
50 size_t plugins_num;
51 identifier_t *identifiers;
52 size_t identifiers_num;
53 } cmd_flush_t;
55 typedef struct {
56 } cmd_listval_t;
58 typedef struct {
59 /* The raw identifier as provided by the user. */
60 char *identifier;
62 /* An array of the fully parsed identifier and all value lists, and their
63 * options as provided by the user. */
64 value_list_t *vl;
65 size_t vl_num;
66 } cmd_putval_t;
68 /*
69 * NAME
70 * cmd_t
71 *
72 * DESCRIPTION
73 * The representation of a fully parsed command.
74 */
75 typedef struct {
76 cmd_type_t type;
77 union {
78 cmd_flush_t flush;
79 cmd_listval_t listval;
80 cmd_putval_t putval;
81 } cmd;
82 } cmd_t;
84 /*
85 * NAME
86 * cmd_status_t
87 *
88 * DESCRIPTION
89 * Status codes describing the parse result.
90 */
91 typedef enum {
92 CMD_OK = 0,
93 CMD_ERROR = -1,
94 CMD_PARSE_ERROR = -2,
95 CMD_UNKNOWN_COMMAND = -3,
97 /* Not necessarily fatal errors. */
98 CMD_NO_OPTION = 1,
99 } cmd_status_t;
101 /*
102 * NAME
103 * cmd_error_handler_t
104 *
105 * DESCRIPTION
106 * An error handler describes a callback to be invoked when the parser
107 * encounters an error. The user data pointer will be passed to the callback
108 * as the first argument.
109 */
110 typedef struct {
111 void (*cb) (void *, cmd_status_t, const char *, va_list);
112 void *ud;
113 } cmd_error_handler_t;
115 /*
116 * NAME:
117 * cmd_error
118 *
119 * DESCRIPTION
120 * Reports an error via the specified error handler (if set).
121 */
122 void cmd_error (cmd_status_t status, cmd_error_handler_t *err,
123 const char *format, ...);
125 /*
126 * NAME
127 * cmd_parse
128 *
129 * DESCRIPTION
130 * Parse a command string and populate a command object.
131 *
132 * PARAMETERS
133 * `buffer' The command string to be parsed.
134 * `ret_cmd' The parse result will be stored at this location.
135 * `err' An optional error handler to invoke on error.
136 *
137 * RETURN VALUE
138 * CMD_OK on success or the respective error code otherwise.
139 */
140 cmd_status_t cmd_parse (char *buffer,
141 cmd_t *ret_cmd, cmd_error_handler_t *err);
143 cmd_status_t cmd_parsev (size_t argc, char **argv,
144 cmd_t *ret_cmd, cmd_error_handler_t *err);
146 void cmd_destroy (cmd_t *cmd);
148 /*
149 * NAME
150 * cmd_parse_option
151 *
152 * DESCRIPTION
153 * Parses a command option which must be of the form:
154 * name=value with \ and spaces
155 *
156 * PARAMETERS
157 * `field' The parsed input field with any quotes removed and special
158 * characters unescaped.
159 * `ret_key' The parsed key will be stored at this location.
160 * `ret_value' The parsed value will be stored at this location.
161 *
162 * RETURN VALUE
163 * CMD_OK on success or an error code otherwise.
164 * CMD_NO_OPTION if `field' does not represent an option at all (missing
165 * equal sign).
166 */
167 cmd_status_t cmd_parse_option (char *field,
168 char **ret_key, char **ret_value, cmd_error_handler_t *err);
170 /*
171 * NAME
172 * cmd_error_fh
173 *
174 * DESCRIPTION
175 * An error callback writing the message to an open file handle using the
176 * format expected by the unixsock or exec plugins.
177 *
178 * PARAMETERS
179 * `ud' Error handler user-data pointer. This must be an open
180 * file-handle (FILE *).
181 * `status' The error status code.
182 * `format' Printf-style format string.
183 * `ap' Variable argument list providing the arguments for the format
184 * string.
185 */
186 void cmd_error_fh (void *ud, cmd_status_t status,
187 const char *format, va_list ap);
189 #endif /* UTILS_CMDS_H */