C Server-Side SDK
LaunchDarkly SDK
variations.h File Reference

Public API Interface for evaluation variations. More...

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...
 

Detailed Description

Public API Interface for evaluation variations.

Enumeration Type Documentation

◆ 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

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.

Parameters
[in]clientThe client to use. May not be NULL.
[in]userThe user to evaluate flags for. Ownership is not transferred. May not be NULL.
Returns
A JSON object, or NULL on failure.

◆ 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]clientThe client to use. May not be NULL.
[in]userThe user to evaluate the flag against. May not be NULL.
[in]keyThe key of the flag to evaluate. May not be NULL.
[in]fallbackThe value to return on error
[out]detailsA 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]clientThe client to use. May not be NULL.
[in]userThe user to evaluate the flag against. May not be NULL.
[in]keyThe key of the flag to evaluate. May not be NULL.
[in]fallbackThe value to return on error
[out]detailsA 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]kindThe 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]kindThe 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]clientThe client to use. May not be NULL.
[in]userThe user to evaluate the flag against. May not be NULL.
[in]keyThe key of the flag to evaluate. May not be NULL.
[in]fallbackThe value to return on error
[out]detailsA 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]clientThe client to use. May not be NULL.
[in]userThe user to evaluate the flag against. May not be NULL.
[in]keyThe key of the flag to evaluate. May not be NULL`
[in]fallbackThe fallback to return on error. Ownership is not transferred. May be NULL.
[out]detailsA 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]detailsThe 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]clientThe client to use. May not be NULL.
[in]userThe user to evaluate the flag against. May not be NULL.
[in]keyThe key of the flag to evaluate. May not be NULL.
[in]fallbackThe value to return on error. Ownership is not transferred. May be NULL.
[out]detailsA 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.