APIs to configure, initialize and shutdown the SDK and agent and related basic functions. More...

Typedefs
typedef void	onesdk_stub_logging_callback_t(onesdk_logging_level_t level, onesdk_xchar_t const *message)
	SDK stub logging function prototype. More...

Functions
void	onesdk_stub_get_version (onesdk_stub_version_t *out_stub_version)
	Retrieves the stub version number. More...

onesdk_xchar_t const *	onesdk_stub_xstrerror (onesdk_result_t error_code, onesdk_xchar_t *buffer, onesdk_size_t buffer_length)
	Retrieves a human readable error message corresponding to an error code that was returned by the SDK stub. More...

onesdk_bool_t	onesdk_stub_is_sdk_cmdline_arg (onesdk_xchar_t const *arg)
	Determines whether a command line argument is an SDK argument. More...

onesdk_result_t	onesdk_stub_process_cmdline_arg (onesdk_xchar_t const *arg, onesdk_bool_t replace_existing)
	Processes one command line argument. More...

onesdk_result_t	onesdk_stub_process_cmdline_args (int argc, onesdk_xchar_t const const argv, onesdk_bool_t replace_existing)
	Processes multiple command line arguments. More...

onesdk_result_t	onesdk_stub_strip_sdk_cmdline_args (int argc, onesdk_xchar_t *argv)
	Removes SDK command line arguments from an `argv` array. More...

onesdk_result_t	onesdk_stub_set_variable (onesdk_xchar_t const *var, onesdk_bool_t replace_existing)
	Sets an SDK initialization variable. More...

void	onesdk_stub_free_variables (void)
	Clears all SDK initialization variables. More...

void	onesdk_stub_default_logging_function (onesdk_logging_level_t level, onesdk_xchar_t const *message)
	The default SDK stub logging function - writes to `stderr`. More...

void	onesdk_stub_set_logging_level (onesdk_logging_level_t level)
	Sets the SDK stub logging level. More...

void	onesdk_stub_set_logging_callback (onesdk_stub_logging_callback_t *stub_logging_callback)
	Sets the SDK stub logging callback function. More...

onesdk_result_t	onesdk_initialize (void)
	Load and initialize the SDK agent. More...

onesdk_result_t	onesdk_initialize_2 (onesdk_uint32_t init_flags)
	Load and initialize the SDK agent, with additional flags. More...

onesdk_result_t	onesdk_shutdown (void)
	Shut down and unload the SDK agent. More...

void	onesdk_stub_get_agent_load_info (onesdk_bool_t agent_found, onesdk_bool_t agent_compatible)
	Retrieves debug information about the currently used agent. More...

Detailed Description

APIs to configure, initialize and shutdown the SDK and agent and related basic functions.

A typical use of these functions could be:

#include <onesdk/onesdk.h>
#include <stdio.h>
// optional but higly recommended (see below)
static void mycallback(char const* message) {
    fputs(message, stderr);
}
int main(int argc, char** argv) {
    onesdk_stub_process_cmdline_args(argc, argv, 1);  // optional: let the SDK process command line arguments 
    onesdk_stub_strip_sdk_cmdline_args(&argc, argv);  // optional: remove SDK command line arguments from argv
    // Initialize SDK
    onesdk_result_t const onesdk_init_result = onesdk_initialize();
    // optional: Set logging callbacks (see @ref misc)
    onesdk_agent_set_warning_callback(mycallback); // Highly recommended.
    onesdk_agent_set_verbose_callback(mycallback); // Recommended for development & debugging.
    // ... use SDK ...
    // Shut down SDK only if initialization suceeded.
    if (onesdk_init_result == ONESDK_SUCCESS)
        onesdk_shutdown();
    return 0;
}

Note that most of the functions in this module have return codes and onesdk_stub_xstrerror can be used to translate them to human-readable messages. After initialization, errors are reported via the logging callbacks (mycallback in the example above).

Typedef Documentation

◆ onesdk_stub_logging_callback_t

typedef void onesdk_stub_logging_callback_t(onesdk_logging_level_t level, onesdk_xchar_t const *message)

SDK stub logging function prototype.

Parameters

level	The logging level of the message. See logging_level_constants.
message	The undecorated log message.

Note: Messages which do not pass the logging level test (see onesdk_stub_set_logging_level) will not be forwarded to the logging function.; The message string will not contain any decoration as described in onesdk_stub_default_logging_function.

Function Documentation

◆ onesdk_initialize()

onesdk_result_t onesdk_initialize ( void )

Load and initialize the SDK agent.

Returns: ONESDK_SUCCESS if successful, an SDK stub error code otherwise.

This function tries to locate, load and initialize the SDK agent. See onesdk_shutdown for shutting down and unloading the agent. If this function is called after the agent has already been initialized, an internal reference count will be incremented. In that case the application must call onesdk_shutdown once for each successful call to onesdk_initialize.

This function behaves just as onesdk_initialize_2(0).

Note: If your application forks while executing onesdk_initialize, onesdk_initialize_2 or onesdk_shutdown on another thread, it is not safe to call SDK functions in the forked child process without calling exec first. Doing so may result in a deadlock.

See also: onesdk_initialize_2; onesdk_stub_get_agent_load_info can give more information about initialization failures.

◆ onesdk_initialize_2()

onesdk_result_t onesdk_initialize_2 ( onesdk_uint32_t init_flags )

Load and initialize the SDK agent, with additional flags.

Parameters

init_flags A bitwise combination of flags from init_flags or zero.

Returns: ONESDK_SUCCESS if successful, an SDK stub error code otherwise.

This function tries to locate, load and initialize the SDK agent. See onesdk_shutdown for shutting down and unloading the agent. If this function is called after the agent has already been initialized, an internal reference count will be incremented. In that case the application must call onesdk_shutdown once for each successful call to onesdk_initialize.

Note: If your application forks while executing onesdk_initialize, onesdk_initialize_2 or onesdk_shutdown on another thread, it is not safe to call SDK functions in the forked child process without calling exec first. Doing so may result in a deadlock. (This restriction also applies when using ONESDK_INIT_FLAG_FORKABLE.)

Since: This function was added in version 1.3.0.

See also: init_flags; onesdk_initialize; onesdk_stub_get_agent_load_info can give more information about initialization failures.

◆ onesdk_shutdown()

onesdk_result_t onesdk_shutdown ( void )

Shut down and unload the SDK agent.

Returns: ONESDK_SUCCESS if successful, an SDK stub error code otherwise.

This function will shut down and unload the SDK agent.

Note: If your application forks while executing onesdk_initialize, onesdk_initialize_2 or onesdk_shutdown on another thread, it is not safe to call SDK functions in the forked child process without calling exec first. Doing so may result in a deadlock.; Unloading the actual SDK agent module (DLL/SO/...) may not be possible on all platforms.

◆ onesdk_stub_default_logging_function()

void onesdk_stub_default_logging_function	(	onesdk_logging_level_t	level,
		onesdk_xchar_t const *	message
	)

The default SDK stub logging function - writes to stderr.

Parameters

level	See onesdk_stub_logging_callback_t.
message	See onesdk_stub_logging_callback_t.

This function will decorate the log message with the following items:

The current date and time (UTC)
An identifier for the current thread
The string representation of the message's logging level
The string "[onesdk]" to mark the log output as coming from the SDK stub
A trailing newline character

The resulting string will the be written to stderr.

An application can

Set this function using onesdk_stub_set_logging_callback to restore the default or
Call this function from its own logging function (e.g. to filter log messages or forward them to some other place in addition to writing them to stderr).

See also: onesdk_stub_set_logging_callback

◆ onesdk_stub_free_variables()

void onesdk_stub_free_variables ( void )

Clears all SDK initialization variables.

This function clears all SDK initialization variables and releases the memory used to store them.

◆ onesdk_stub_get_agent_load_info()

void onesdk_stub_get_agent_load_info	(	onesdk_bool_t *	agent_found,
		onesdk_bool_t *	agent_compatible
	)

Retrieves debug information about the currently used agent.

Parameters

[out]	agent_found	[optional] Pointer to a bool indicating whether the agent was found or not.
[out]	agent_compatible	[optional] Pointer to a bool indicating whether the agent was both found and compatible or not.

This function only yields meaningful results between calling onesdk_initialize (or onesdk_initialize_2) and onesdk_shutdown. It is useful to get more information about why initialization failed. Sucessful initialization always implies that both *agent_found and *agent_compatible are true.

Note that *agent_found is also false if initialization failed before even trying to find the agent and *agent_compatible is also false if the agent was found but its compatibility could not be checked.

See also: onesdk_agent_get_version_string may have the version of the agent, which is interesting if *agent_found is true but *agent_compatible is not.

Since: This function was added in version 1.3.0.

◆ onesdk_stub_get_version()

void onesdk_stub_get_version ( onesdk_stub_version_t * out_stub_version )

Retrieves the stub version number.

Parameters

[out] out_stub_version Pointer to a onesdk_stub_version_t struct that will be filled with the stub version number.

An application can use this function to make sure the stub binary matches the header files that were used to compile the application. Especially useful when using the shared stub version (DLL/SO).

Since: This function was added in version 1.2.0.

◆ onesdk_stub_is_sdk_cmdline_arg()

onesdk_bool_t onesdk_stub_is_sdk_cmdline_arg ( onesdk_xchar_t const * arg )

Determines whether a command line argument is an SDK argument.

Parameters

arg	A command line argument.

Returns: A non-zero value if arg starts with --dt_, zero otherwise.

◆ onesdk_stub_process_cmdline_arg()

onesdk_result_t onesdk_stub_process_cmdline_arg	(	onesdk_xchar_t const *	arg,
		onesdk_bool_t	replace_existing
	)

Processes one command line argument.

Parameters

arg	A command line argument.
replace_existing	Tells the function whether it should overwrite an existing value (non-zero) or not (zero).

Returns

ONESDK_SUCCESS if successful, an SDK stub error code otherwise.

If arg is an SDK command line argument with invalid format (e.g. not in the form key=value) this function will return ONESDK_ERROR_INVALID_ARGUMENT.
If arg is an SDK command line argument with a key for which a value has already been set and replace_existing is zero this function will return ONESDK_ERROR_ENTRY_ALREADY_EXISTS.

If arg is an SDK command line argument, this function will store the key=value pair defined by that argument. If called with arg set to NULL or a string that isn't an SDK command line arguments this function will do nothing and return ONESDK_SUCCESS.

◆ onesdk_stub_process_cmdline_args()

onesdk_result_t onesdk_stub_process_cmdline_args	(	int	argc,
		onesdk_xchar_t const const	argv,
		onesdk_bool_t	replace_existing
	)

Processes multiple command line arguments.

Parameters

argc	The number of entries in `argv`.
argv	Points to an array of pointers to command line argument strings.
replace_existing	Tells the function whether it should overwrite existing values (non-zero) or not (zero).

Returns

ONESDK_SUCCESS if successful, an SDK error code otherwise.

If one of the processed strings is an SDK command line argument with invalid format this function will return ONESDK_ERROR_INVALID_ARGUMENT.
If one of the processed strings was an SDK command line argument with a key for which a value has already been set, replace_existing is zero and no other error occurred, this function will return ONESDK_ERROR_ENTRY_ALREADY_EXISTS.

This function will process the arguments argv[1] ... argv[argc - 1] as if by calling onesdk_stub_process_cmdline_arg(argv[i]). argv[0] is ignored. That means it's possible to call it with the argc and argv arguments of a typical C main function. Neither argc or argv will be modified.

See also: onesdk_stub_process_cmdline_arg; onesdk_stub_strip_sdk_cmdline_args

◆ onesdk_stub_set_logging_callback()

void onesdk_stub_set_logging_callback ( onesdk_stub_logging_callback_t * stub_logging_callback )

Sets the SDK stub logging callback function.

Parameters

stub_logging_callback The new SDK stub logging callback function.

The stub logging callback function is used to log messages while initializing (locating and loading the agent) and shutting down the SDK (unloading the agent).

The default logging function is onesdk_stub_default_logging_function.

An application can use this function to change how SDK stub log messages are formatted and where they're written to.

If stub_logging_callback is set to NULL, all log messages will be discarded.

See also: onesdk_stub_logging_callback_t; onesdk_stub_default_logging_function; onesdk_agent_set_logging_callback

◆ onesdk_stub_set_logging_level()

void onesdk_stub_set_logging_level ( onesdk_logging_level_t level )

Sets the SDK stub logging level.

Parameters

level The new SDK stub logging level.

The default SDK stub logging level is ONESDK_LOGGING_LEVEL_NONE which means no messages will be logged. Messages with a level < the current SDK stub logging level will be suppressed (=not sent to the logging function).

Note: This only affects log messages generated in the SDK stub itself. The actual agent uses a different logging mechanism.

See also: logging_level_constants; onesdk_stub_set_logging_callback

◆ onesdk_stub_set_variable()

onesdk_result_t onesdk_stub_set_variable	(	onesdk_xchar_t const *	var,
		onesdk_bool_t	replace_existing
	)

Sets an SDK initialization variable.

Parameters

var	A string with an SDK initialization variable definition in the form `key=value`.
replace_existing	Tells the function whether it should overwrite an existing value (non-zero) or not (zero).

Returns

ONESDK_SUCCESS if successful, an SDK stub error code otherwise.

If var is NULL or points to an empty string this function will do nothing and return ONESDK_SUCCESS.
If var has an invalid format this function will return ONESDK_ERROR_INVALID_ARGUMENT.
If var defines a variable with a key for which a value has already been set and replace_existing is zero this function will return ONESDK_ERROR_ENTRY_ALREADY_EXISTS.

◆ onesdk_stub_strip_sdk_cmdline_args()

onesdk_result_t onesdk_stub_strip_sdk_cmdline_args	(	int *	argc,
		onesdk_xchar_t **	argv
	)

Removes SDK command line arguments from an argv array.

Parameters

[in,out]	argc	Points to an `int` which specifies the number of entries in `argv`.
[in,out]	argv	Points to an array of pointers to command line argument strings.

Returns: ONESDK_SUCCESS if successful, an SDK stub error code otherwise.

This function modifies the array pointed to by argv by removing entries that are SDK command line arguments. argv[0] is ignored. The value pointed to by argc is then updated to reflect the new array size.

◆ onesdk_stub_xstrerror()

onesdk_xchar_t const* onesdk_stub_xstrerror	(	onesdk_result_t	error_code,
		onesdk_xchar_t *	buffer,
		onesdk_size_t	buffer_length
	)

Retrieves a human readable error message corresponding to an error code that was returned by the SDK stub.

Parameters

	error_code	An error code returned by an SDK stub function.
[out]	buffer	Pointer to a buffer into which the error message shall be copied.
	buffer_length	The length of the buffer pointed to by `buffer` in onesdk_xchar_t characters.

Returns: buffer

If buffer_length is at least one, this function will make sure that the string copied to buffer is always null-terminated. If the provided buffer is too small, the error message will be truncated.

Typedefs

Functions

Detailed Description

Typedef Documentation

◆ onesdk_stub_logging_callback_t

Function Documentation

◆ onesdk_initialize()

◆ onesdk_initialize_2()

◆ onesdk_shutdown()

◆ onesdk_stub_default_logging_function()

◆ onesdk_stub_free_variables()

◆ onesdk_stub_get_agent_load_info()

◆ onesdk_stub_get_version()

◆ onesdk_stub_is_sdk_cmdline_arg()

◆ onesdk_stub_process_cmdline_arg()

◆ onesdk_stub_process_cmdline_args()

◆ onesdk_stub_set_logging_callback()

◆ onesdk_stub_set_logging_level()

◆ onesdk_stub_set_variable()

◆ onesdk_stub_strip_sdk_cmdline_args()

◆ onesdk_stub_xstrerror()