C++ API

10 minute readReference

The following information is for the latest version of the C++ Client SDK. If you are running an older version, please check the CloudBees Feature Management - C/C++ changelog for any differences.

ROX C++ header

#import <roxx/client.h>
▼

Rox Namespace

The Rox namespace provides an interface for CloudBees Feature Management to manage feature flags that control the behavior of your application. This is the central repository for your application’s flags. This namespace handles communications with the server to obtain the latest flag values, implement flag settings, and set up flag configurations. The values in the namespace are marked as feature flags and display in the CloudBees Feature Management UI once the application is run.

These classes and interfaces also allow you to manage custom properties. These can be static settings of type string, boolean, integer, or double, or you can use a generator class to provide a custom property that is dependent upon code state. These generated properties must derive from CustomPropertyGeneratorInterface.

You can also use an Options object to configure some aspects of feature flag management in CloudBees Feature Management. You can set the custom platform, impression handler, dynamic properties rule, and configuration fetched handler.

Setup

StateCode Setup(const char *api_key, Options *options = nullptr)
▼

Configures the Rox object to work with the provided application.

Parameter Modifier and Type Description

apiKey

const char *

The environment key provided by the dashboard

options

Options*

A Options instance with the desired configuration for this application.

Return value

typedef enum RoxStateCode {
    RoxUninitialized = 0,
    RoxSettingUp = 1,
    RoxInitialized = 2,
    RoxShuttingDown = 3,
    RoxErrorEmptyApiKey = -1,
    RoxErrorInvalidApiKey = -2,
    RoxErrorGenericSetupFailure = -1000
} RoxStateCode;
▼

In case of a successful call, Setup will return RoxInitialized code. Otherwise, the application logs should be analyzed for errors and warnings. If Setup returned failure code, it may be called again after fixing the errors from the logs.

Shutdown

void Shutdown()
▼

Frees all Rox Internal Objects. Should be used on application exit.

Setup may be called again after Shutdown. 
// application start
Rox::Setup(DEFAULT_API_KEY)

// application end
Rox::Shutdown();
▼

SetContext

void SetContext(Context *context)
▼

Set a global context. This context will be available to all flags evaluations (in addition to the specific call context).

Fetch

void Fetch()
▼

Create a network request for the latest configuration.

Rox::Client Namespace

The Rox::Client namespace comes in addition to its parent Rox namespace. It contains client-specific classes and interfaces. Features like flag freeze and flag value overrides are implemented there. Also, there’s the client-specific OptionsBuilder class which extends the class of the same name from the parent Rox namespace. It allows to set the default flag freeze level and other options related to the client-only features.

If you need client-side features working on your feature flags, use the feature flag classes from the Rox::Client namespace.

Unfreeze

void Unfreeze(const char *ns = nullptr)
▼

Unfreeze the state of all flags.

If a namespace was specified, this will affect only the flags in given namespace.

Custom Properties

The role of Custom Properties is to segment the audience.

The custom properties can be these types:

  • bool

  • int

  • double

  • semver

  • string

There are simple (direct) Custom Properties and calculated ones, using RoxContext to be more dynamic.

Simple (direct) Custom Properties

SetCustomProperty

template<typename T> void SetCustomProperty(const char *name, T value)
▼

Sets a custom property representing a T value.

Parameter Modifier and Type Description

name

const char *

The name of the property to create

value

T

The value for the custom property depends on the type

SetCustomSemverProperty

voidSetCustomSemverProperty(const char *name, const char *value)
▼

Sets a custom property representing a semver value.

Parameter Modifier and Type Description

name

const char *

The name of the property to create

value

const char *

The semver value for the custom property

Computed Custom properties (using RoxContext)

SetCustomComputedProperty

template<typename T> void SetCustomComputedProperty(const char *name, CustomPropertyGeneratorInterface *generator)
▼

Sets a computed T Custom Property on the Rox client. This is a computable T, with an object that generates the value for the property. The generator should be a delegate of type CustomPropertyGeneratorInterface.

Parameter Modifier and Type Description

name

const char *

The name of the property to create

generator

CustomPropertyGeneratorInterface *

A CustomPropertyGeneratorInterface class

SetCustomComputedSemverProperty

void SetCustomComputedSemverProperty(const char *name, CustomPropertyGeneratorInterface *generator)
▼

Sets a computed semver Custom Property on the Rox client. This is a computable semver, with an object that generates the value for the property. The generator should be a delegate of type CustomPropertyGeneratorInterface.

Parameter Modifier and Type Description

name

string

The name of the property to create

generator

CustomPropertyGeneratorInterface *

A CustomPropertyGeneratorInterface class

Class Options

RoxOptions covers configuration options for the Rox client. This includes settings like configuration fetch interval, impression handler and more.

Instances of this class should be created using OptionsBuilder.

Here is an example of setting up a new Options object. This options object sets the version, provides an impression handler, and calls the fetch handler.

using namespace Rox::Client;

class ImpressionHandler : public Rox::ImpressionHandlerInterface {
    public:
        explicit ImpressionHandler() {}

    public:
        void HandleImpression(RoxReportingValue *value, RoxExperiment *experiment, RoxContext *context) {
            // TODO: do something on impression
        }
};

class ConfigurationFetchedHandler : public Rox::ConfigurationFetchedHandlerInterface {
    public:
        explicit ConfigurationFetchedHandler() {
    }

    public:
        void ConfigurationFetched(Rox::ConfigurationFetchedArgs *args) override {
            // TODO: do something on configuration fetched
        }
};

class DynamicRulerHandler : public Rox::DynamicPropertiesRuleInterface {
    public:
        explicit DynamicRulerHandler() {}

    public:
        DynamicValue *Invoke(const char *propName, Context *context) {
            // TODO: return a DynanmicValue
        }
};

int main(int argc, char **argv) {

    ImpressionHandler imp = ImpressionHandler();
    ConfigurationFetchedHandler conf = ConfigurationFetchedHandler();
    DynamicRulerHandler dynamicRule = DynamicRulerHandler();

    Rox::Options *options = Rox::Client::OptionsBuilder()
        .SetDefaultFreeze(RoxFreezeUntilLaunch)
        .SetConfigurationFetchedHandler(&conf)
        .SetDevModeKey("your_dev_mode_secret")
        .SetDynamicPropertiesRule(&dynamicRule)
        .SetImpressionHandler(&imp)
        .SetRoxyUrl("http://localhost:4444")
        .SetVersion("2.1.0")
        .SetFetchInterval(100)
        .Build();

    Rox::Setup("ROLLOUT_KEY", options);

    // do something...

    Rox::Shutdown();
}
▼

Class OptionsBuilder

This class is from Rox::Client namespace.

This Builder class is used to create a new Options instance.

SetDefaultFreeze

OptionsBuilder &SetDefaultFreeze(::Rox::Client::Freeze freeze)
▼

Sets the default freeze level.

SetVersion

OptionsBuilder &SetVersion(const char *version);
▼

Set the version of the service running the CloudBees Feature Management SDK. This can be used on the dashboard for targeting filtering.

SetFetchInterval

OptionsBuilder &SetFetchInterval(int intervalInSeconds)
▼

Set the polling interval for fetching configuration from the CloudBees Feature Management storage service.

SetConfigurationFetchedHandler

OptionsBuilder &SetConfigurationFetchedHandler(ConfigurationFetchedHandlerInterface *handler)
▼

Set the configuration event handler to actions after configurations are fetched.

SetImpressionHandler

OptionsBuilder &SetImpressionHandler(ImpressionHandlerInterface *handler)
▼

Set the impression event handler to add actions after an impression.

SetDynamicPropertiesRule

OptionsBuilder &SetDynamicPropertiesRule(DynamicPropertiesRuleInterface *rule)
▼

The Dynamic Custom Property Generator is called when an explicit Custom property definition does not exists on the client side.

If you do not set the SetDynamicPropertiesRule, it will then activate the default function which tries to extract the prop value from the context by its name.

if (context != NULL) {    return rox_context_get(context, prop_name);  }  return NULL;
▼

Class DynamicPropertiesRuleInterface

Create a custom dynamic property rule, by overriding this class.

Invoke
virtual DynamicValue *Invoke(const char *propName, Context *context) = 0
▼

See C API RoxDynamicValue for DynamicValue.

For an example, see Defining custom properties.

SetRoxyUrl

OptionsBuilder &SetRoxyUrl(const char *roxy_url)
▼

A roxy URL (see Microservices automated testing and local development).

SetDevModeKey

OptionsBuilder &SetDevModeKey(const char *devModeKey)
▼

Set dev mode secret.

See Enabling secret mode.

Build

Options *Build()
▼

Creates the options object with all the property that were set.

Class Flag

Boolean feature flag.

This class is from Rox::Client namespace.

GetName

const char *GetName()
▼

Returns the flag’s name.

Create

static Flag *Create(const char *name, bool defaultValue = false, ::Rox::Client::Freeze freeze = RoxFreezeNone)
▼

Create a Flag with a default value and freeze level.

IsEnabled

bool IsEnabled(Context *context = nullptr)
▼

Returns the feature flag’s current value, or the default if no value was set.

Freeze

void Freeze()
void Freeze(::Rox::Client::Freeze freeze)
▼

Sets the freeze level for the flag.

Unfreeze

void Unfreeze(::Rox::Client::Freeze freeze)
▼

Unlock the flag value from changes from the last time it was frozen.

PeekCurrentValue

char *PeekCurrentValue()
▼

Retrieves the current flag value without freezing it, and without invoking impression.

This method is added for development only. Do not use this method in production.

PeekOriginalValue

char *PeekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression.

This method is added for development only. Do not use this method in production.

Class String

String is a feature flag containing string values.

This class is from Rox::Client namespace.

GetName

const char *GetName()
▼

Returns the flag’s name.

GetValue

char *GetValue(Context *context = nullptr)
▼

Returns the feature flag’s current value, or the default if no value was set.

Create

static Flag *Create(const char *name, bool defaultValue = false)

static String *Create(const char *name, const char *defaultValue, const std::vector<std::string> &options);
▼

Create a String with default value and options.

Freeze

void Freeze()
void Freeze(::Rox::Client::Freeze freeze)
▼

Sets the freeze level for the flag.

Unfreeze

void Unfreeze(::Rox::Client::Freeze freeze)
▼

Unlock the flag value from changes from the last time it was frozen.

PeekCurrentValue

char *PeekCurrentValue()
▼

Retrieves the current flag value without freezing it, and without invoking impression.

This method is added for development only. Do not use this method in production.

PeekOriginalValue

char *PeekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression.

This method is added for development only. Do not use this method in production.

Class Int

Int is a feature flag containing integer values.

This class is from Rox::Client namespace.

GetName

const char *GetName()
▼

Returns the flag’s name.

GetValue

int GetValue(Context *context = nullptr)
▼

Returns the feature flag’s current value, or the default if no value was set.

Create

static Int *Create(const char *name, int defaultValue)

static Int *Create(const char *name, int defaultValue, const std::vector<int> &options);
▼

Create a Int with default value and options.

Freeze

void Freeze()
void Freeze(::Rox::Client::Freeze freeze)
▼

Sets the freeze level for the flag.

Unfreeze

void Unfreeze(::Rox::Client::Freeze freeze)
▼

Unlock the flag value from changes from the last time it was frozen.

PeekCurrentValue

char *PeekCurrentValue()
▼

Retrieves the current flag value without freezing it, and without invoking impression.

This method is added for development only. Do not use this method in production.

PeekOriginalValue

char *PeekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression.

This method is added for development only. Do not use this method in production.

Class Double

Double is a feature flag containing double precision values.

This class is from Rox::Client namespace.

GetName

const char *GetName()
▼

Returns the flag’s name.

GetValue

double GetValue(Context *context = nullptr)
▼

Returns the feature flag’s current value, or the default if no value was set.

Create

static Double *Create(const char *name, double defaultValue)

static Double *Create(const char *name, double defaultValue, const std::vector<double> &options);
▼

Create a Double with default value and options.

Freeze

void Freeze()
void Freeze(::Rox::Client::Freeze freeze)
▼

Sets the freeze level for the flag.

Unfreeze

void Unfreeze(::Rox::Client::Freeze freeze)
▼

Unlock the flag value from changes from the last time it was frozen.

PeekCurrentValue

char *PeekCurrentValue()
▼

Retrieves the current flag value without freezing it, and without invoking impression.

This method is added for development only. Do not use this method in production.

PeekOriginalValue

char *PeekOriginalValue()
▼

Retrieves the original value with no overrides, no freeze, and without invoking impression.

This method is added for development only. Do not use this method in production.

Class Overrides

Rox::Client::Overrides is used to override a flag value locally, it is designed for developers working on a feature in dev mode and shouldn’t be used in production builds.

It is the base API that is used to show the Flag update flow. Currently, the C++ SDK doesn’t have a UI support that wraps overrides. The only way to use overrides is via the code.

When you override an existing flag value using the SetOverride method, the SDK will disregard existing configuration coming from the dashboard and will serialize the override on disk. This value will be loaded and override the flag right after you call Rox::Setup. To clear the override from the cache you need to call the Clear method.

This class is from Rox::Client namespace.

Get

static Overrides *Get()
▼

Get access to flag overrides singleton object.

SetOverride

void SetOverride(const char *name, const char *value)
▼

Sets an override value on a specific flag.

This function also saves the override value on the local device disk, so it is "remembered" for the next the SDK is loaded to production.

Parameter Type Description

name

const char*

The full flag name including the namespace, e.g. default.flagName.

value

const char*

The value of a flag, if this is a boolean flag the value should be "true" or "false".

GetOverride

const char *GetOverride(const char *name)
▼

Returns the overridden flag value or nullptr, if not overridden yet.

Parameter Type Description

name

const char*

The full flag name including the namespace, e.g. default.flagName.

HasOverride

bool HasOverride(const char *name)
▼

Checks whether the flag value has been overridden.

Parameter Type Description

name

const char*

The full flag name including the namespace, e.g. default.flagName.

Clear

void Clear()
void Clear(const char *name)
▼

Clears the overridden flag value(s).

Parameter Type Description

name

const char*

The full flag name including the namespace, e.g. default.flagName.

Class Context

The context class is used to pass data to the feature flag evaluation. This object is used by the registered CustomProperties to evaluate the experiment expression and return the value.

You can create a context using the ContextBuilder.

Class ContextBuilder

ContextBuilder

ContextBuilder()
▼

A simple constructor.

AddBoolValue

ContextBuilder &AddBoolValue(const char *name, bool value)
▼

Adds a bool value to the name key in the context.

AddIntValue

ContextBuilder &AddIntValue(const char *name, int value)
▼

Adds a int value to the name key in the context.

AddDoubleValue

ContextBuilder &AddDoubleValue(const char *name, double value)
▼

Adds a double value to the name key in the context.

AddStringValue

ContextBuilder &AddStringValue(const char *name, const char *value)
▼

Adds a string value to the name key in the context.

AddUndefined

ContextBuilder &AddUndefined(const char *name)
▼

Adds an undefined value to the name key in the context.

AddNull

ContextBuilder &AddNull(const char *name)
▼

Adds a NULL value to the name key in the context.

Build

Context *Build()
▼

Builds the Context to use in the evaluation of Flag and Variant.

For an example, see Flag context.

Using ConfigurationFetchedHandler

As seen in OptionsBuilder, SetConfigurationFetchedHandler can be used to write a handler for after new configurations request. To do so, implement ConfigurationFetchedHandlerInterface.

Class ConfigurationFetchedHandlerInterface

ConfigurationFetched

virtual void ConfigurationFetched(ConfigurationFetchedArgs *args) = 0
▼

For ConfigurationFetchedArgs, please see RoxConfigurationFetchedArgs C API.

For an example, see Configuration fetched handler.

Using ImpressionHandler

The impression handler delegate (as seen in OptionsBuilder SetImpressionHandler) has a couple of useful parameters which can help you decide on further actions.

To use the impressions handler implement the class ImpressionHandlerInterface.

Class ImpressionHandlerInterface

HandleImpression

virtual void HandleImpression(ReportingValue *value, Experiment *experiment, Context *context) = 0
▼

See C API RoxReportingValue (for ReportingValue) and RoxExperiment (for Experiment).

For an example, see Impression handler.

Class DynamicApi

DynamicApi is a way to evaluate flags and variants by their name, on the fly, without creating a Flag or Variant object before (using their Create method).

Create

static DynamicApi *Create()
▼

Create a DynamicApi, the proxy to all dynamic flags and variants evaluation.

IsEnabled

bool IsEnabled(const char *name, bool default_value = false, Context *context = nullptr)
▼

Evaluate a flag by its name, and context.

If no experiment was set via the dashboard, the default_value will be returned.

GetString/GetInt/GetDouble - obtain flag value

char *GetString(const char *name, char *default_value = nullptr, Context *context = nullptr);

char *GetString(const char *name, char *default_value, const std::vector<std::string> &options, Context *context);

int GetInt(const char *name, int default_value, Context *context = nullptr)

int GetInt(const char *name, int default_value, const std::vector<int> &options Context *context)

double GetDouble(const char *name, double default_value, Context *context = nullptr);

double GetDouble(const char *name, double default_value, const std::vector<double> &options, Context *context);
▼

Evaluate a feature flag by its name, and context. Options will be sent to the dashboard to allow an easy pick in the experiment.

If no experiment was set via the dashboard, the default_value will be returned.

For an example, see Dynamic API.

Logging

Logging helps debug in case something behave unexpectedly.

If no logging was set, default will be used, this means print to stdout errors level logs.

There are 2 method to control logging:

SetLogLevel

static void SetLogLevel(LogLevel logLevel)
▼

To use the default logging, with a different log level.

See RoxLogLevel in C API.

SetLogMessageHandler

static void SetLogMessageHandler(LogMessageHandlerInterface *handler)
▼

To use a customized logger, this is done by providing a class that implements LogMessageHandlerInterface.

Class LogMessageHandlerInterface

HandleLogMessage

virtual void HandleLogMessage(LogMessage *message) = 0
▼

The customized logging handler. See RoxLogMessage C API for LogMessage.

For an example, see Turning on verbose logging.

C++ is a C wrapper

Didn’t find what you were looking for? Please look in C Api, some structs have a matching struct without the Rox prefix (For Example C’s RoxDynamicValue ⇒ C++'s DynamicValue)

Still no luck? Please contact us.
C++ API
C# API