Context is a management class that describes the runtime of the SDK and is responsible for resource allocation and release of the SDK. Context has the ability to manage multiple devices. It is responsible for enumerating devices, monitoring device callbacks, and enabling multi-device synchronization. More...

#include "ObTypes.h"

Macros
#define	ob_enable_multi_device_sync ob_enable_device_clock_sync
#define	ob_set_logger_callback ob_set_logger_to_callback

Functions
OB_EXPORT ob_context *	ob_create_context (ob_error **error)
	Create a context object with the default configuration file.
OB_EXPORT ob_context *	ob_create_context_with_config (const char config_file_path, ob_error *error)
	Create a context object with a specified configuration file.
OB_EXPORT void	ob_delete_context (ob_context context, ob_error *error)
	Delete a context object.
OB_EXPORT ob_device_list *	ob_query_device_list (ob_context context, ob_error *error)
	Get a list of enumerated devices.
OB_EXPORT void	ob_enable_net_device_enumeration (ob_context context, bool enable, ob_error *error)
	Enable or disable network device enumeration.
OB_EXPORT bool	ob_force_ip_config (const char macAddress, ob_net_ip_config config, ob_error *error)
	"Force" a static IP address configuration in a device identified by its MAC Address.
OB_EXPORT bool	ob_send_action_command (uint32_t deviceKey, uint32_t groupKey, uint32_t groupMask, const char destIp, uint64_t scheduledTime, ob_error *error)
	Send an Action Command to GVCP devices.
OB_EXPORT void	ob_set_gvcp_port_scheme (ob_context context, ob_gvcp_port_scheme scheme, ob_error *error)
	Set the GVCP port scheme used for network device discovery and control.
OB_EXPORT ob_gvcp_port_scheme	ob_get_gvcp_port_scheme (ob_context context, ob_error *error)
	Get the current GVCP port scheme.
OB_EXPORT ob_device *	ob_create_net_device (ob_context context, const char address, uint16_t port, ob_error **error)
	Create a network device object.
OB_EXPORT ob_device *	ob_create_net_device_ex (ob_context context, const char address, uint16_t port, ob_device_access_mode accessMode, ob_error **error)
	Create a network device object.
OB_EXPORT void	ob_set_device_changed_callback (ob_context context, ob_device_changed_callback callback, void user_data, ob_error **error)
	Set a device plug-in callback function.
OB_EXPORT ob_callback_id	ob_register_device_changed_callback (ob_context context, ob_device_changed_callback callback, void user_data, ob_error **error)
	Register a device plug-in callback function.
OB_EXPORT void	ob_unregister_device_changed_callback (ob_context context, ob_callback_id callback_id, ob_error *error)
	Unregister a previously registered device plug-in callback function.
OB_EXPORT void	ob_enable_device_clock_sync (ob_context context, uint64_t repeat_interval_msec, ob_error *error)
	Activates device clock synchronization to synchronize the clock of the host and all created devices (if supported).
OB_EXPORT void	ob_sync_device_hardware_pps_time (ob_context context, uint64_t hardware_pps_time, ob_error *error)
	Synchronize the device time (synchronize hardwarePPS time to all created devices).
OB_EXPORT void	ob_free_idle_memory (ob_context context, ob_error *error)
	Free idle memory from the internal frame memory pool.
OB_EXPORT void	ob_set_uvc_backend_type (ob_context context, ob_uvc_backend_type backend_type, ob_error *error)
	For linux, there are two ways to enable the UVC backend: libuvc and v4l2. This function is used to set the backend type.
OB_EXPORT void	ob_set_logger_severity (ob_log_severity severity, ob_error **error)
	Set the global log level.
OB_EXPORT void	ob_set_logger_to_file (ob_log_severity severity, const char directory, ob_error *error)
	Set the log output to a file.
OB_EXPORT void	ob_set_logger_file_name (const char file_name, ob_error *error)
	Set the log file name for file output.
OB_EXPORT void	ob_set_logger_to_callback (ob_log_severity severity, ob_log_callback callback, void user_data, ob_error *error)
	Set the log callback function.
OB_EXPORT void	ob_set_logger_to_console (ob_log_severity severity, ob_error **error)
	Set the log output to the console.
OB_EXPORT void	ob_log_external_message (ob_log_severity severity, const char module, const char message, const char file, const char func, int line, ob_error **error)
	Logs a message with severity, file, function, and line info.
OB_EXPORT void	ob_set_extensions_directory (const char directory, ob_error *error)
	Set the extensions directory.
OB_EXPORT void	ob_context_set_timestamp_clock_type (ob_context context, ob_clock_type clock_type, ob_error *error)
	Set the host-side timestamp clock type for the current context.
OB_EXPORT ob_clock_type	ob_context_get_timestamp_clock_type (const ob_context context, ob_error *error)
	Get the current host-side timestamp clock type for the context.

Detailed Description

Context is a management class that describes the runtime of the SDK and is responsible for resource allocation and release of the SDK. Context has the ability to manage multiple devices. It is responsible for enumerating devices, monitoring device callbacks, and enabling multi-device synchronization.

Definition in file Context.h.

Macro Definition Documentation

◆ ob_enable_multi_device_sync

#define ob_enable_multi_device_sync ob_enable_device_clock_sync

Definition at line 332 of file Context.h.

◆ ob_set_logger_callback

#define ob_set_logger_callback ob_set_logger_to_callback

Definition at line 333 of file Context.h.

Function Documentation

◆ ob_create_context()

OB_EXPORT ob_context * ob_create_context ( ob_error ** error )

Create a context object with the default configuration file.

Parameters

[out] error Pointer to an error object that will be populated if an error occurs during context creation

Returns: Pointer to the created context object

Referenced by ob_create_context().

◆ ob_create_context_with_config()

OB_EXPORT ob_context * ob_create_context_with_config	(	const char *	config_file_path,
		ob_error **	error )

Create a context object with a specified configuration file.

Parameters

[in]	config_file_path	Path to the configuration file. If NULL, the default configuration file will be used.
[out]	error	Pointer to an error object that will be populated if an error occurs during context creation

Returns: Pointer to the created context object

Referenced by ob::Context::Context(), and ob_create_context_with_config().

◆ ob_delete_context()

OB_EXPORT void ob_delete_context	(	ob_context *	context,
		ob_error **	error )

Delete a context object.

Parameters

[in]	context	Pointer to the context object to be deleted
[out]	error	Pointer to an error object that will be populated if an error occurs during context deletion

Referenced by ob_delete_context(), and ob::Context::~Context().

◆ ob_query_device_list()

OB_EXPORT ob_device_list * ob_query_device_list	(	ob_context *	context,
		ob_error **	error )

Get a list of enumerated devices.

Parameters

[in]	context	Pointer to the context object
[out]	error	Pointer to an error object that will be populated if an error occurs during device enumeration

Returns: Pointer to the device list object

Referenced by ob_query_device_list(), and ob::Context::queryDeviceList().

◆ ob_enable_net_device_enumeration()

OB_EXPORT void ob_enable_net_device_enumeration	(	ob_context *	context,
		bool	enable,
		ob_error **	error )

Enable or disable network device enumeration.

After enabling, the network device will be automatically discovered and can be retrieved through ob_query_device_list. The default state can be set in the configuration file.

Attention: Network device enumeration is performed through the GVCP protocol. If the device is not in the same subnet as the host, it will be discovered but cannot be connected.

Parameters

[in]	context	Pointer to the context object
[in]	enable	true to enable, false to disable
[out]	error	Pointer to an error object that will be populated if an error occurs.

Referenced by ob::Context::enableNetDeviceEnumeration(), and ob_enable_net_device_enumeration().

◆ ob_force_ip_config()

OB_EXPORT bool ob_force_ip_config	(	const char *	macAddress,
		ob_net_ip_config	config,
		ob_error **	error )

"Force" a static IP address configuration in a device identified by its MAC Address.

Parameters

[in]	macAddress	MAC address of the network device. You can obtain it from ob_device_info_get_uid, or specify it manually in the format xx:xx:xx:xx:xx:xx, where each xx is a two-digit hexadecimal value.
[in]	config	The new IP configuration.
[out]	error	Pointer to an error object that will be populated if an error occurs.

Returns: bool true if the configuration command was processed successfully, false otherwise.

Note: This applies to all GVCP devices

Referenced by ob::Context::forceIp(), and ob_force_ip_config().

◆ ob_send_action_command()

OB_EXPORT bool ob_send_action_command	(	uint32_t	deviceKey,
		uint32_t	groupKey,
		uint32_t	groupMask,
		const char *	destIp,
		uint64_t	scheduledTime,
		ob_error **	error )

Send an Action Command to GVCP devices.

Parameters

[in]	deviceKey	Device key to match.
[in]	groupKey	Group key to match against the camera's Action blocks.
[in]	groupMask	Group mask, bitwise-ANDed with each Action block's mask.
[in]	destIp	Destination IPv4 address. NULL or "255.255.255.255" uses broadcast.
[in]	scheduledTime	PTP absolute timestamp. 0 = immediate trigger, non-zero = scheduled.
[out]	error	Pointer to an error object that will be populated if an error occurs.

Returns: bool true on success. Fire-and-forget; does not wait for camera ACK.

Referenced by ob_send_action_command(), and ob::Context::sendActionCommand().

◆ ob_set_gvcp_port_scheme()

OB_EXPORT void ob_set_gvcp_port_scheme	(	ob_context *	context,
		ob_gvcp_port_scheme	scheme,
		ob_error **	error )

Set the GVCP port scheme used for network device discovery and control.

Parameters

[in]	context	Pointer to the context object.
[in]	scheme	Target GVCP port scheme. Return error if the specified scheme is invalid or unsupported.
[out]	error	Pointer to an error object that will be populated if an error occurs.

Note: This change affects only the current session and is not persisted.; Switching to a different scheme will force disconnection of all currently connected network devices.

Referenced by ob_set_gvcp_port_scheme(), and ob::Context::setGvcpPortScheme().

◆ ob_get_gvcp_port_scheme()

OB_EXPORT ob_gvcp_port_scheme ob_get_gvcp_port_scheme	(	ob_context *	context,
		ob_error **	error )

Get the current GVCP port scheme.

Parameters

[in]	context	Pointer to the context object
[out]	error	Pointer to an error object that will be populated if an error occurs.

Returns: Current GVCP port scheme.

Referenced by ob::Context::getGvcpPortScheme(), and ob_get_gvcp_port_scheme().

◆ ob_create_net_device()

OB_EXPORT ob_device * ob_create_net_device	(	ob_context *	context,
		const char *	address,
		uint16_t	port,
		ob_error **	error )

Create a network device object.

Parameters

[in]	context	Pointer to the context object
[in]	address	IP address of the device
[in]	port	Port number of the device
[out]	error	Pointer to an error object that will be populated if an error occurs during device creation

Returns: Pointer to the created device object

Referenced by ob_create_net_device().

◆ ob_create_net_device_ex()

OB_EXPORT ob_device * ob_create_net_device_ex	(	ob_context *	context,
		const char *	address,
		uint16_t	port,
		ob_device_access_mode	accessMode,
		ob_error **	error )

Create a network device object.

Parameters

[in]	context	Pointer to the context object
[in]	address	IP address of the device
[in]	port	Port number of the device
[in]	accessMode	Device access mode. ob_device_access_mode. If the device does not support setting the Access Mode, the default OB_DEVICE_DEFAULT_ACCESS is used. Applies only on first device creation or after release and re-creation; subsequent calls ignore it.
[out]	error	Pointer to an error object that will be populated if an error occurs during device creation

Returns: Pointer to the created device object

Referenced by ob::Context::createNetDevice(), and ob_create_net_device_ex().

◆ ob_set_device_changed_callback()

OB_EXPORT void ob_set_device_changed_callback	(	ob_context *	context,
		ob_device_changed_callback	callback,
		void *	user_data,
		ob_error **	error )

Set a device plug-in callback function.

Deprecated: This function is deprecated. Please use ob_register_device_changed_callback() instead.

Attention: The added and removed device lists returned through the callback interface need to be released manually; This function supports multiple callbacks. Each call to this function adds a new callback to an internal list.

Parameters

[in]	context	Pointer to the context object
[in]	callback	Pointer to the callback function triggered when a device is plugged or unplugged
[in]	user_data	Pointer to user data that can be passed to and retrieved from the callback function
[out]	error	Pointer to an error object that will be populated if an error occurs during callback function setting

Referenced by ob_set_device_changed_callback().

◆ ob_register_device_changed_callback()

OB_EXPORT ob_callback_id ob_register_device_changed_callback	(	ob_context *	context,
		ob_device_changed_callback	callback,
		void *	user_data,
		ob_error **	error )

Register a device plug-in callback function.

This function registers a callback that will be triggered whenever a device is plugged in or unplugged.

Attention: The added and removed device lists returned through the callback interface need to be released manually.; This function supports multiple callbacks. Each call to this function adds a new callback to an internal list.

Parameters

[in]	context	Pointer to the context object.
[in]	callback	Pointer to the callback function triggered when a device is plugged or unplugged.
[in]	user_data	Pointer to user data that can be passed to and retrieved from the callback function.
[out]	error	Pointer to an error object that will be populated if an error occurs during callback function setting.

Returns: A ob_callback_id that uniquely identifies the registered callback. This ID can be used later to unregister the callback with ob_unregister_device_changed_callback(). Returns INVALID_DEVICE_CHANGED_CALLBACK_ID if the registration fails.

Referenced by ob_register_device_changed_callback(), and ob::Context::registerDeviceChangedCallback().

◆ ob_unregister_device_changed_callback()

OB_EXPORT void ob_unregister_device_changed_callback	(	ob_context *	context,
		ob_callback_id	callback_id,
		ob_error **	error )

Unregister a previously registered device plug-in callback function.

This function removes a callback that was registered by ob_register_device_changed_callback().

Parameters

[in]	context	Pointer to the context object.
[in]	callback_id	The callback ID returned by ob_register_device_changed_callback().
[out]	error	Pointer to an error object that will be populated if an error occurs during callback function setting.

Referenced by ob_unregister_device_changed_callback(), and ob::Context::unregisterDeviceChangedCallback().

◆ ob_enable_device_clock_sync()

OB_EXPORT void ob_enable_device_clock_sync	(	ob_context *	context,
		uint64_t	repeat_interval_msec,
		ob_error **	error )

Activates device clock synchronization to synchronize the clock of the host and all created devices (if supported).

Parameters

[in]	context	Pointer to the context object
[in]	repeat_interval_msec	The interval for auto-repeated synchronization, in milliseconds. If the value is 0, synchronization is performed only once.
[out]	error	Pointer to an error object that will be populated if an error occurs during execution

Referenced by ob::Context::enableDeviceClockSync(), and ob_enable_device_clock_sync().

◆ ob_sync_device_hardware_pps_time()

OB_EXPORT void ob_sync_device_hardware_pps_time	(	ob_context *	context,
		uint64_t	hardware_pps_time,
		ob_error **	error )

Synchronize the device time (synchronize hardwarePPS time to all created devices).

Parameters

[in]	context	Pointer to the context object
[in]	hardware_pps_time	unit: ms.
[out]	error	Pointer to an error object that will be populated if an error occurs during execution

Referenced by ob_sync_device_hardware_pps_time(), and ob::Context::syncDeviceHardwarePPSTime().

◆ ob_free_idle_memory()

OB_EXPORT void ob_free_idle_memory	(	ob_context *	context,
		ob_error **	error )

Free idle memory from the internal frame memory pool.

Parameters

[in]	context	Pointer to the context object
[out]	error	Pointer to an error object that will be populated if an error occurs during memory freeing

Referenced by ob::Context::freeIdleMemory(), and ob_free_idle_memory().

◆ ob_set_uvc_backend_type()

OB_EXPORT void ob_set_uvc_backend_type	(	ob_context *	context,
		ob_uvc_backend_type	backend_type,
		ob_error **	error )

For linux, there are two ways to enable the UVC backend: libuvc and v4l2. This function is used to set the backend type.

It is effective when the new device is created.

Attention: This interface is only available for Linux.

Parameters

[in]	context	Pointer to the context object
[in]	backend_type	The backend type to be used.
[out]	error	Pointer to an error object that will be populated if an error occurs during backend type setting

Referenced by ob_set_uvc_backend_type(), and ob::Context::setUvcBackendType().

◆ ob_set_logger_severity()

OB_EXPORT void ob_set_logger_severity	(	ob_log_severity	severity,
		ob_error **	error )

Set the global log level.

Attention: This interface setting will affect the output level of all logs (terminal, file, callback)

Parameters

[in]	severity	Log level to set
[out]	error	Pointer to an error object that will be populated if an error occurs during log level setting

Referenced by ob_set_logger_severity(), and ob::Context::setLoggerSeverity().

◆ ob_set_logger_to_file()

OB_EXPORT void ob_set_logger_to_file	(	ob_log_severity	severity,
		const char *	directory,
		ob_error **	error )

Set the log output to a file.

Parameters

[in]	severity	Log level to output to file
[in]	directory	Path to the log file output directory. If empty, the existing configuration is used; if the existing configuration is also empty, the value from the config file or the default configuration will be used.
[out]	error	Pointer to an error object that will be populated if an error occurs during log output setting

Note: Other settings, such as log file name, remain unchanged.

Referenced by ob_set_logger_to_file(), and ob::Context::setLoggerToFile().

◆ ob_set_logger_file_name()

OB_EXPORT void ob_set_logger_file_name	(	const char *	file_name,
		ob_error **	error )

Set the log file name for file output.

Parameters

[in]	file_name	Log file name. Must not be empty.
[out]	error	Pointer to an error object that will be set if an error occurs.

Note: Other settings, such as log level and output directory, remain unchanged.

Referenced by ob_set_logger_file_name(), and ob::Context::setLoggerFileName().

◆ ob_set_logger_to_callback()

OB_EXPORT void ob_set_logger_to_callback	(	ob_log_severity	severity,
		ob_log_callback	callback,
		void *	user_data,
		ob_error **	error )

Set the log callback function.

Parameters

[in]	severity	Log level to set for the callback function
[in]	callback	Pointer to the callback function
[in]	user_data	Pointer to user data that can be passed to and retrieved from the callback function
[out]	error	Pointer to an error object that will be populated if an error occurs during log callback function setting

Referenced by ob_set_logger_to_callback(), and ob::Context::setLoggerToCallback().

◆ ob_set_logger_to_console()

OB_EXPORT void ob_set_logger_to_console	(	ob_log_severity	severity,
		ob_error **	error )

Set the log output to the console.

Parameters

[in]	severity	Log level to output to the console
[out]	error	Pointer to an error object that will be populated if an error occurs during log output setting

Referenced by ob_set_logger_to_console(), and ob::Context::setLoggerToConsole().

◆ ob_log_external_message()

OB_EXPORT void ob_log_external_message	(	ob_log_severity	severity,
		const char *	module,
		const char *	message,
		const char *	file,
		const char *	func,
		int	line,
		ob_error **	error )

Logs a message with severity, file, function, and line info.

Parameters

[in]	severity	Log level, see ob_log_severity for details
[in]	module	The module or component the log belongs to
[in]	message	Message string to log
[in]	file	Source file name, e.g., FILE
[in]	func	Function name, e.g., func
[in]	line	Line number, e.g., LINE
[out]	error	Pointer to an error object that will be populated if an error occurs during log output setting

Referenced by ob::Context::logExternalMessage(), and ob_log_external_message().

◆ ob_set_extensions_directory()

OB_EXPORT void ob_set_extensions_directory	(	const char *	directory,
		ob_error **	error )

Set the extensions directory.

The extensions directory is used to search for dynamic libraries that provide additional functionality to the SDK, such as the Frame filters.

Attention: Should be called before creating the context and pipeline, otherwise the default extensions directory (./extensions) will be used.

Parameters

[in]	directory	Path to the extensions directory. If the path is empty, extensions path will be set to the current working directory.
[out]	error	Pointer to an error object that will be populated if an error occurs during extensions directory setting

Referenced by ob_set_extensions_directory(), and ob::Context::setExtensionsDirectory().

◆ ob_context_set_timestamp_clock_type()

OB_EXPORT void ob_context_set_timestamp_clock_type	(	ob_context *	context,
		ob_clock_type	clock_type,
		ob_error **	error )

Set the host-side timestamp clock type for the current context.

Attention: All ob::Context instances share the same underlying SDK runtime and clock type.; Switching affects frame system and global timestamps; avoid switching during streaming.; It is recommended to synchronize device timestamps after switching.

Parameters

[in]	context	Pointer to the context object
[in]	clock_type	The clock type to use for host-side timestamps
[out]	error	Pointer to an error object that will be populated if an error occurs

Referenced by ob_context_set_timestamp_clock_type(), and ob::Context::setTimestampClockType().

◆ ob_context_get_timestamp_clock_type()

OB_EXPORT ob_clock_type ob_context_get_timestamp_clock_type	(	const ob_context *	context,
		ob_error **	error )

Get the current host-side timestamp clock type for the context.

Parameters

[in]	context	Pointer to the context object
[out]	error	Pointer to an error object that will be populated if an error occurs

Returns: ob_clock_type The current clock type

Referenced by ob::Context::getTimestampClockType(), and ob_context_get_timestamp_clock_type().

Macros

Functions

Detailed Description

Macro Definition Documentation

◆ ob_enable_multi_device_sync

◆ ob_set_logger_callback

Function Documentation

◆ ob_create_context()

◆ ob_create_context_with_config()

◆ ob_delete_context()

◆ ob_query_device_list()

◆ ob_enable_net_device_enumeration()

◆ ob_force_ip_config()

◆ ob_send_action_command()

◆ ob_set_gvcp_port_scheme()

◆ ob_get_gvcp_port_scheme()

◆ ob_create_net_device()

◆ ob_create_net_device_ex()

◆ ob_set_device_changed_callback()

◆ ob_register_device_changed_callback()

◆ ob_unregister_device_changed_callback()

◆ ob_enable_device_clock_sync()

◆ ob_sync_device_hardware_pps_time()

◆ ob_free_idle_memory()

◆ ob_set_uvc_backend_type()

◆ ob_set_logger_severity()

◆ ob_set_logger_to_file()

◆ ob_set_logger_file_name()

◆ ob_set_logger_to_callback()

◆ ob_set_logger_to_console()

◆ ob_log_external_message()

◆ ob_set_extensions_directory()

◆ ob_context_set_timestamp_clock_type()

◆ ob_context_get_timestamp_clock_type()