Public API for evaluation variations. More...

#include <launchdarkly/boolean.h>
#include <launchdarkly/client.h>
#include <launchdarkly/export.h>
#include <launchdarkly/json.h>
#include <launchdarkly/user.h>
#include <launchdarkly/flag_state.h>

Include dependency graph for variations.h:

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

Go to the source code of this file.

Data Structures
struct	LDDetailsRule
	Indicates which rule matched a user. More...

struct	LDDetailsFallthrough
	Extra information when reason == LD_FALLTHROUGH. More...

struct	LDDetails

Enumerations
enum	LDEvalReason { LD_UNKNOWN = 0, LD_ERROR, LD_OFF, LD_PREREQUISITE_FAILED, LD_TARGET_MATCH, LD_RULE_MATCH, LD_FALLTHROUGH }
	The reason an evaluation occurred. More...

enum	LDEvalErrorKind { LD_CLIENT_NOT_READY, LD_NULL_KEY, LD_STORE_ERROR, LD_FLAG_NOT_FOUND, LD_USER_NOT_SPECIFIED, LD_CLIENT_NOT_SPECIFIED, LD_MALFORMED_FLAG, LD_WRONG_TYPE, LD_OOM }
	Details about the type of error that caused an evaluation to fail. More...

Functions
void	LDDetailsInit (struct LDDetails *const details)
	Initialize `details` to a default value.

void	LDDetailsClear (struct LDDetails *const details)
	Free any resources associated with `details`

const char *	LDEvalReasonKindToString (const enum LDEvalReason kind)
	Convert an `LDEvalReason` enum to an equivalent string. More...

const char *	LDEvalErrorKindToString (const enum LDEvalErrorKind kind)
	Converts an `LDEvalErrorKind` enum to an equivalent string. More...

struct LDJSON *	LDReasonToJSON (const struct LDDetails *const details)
	Marshal just the evaluation reason portion of `LDDetails` to JSON. More...

LDBoolean	LDBoolVariation (struct LDClient const client, const struct LDUser const user, const char const key, const LDBoolean fallback, struct LDDetails const details)
	Evaluate a boolean flag. More...

int	LDIntVariation (struct LDClient const client, const struct LDUser const user, const char const key, const int fallback, struct LDDetails const details)
	Evaluate a integer flag. More...

double	LDDoubleVariation (struct LDClient const client, const struct LDUser const user, const char const key, const double fallback, struct LDDetails const details)
	Evaluate a double flag. More...

char *	LDStringVariation (struct LDClient const client, const struct LDUser const user, const char const key, const char const fallback, struct LDDetails *const details)
	Evaluate a text flag. More...

struct LDJSON *	LDJSONVariation (struct LDClient const client, const struct LDUser const user, const char const key, const struct LDJSON const fallback, struct LDDetails *const details)
	Evaluate a JSON flag. More...

struct LDJSON *	LDAllFlags (struct LDClient const client, const struct LDUser const user)
	Returns a map from feature flag keys to values for a given user. This does not send analytics events back to LaunchDarkly. More...

struct LDAllFlagsState *	LDAllFlagsState (struct LDClient const client, const struct LDUser const user, unsigned int options)
	AllFlagsState returns an object that encapsulates the state of all feature flags for a given user. The state includes flag values, and also metadata that can be used on the front end. This does not send analytics events back to LaunchDarkly. More...

Detailed Description

Public API for evaluation variations.

Enumeration Type Documentation

◆ LDEvalErrorKind

enum LDEvalErrorKind

Details about the type of error that caused an evaluation to fail.

Enumerator
LD_CLIENT_NOT_READY	Indicates that the caller tried to evaluate a flag before the client had successfully initialized.
LD_NULL_KEY	Indicates a `NULL` flag key was used.
LD_STORE_ERROR	Indicates an internal exception with the flag store.
LD_FLAG_NOT_FOUND	Indicates that the caller provided a flag key that did not match any known flag.
LD_USER_NOT_SPECIFIED	Indicates that a `NULL` user was passed for the user parameter.
LD_CLIENT_NOT_SPECIFIED	Indicates that a `NULL` client was passed for the client parameter.
LD_MALFORMED_FLAG	Indicates that there was an internal inconsistency in the flag data, a rule specified a nonexistent variation.
LD_WRONG_TYPE	Indicates that the result value was not of the requested type, e.g. you called `LDBoolVariation` but the value was an integer.
LD_OOM	Evaluation failed because the client ran out of memory.

◆ LDEvalReason

enum LDEvalReason

The reason an evaluation occurred.

Enumerator
LD_UNKNOWN	A default unset reason.
LD_ERROR	Indicates that the flag could not be evaluated, e.g. because it does not exist or due to an unexpected error. In this case the result value will be the default value that the caller passed to the client.
LD_OFF	Indicates that the flag was off and therefore returned its configured off value.
LD_PREREQUISITE_FAILED	Indicates that the flag was considered off because it had at least one prerequisite flag that either was off or did not return the desired variation.
LD_TARGET_MATCH	Indicates that the user key was specifically targeted for this flag.
LD_RULE_MATCH	Indicates that the user matched one of the flag's rules.
LD_FALLTHROUGH	Indicates that the flag was on but the user did not match any targets or rules.

Function Documentation

◆ LDAllFlags()

struct LDJSON* LDAllFlags	(	struct LDClient *const	client,
		const struct LDUser *const	user
	)

Returns a map from feature flag keys to values for a given user. This does not send analytics events back to LaunchDarkly.

Deprecated:: Please use LDAllFlagsState (LDAllFlagsStateToValuesMap) instead.

Parameters

[in]	client	The client to use. May not be `NULL`.
[in]	user	The user to evaluate flags for. Ownership is not transferred. May not be `NULL`.

Returns: A JSON object, or NULL on failure.

◆ LDAllFlagsState()

struct LDAllFlagsState* LDAllFlagsState	(	struct LDClient *const	client,
		const struct LDUser *const	user,
		unsigned int	options
	)

AllFlagsState returns an object that encapsulates the state of all feature flags for a given user. The state includes flag values, and also metadata that can be used on the front end. This does not send analytics events back to LaunchDarkly.

Parameters

[in]	client	The client to use. May not be `NULL`.
[in]	user	The user to evaluate flags for. Ownership is not transferred. May not be `NULL`.
[in]	options	Options affecting the returned flags.

Returns: Opaque LDAllFlagsState object, or NULL on failure. User is responsible for freeing with LDAllFlagsStateFree. Validity of the returned value can be checked with LDAllFlagsStateValid.

◆ LDBoolVariation()

LDBoolean LDBoolVariation	(	struct LDClient *const	client,
		const struct LDUser *const	user,
		const char *const	key,
		const LDBoolean	fallback,
		struct LDDetails *const	details
	)

Evaluate a boolean flag.

Parameters

[in]	client	The client to use. May not be `NULL`.
[in]	user	The user to evaluate the flag against. May not be `NULL`.
[in]	key	The key of the flag to evaluate. May not be `NULL`.
[in]	fallback	The value to return on error
[out]	details	A struct where the evaluation explanation will be put. If `NULL` no explanation will be generated.

Returns: The fallback will be returned on any error.

◆ LDDoubleVariation()

double LDDoubleVariation	(	struct LDClient *const	client,
		const struct LDUser *const	user,
		const char *const	key,
		const double	fallback,
		struct LDDetails *const	details
	)

Evaluate a double flag.

Parameters

[in]	client	The client to use. May not be `NULL`.
[in]	user	The user to evaluate the flag against. May not be `NULL`.
[in]	key	The key of the flag to evaluate. May not be `NULL`.
[in]	fallback	The value to return on error
[out]	details	A struct where the evaluation explanation will be put. If `NULL` no explanation will be generated.

Returns: The fallback will be returned on any error.

◆ LDEvalErrorKindToString()

const char* LDEvalErrorKindToString ( const enum LDEvalErrorKind kind )

Converts an LDEvalErrorKind enum to an equivalent string.

Parameters

[in] kind The error kind to convert.

Returns: A string, or NULL on invalid input.

◆ LDEvalReasonKindToString()

const char* LDEvalReasonKindToString ( const enum LDEvalReason kind )

Convert an LDEvalReason enum to an equivalent string.

Converts an LDEvalReason enum to an equivalent string

Parameters

[in] kind The reason kind to convert.

Returns: A string, or NULL on invalid input.

◆ LDIntVariation()

int LDIntVariation	(	struct LDClient *const	client,
		const struct LDUser *const	user,
		const char *const	key,
		const int	fallback,
		struct LDDetails *const	details
	)

Evaluate a integer flag.

Parameters

[in]	client	The client to use. May not be `NULL`.
[in]	user	The user to evaluate the flag against. May not be `NULL`.
[in]	key	The key of the flag to evaluate. May not be `NULL`.
[in]	fallback	The value to return on error
[out]	details	A struct where the evaluation explanation will be put. If `NULL` no explanation will be generated.

Returns: The fallback will be returned on any error.

◆ LDJSONVariation()

struct LDJSON* LDJSONVariation	(	struct LDClient *const	client,
		const struct LDUser *const	user,
		const char *const	key,
		const struct LDJSON *const	fallback,
		struct LDDetails *const	details
	)

Evaluate a JSON flag.

Parameters

[in]	client	The client to use. May not be `NULL`.
[in]	user	The user to evaluate the flag against. May not be `NULL`.
[in]	key	The key of the flag to evaluate. May not be `NULL``
[in]	fallback	The fallback to return on error. Ownership is not transferred. May be `NULL`.
[out]	details	A struct where the evaluation explanation will be put. If `NULL` no explanation will be generated.

Returns: The fallback will be returned on any error but may be NULL on allocation failure. The result must be cleaned up with LDJSONFree.

◆ LDReasonToJSON()

struct LDJSON* LDReasonToJSON ( const struct LDDetails *const details )

Marshal just the evaluation reason portion of LDDetails to JSON.

Parameters

[in] details The structure to marshal. Ownership is not transferred. May not be NULL (assert)

Returns: A JSON representation, or NULL on malloc failure.

◆ LDStringVariation()

char* LDStringVariation	(	struct LDClient *const	client,
		const struct LDUser *const	user,
		const char *const	key,
		const char *const	fallback,
		struct LDDetails *const	details
	)

Evaluate a text flag.

Parameters

[in]	client	The client to use. May not be `NULL`.
[in]	user	The user to evaluate the flag against. May not be `NULL`.
[in]	key	The key of the flag to evaluate. May not be `NULL`.
[in]	fallback	The value to return on error. Ownership is not transferred. May be `NULL`.
[out]	details	A struct where the evaluation explanation will be put. If `NULL` no explanation will be generated.

Returns: The fallback will be returned on any error but may be NULL on allocation failure. The result must be cleaned up with LDFree.

Data Structures

Enumerations

Functions

Detailed Description

Enumeration Type Documentation

◆ LDEvalErrorKind

◆ LDEvalReason

Function Documentation

◆ LDAllFlags()

◆ LDAllFlagsState()

◆ LDBoolVariation()

◆ LDDoubleVariation()

◆ LDEvalErrorKindToString()

◆ LDEvalReasonKindToString()

◆ LDIntVariation()

◆ LDJSONVariation()

◆ LDReasonToJSON()

◆ LDStringVariation()