C++ Client-Side SDK
LaunchDarkly SDK
|
LaunchDarkly Client-side C Bindings. More...
#include <launchdarkly/client_side/bindings/c/config/builder.h>
#include <launchdarkly/bindings/c/context.h>
#include <launchdarkly/bindings/c/data/evaluation_detail.h>
#include <launchdarkly/bindings/c/data_source/error_info.h>
#include <launchdarkly/bindings/c/export.h>
#include <launchdarkly/bindings/c/flag_listener.h>
#include <launchdarkly/bindings/c/listener_connection.h>
#include <launchdarkly/bindings/c/memory_routines.h>
#include <launchdarkly/bindings/c/shared_function_argument_macro_definitions.h>
#include <launchdarkly/bindings/c/status.h>
#include <launchdarkly/bindings/c/value.h>
#include <stddef.h>
#include <stdint.h>
#include <time.h>
Go to the source code of this file.
Classes | |
struct | LDDataSourceStatusListener |
Typedefs | |
typedef struct _LDClientSDK * | LDClientSDK |
typedef struct _LDDataSourceStatus * | LDDataSourceStatus |
typedef void(* | DataSourceStatusCallbackFn) (LDDataSourceStatus status, void *user_data) |
Enumerations | |
enum | LDDataSourceStatus_State { LD_DATASOURCESTATUS_STATE_INITIALIZING = 0 , LD_DATASOURCESTATUS_STATE_VALID = 1 , LD_DATASOURCESTATUS_STATE_INTERRUPTED = 2 , LD_DATASOURCESTATUS_STATE_OFFLINE = 3 , LD_DATASOURCESTATUS_STATE_SHUTDOWN = 4 , LD_DATASOURCESTATUS_STATE_UNUSED_MAXVALUE } |
Functions | |
LDClientSDK_New (LDClientConfig config, LDContext context) | |
LDClientSDK_Version (void) | |
LDClientSDK_Start (LDClientSDK sdk, unsigned int milliseconds, bool *out_succeeded) | |
LDClientSDK_Initialized (LDClientSDK sdk) | |
LDClientSDK_TrackEvent (LDClientSDK sdk, char const *event_name) | |
LDClientSDK_TrackMetric (LDClientSDK sdk, char const *event_name, double metric_value, LDValue data) | |
LDClientSDK_TrackData (LDClientSDK sdk, char const *event_name, LDValue data) | |
LDClientSDK_Flush (LDClientSDK sdk, unsigned int reserved) | |
LDClientSDK_Identify (LDClientSDK sdk, LDContext context, unsigned int milliseconds, bool *out_succeeded) | |
LDClientSDK_BoolVariation (LDClientSDK sdk, char const *flag_key, bool default_value) | |
LDClientSDK_BoolVariationDetail (LDClientSDK sdk, char const *flag_key, bool default_value, LDEvalDetail *out_detail) | |
LDClientSDK_StringVariation (LDClientSDK sdk, char const *flag_key, char const *default_value) | |
LDClientSDK_StringVariationDetail (LDClientSDK sdk, char const *flag_key, char const *default_value, LDEvalDetail *out_detail) | |
LDClientSDK_IntVariation (LDClientSDK sdk, char const *flag_key, int default_value) | |
LDClientSDK_IntVariationDetail (LDClientSDK sdk, char const *flag_key, int default_value, LDEvalDetail *out_detail) | |
LDClientSDK_DoubleVariation (LDClientSDK sdk, char const *flag_key, double default_value) | |
LDClientSDK_DoubleVariationDetail (LDClientSDK sdk, char const *flag_key, double default_value, LDEvalDetail *out_detail) | |
LDClientSDK_JsonVariation (LDClientSDK sdk, char const *flag_key, LDValue default_value) | |
LDClientSDK_JsonVariationDetail (LDClientSDK sdk, char const *flag_key, LDValue default_value, LDEvalDetail *out_detail) | |
LDClientSDK_AllFlags (LDClientSDK sdk) | |
LDClientSDK_Free (LDClientSDK sdk) | |
LDClientSDK_FlagNotifier_OnFlagChange (LDClientSDK sdk, char const *flag_key, struct LDFlagListener listener) | |
LDDataSourceStatus_State_Name (enum LDDataSourceStatus_State state, char const *default_if_unknown) | |
LDDataSourceStatus_GetState (LDDataSourceStatus status) | |
LDDataSourceStatus_GetLastError (LDDataSourceStatus status) | |
LDDataSourceStatus_StateSince (LDDataSourceStatus status) | |
LDDataSourceStatusListener_Init (struct LDDataSourceStatusListener *listener) | |
LDClientSDK_DataSourceStatus_OnStatusChange (LDClientSDK sdk, struct LDDataSourceStatusListener listener) | |
LDClientSDK_DataSourceStatus_Status (LDClientSDK sdk) | |
LDDataSourceStatus_Free (LDDataSourceStatus status) | |
LaunchDarkly Client-side C Bindings.
Enumeration of possible data source states.
LDClientSDK_AllFlags | ( | LDClientSDK | sdk | ) |
Returns a map from feature flag keys to feature flag values for the current context.
In the example, all flags of type boolean are printed.
sdk | SDK. Must not be NULL. |
LDClientSDK_BoolVariation | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
bool | default_value | ||
) |
Returns the boolean value of a feature flag for a given flag key.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. |
LDClientSDK_BoolVariationDetail | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
bool | default_value, | ||
LDEvalDetail * | out_detail | ||
) |
Returns the boolean value of a feature flag for a given flag key, and details that also describes the way the value was determined.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. |
detail | Out parameter to store the details. May pass LD_DISCARD_DETAILS or NULL to discard the details. The details object must be freed with LDEvalDetail_Free. |
LDClientSDK_DataSourceStatus_OnStatusChange | ( | LDClientSDK | sdk, |
struct LDDataSourceStatusListener | listener | ||
) |
Listen for changes to the data source status.
sdk | SDK. Must not be NULL. |
listener | The listener, whose StatusChanged callback will be invoked, when the data source status changes. Must not be NULL. |
LDClientSDK_DataSourceStatus_Status | ( | LDClientSDK | sdk | ) |
The current status of the data source.
The caller must free the returned value using LDDataSourceStatus_Free.
LDClientSDK_DoubleVariation | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
double | default_value | ||
) |
Returns the double value of a feature flag for a given flag key.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. |
LDClientSDK_DoubleVariationDetail | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
double | default_value, | ||
LDEvalDetail * | out_detail | ||
) |
Returns the double value of a feature flag for a given flag key, and details that also describes the way the value was determined.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. |
detail | Out parameter to store the details. May pass LD_DISCARD_DETAILS or NULL to discard the details. The details object must be freed with LDEvalDetail_Free. |
LDClientSDK_FlagNotifier_OnFlagChange | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
struct LDFlagListener | listener | ||
) |
Listen for changes for the specific flag.
If the FlagChanged member of the listener struct is not set (NULL), then the function will not register a listener. In that case the return value will be NULL.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
listener | The listener, whose FlagChanged callback will be invoked, when the flag changes. Must not be NULL. |
LDClientSDK_Flush | ( | LDClientSDK | sdk, |
unsigned int | reserved | ||
) |
Requests delivery of all pending analytic events (if any).
You MUST pass LD_NONBLOCKING
as the second parameter.
sdk | SDK. Must not be NULL. |
milliseconds | Must pass LD_NONBLOCKING . |
LDClientSDK_Free | ( | LDClientSDK | sdk | ) |
Frees the SDK's resources, shutting down any connections. May block.
sdk | SDK. |
LDClientSDK_Identify | ( | LDClientSDK | sdk, |
LDContext | context, | ||
unsigned int | milliseconds, | ||
bool * | out_succeeded | ||
) |
Changes the current evaluation context, requests flags for that context from LaunchDarkly if online, and generates an analytics event to tell LaunchDarkly about the context.
Only one Identify call can be in progress at once; calling it concurrently invokes undefined behavior.
The method may be blocking or asynchronous depending on the arguments.
To block, pass a positive milliseconds value and an optional pointer to a boolean. The return value will be true if the SDK was able to attempt the operation within the specified timeframe, or false if the operation couldn't complete in time. The value of out_succeeded will be true if the SDK successfully changed evaluation contexts.
Example:
To start asynchronously, pass LD_NONBLOCKING
. In this case, the return value will be false and you may pass NULL to out_succeeded.
sdk | SDK. Must not be NULL. |
context | The new evaluation context. |
milliseconds | Milliseconds to wait for identify to complete, or LD_NONBLOCKING to return immediately. |
out_succeeded | Pointer to bool representing successful identification. Only modified if a positive milliseconds value is passed; may be NULL. |
LDClientSDK_Initialized | ( | LDClientSDK | sdk | ) |
Returns a boolean value indicating LaunchDarkly connection and flag state within the client.
When you first start the client, once Start has completed, Initialized should return true if and only if either 1. it connected to LaunchDarkly and successfully retrieved flags, or 2. it started in offline mode so there's no need to connect to LaunchDarkly.
If the client timed out trying to connect to LD, then Initialized returns false (even if we do have cached flags). If the client connected and got a 401 error, Initialized is will return false. This serves the purpose of letting the app know that there was a problem of some kind.
sdk | SDK. Must not be NULL. |
LDClientSDK_IntVariation | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
int | default_value | ||
) |
Returns the int value of a feature flag for a given flag key.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. |
LDClientSDK_IntVariationDetail | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
int | default_value, | ||
LDEvalDetail * | out_detail | ||
) |
Returns the int value of a feature flag for a given flag key, and details that also describes the way the value was determined.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. |
detail | Out parameter to store the details. May pass LD_DISCARD_DETAILS or NULL to discard the details. The details object must be freed with LDEvalDetail_Free. |
LDClientSDK_JsonVariation | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
LDValue | default_value | ||
) |
Returns the JSON value of a feature flag for a given flag key.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. Ownership is retained by the caller; a copy is made internally. Must not be NULL. |
LDClientSDK_JsonVariationDetail | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
LDValue | default_value, | ||
LDEvalDetail * | out_detail | ||
) |
Returns the JSON value of a feature flag for a given flag key, and details that also describes the way the value was determined.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. Ownership is retained by the caller; a copy is made internally. Must not be NULL. |
detail | Out parameter to store the details. May pass LD_DISCARD_DETAILS or NULL to discard the details. The details object must be freed with LDEvalDetail_Free. |
LDClientSDK_New | ( | LDClientConfig | config, |
LDContext | context | ||
) |
Constructs a new client-side LaunchDarkly SDK from a configuration and context.
config | The configuration. Ownership is transferred. Do not free or access the LDClientConfig in any way after this call; behavior is undefined. Must not be NULL. |
context | The initial context. Ownership is transferred. Do not free or access the LDContext in any way after this call; behavior is undefined. Must not be NULL. |
LDClientSDK_Start | ( | LDClientSDK | sdk, |
unsigned int | milliseconds, | ||
bool * | out_succeeded | ||
) |
Starts the SDK, initiating a connection to LaunchDarkly if not offline.
Only one Start call can be in progress at once; calling it concurrently invokes undefined behavior.
The method may be blocking or asynchronous depending on the arguments.
To block, pass a positive milliseconds value and an optional pointer to a boolean. The return value will be true if the SDK started within the specified timeframe, or false if the operation couldn't complete in time. The value of out_succeeded will be true if the SDK successfully initialized.
Example:
To start asynchronously, pass LD_NONBLOCKING
. In this case, the return value will be false and you may pass NULL to out_succeeded.
sdk | SDK. Must not be NULL. |
milliseconds | Milliseconds to wait for initialization or LD_NONBLOCKING to return immediately. |
out_succeeded | Pointer to bool representing successful initialization. Only modified if a positive milliseconds value is passed; may be NULL. |
LDClientSDK_StringVariation | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
char const * | default_value | ||
) |
Returns the string value of a feature flag for a given flag key. Ensure the string is freed with LDMemory_FreeString.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. |
LDClientSDK_StringVariationDetail | ( | LDClientSDK | sdk, |
char const * | flag_key, | ||
char const * | default_value, | ||
LDEvalDetail * | out_detail | ||
) |
Returns the string value of a feature flag for a given flag key, and details that also describes the way the value was determined. Ensure the string is freed with LDMemory_FreeString.
sdk | SDK. Must not be NULL. |
flag_key | The unique key for the feature flag. Must not be NULL. |
default_value | The default value of the flag. |
detail | Out parameter to store the details. May pass LD_DISCARD_DETAILS or NULL to discard the details. The details object must be freed with LDEvalDetail_Free. |
LDClientSDK_TrackData | ( | LDClientSDK | sdk, |
char const * | event_name, | ||
LDValue | data | ||
) |
Tracks that the current context performed an event for the given event name, with additional JSON data.
sdk | SDK. Must not be NULL. |
event_name | Must not be NULL. |
data | A JSON value containing additional data associated with the event. Do not free or access the LDValue in any way after this call; behavior is undefined. Must not be NULL. |
LDClientSDK_TrackEvent | ( | LDClientSDK | sdk, |
char const * | event_name | ||
) |
Tracks that the current context performed an event for the given event name.
sdk | SDK. Must not be NULL. |
event_name | Name of the event. Must not be NULL. |
LDClientSDK_TrackMetric | ( | LDClientSDK | sdk, |
char const * | event_name, | ||
double | metric_value, | ||
LDValue | data | ||
) |
Tracks that the current context performed an event for the given event name, and associates it with a numeric metric and value.
sdk | SDK. Must not be NULL. |
event_name | The name of the event. Must not be NULL. |
metric_value | this value is used by the LaunchDarkly experimentation feature in numeric custom metrics, and will also be returned as part of the custom event for Data Export. |
data | A JSON value containing additional data associated with the event. Ownership is transferred. Do not free or access the LDValue in any way after this call; behavior is undefined. Must not be NULL. |
LDClientSDK_Version | ( | void | ) |
Returns the version of the SDK.
LDDataSourceStatus_Free | ( | LDDataSourceStatus | status | ) |
Frees the data source status.
status | The data source status to free. |
LDDataSourceStatus_GetLastError | ( | LDDataSourceStatus | status | ) |
Information about the last error that the data source encountered, if any. If there has not been an error, then NULL will be returned.
If a non-NULL value is returned, then it should be freed using LDDataSourceStatus_ErrorInfo_Free.
This property should be updated whenever the data source encounters a problem, even if it does not cause the state to change. For instance, if a stream connection fails and the state changes to LD_DATASOURCESTATUS_STATE_INTERRUPTED, and then subsequent attempts to restart the connection also fail, the state will remain LD_DATASOURCESTATUS_STATE_INTERRUPTED but the error information will be updated each time– and the last error will still be reported in this property even if the state later becomes LD_DATASOURCESTATUS_STATE_VALID.
LDDataSourceStatus_GetState | ( | LDDataSourceStatus | status | ) |
Get an enumerated value representing the overall current state of the data source.
LDDataSourceStatus_State_Name | ( | enum LDDataSourceStatus_State | state, |
char const * | default_if_unknown | ||
) |
state | The state to convert to a string. |
default_if_unknown | The default string to return if the state is not recognized. |
LDDataSourceStatus_StateSince | ( | LDDataSourceStatus | status | ) |
The date/time that the value of State most recently changed, in seconds since epoch.
The meaning of this depends on the current state:
LDDataSourceStatusListener_Init | ( | struct LDDataSourceStatusListener * | listener | ) |
Initializes a data source status change listener. Must be called before passing the listener to LDClientSDK_DataSourceStatus_OnStatusChange.
If the StatusChanged member of the listener struct is not set (NULL), then the function will not register a listener. In that case the return value will be NULL.
Create the struct, initialize the struct, set the StatusChanged handler and optionally UserData, and then pass the struct to LDClientSDK_DataSourceStatus_OnStatusChange. NULL will be returned if the StatusChanged member of the listener struct is NULL.
listener | Listener to initialize. |