[lttng-tools.git] / include / lttng / event-field-value.h

/*
 * Copyright (C) 2020 Philippe Proulx <pproulx@efficios.com>
 *
 * SPDX-License-Identifier: LGPL-2.1-only
 *
 */

#ifndef LTTNG_EVENT_FIELD_VALUE_H
#define LTTNG_EVENT_FIELD_VALUE_H

#include <stdint.h>

struct lttng_event_field_value;

#ifdef __cplusplus
extern "C" {
#endif

/*
 * Types of a event field value expression.
 */
enum lttng_event_field_value_type {
	/*
	 * Unknown.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_UNKNOWN = -2,

	/*
	 * Returned by lttng_event_field_value_get_type() with an
	 * invalid parameter.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_INVALID = -1,

	/*
	 * Unsigned integer event field value.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT = 0,

	/*
	 * Signed integer event field value.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT = 1,

	/*
	 * Unsigned enumeration event field value.
	 *
	 * This type conceptually inherits
	 * `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT`.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_ENUM = 2,

	/*
	 * Signed enumeration event field value.
	 *
	 * This type conceptually inherits
	 * `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT`.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_ENUM = 3,

	/*
	 * Real event field value.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_REAL = 4,

	/*
	 * String event field value.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_STRING = 5,

	/*
	 * Array event field value.
	 */
	LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY = 6,
};

/*
 * Event field value API status codes.
 */
enum lttng_event_field_value_status {
	/*
	 * Event field value is not available.
	 */
	LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE = -2,

	/*
	 * Invalid parameter.
	 */
	LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID = -1,

	/*
	 * Success.
	 */
	LTTNG_EVENT_FIELD_VALUE_STATUS_OK = 0,
};

/*
 * Returns the type of the event field value `field_val`, or:
 *
 * `LTTNG_EVENT_FIELD_VALUE_TYPE_UNKNOWN`:
 *     The type of `field_val` is unknown as of this version of the
 *     LTTng control library.
 *
 * `LTTNG_EVENT_FIELD_VALUE_TYPE_INVALID`:
 *     `field_val` is `NULL`.
 */
extern enum lttng_event_field_value_type lttng_event_field_value_get_type(
		const struct lttng_event_field_value *field_val);

/*
 * Sets `*val` to the raw value of the unsigned integer/enumeration
 * event field value `field_val`.
 *
 * Returns:
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 *     * `field_val` is `NULL`.
 *     * The type of `field_val` is not
 *       `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT` or
 *       `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_ENUM`.
 *     * `val` is `NULL`.
 */
extern enum lttng_event_field_value_status
lttng_event_field_value_unsigned_int_get_value(
		const struct lttng_event_field_value *field_val, uint64_t *val);

/*
 * Sets `*val` to the raw value of the signed integer/enumeration event
 * field value `field_val`.
 *
 * Returns:
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 *     * `field_val` is `NULL`.
 *     * The type of `field_val` is not
 *       `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT` or
 *       `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_ENUM`.
 *     * `val` is `NULL`.
 */
extern enum lttng_event_field_value_status
lttng_event_field_value_signed_int_get_value(
		const struct lttng_event_field_value *field_val, int64_t *val);

/*
 * Sets `*val` to the raw value of the real event field value
 * `field_val`.
 *
 * Returns:
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 *     * `field_val` is `NULL`.
 *     * The type of `field_val` is not
 *       `LTTNG_EVENT_FIELD_VALUE_TYPE_REAL`.
 *     * `val` is `NULL`.
 */
extern enum lttng_event_field_value_status
lttng_event_field_value_real_get_value(
		const struct lttng_event_field_value *field_val, double *val);

/*
 * Returns the raw value (an UTF-8 C string) of the string event field
 * value `field_val`, or `NULL` if:
 *
 * * `field_val` is `NULL`.
 * * The type of `field_val` is not
 *   `LTTNG_EVENT_FIELD_VALUE_TYPE_STRING`.
 */
extern const char *lttng_event_field_value_string_get_value(
		const struct lttng_event_field_value *field_val);

/*
 * Sets `*length` to the length (the number of contained elements) of
 * the array event field value `field_val`.
 *
 * Returns:
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 *     * `field_val` is `NULL`.
 *     * The type of `field_val` is not
 *       `LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY`.
 *     * `length` is `NULL`.
 */
extern enum lttng_event_field_value_status
lttng_event_field_value_array_get_length(
		const struct lttng_event_field_value *field_val,
		unsigned int *length);

/*
 * Sets `*elem_field_val` to the event field value at index `index` in
 * the array event field value `field_val`.
 *
 * Returns:
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
 *     Success.
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
 *     * `field_val` is `NULL`.
 *     * The type of `field_val` is not
 *       `LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY`.
 *     * `index` is greater than or equal to the length of `field_val`,
 *       as returned by lttng_event_field_value_array_get_length().
 *
 * `LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE`:
 *     * No event field value exists at index `index` within
 *       `field_val`.
 */
extern enum lttng_event_field_value_status
lttng_event_field_value_array_get_element_at_index(
		const struct lttng_event_field_value *field_val,
		unsigned int index,
		const struct lttng_event_field_value **elem_field_val);

#ifdef __cplusplus
}
#endif

#endif /* LTTNG_EVENT_FIELD_VALUE_H */
Commit	Line	Data
2463b787 JR	1	/*
	2	* Copyright (C) 2020 Philippe Proulx <pproulx@efficios.com>
	3	*
	4	* SPDX-License-Identifier: LGPL-2.1-only
	5	*
	6	*/
	7
	8	#ifndef LTTNG_EVENT_FIELD_VALUE_H
	9	#define LTTNG_EVENT_FIELD_VALUE_H
	10
	11	#include <stdint.h>
	12
	13	struct lttng_event_field_value;
	14
	15	#ifdef __cplusplus
	16	extern "C" {
	17	#endif
	18
	19	/*
	20	* Types of a event field value expression.
	21	*/
	22	enum lttng_event_field_value_type {
	23	/*
	24	* Unknown.
	25	*/
	26	LTTNG_EVENT_FIELD_VALUE_TYPE_UNKNOWN = -2,
	27
	28	/*
	29	* Returned by lttng_event_field_value_get_type() with an
	30	* invalid parameter.
	31	*/
	32	LTTNG_EVENT_FIELD_VALUE_TYPE_INVALID = -1,
	33
	34	/*
	35	* Unsigned integer event field value.
	36	*/
	37	LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT = 0,
	38
	39	/*
	40	* Signed integer event field value.
	41	*/
	42	LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT = 1,
	43
	44	/*
	45	* Unsigned enumeration event field value.
	46	*
	47	* This type conceptually inherits
	48	* `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT`.
	49	*/
	50	LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_ENUM = 2,
	51
	52	/*
	53	* Signed enumeration event field value.
	54	*
	55	* This type conceptually inherits
	56	* `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT`.
	57	*/
	58	LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_ENUM = 3,
	59
	60	/*
	61	* Real event field value.
	62	*/
	63	LTTNG_EVENT_FIELD_VALUE_TYPE_REAL = 4,
	64
65	/*
66	* String event field value.
67	*/
68	LTTNG_EVENT_FIELD_VALUE_TYPE_STRING = 5,
69
70	/*
71	* Array event field value.
72	*/
73	LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY = 6,
74	};
75
76	/*
77	* Event field value API status codes.
78	*/
79	enum lttng_event_field_value_status {
80	/*
81	* Event field value is not available.
82	*/
83	LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE = -2,
84
85	/*
86	* Invalid parameter.
87	*/
88	LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID = -1,
89
90	/*
91	* Success.
92	*/
93	LTTNG_EVENT_FIELD_VALUE_STATUS_OK = 0,
94	};
95
96	/*
97	* Returns the type of the event field value `field_val`, or:
98	*
99	* `LTTNG_EVENT_FIELD_VALUE_TYPE_UNKNOWN`:
100	* The type of `field_val` is unknown as of this version of the
101	* LTTng control library.
102	*
103	* `LTTNG_EVENT_FIELD_VALUE_TYPE_INVALID`:
104	* `field_val` is `NULL`.
105	*/
106	extern enum lttng_event_field_value_type lttng_event_field_value_get_type(
107	const struct lttng_event_field_value *field_val);
108
109	/*
110	* Sets `*val` to the raw value of the unsigned integer/enumeration
111	* event field value `field_val`.
112	*
113	* Returns:
114	*
115	* `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
116	* Success.
117	*
118	* `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
119	* * `field_val` is `NULL`.
120	* * The type of `field_val` is not
121	* `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_INT` or
122	* `LTTNG_EVENT_FIELD_VALUE_TYPE_UNSIGNED_ENUM`.
123	* * `val` is `NULL`.
124	*/
125	extern enum lttng_event_field_value_status
126	lttng_event_field_value_unsigned_int_get_value(
127	const struct lttng_event_field_value field_val, uint64_t val);
128
129	/*
130	* Sets `*val` to the raw value of the signed integer/enumeration event
131	* field value `field_val`.
132	*
133	* Returns:
134	*
135	* `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
136	* Success.
137	*
138	* `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
139	* * `field_val` is `NULL`.
140	* * The type of `field_val` is not
141	* `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_INT` or
142	* `LTTNG_EVENT_FIELD_VALUE_TYPE_SIGNED_ENUM`.
143	* * `val` is `NULL`.
144	*/
145	extern enum lttng_event_field_value_status
146	lttng_event_field_value_signed_int_get_value(
147	const struct lttng_event_field_value field_val, int64_t val);
148
149	/*
150	* Sets `*val` to the raw value of the real event field value
151	* `field_val`.
152	*
153	* Returns:
154	*
155	* `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
156	* Success.
157	*
158	* `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
159	* * `field_val` is `NULL`.
160	* * The type of `field_val` is not
161	* `LTTNG_EVENT_FIELD_VALUE_TYPE_REAL`.
162	* * `val` is `NULL`.
163	*/
164	extern enum lttng_event_field_value_status
165	lttng_event_field_value_real_get_value(
166	const struct lttng_event_field_value field_val, double val);
167
168	/*
169	* Returns the raw value (an UTF-8 C string) of the string event field
170	* value `field_val`, or `NULL` if:
171	*
172	* * `field_val` is `NULL`.
173	* * The type of `field_val` is not
174	* `LTTNG_EVENT_FIELD_VALUE_TYPE_STRING`.
175	*/
176	extern const char *lttng_event_field_value_string_get_value(
177	const struct lttng_event_field_value *field_val);
178
179	/*
180	* Sets `*length` to the length (the number of contained elements) of
181	* the array event field value `field_val`.
182	*
183	* Returns:
184	*
185	* `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
186	* Success.
187	*
188	* `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
189	* * `field_val` is `NULL`.
190	* * The type of `field_val` is not
191	* `LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY`.
192	* * `length` is `NULL`.
193	*/
194	extern enum lttng_event_field_value_status
195	lttng_event_field_value_array_get_length(
196	const struct lttng_event_field_value *field_val,
197	unsigned int *length);
198
199	/*
200	* Sets `*elem_field_val` to the event field value at index `index` in
201	* the array event field value `field_val`.
202	*
203	* Returns:
204	*
205	* `LTTNG_EVENT_FIELD_VALUE_STATUS_OK`:
206	* Success.
207	*
208	* `LTTNG_EVENT_FIELD_VALUE_STATUS_INVALID`:
209	* * `field_val` is `NULL`.
210	* * The type of `field_val` is not
211	* `LTTNG_EVENT_FIELD_VALUE_TYPE_ARRAY`.
212	* * `index` is greater than or equal to the length of `field_val`,
213	* as returned by lttng_event_field_value_array_get_length().
214	*
215	* `LTTNG_EVENT_FIELD_VALUE_STATUS_UNAVAILABLE`:
216	* * No event field value exists at index `index` within
217	* `field_val`.
218	*/
219	extern enum lttng_event_field_value_status
220	lttng_event_field_value_array_get_element_at_index(
221	const struct lttng_event_field_value *field_val,
222	unsigned int index,
223	const struct lttng_event_field_value **elem_field_val);
224
225	#ifdef __cplusplus
226	}
227	#endif
228
229	#endif /* LTTNG_EVENT_FIELD_VALUE_H */