hook.h File Reference

C bindings for LaunchDarkly SDK hooks. More...

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

Include dependency graph for hook.h:

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

Go to the source code of this file.

Classes
struct	LDServerSDKHook
	Hook structure containing callback function pointers. More...

Typedefs
typedef struct p_LDServerSDKEvaluationSeriesContext *	LDServerSDKEvaluationSeriesContext
typedef struct p_LDServerSDKEvaluationSeriesData *	LDServerSDKEvaluationSeriesData
typedef struct p_LDServerSDKTrackSeriesContext *	LDServerSDKTrackSeriesContext
typedef LDServerSDKEvaluationSeriesData(*	LDServerSDKHook_BeforeEvaluation) (LDServerSDKEvaluationSeriesContext series_context, LDServerSDKEvaluationSeriesData data, void *user_data)
	Callback invoked before a flag evaluation. More...
typedef LDServerSDKEvaluationSeriesData(*	LDServerSDKHook_AfterEvaluation) (LDServerSDKEvaluationSeriesContext series_context, LDServerSDKEvaluationSeriesData data, LDEvalDetail detail, void *user_data)
	Callback invoked after a flag evaluation. More...
typedef void(*	LDServerSDKHook_AfterTrack) (LDServerSDKTrackSeriesContext series_context, void *user_data)
	Callback invoked after a track event. More...

Functions
	LDServerSDKHook_Init (struct LDServerSDKHook *hook)
	Initialize a hook structure to safe defaults. More...

Detailed Description

C bindings for LaunchDarkly SDK hooks.

Hooks allow you to instrument the SDK's evaluation and tracking behavior for purposes like logging, analytics, or distributed tracing (e.g. OpenTelemetry).

LIFETIME AND OWNERSHIP:

• The LDServerSDKHook struct should be allocated by the caller (stack or heap)
• The function pointers and UserData pointer are copied when the hook is registered with the config builder
• UserData lifetime must extend for the entire lifetime of the SDK client

WARNING: All pointers passed to callbacks by the SDK (series_context, data, detail, etc.) are owned by the SDK and may be freed after the callback returns. You MUST NOT retain, cache, or store these pointers, or any references to data within them, beyond the scope of the callback invocation. Any data needed outside the duration of a callback must be copied during the callback. Accessing a stored pointer or reference after the callback has returned results in undefined behavior.

• EvaluationSeriesData returned from callbacks transfers ownership to the SDK

Typedef Documentation

LDServerSDKHook_AfterEvaluation

typedef LDServerSDKEvaluationSeriesData(* LDServerSDKHook_AfterEvaluation) (LDServerSDKEvaluationSeriesContext series_context, LDServerSDKEvaluationSeriesData data, LDEvalDetail detail, void *user_data)

Callback invoked after a flag evaluation.

Use this to instrument evaluation results, such as ending a span for distributed tracing or logging the result.

PARAMETERS:

Parameters

series_context	Read-only context about the evaluation. Valid only during this callback.
data	Mutable data passed from beforeEvaluation. Ownership transfers to SDK. May contain data from previous stages.
detail	The evaluation result. Valid only during this callback.
user_data	Application-specific context pointer.

RETURNS: EvaluationSeriesData for potential future stages. Return the input data unmodified if you don't need to modify it. Ownership transfers to SDK; the caller must not retain or access the returned pointer after returning. If NULL is returned, an empty data object will be created.

LIFETIME:

• series_context: Valid only during callback execution - do not store
• data: Valid only during callback execution - do not store. Ownership of the returned value transfers to the SDK.
• detail: Valid only during callback execution - do not store
• user_data: Managed by caller - must remain valid for SDK lifetime

LDServerSDKHook_AfterTrack

typedef void(* LDServerSDKHook_AfterTrack) (LDServerSDKTrackSeriesContext series_context, void *user_data)

Callback invoked after a track event.

Use this to instrument custom events, such as logging or adding tracing information.

PARAMETERS:

Parameters

series_context	Read-only context about the track call. Valid only during this callback.
user_data	Application-specific context pointer.

RETURNS: void (no data is passed between track stages)

LIFETIME:

• series_context: Valid only during callback execution - do not store
• user_data: Managed by caller - must remain valid for SDK lifetime

LDServerSDKHook_BeforeEvaluation

typedef LDServerSDKEvaluationSeriesData(* LDServerSDKHook_BeforeEvaluation) (LDServerSDKEvaluationSeriesContext series_context, LDServerSDKEvaluationSeriesData data, void *user_data)

Callback invoked before a flag evaluation.

Use this to instrument evaluations, such as starting a span for distributed tracing.

PARAMETERS:

Parameters

series_context	Read-only context about the evaluation. Valid only during this callback.
data	Mutable data that can be passed to afterEvaluation. Ownership transfers to the SDK. May be NULL initially.
user_data	Application-specific context pointer set when creating the hook.

RETURNS: EvaluationSeriesData to pass to afterEvaluation. Return the input data unmodified if you don't need to add anything. Ownership transfers to SDK; the caller must not retain or access the returned pointer after returning. If NULL is returned, an empty data object will be created.

LIFETIME:

• series_context: Valid only during callback execution - do not store
• data: Valid only during callback execution - do not store. Ownership of the returned value transfers to the SDK.
• user_data: Managed by caller - must remain valid for SDK lifetime

Function Documentation

LDServerSDKHook_Init()

LDServerSDKHook_Init

(

struct LDServerSDKHook *

hook

)

Initialize a hook structure to safe defaults.

Sets all function pointers and UserData to NULL, and Name to NULL. Must be called before setting any fields.

Parameters

hook	Pointer to hook structure to initialize. Must not be NULL.