Mercurial > dovecot > core
annotate src/lib/lib-event.h @ 26726:e3129a5210e4
lib: Allow events to store internal pointers
These pointers are independent of event fields, so they're ignored by event
matching, exporting and importing. Their main purpose is to allow storing
internal state to an event and allow it to be accessed by any code that can
access the event.
| author | Timo Sirainen <timo.sirainen@open-xchange.com> |
|---|---|
| date | Fri, 29 Nov 2019 15:25:21 +0200 |
| parents | cb6e085f8d2d |
| children |
| rev | line source |
|---|---|
| 23949 | 1 #ifndef LIB_EVENT_H |
| 2 #define LIB_EVENT_H | |
| 3 /* event.h name is probably a bit too generic, so lets avoid using it. */ | |
| 4 | |
| 5 #include <sys/time.h> | |
| 6 | |
| 7 struct event; | |
|
26290
61b5c52561f2
lib: event-log - Add support for appending part of the log message to a string buffer while sending the event.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26289
diff
changeset
|
8 struct event_log_params; |
| 23949 | 9 |
| 10 /* Hierarchical category of events. Each event can belong to multiple | |
| 11 categories. For example [ lib-storage/maildir, syscall/io ]. The categories | |
| 12 are expected to live as long as they're used in events. */ | |
| 13 struct event_category { | |
| 14 struct event_category *parent; | |
| 15 const char *name; | |
| 16 | |
|
26653
dab46c3559e0
lib: events: Replace ->registered with ->internal
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26652
diff
changeset
|
17 /* non-NULL if this category has been registered |
|
dab46c3559e0
lib: events: Replace ->registered with ->internal
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26652
diff
changeset
|
18 |
|
26654
39243cde767f
lib: Keep an internal event category structure
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26653
diff
changeset
|
19 Do NOT dereference outside of event code in src/lib. |
|
39243cde767f
lib: Keep an internal event category structure
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26653
diff
changeset
|
20 |
|
39243cde767f
lib: Keep an internal event category structure
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26653
diff
changeset
|
21 At any point in time it is safe to (1) check the pointer for |
|
39243cde767f
lib: Keep an internal event category structure
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26653
diff
changeset
|
22 NULL/non-NULL to determine if this particular category instance |
|
39243cde767f
lib: Keep an internal event category structure
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26653
diff
changeset
|
23 has been registered, and (2) compare two categories' internal |
|
39243cde767f
lib: Keep an internal event category structure
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26653
diff
changeset
|
24 pointers to determine if they represent the same category. */ |
|
26653
dab46c3559e0
lib: events: Replace ->registered with ->internal
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26652
diff
changeset
|
25 void *internal; |
| 23949 | 26 }; |
| 27 | |
| 28 enum event_field_value_type { | |
| 29 EVENT_FIELD_VALUE_TYPE_STR, | |
| 30 EVENT_FIELD_VALUE_TYPE_INTMAX, | |
| 31 EVENT_FIELD_VALUE_TYPE_TIMEVAL, | |
| 32 }; | |
| 33 | |
| 34 struct event_field { | |
| 35 const char *key; | |
| 36 enum event_field_value_type value_type; | |
| 37 struct { | |
| 38 const char *str; | |
| 39 intmax_t intmax; | |
| 40 struct timeval timeval; | |
| 41 } value; | |
| 42 }; | |
| 43 | |
| 44 struct event_add_field { | |
| 45 const char *key; | |
| 46 /* The first non-0/NULL value is used. */ | |
| 47 const char *value; | |
| 48 intmax_t value_intmax; | |
| 49 struct timeval value_timeval; | |
| 50 }; | |
| 51 | |
| 52 struct event_passthrough { | |
| 53 /* wrappers to event_set_*() and event_add_*() for passthrough events, | |
| 54 so these can be chained like: | |
| 55 event_create_passthrough(parent)->name("name")->...->event() */ | |
| 56 struct event_passthrough * | |
| 57 (*append_log_prefix)(const char *prefix); | |
| 58 struct event_passthrough * | |
| 59 (*replace_log_prefix)(const char *prefix); | |
| 60 struct event_passthrough * | |
| 61 (*set_name)(const char *name); | |
| 62 struct event_passthrough * | |
| 63 (*set_source)(const char *filename, | |
| 64 unsigned int linenum, bool literal_fname); | |
| 65 struct event_passthrough * | |
| 66 (*set_always_log_source)(void); | |
| 67 | |
| 68 struct event_passthrough * | |
| 69 (*add_categories)(struct event_category *const *categories); | |
| 70 struct event_passthrough * | |
| 71 (*add_category)(struct event_category *category); | |
| 72 struct event_passthrough * | |
| 73 (*add_fields)(const struct event_add_field *fields); | |
| 74 | |
| 75 struct event_passthrough * | |
| 76 (*add_str)(const char *key, const char *value); | |
| 77 struct event_passthrough * | |
| 78 (*add_int)(const char *key, intmax_t num); | |
| 79 struct event_passthrough * | |
| 80 (*add_timeval)(const char *key, const struct timeval *tv); | |
|
25156
f79723963150
lib: lib-event - Add inc_int to passthrough events
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25133
diff
changeset
|
81 |
|
f79723963150
lib: lib-event - Add inc_int to passthrough events
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25133
diff
changeset
|
82 struct event_passthrough * |
|
f79723963150
lib: lib-event - Add inc_int to passthrough events
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25133
diff
changeset
|
83 (*inc_int)(const char *key, intmax_t num); |
|
f79723963150
lib: lib-event - Add inc_int to passthrough events
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25133
diff
changeset
|
84 |
|
26699
cb6e085f8d2d
lib: Add ->clear_field() passthrough event op
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26654
diff
changeset
|
85 struct event_passthrough * |
|
cb6e085f8d2d
lib: Add ->clear_field() passthrough event op
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26654
diff
changeset
|
86 (*clear_field)(const char *key); |
|
cb6e085f8d2d
lib: Add ->clear_field() passthrough event op
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26654
diff
changeset
|
87 |
| 23949 | 88 struct event *(*event)(void); |
| 89 }; | |
| 90 | |
|
26289
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
91 typedef const char * |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
92 event_log_prefix_callback_t(void *context); |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
93 typedef const char * |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
94 event_log_message_callback_t(void *context, enum log_type log_type, |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
95 const char *message); |
|
25661
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
96 |
|
25210
0f9f8c0177ff
lib: Add some event handling functions.
Sergey Kitov <sergey.kitov@open-xchange.com>
parents:
25156
diff
changeset
|
97 /* Returns TRUE if the event has all the categories that the "other" event has (and maybe more). */ |
|
0f9f8c0177ff
lib: Add some event handling functions.
Sergey Kitov <sergey.kitov@open-xchange.com>
parents:
25156
diff
changeset
|
98 bool event_has_all_categories(struct event *event, const struct event *other); |
|
0f9f8c0177ff
lib: Add some event handling functions.
Sergey Kitov <sergey.kitov@open-xchange.com>
parents:
25156
diff
changeset
|
99 /* Returns TRUE if the event has all the fields that the "other" event has (and maybe more). |
|
0f9f8c0177ff
lib: Add some event handling functions.
Sergey Kitov <sergey.kitov@open-xchange.com>
parents:
25156
diff
changeset
|
100 Only the fields in the events themselves are checked. Parent events' fields are not checked. */ |
|
0f9f8c0177ff
lib: Add some event handling functions.
Sergey Kitov <sergey.kitov@open-xchange.com>
parents:
25156
diff
changeset
|
101 bool event_has_all_fields(struct event *event, const struct event *other); |
|
0f9f8c0177ff
lib: Add some event handling functions.
Sergey Kitov <sergey.kitov@open-xchange.com>
parents:
25156
diff
changeset
|
102 |
|
26726
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
103 /* Returns the source event duplicated into a new event. Event pointers are |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
104 dropped. */ |
|
25210
0f9f8c0177ff
lib: Add some event handling functions.
Sergey Kitov <sergey.kitov@open-xchange.com>
parents:
25156
diff
changeset
|
105 struct event *event_dup(const struct event *source); |
|
26198
61c80663a129
lib: Add event_flatten() to return a flattened event
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26197
diff
changeset
|
106 /* Returns a flattened version of the source event. |
|
61c80663a129
lib: Add event_flatten() to return a flattened event
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26197
diff
changeset
|
107 Both categories and fields will be flattened. |
|
61c80663a129
lib: Add event_flatten() to return a flattened event
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26197
diff
changeset
|
108 A new reference to the source event is returned if no flattening was |
|
26726
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
109 needed. Event pointers are dropped if a new event was created. */ |
|
26198
61c80663a129
lib: Add event_flatten() to return a flattened event
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26197
diff
changeset
|
110 struct event *event_flatten(struct event *src); |
|
26204
fc89bb28362f
lib: Add event_minimize()
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26198
diff
changeset
|
111 /* Returns a minimized version of the source event. |
|
fc89bb28362f
lib: Add event_minimize()
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26198
diff
changeset
|
112 Remove parents with no fields or categories, attempt to flatten fields |
|
fc89bb28362f
lib: Add event_minimize()
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26198
diff
changeset
|
113 and categories to avoid sending one-off parent events. (There is a more |
|
fc89bb28362f
lib: Add event_minimize()
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26198
diff
changeset
|
114 detailed description in a comment above the function implementation.) |
|
fc89bb28362f
lib: Add event_minimize()
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26198
diff
changeset
|
115 A new reference to the source event is returned if no simplification |
|
26726
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
116 occured. Event pointers are dropped if a new event was created. */ |
|
26204
fc89bb28362f
lib: Add event_minimize()
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26198
diff
changeset
|
117 struct event *event_minimize(struct event *src); |
|
26197
93a9a741863a
lib: replace event_copy_categories_fields() into two
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26175
diff
changeset
|
118 /* Copy all categories from source to dest. |
|
93a9a741863a
lib: replace event_copy_categories_fields() into two
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26175
diff
changeset
|
119 Only the categories in source event itself are copied. |
|
93a9a741863a
lib: replace event_copy_categories_fields() into two
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26175
diff
changeset
|
120 Parent events' categories aren't copied. */ |
|
93a9a741863a
lib: replace event_copy_categories_fields() into two
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26175
diff
changeset
|
121 void event_copy_categories(struct event *to, struct event *from); |
|
93a9a741863a
lib: replace event_copy_categories_fields() into two
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26175
diff
changeset
|
122 /* Copy all fields from source to dest. |
|
93a9a741863a
lib: replace event_copy_categories_fields() into two
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26175
diff
changeset
|
123 Only the fields in source event itself are copied. |
|
93a9a741863a
lib: replace event_copy_categories_fields() into two
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26175
diff
changeset
|
124 Parent events' fields aren't copied. */ |
|
93a9a741863a
lib: replace event_copy_categories_fields() into two
Josef 'Jeff' Sipek <jeff.sipek@open-xchange.com>
parents:
26175
diff
changeset
|
125 void event_copy_fields(struct event *to, struct event *from); |
|
25210
0f9f8c0177ff
lib: Add some event handling functions.
Sergey Kitov <sergey.kitov@open-xchange.com>
parents:
25156
diff
changeset
|
126 |
| 23949 | 127 /* Create a new empty event under the parent event, or NULL for root event. */ |
| 128 struct event *event_create(struct event *parent, const char *source_filename, | |
| 129 unsigned int source_linenum); | |
| 130 #define event_create(parent) \ | |
| 131 event_create((parent), __FILE__, __LINE__) | |
| 132 /* This is a temporary "passthrough" event. Its main purpose is to make it | |
| 133 easier to create temporary events as part of the event parameter in | |
| 134 e_error(), e_warning(), e_info() or e_debug(). These passthrough events are | |
| 135 automatically freed when the e_*() call is finished. Because this makes the | |
| 136 freeing less obvious, it should be avoided outside e_*()'s event parameter. | |
| 137 | |
| 138 The passthrough events also change the API to be more convenient towards | |
| 139 being used in a parameter. Instead of having to use e.g. | |
| 140 event_add_str(event_set_name(event_create(parent), "name"), "key", "value") | |
| 141 the event_passthrough API can be a bit more readable as: | |
| 142 event_create_passthrough(parent)->set_name("name")-> | |
| 143 add_str("key", "value")->event(). The passthrough event is converted to | |
| 144 a normal event at the end with the event() call. Note that this API works | |
| 145 by modifying the last created passthrough event, so it's not possible to | |
| 146 have multiple passthrough events created in parallel. */ | |
| 147 struct event_passthrough * | |
| 148 event_create_passthrough(struct event *parent, const char *source_filename, | |
| 149 unsigned int source_linenum); | |
| 150 #define event_create_passthrough(parent) \ | |
| 151 event_create_passthrough((parent), __FILE__, __LINE__) | |
| 152 | |
| 153 /* Reference the event. Returns the event parameter. */ | |
| 154 struct event *event_ref(struct event *event); | |
| 155 /* Unreference the event. If the reference count drops to 0, the event is | |
| 156 freed. The current global event's refcount must not drop to 0. */ | |
| 157 void event_unref(struct event **event); | |
| 158 | |
| 159 /* Set the event to be the global default event used by i_error(), etc. | |
| 160 Returns the event parameter. The event must be explicitly popped before | |
| 161 it's freed. | |
| 162 | |
| 163 The global event stack is also an alternative nonpermanent hierarchy for | |
| 164 events. For example the global event can be "IMAP command SELECT", which | |
| 165 can be used for filtering events that happen while the SELECT command is | |
| 166 being executed. However, for the created struct mailbox the parent event | |
| 167 should be the mail_user, not the SELECT command. Otherwise everything else | |
| 168 that happens afterwards to the selected mailbox would also count towards | |
| 169 SELECT. This means that events shouldn't be using the current global event | |
| 170 as their parent event. */ | |
| 171 struct event *event_push_global(struct event *event); | |
| 172 /* Pop the global event. Assert-crash if the current global event isn't the | |
| 173 given event parameter. Returns the new global event. */ | |
| 174 struct event *event_pop_global(struct event *event); | |
| 175 /* Returns the current global event. */ | |
| 176 struct event *event_get_global(void); | |
| 177 | |
| 178 /* Set the appended log prefix string for this event. All the parent events' | |
|
25222
0ed420965507
lib: Move log type to be written before appended log prefix
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25210
diff
changeset
|
179 log prefixes will be concatenated together when logging. The log type |
|
0ed420965507
lib: Move log type to be written before appended log prefix
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25210
diff
changeset
|
180 text (e.g. "Info: ") will be inserted before appended log prefixes (but |
|
25661
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
181 after replaced log prefix). |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
182 |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
183 Clears log_prefix callback. |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
184 */ |
| 23949 | 185 struct event * |
| 186 event_set_append_log_prefix(struct event *event, const char *prefix); | |
| 187 /* Replace the full log prefix string for this event. The parent events' log | |
|
26289
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
188 prefixes won't be used. Also, any parent event's message amendment callback |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
189 is not used. |
|
25661
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
190 |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
191 Clears log_prefix callback. |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
192 */ |
| 23949 | 193 struct event *event_replace_log_prefix(struct event *event, const char *prefix); |
| 194 | |
|
26329
12df5cbda60a
lib: lib-event - Add support for dropping log prefixes introduced by parent events.
Stephan Bosch <stephan.bosch@open-xchange.com>
parents:
26290
diff
changeset
|
195 /* Drop count prefixes from parents when this event is used for logging. This |
|
12df5cbda60a
lib: lib-event - Add support for dropping log prefixes introduced by parent events.
Stephan Bosch <stephan.bosch@open-xchange.com>
parents:
26290
diff
changeset
|
196 does not affect the parent events. This only counts actual prefixes and not |
|
12df5cbda60a
lib: lib-event - Add support for dropping log prefixes introduced by parent events.
Stephan Bosch <stephan.bosch@open-xchange.com>
parents:
26290
diff
changeset
|
197 parents. If the count is higher than the actual number of prefixes added by |
|
12df5cbda60a
lib: lib-event - Add support for dropping log prefixes introduced by parent events.
Stephan Bosch <stephan.bosch@open-xchange.com>
parents:
26290
diff
changeset
|
198 parents, all will be dropped. */ |
|
12df5cbda60a
lib: lib-event - Add support for dropping log prefixes introduced by parent events.
Stephan Bosch <stephan.bosch@open-xchange.com>
parents:
26290
diff
changeset
|
199 struct event * |
|
12df5cbda60a
lib: lib-event - Add support for dropping log prefixes introduced by parent events.
Stephan Bosch <stephan.bosch@open-xchange.com>
parents:
26290
diff
changeset
|
200 event_drop_parent_log_prefixes(struct event *event, unsigned int count); |
|
25661
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
201 |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
202 /* Sets event prefix callback, sets log_prefix empty */ |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
203 struct event *event_set_log_prefix_callback(struct event *event, |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
204 bool replace, |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
205 event_log_prefix_callback_t *callback, |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
206 void *context); |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
207 #define event_set_log_prefix_callback(event, replace, callback, context) \ |
|
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
208 event_set_log_prefix_callback(event, replace, (event_log_prefix_callback_t*)callback, \ |
|
26175
f04aaf1249f2
global: Change CALLBACK_TYPECHECK() to used with subtraction
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
25731
diff
changeset
|
209 context - CALLBACK_TYPECHECK(callback, const char *(*)(typeof(context)))) |
|
25661
86b6c23d1d6a
lib: event - Add event_set_log_prefix_callback
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25501
diff
changeset
|
210 |
|
26289
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
211 /* Sets event message amendment callback */ |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
212 struct event *event_set_log_message_callback(struct event *event, |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
213 event_log_message_callback_t *callback, |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
214 void *context); |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
215 #define event_set_log_message_callback(event, callback, context) \ |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
216 event_set_log_message_callback(event, \ |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
217 (event_log_message_callback_t*)callback, \ |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
218 context - CALLBACK_TYPECHECK(callback, \ |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
219 const char *(*)(typeof(context), enum log_type, \ |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
220 const char *))) |
|
5187df6aa0b5
lib: lib-event - Add support for amending the event log message in a callback.
Stephan Bosch <stephan.bosch@dovecot.fi>
parents:
26204
diff
changeset
|
221 |
| 23949 | 222 /* Set the event's name. The name is specific to a single sending of an event, |
| 223 and it'll be automatically cleared once the event is sent. This should | |
| 224 typically be used only in a parameter to e_debug(), etc. */ | |
| 225 struct event * | |
| 226 event_set_name(struct event *event, const char *name); | |
| 227 /* Set the source filename:linenum to the event. If literal_fname==TRUE, | |
| 228 it's assumed that __FILE__ has been used and the pointer is stored directly, | |
| 229 otherwise the filename is strdup()ed. */ | |
| 230 struct event * | |
| 231 event_set_source(struct event *event, const char *filename, | |
| 232 unsigned int linenum, bool literal_fname); | |
| 233 /* Always include the source path:line in the log replies. This is | |
| 234 especially useful when logging about unexpected syscall failures, because | |
| 235 it allow quickly finding which of the otherwise identical syscalls in the | |
| 236 code generated the error. */ | |
| 237 struct event *event_set_always_log_source(struct event *event); | |
|
25731
8f053eda8a69
lib: event - Add min_log_level
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25661
diff
changeset
|
238 /* Set minimum log level for the event */ |
|
8f053eda8a69
lib: event - Add min_log_level
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25661
diff
changeset
|
239 struct event *event_set_min_log_level(struct event *event, enum log_type level); |
|
8f053eda8a69
lib: event - Add min_log_level
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25661
diff
changeset
|
240 enum log_type event_get_min_log_level(const struct event *event); |
| 23949 | 241 |
|
26726
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
242 /* Add an internal pointer to an event. It can be looked up only with |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
243 event_get_ptr(). The keys are in their own namespace and won't conflict |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
244 with event fields. The pointers are specific to this specific event only - |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
245 they will be dropped from any duplicated/flattened/minimized events. */ |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
246 struct event *event_set_ptr(struct event *event, const char *key, void *value); |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
247 /* Return a pointer set with event_set_ptr(), or NULL if it doesn't exist. |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
248 The pointer is looked up only from the event itself, not its parents. */ |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
249 void *event_get_ptr(struct event *event, const char *key); |
|
e3129a5210e4
lib: Allow events to store internal pointers
Timo Sirainen <timo.sirainen@open-xchange.com>
parents:
26699
diff
changeset
|
250 |
| 23949 | 251 /* Add NULL-terminated list of categories to the event. The categories pointer |
| 252 doesn't need to stay valid afterwards, but the event_category structs | |
| 253 themselves must be. Returns the event parameter. */ | |
| 254 struct event * | |
| 255 event_add_categories(struct event *event, | |
| 256 struct event_category *const *categories); | |
| 257 /* Add a single category to the event. */ | |
| 258 struct event * | |
| 259 event_add_category(struct event *event, struct event_category *category); | |
| 260 | |
| 261 /* Add key=value field to the event. If a key already exists, it's replaced. | |
| 262 Child events automatically inherit key=values from their parents at the | |
| 263 time the event is sent. So changing a key in parent will change the values | |
|
25133
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
264 in the child events as well, unless the key has been overwritten in the |
|
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
265 child event. Setting the value to "" is the same as event_field_clear(). |
|
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
266 Returns the event parameter. */ |
| 23949 | 267 struct event * |
| 268 event_add_str(struct event *event, const char *key, const char *value); | |
| 269 struct event * | |
| 270 event_add_int(struct event *event, const char *key, intmax_t num); | |
|
25132
bd08f13e1c88
lib: Add event_inc_int()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
23949
diff
changeset
|
271 /* Increase the key's value. If it's not set or isn't an integer type, |
|
bd08f13e1c88
lib: Add event_inc_int()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
23949
diff
changeset
|
272 initialize the value to num. */ |
|
bd08f13e1c88
lib: Add event_inc_int()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
23949
diff
changeset
|
273 struct event * |
|
bd08f13e1c88
lib: Add event_inc_int()
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
23949
diff
changeset
|
274 event_inc_int(struct event *event, const char *key, intmax_t num); |
| 23949 | 275 struct event * |
| 276 event_add_timeval(struct event *event, const char *key, | |
| 277 const struct timeval *tv); | |
| 278 /* Same as event_add_str/int(), but do it via event_field struct. The fields | |
| 279 terminates with key=NULL. Returns the event parameter. */ | |
| 280 struct event * | |
| 281 event_add_fields(struct event *event, const struct event_add_field *fields); | |
|
25133
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
282 /* Mark a field as nonexistent. If a parent event has the field set, this |
|
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
283 allows removing it from the child event. Using an event filter with e.g. |
|
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
284 "key=*" won't match this field anymore, although it's still visible in |
|
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
285 event_find_field*() and event_get_fields(). This is the same as using |
|
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
286 event_add_str() with value="". */ |
|
26f8ad2dec93
lib: Add event_field_clear() to allow clearing parent event's fields
Timo Sirainen <timo.sirainen@dovecot.fi>
parents:
25132
diff
changeset
|
287 void event_field_clear(struct event *event, const char *key); |
| 23949 | 288 |
| 289 /* Returns the parent event, or NULL if it doesn't exist. */ | |
| 290 struct event *event_get_parent(struct event *event); | |
| 291 /* Get the event's creation time. */ | |
| 292 void event_get_create_time(struct event *event, struct timeval *tv_r); | |
| 293 /* Get the time when the event was last sent. Returns TRUE if time was | |
| 294 returned, FALSE if event has never been sent. */ | |
| 295 bool event_get_last_send_time(struct event *event, struct timeval *tv_r); | |
|
25501
d472067ab34a
lib: event - Record real duration
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25222
diff
changeset
|
296 /* Get the event duration field, calculated after event has been sent. */ |
|
d472067ab34a
lib: event - Record real duration
Aki Tuomi <aki.tuomi@dovecot.fi>
parents:
25222
diff
changeset
|
297 void event_get_last_duration(struct event *event, intmax_t *duration_msec_r); |
| 23949 | 298 /* Returns field for a given key, or NULL if it doesn't exist. If the key |
| 299 isn't found from the event itself, find it from parent events. */ | |
| 300 const struct event_field * | |
| 301 event_find_field(struct event *event, const char *key); | |
| 302 /* Returns the given key's value as string, or NULL if it doesn't exist. | |
| 303 If the field isn't stored as a string, the result is allocated from | |
| 304 data stack. */ | |
| 305 const char * | |
| 306 event_find_field_str(struct event *event, const char *key); | |
| 307 /* Returns all key=value fields that the event has. | |
| 308 Parent events' fields aren't returned. */ | |
| 309 const struct event_field * | |
| 310 event_get_fields(struct event *event, unsigned int *count_r); | |
| 311 /* Return all categories that the event has. | |
| 312 Parent events' categories aren't returned. */ | |
| 313 struct event_category *const * | |
| 314 event_get_categories(struct event *event, unsigned int *count_r); | |
| 315 | |
| 316 /* Export the event into a tabescaped string, so its fields are separated | |
| 317 with TABs and there are no NUL, CR or LF characters. */ | |
| 318 void event_export(const struct event *event, string_t *dest); | |
| 319 /* Import event. The string is expected to be generated by event_export(). | |
| 320 All the used categories must already be registered. | |
| 321 Returns TRUE on success, FALSE on invalid string. */ | |
| 322 bool event_import(struct event *event, const char *str, const char **error_r); | |
| 323 /* Same as event_import(), but string is already split into an array | |
| 324 of strings via *_strsplit_tabescaped(). */ | |
| 325 bool event_import_unescaped(struct event *event, const char *const *args, | |
| 326 const char **error_r); | |
| 327 | |
| 328 /* The event wasn't sent after all - free everything related to it. | |
| 329 Most importantly this frees any passthrough events. Typically this shouldn't | |
| 330 need to be called. */ | |
| 331 void event_send_abort(struct event *event); | |
| 332 | |
| 333 void lib_event_init(void); | |
| 334 void lib_event_deinit(void); | |
| 335 | |
| 336 #endif |