Public Client control and variations. More...

#include <stddef.h>
#include <launchdarkly/boolean.h>
#include <launchdarkly/config.h>
#include <launchdarkly/export.h>
#include <launchdarkly/json.h>
#include <launchdarkly/user.h>

Include dependency graph for client.h:

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

Go to the source code of this file.

Data Structures
struct	LDVariationDetails
	To use detail variations you must provide a pointer to an `LDVariationDetails` struct that will be filled by the evaluation function. More...

Macros
#define	LDPrimaryEnvironmentName "default"
	The name of the primary environment for use with `LDClientGetForMobileKey`

Typedefs
typedef void(*	LDstatusfn) (LDStatus status, void *userData)
	Status callback type. More...

typedef void(*	LDlistenerfn) (const char *const flagKey, const int status)
	Feature flag listener callback type. Callbacks are not reentrant safe. More...

Enumerations
enum	LDStatus { LDStatusInitializing = 0, LDStatusInitialized, LDStatusFailed, LDStatusShuttingdown, LDStatusShutdown }
	Current status of the client. More...

Functions
struct LDClient *	LDClientGet (void)
	Get a reference to the (single, global) client.

struct LDClient *	LDClientGetForMobileKey (const char *const keyName)
	Get a reference to a secondary environment established in the configuration. More...

struct LDClient *	LDClientInit (struct LDConfig const config, struct LDUser const user, const unsigned int maxwaitmilli)
	Initialize the client with the config and user. After this call,. More...

char *	LDClientSaveFlags (struct LDClient *const client)
	Get JSON string containing all flags.

LDBoolean	LDClientRestoreFlags (struct LDClient const client, const char const data)
	Set flag store from JSON string.

void	LDClientIdentify (struct LDClient const client, struct LDUser const user)
	Asynchronously update the client with a new user. More...

void	LDClientFlush (struct LDClient *const client)
	Send any pending events to the server. They will normally be. More...

LDBoolean	LDClientIsInitialized (struct LDClient *const client)
	Returns true if the client has been initialized.

LDBoolean	LDClientAwaitInitialized (struct LDClient *const client, const unsigned int timeoutmilli)
	Block until initialized up to timeout, returns true if initialized.

LDBoolean	LDClientIsOffline (struct LDClient *const client)
	Returns the offline status of the client.

void	LDClientSetOffline (struct LDClient *const client)
	Make the client operate in offline mode. No network traffic.

void	LDClientSetOnline (struct LDClient *const client)
	Return the client to online mode.

void	LDClientSetBackground (struct LDClient *const client, const LDBoolean background)
	Enable or disable polling mode.

void	LDClientClose (struct LDClient *const client)
	Close the client, free resources, and generally shut down. More...

void	LDSetClientStatusCallback (void(callback)(int status))
	Add callback for client status changes, replacing any existing callback (including any set with LDSetClientStatusCallbackUserData.) More...

void	LDSetClientStatusCallbackUserData (LDstatusfn callback, void *userData)
	Add callback for client status changes, replacing any existing callback (including any set with LDSetClientStatusCallback.) More...

void	LDClientAlias (struct LDClient client, const struct LDUser currentUser, const struct LDUser *previousUser)
	Record a alias event.

void	LDClientTrack (struct LDClient const client, const char const name)
	Record a custom event.

void	LDClientTrackData (struct LDClient const client, const char const name, struct LDJSON *const data)
	Record a custom event and include custom data.

void	LDClientTrackMetric (struct LDClient const client, const char const name, struct LDJSON *const data, const double metric)
	Record a custom event and include custom data / a metric.

struct LDJSON *	LDAllFlags (struct LDClient *const client)
	Returns an object of all flags. This must be freed with `LDJSONFree`.

LDBoolean	LDBoolVariation (struct LDClient const client, const char const featureKey, const LDBoolean fallback)
	Evaluate Bool flag.

int	LDIntVariation (struct LDClient const client, const char const featureKey, const int fallback)
	Evaluate Int flag. More...

double	LDDoubleVariation (struct LDClient const client, const char const featureKey, const double fallback)
	Evaluate Double flag.

char *	LDStringVariationAlloc (struct LDClient const client, const char const featureKey, const char *const fallback)
	Evaluate String flag.

char *	LDStringVariation (struct LDClient const client, const char const featureKey, const char const fallback, char const resultBuffer, const size_t resultBufferSize)
	Evaluate String flag into fixed buffer.

struct LDJSON *	LDJSONVariation (struct LDClient const client, const char const featureKey, const struct LDJSON *const fallback)
	Evaluate JSON flag.

LDBoolean	LDBoolVariationDetail (struct LDClient const client, const char const featureKey, const LDBoolean fallback, LDVariationDetails *const details)
	Evaluate Bool flag with details.

int	LDIntVariationDetail (struct LDClient const client, const char const featureKey, const int fallback, LDVariationDetails *const details)
	Evaluate Int flag with details. More...

double	LDDoubleVariationDetail (struct LDClient const client, const char const featureKey, const double fallback, LDVariationDetails *const details)
	Evaluate Double flag with details.

char *	LDStringVariationAllocDetail (struct LDClient const client, const char const featureKey, const char const fallback, LDVariationDetails const details)
	Evaluate String flag with details.

char *	LDStringVariationDetail (struct LDClient const client, const char const featureKey, const char const fallback, char const resultBuffer, const size_t resultBufferSize, LDVariationDetails *const details)
	Evaluate String flag into fixed buffer with details.

struct LDJSON *	LDJSONVariationDetail (struct LDClient const client, const char const key, const struct LDJSON const fallback, LDVariationDetails const details)
	Evaluate JSON flag with details.

void	LDFreeDetailContents (LDVariationDetails details)
	Clear any memory associated with `LDVariationDetails`

LDBoolean	LDClientRegisterFeatureFlagListener (struct LDClient const client, const char const flagKey, LDlistenerfn listener)
	Register a callback for when a flag is updated.

void	LDClientUnregisterFeatureFlagListener (struct LDClient const client, const char const flagKey, LDlistenerfn listener)
	Unregister a callback registered with `LDClientRegisterFeatureFlagListener`

Detailed Description

Public Client control and variations.

Typedef Documentation

◆ LDlistenerfn

typedef void(* LDlistenerfn) (const char *const flagKey, const int status)

Feature flag listener callback type. Callbacks are not reentrant safe.

Status 0 for new or updated, 1 for deleted.

◆ LDstatusfn

typedef void(* LDstatusfn) (LDStatus status, void *userData)

Status callback type.

The callback's userData parameter is forwarded from the initial call to LDSetClientStatusCallbackUserData.

Enumeration Type Documentation

◆ LDStatus

enum LDStatus

Current status of the client.

Enumerator
LDStatusShutdown	Deprecated: Unused.

Function Documentation

◆ LDClientClose()

void LDClientClose ( struct LDClient *const client )

Close the client, free resources, and generally shut down.

This will additionally close all secondary environments. Do not attempt to manage secondary environments directly.

◆ LDClientFlush()

void LDClientFlush ( struct LDClient *const client )

Send any pending events to the server. They will normally be.

flushed after a timeout, but may also be flushed manually. This operation does not block.

◆ LDClientGetForMobileKey()

struct LDClient* LDClientGetForMobileKey ( const char *const keyName )

Get a reference to a secondary environment established in the configuration.

If the environment name does not exist this function returns NULL.

◆ LDClientIdentify()

void LDClientIdentify	(	struct LDClient *const	client,
		struct LDUser *const	user
	)

Asynchronously update the client with a new user.

The old user is freed. This will re-fetch feature flag settings from LaunchDarkly in the background. For performance reasons, user contexts should not be changed frequently.

Since this is an asynchronous network operation, flag evaluations immediately after LDClientIdentify will likely be evaluated in the context of the previous user.

There are multiple ways to ensure flags are evaluated in the context of the new user: 1) Call LDClientAwaitInitialized, allowing the client to block the calling thread for a specified duration. The client is initialized if the return value is true. 2) Call LDClientIsInitialized, which doesn't block. The client is initialized if the return value is true. 3) Monitor the client status via LDSetClientStatusCallbackUserData. The client is initialized if the status parameter is equal to LDStatusInitialized.

◆ LDClientInit()

struct LDClient* LDClientInit	(	struct LDConfig *const	config,
		struct LDUser *const	user,
		const unsigned int	maxwaitmilli
	)

Initialize the client with the config and user. After this call,.

the config and user must not be modified. The parameter maxwaitmilli indicates the maximum amount of time the client will wait to be fully initialized. If the timeout is hit the client will be available for feature flag evaluation but the results will be fallbacks. The client will continue attempting to connect to LaunchDarkly in the background. If maxwaitmilli is set to 0 then LDClientInit will wait indefinitely.

Only a single initialized client from LDClientInit may exist at one time. To initialize another instance you must first cleanup the previous client with LDClientClose. Should you initialize with LDClientInit while another client exists abort will be called. Both LDClientInit, and LDClientClose are not thread safe.

◆ LDIntVariation()

int LDIntVariation	(	struct LDClient *const	client,
		const char *const	featureKey,
		const int	fallback
	)

Evaluate Int flag.

If the flag value is actually a float the result is truncated.

◆ LDIntVariationDetail()

int LDIntVariationDetail	(	struct LDClient *const	client,
		const char *const	featureKey,
		const int	fallback,
		LDVariationDetails *const	details
	)

Evaluate Int flag with details.

If the flag value is actually a float the result is truncated.

◆ LDSetClientStatusCallback()

void LDSetClientStatusCallback ( void(callback)(int status) )

Add callback for client status changes, replacing any existing callback (including any set with LDSetClientStatusCallbackUserData.)

Deprecated:: This function does not allow for forwarding a user data parameter. See LDSetClientStatusCallbackUserData instead.

Parameters

callback Callback function to invoke when client status changes, or NULL to unset any callback.

◆ LDSetClientStatusCallbackUserData()

void LDSetClientStatusCallbackUserData	(	LDstatusfn	callback,
		void *	userData
	)

Add callback for client status changes, replacing any existing callback (including any set with LDSetClientStatusCallback.)

The callback is invoked with the supplied userData parameter.