1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
// Copyright (c) Orbbec Inc. All Rights Reserved.
// Licensed under the MIT License.
/**
* @file Context.h
* @brief 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.
*/
#pragma once
#ifdef __cplusplus
extern "C" {
#endif
#include "ObTypes.h"
/**
* @brief Create a context object with the default configuration file
*
* @param[out] error Pointer to an error object that will be populated if an error occurs during context creation
* @return Pointer to the created context object
*/
OB_EXPORT ob_context *ob_create_context(ob_error **error);
/**
* @brief Create a context object with a specified configuration file
*
* @param[in] config_file_path Path to the configuration file. If NULL, the default configuration file will be used.
* @param[out] error Pointer to an error object that will be populated if an error occurs during context creation
* @return Pointer to the created context object
*/
OB_EXPORT ob_context *ob_create_context_with_config(const char *config_file_path, ob_error **error);
/**
* @brief Delete a context object
*
* @param[in] context Pointer to the context object to be deleted
* @param[out] error Pointer to an error object that will be populated if an error occurs during context deletion
*/
OB_EXPORT void ob_delete_context(ob_context *context, ob_error **error);
/**
* @brief Get a list of enumerated devices
*
* @param[in] context Pointer to the context object
* @param[out] error Pointer to an error object that will be populated if an error occurs during device enumeration
* @return Pointer to the device list object
*/
OB_EXPORT ob_device_list *ob_query_device_list(ob_context *context, ob_error **error);
/**
* @brief Enable or disable network device enumeration
* @brief After enabling, the network device will be automatically discovered and can be retrieved through @ref 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.
*
* @param[in] context Pointer to the context object
* @param[in] enable true to enable, false to disable
* @param[out] error Pointer to an error object that will be populated if an error occurs.
*/
OB_EXPORT void ob_enable_net_device_enumeration(ob_context *context, bool enable, ob_error **error);
/**
* @brief "Force" a static IP address configuration in a device identified by its MAC Address.
*
* @param[in] macAddress MAC address of the network device.
* You can obtain it from @ref DeviceList::uid(), or specify it manually
* in the format xx:xx:xx:xx:xx:xx, where each xx is a two-digit hexadecimal value.
* @param[in] config The new IP configuration.
* @param[out] error Pointer to an error object that will be populated if an error occurs.
* @return bool true if the configuration command was processed successfully, false otherwise.
*
* @note This applies to all Orbbec GigE Vision devices
*/
OB_EXPORT bool ob_force_ip_config(const char *deviceUid, ob_net_ip_config config, ob_error **error);
/**
* @brief Create a network device object
*
* @param[in] context Pointer to the context object
* @param[in] address IP address of the device
* @param[in] port Port number of the device
* @param[out] error Pointer to an error object that will be populated if an error occurs during device creation
* @return Pointer to the created device object
*/
OB_EXPORT ob_device *ob_create_net_device(ob_context *context, const char *address, uint16_t port, ob_error **error);
/**
* @brief Set a device plug-in callback function
* @attention The added and removed device lists returned through the callback interface need to be released manually
* @attention This function supports multiple callbacks. Each call to this function adds a new callback to an internal list.
*
* @param[in] context Pointer to the context object
* @param[in] callback Pointer to the callback function triggered when a device is plugged or unplugged
* @param[in] user_data Pointer to user data that can be passed to and retrieved from the callback function
* @param[out] error Pointer to an error object that will be populated if an error occurs during callback function setting
*/
OB_EXPORT void ob_set_device_changed_callback(ob_context *context, ob_device_changed_callback callback, void *user_data, ob_error **error);
/**
* @brief Activates device clock synchronization to synchronize the clock of the host and all created devices (if supported).
*
* @param[in] context Pointer to the context object
* @param[in] repeat_interval_msec The interval for auto-repeated synchronization, in milliseconds. If the value is 0, synchronization is performed only once.
* @param[out] error Pointer to an error object that will be populated if an error occurs during execution
*/
OB_EXPORT void ob_enable_device_clock_sync(ob_context *context, uint64_t repeat_interval_msec, ob_error **error);
/**
* @brief Free idle memory from the internal frame memory pool
*
* @param[in] context Pointer to the context object
* @param[out] error Pointer to an error object that will be populated if an error occurs during memory freeing
*/
OB_EXPORT void ob_free_idle_memory(ob_context *context, ob_error **error);
/**
* @brief For linux, there are two ways to enable the UVC backend: libuvc and v4l2. This function is used to set the backend type.
* @brief It is effective when the new device is created.
*
* @attention This interface is only available for Linux.
*
* @param[in] context Pointer to the context object
* @param[in] backend_type The backend type to be used.
* @param[out] error Pointer to an error object that will be populated if an error occurs during backend type setting
*/
OB_EXPORT void ob_set_uvc_backend_type(ob_context *context, ob_uvc_backend_type backend_type, ob_error **error);
/**
* @brief Set the global log level
*
* @attention This interface setting will affect the output level of all logs (terminal, file, callback)
*
* @param[in] severity Log level to set
* @param[out] error Pointer to an error object that will be populated if an error occurs during log level setting
*/
OB_EXPORT void ob_set_logger_severity(ob_log_severity severity, ob_error **error);
/**
* @brief Set the log output to a file
*
* @param[in] severity Log level to output to file
* @param[in] directory Path to the log file output directory. If the path is empty, the existing settings will continue to be used (if the existing
* configuration is also empty, the log will not be output to the file)
* @param[out] error Pointer to an error object that will be populated if an error occurs during log output setting
*/
OB_EXPORT void ob_set_logger_to_file(ob_log_severity severity, const char *directory, ob_error **error);
/**
* @brief Set the log callback function
*
* @param[in] severity Log level to set for the callback function
* @param[in] callback Pointer to the callback function
* @param[in] user_data Pointer to user data that can be passed to and retrieved from the callback function
* @param[out] error Pointer to an error object that will be populated if an error occurs during log callback function setting
*/
OB_EXPORT void ob_set_logger_to_callback(ob_log_severity severity, ob_log_callback callback, void *user_data, ob_error **error);
/**
* @brief Set the log output to the console
*
* @param[in] severity Log level to output to the console
* @param[out] error Pointer to an error object that will be populated if an error occurs during log output setting
*/
OB_EXPORT void ob_set_logger_to_console(ob_log_severity severity, ob_error **error);
/**
* @brief Set the extensions directory
* @brief 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.
*
* @param directory Path to the extensions directory. If the path is empty, extensions path will be set to the current working directory.
* @param error Pointer to an error object that will be populated if an error occurs during extensions directory setting
*/
OB_EXPORT void ob_set_extensions_directory(const char *directory, ob_error **error);
// The following interfaces are deprecated and are retained here for compatibility purposes.
#define ob_enable_multi_device_sync ob_enable_device_clock_sync
#define ob_set_logger_callback ob_set_logger_to_callback
#ifdef __cplusplus
}
#endif