[lttng-ust.git] / src / common / ust-context-provider.h

/*
 * SPDX-License-Identifier: MIT
 *
 * Copyright (C) 2016 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
 *
 * The context provider feature is part of the ABI and used by the Java jni
 * interface. This header should be moved to the public header directory once
 * some test code and documentation is written.
 */

#ifndef _LTTNG_UST_CONTEXT_PROVIDER_H
#define _LTTNG_UST_CONTEXT_PROVIDER_H

#include <stddef.h>
#include <lttng/ust-events.h>

#include "common/dynamic-type.h"

struct lttng_ust_registered_context_provider;
struct lttng_ust_probe_ctx;

/*
 * Context value
 *
 * IMPORTANT: this structure is part of the ABI between the probe and
 * UST. Additional selectors may be added in the future, mapping to new
 * union fields, which means the overall size of this structure may
 * increase. This means this structure should never be nested within a
 * public structure interface, nor embedded in an array.
 */

struct lttng_ust_ctx_value {
	enum lttng_ust_dynamic_type sel;	/* Type selector */
	union {
		int64_t s64;
		uint64_t u64;
		const char *str;
		double d;
	} u;
};

/*
 * Context provider
 *
 * IMPORTANT: this structure is part of the ABI between the probe and
 * UST. Fields need to be only added at the end, never reordered, never
 * removed.
 *
 * The field @struct_size should be used to determine the size of the
 * structure. It should be queried before using additional fields added
 * at the end of the structure.
 */

struct lttng_ust_context_provider {
	uint32_t struct_size;

	const char *name;
	size_t (*get_size)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
			size_t offset);
	void (*record)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
			struct lttng_ust_ring_buffer_ctx *ctx,
			struct lttng_ust_channel_buffer *chan);
	void (*get_value)(void *priv, struct lttng_ust_probe_ctx *probe_ctx,
			struct lttng_ust_ctx_value *value);
	void *priv;

	/* End of base ABI. Fields below should be used after checking struct_size. */
};

/*
 * Application context callback private data
 *
 * IMPORTANT: this structure is part of the ABI between the probe and
 * UST. Fields need to be only added at the end, never reordered, never
 * removed.
 *
 * The field @struct_size should be used to determine the size of the
 * structure. It should be queried before using additional fields added
 * at the end of the structure.
 */

struct lttng_ust_app_context {
	uint32_t struct_size;

	struct lttng_ust_event_field *event_field;
	char *ctx_name;

	/* End of base ABI. Fields below should be used after checking struct_size. */
};

/*
 * Returns an opaque pointer on success, which must be passed to
 * lttng_ust_context_provider_unregister for unregistration. Returns
 * NULL on error.
 */
struct lttng_ust_registered_context_provider *lttng_ust_context_provider_register(struct lttng_ust_context_provider *provider);

void lttng_ust_context_provider_unregister(struct lttng_ust_registered_context_provider *reg_provider);

#endif /* _LTTNG_UST_CONTEXT_PROVIDER_H */
Commit	Line	Data
53569322	1	/*
c0c0989a	2	* SPDX-License-Identifier: MIT
53569322	3	*
c0c0989a	4	* Copyright (C) 2016 Mathieu Desnoyers <mathieu.desnoyers@efficios.com>
28b9540b MJ	5	*
	6	* The context provider feature is part of the ABI and used by the Java jni
	7	* interface. This header should be moved to the public header directory once
	8	* some test code and documentation is written.
53569322 MD	9	*/
53569322 MD	10
c0c0989a MJ	11	#ifndef _LTTNG_UST_CONTEXT_PROVIDER_H
	12	#define _LTTNG_UST_CONTEXT_PROVIDER_H
	13
b4051ad8	14	#include <stddef.h>
53569322	15	#include <lttng/ust-events.h>
53569322	16
9d315d6d	17	#include "common/dynamic-type.h"
fa194c41	18
4e48b5d2	19	struct lttng_ust_registered_context_provider;
b2e37d27	20	struct lttng_ust_probe_ctx;
4e48b5d2	21
daacdbfc MD	22	/*
	23	* Context value
	24	*
	25	* IMPORTANT: this structure is part of the ABI between the probe and
35c1f459 MD	26	* UST. Additional selectors may be added in the future, mapping to new
	27	* union fields, which means the overall size of this structure may
	28	* increase. This means this structure should never be nested within a
	29	* public structure interface, nor embedded in an array.
daacdbfc MD	30	*/
	31
	32	struct lttng_ust_ctx_value {
35c1f459	33	enum lttng_ust_dynamic_type sel; /* Type selector */
fa194c41 MJ	34	union {
	35	int64_t s64;
	36	uint64_t u64;
	37	const char *str;
	38	double d;
	39	} u;
	40	};
	41
daacdbfc MD	42	/*
	43	* Context provider
	44	*
	45	* IMPORTANT: this structure is part of the ABI between the probe and
	46	* UST. Fields need to be only added at the end, never reordered, never
	47	* removed.
	48	*
	49	* The field @struct_size should be used to determine the size of the
	50	* structure. It should be queried before using additional fields added
	51	* at the end of the structure.
	52	*/
	53
53569322	54	struct lttng_ust_context_provider {
daacdbfc MD	55	uint32_t struct_size;
daacdbfc MD	56
4e48b5d2	57	const char *name;
b2e37d27 MD	58	size_t (get_size)(void priv, struct lttng_ust_probe_ctx *probe_ctx,
	59	size_t offset);
	60	void (record)(void priv, struct lttng_ust_probe_ctx *probe_ctx,
	61	struct lttng_ust_ring_buffer_ctx *ctx,
	62	struct lttng_ust_channel_buffer *chan);
	63	void (get_value)(void priv, struct lttng_ust_probe_ctx *probe_ctx,
	64	struct lttng_ust_ctx_value *value);
4e48b5d2	65	void *priv;
daacdbfc MD	66
daacdbfc MD	67	/* End of base ABI. Fields below should be used after checking struct_size. */
53569322 MD	68	};
53569322 MD	69
577f6dfc MD	70	/*
	71	* Application context callback private data
	72	*
	73	* IMPORTANT: this structure is part of the ABI between the probe and
	74	* UST. Fields need to be only added at the end, never reordered, never
	75	* removed.
	76	*
	77	* The field @struct_size should be used to determine the size of the
	78	* structure. It should be queried before using additional fields added
	79	* at the end of the structure.
	80	*/
	81
	82	struct lttng_ust_app_context {
	83	uint32_t struct_size;
	84
	85	struct lttng_ust_event_field *event_field;
	86	char *ctx_name;
	87
	88	/* End of base ABI. Fields below should be used after checking struct_size. */
	89	};
	90
4e48b5d2 MD	91	/*
	92	* Returns an opaque pointer on success, which must be passed to
	93	* lttng_ust_context_provider_unregister for unregistration. Returns
	94	* NULL on error.
	95	*/
	96	struct lttng_ust_registered_context_provider lttng_ust_context_provider_register(struct lttng_ust_context_provider provider);
53569322	97
4e48b5d2	98	void lttng_ust_context_provider_unregister(struct lttng_ust_registered_context_provider *reg_provider);
53569322 MD	99
53569322 MD	100	#endif /* _LTTNG_UST_CONTEXT_PROVIDER_H */