Debian Codegraph @

src/utils/message_parser/message_parser.h

raw
1 /*
2 * collectd - src/utils/message_parser/message_parser.h
3 * MIT License
4 *
5 * Copyright(c) 2017-2018 Intel Corporation. All rights reserved.
6 *
7 * Permission is hereby granted, free of charge, to any person obtaining a
8 * copy of this software and associated documentation files (the "Software"),
9 * to deal in the Software without restriction, including without limitation
10 * the rights to use, copy, modify, merge, publish, distribute, sublicense,
11 * and/or sell copies of the Software, and to permit persons to whom the
12 * Software is furnished to do so, subject to the following conditions:
13 *
14 * The above copyright notice and this permission notice shall be included in
15 * all copies or substantial portions of the Software.
16 *
17 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
18 * IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
19 * FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
20 * AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
21 * LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
22 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
23 * DEALINGS IN THE SOFTWARE.
24 *
25 * Authors:
26 * Krzysztof Matczak <[email protected]>
27 * Marcin Mozejko <[email protected]>
28 */
29
30 #ifndef UTILS_MESSAGE_PARSER_H
31 #define UTILS_MESSAGE_PARSER_H 1
32
33 #include "utils_tail_match.h"
34
35 typedef struct message_pattern_s {
36 /* User defined name for message item */
37 char *name;
38 /* Regular expression for finding out specific message item. The match result
39 * is taken only from submatch pointed by submatch_idx variable, so multiple
40 * submatches are supported. Example syntax:
41 * "(STRING1|STRING2)(.*)"
42 * For this example (STRING1|STRING2) is the first submatch and (.*) second
43 * so user can choose which one to store by setting submatch_idx argument.
44 */
45 char *regex;
46 /* Index of regex submatch that is stored as result. Value 0 takes whole
47 * match result. Value -1 does not add result to message item. */
48 int submatch_idx;
49 /* Regular expression that excludes string from further processing */
50 char *excluderegex;
51 /* Flag indicating if this item is mandatory for message validation */
52 bool is_mandatory;
53 /* Pointer to optional user data */
54 void *user_data;
55 /* Freeing function */
56 void (*free_user_data)(void *data);
57 } message_pattern_t;
58
59 typedef struct message_item_s {
60 char name[32];
61 char value[64];
62 void *user_data;
63 void (*free_user_data)(void *data);
64 } message_item_t;
65
66 typedef struct message_s {
67 message_item_t message_items[32];
68 int matched_patterns_check[32];
69 bool started;
70 bool completed;
71 } message_t;
72
73 typedef struct parser_job_data_s parser_job_data_t;
74
75 /*
76 * NAME
77 * message_parser_init
78 *
79 * DESCRIPTION
80 * Configures unique message parser job. Performs necessary buffer
81 * allocations. If there's need to create multiple parser jobs with different
82 * parameters, this function may be called many times accordingly.
83 *
84 * PARAMETERS
85 * `filename' The name of the file to be parsed.
86 * `start_idx' Index of regular expression that indicates beginning of
87 * message.
88 * This index refers to 'message_patterns' array.
89 * `stop_idx' Index of the regular expression that indicates the end of
90 * message. This index refers to 'message_patterns' array.
91 * `message_patterns' Array of regular expression patterns for populating
92 * message items. Example:
93 * message_pattern message_patterns[]= {
94 * {.name = "START", .regex = "(Running trigger.*)", submatch_idx = 1,
95 * .excluderegex = "kernel", .is_mandatory = 1},
96 * {.name = "BANK", .regex = "BANK ([0-9]*)", submatch_idx = 1,
97 * .excluderegex = "kernel", .is_mandatory = 1},
98 * {.name = "TSC", .regex = "TSC ([a-z0-9]*)", submatch_idx = 1,
99 * .excluderegex = "kernel", .is_mandatory = 1},
100 * {.name = "MCA", .regex = "MCA: (.*)", submatch_idx = 1,
101 * .excluderegex = "kernel", .is_mandatory = 0},
102 * {.name = "END", .regex = "(CPUID Vendor.*)", submatch_idx = 1,
103 * .excluderegex = "kernel", .is_mandatory = 1}
104 * };
105 *
106 * `message_patterns_len' Length of message_patterns array.
107 *
108 * RETURN VALUE
109 * Returns NULL upon failure, pointer to new parser job otherwise.
110 */
111 parser_job_data_t *message_parser_init(const char *filename,
112 unsigned int start_idx,
113 unsigned int stop_idx,
114 message_pattern_t message_patterns[],
115 size_t message_patterns_len);
116
117 /*
118 * NAME
119 * message_parser_read
120 *
121 * DESCRIPTION
122 * Collects all new messages matching criteria set in 'message_parser_init'.
123 * New messages means those reported or finished after previous call for this
124 * function.
125 *
126 * PARAMETERS
127 * `parser_job' Pointer to parser job to read.
128 * `messages_storage' Pointer to be set to internally allocated messages
129 * storage.
130 * `force_rewind' If value set to non zero, file will be parsed from
131 * beginning, otherwise tailing end of file.
132 *
133 * RETURN VALUE
134 * Returns -1 upon failure, number of messages collected from last read
135 * otherwise.
136 */
137 int message_parser_read(parser_job_data_t *parser_job,
138 message_t **messages_storage, bool force_rewind);
139
140 /*
141 * NAME
142 * message_parser_cleanup
143 *
144 * DESCRIPTION
145 * Performs parser job resource deallocation and cleanup.
146 *
147 * PARAMETERS
148 * `parser_job' Pointer to parser job to be cleaned up.
149 *
150 */
151 void message_parser_cleanup(parser_job_data_t *parser_job);
152
153 #endif /* UTILS_MESSAGE_PARSER_H */