hook_context.h File Reference

C bindings for passing caller data to hooks. More...

#include <launchdarkly/bindings/c/export.h>

Include dependency graph for hook_context.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Typedefs
typedef struct p_LDHookContext *	LDHookContext
	Opaque hook context handle. More...

Functions
	LDHookContext_New (void)
	Create a new hook context. More...
	LDHookContext_Set (LDHookContext hook_context, char const *key, void const *value)
	Set a pointer value in the hook context. More...
	LDHookContext_Get (LDHookContext hook_context, char const *key, void const **out_value)
	Get a pointer value from the hook context. More...
	LDHookContext_Free (LDHookContext hook_context)
	Free a hook context. More...

Detailed Description

C bindings for passing caller data to hooks.

HookContext allows application code to pass arbitrary data through to hooks. This is useful for propagating context like OpenTelemetry span parents in asynchronous web frameworks where thread-local storage doesn't work.

USAGE: Most applications don't need HookContext. Only use it when you need to pass data from the evaluation call site to your hooks, such as:

• OpenTelemetry span parents in async frameworks
• Request IDs for distributed tracing
• Custom metadata for logging

LIFETIME AND OWNERSHIP:

• Hook context must remain valid for the duration of the variation call
• Data stored in hook context must be managed by the caller
• Hook context can be stack-allocated and freed after the variation call

Typedef Documentation

LDHookContext

typedef struct p_LDHookContext* LDHookContext

Opaque hook context handle.

Created by LDHookContext_New(), must be freed with LDHookContext_Free().

Function Documentation

LDHookContext_Free()

LDHookContext_Free

(

LDHookContext

hook_context

)

Free a hook context.

Parameters

hook_context

Hook context to free. May be NULL (no-op).

LDHookContext_Get()

LDHookContext_Get	(	LDHookContext	hook_context,
		char const *	key,
		void const **	out_value
	)

Get a pointer value from the hook context.

Retrieves an application-specific pointer previously stored with LDHookContext_Set().

USAGE IN HOOKS:

void* span_parent;
if (LDHookContext_Get(hook_ctx, "span_parent", &span_parent)) {
    // Use span_parent
}

Parameters

hook_context	Hook context. Must not be NULL.
key	Key to look up. Must be null-terminated UTF-8 string. Must not be NULL.
out_value	Pointer to receive the value. Must not be NULL. Set to NULL if key not found.

Returns

true if key was found, false otherwise.

LDHookContext_New()

LDHookContext_New

(

void

)

Create a new hook context.

Returns

New hook context. Must be freed with LDHookContext_Free().

LDHookContext_Set()

LDHookContext_Set	(	LDHookContext	hook_context,
		char const *	key,
		void const *	value
	)

Set a pointer value in the hook context.

Stores an application-specific pointer that can be retrieved by hooks. The lifetime of the pointed-to data must extend through the variation call.

EXAMPLE - OpenTelemetry span parent:

LDHookContext ctx = LDHookContext_New();
LDHookContext_Set(ctx, "span_parent", my_span_context);
bool result = LDClientSDK_BoolVariation_WithHookContext(
    client, context, "flag-key", false, ctx);
LDHookContext_Free(ctx);

Parameters

hook_context	Hook context. Must not be NULL.
key	Key for the value. Must be null-terminated UTF-8 string. Must not be NULL.
value	Pointer to application data. May be NULL. Lifetime managed by caller - must remain valid through the variation call.