ob2device.h 文件参考

#include "ob2types.h"

浏览源代码.

宏定义
#define	ob2_device_set_installed_callback   ob2_context_set_device_installed_callback
#define	ob2_device_set_removed_callback   ob2_context_set_device_removed_callback
#define	ob2_device_get_installed_count   ob2_context_get_installed_device_count
#define	ob2_device_get_installation_info   ob2_context_get_installed_device_info
#define	ob2_device_open   ob2_context_open_device
#define	ob2_device_open_by_serial_number   ob2_context_open_device_by_serial_number
#define	ob2_device_open_by_url   ob2_context_open_device_by_url
#define	ob2_net_device_open   ob2_context_open_net_device

函数
void	ob2_context_set_device_installed_callback (ob2_context_t context_handle, ob2_device_info_cb_t device_installed_cb, void *user_data, ob2_status_t *status)
	设置设备安装（上线）回调 更多...
void	ob2_context_set_device_removed_callback (ob2_context_t context_handle, ob2_device_info_cb_t device_removed_cb, void *user_data, ob2_status_t *status)
	设置设备移除（掉线）回调 更多...
uint32_t	ob2_context_get_installed_device_count (ob2_context_t context_handle, ob2_status_t *status)
	获取已安装（上线）的设备数量 更多...
ob2_device_installation_info_t	ob2_context_get_installed_device_info (ob2_context_t context_handle, uint32_t index, ob2_status_t *status)
	通过索引号获取安装设备信息 更多...
ob2_device_t	ob2_context_open_device (ob2_context_t context_handle, uint32_t index, ob2_status_t *status)
	通过索引号打开设备 更多...
ob2_device_t	ob2_context_open_device_by_serial_number (ob2_context_t context_handle, const char *serial_number, ob2_status_t *status)
	通过序列号打开设备 更多...
ob2_device_t	ob2_context_open_device_by_url (ob2_context_t context_handle, const char *url, ob2_status_t *status)
	通过 URL 打开设备 更多...
ob2_device_t	ob2_context_open_net_device (ob2_context_t context_handle, const char *address, uint32_t port, ob2_status_t *status)
	打开网络设备 更多...
void	ob2_device_close (ob2_device_t device_handle, ob2_status_t *status)
	关闭设备 更多...
ob2_device_info_t	ob2_device_get_info (ob2_device_t device_handle, ob2_status_t *status)
	获取设备信息 更多...
void	ob2_device_update_firmware (ob2_device_t device_handle, const char *firmware_file_path, ob2_firmware_update_state_cb_t callback, void *user_data, ob2_enable_ctrl_t enable_async_mode, ob2_status_t *status)
	升级设备固件 更多...
void	ob2_device_reboot (ob2_device_t device_handle, ob2_status_t *status)
	设备重启 更多...
void	ob2_device_sync_clock_with_host (ob2_device_t device_handle, ob2_status_t *status)
	同步设备时钟 更多...

宏定义说明

ob2_device_set_installed_callback

#define ob2_device_set_installed_callback   ob2_context_set_device_installed_callback

在文件 ob2device.h 第 34 行定义.

ob2_device_set_removed_callback

#define ob2_device_set_removed_callback   ob2_context_set_device_removed_callback

在文件 ob2device.h 第 65 行定义.

ob2_device_get_installed_count

#define ob2_device_get_installed_count   ob2_context_get_installed_device_count

在文件 ob2device.h 第 87 行定义.

ob2_device_get_installation_info

#define ob2_device_get_installation_info   ob2_context_get_installed_device_info

在文件 ob2device.h 第 120 行定义.

ob2_device_open

#define ob2_device_open   ob2_context_open_device

在文件 ob2device.h 第 161 行定义.

ob2_device_open_by_serial_number

#define ob2_device_open_by_serial_number   ob2_context_open_device_by_serial_number

在文件 ob2device.h 第 194 行定义.

ob2_device_open_by_url

#define ob2_device_open_by_url   ob2_context_open_device_by_url

在文件 ob2device.h 第 231 行定义.

ob2_net_device_open

#define ob2_net_device_open   ob2_context_open_net_device

在文件 ob2device.h 第 268 行定义.

函数说明

ob2_context_set_device_installed_callback()

void ob2_context_set_device_installed_callback	(	ob2_context_t	context_handle,
		ob2_device_info_cb_t	device_installed_cb,
		void *	user_data,
		ob2_status_t *	status
	)

设置设备安装（上线）回调

设置回调后，当有新设备接入并完成驱动加载后，会调用设置的回调函数，此时用户可以通过回调的信息打开设备

参数

[in]	context_handle	context 句柄
[in]	device_installed_cb	设备安装回调函数
[in]	user_data	用户自定义数据，会在调用 device_installed_cb 时原样返回
[out]	status	返回函数调用状态

被这些函数引用 ob2::context::set_device_installed_callback().

ob2_context_set_device_removed_callback()

void ob2_context_set_device_removed_callback	(	ob2_context_t	context_handle,
		ob2_device_info_cb_t	device_removed_cb,
		void *	user_data,
		ob2_status_t *	status
	)

设置设备移除（掉线）回调

设置回调后，当有设备出现掉线情况，会立即调用设置的回调函数，回调函数会传会掉线设备的信息。

注意

出现设备掉线后，如果掉线的设备是已打开的设备，应立即停止对该设备的访问，并关闭设备。

参数

[in]	context_handle	context 句柄
[in]	device_removed_cb	设备移除回调函数
[in]	user_data	用户自定义数据，会在调用 device_removed_cb 时原样返回
[out]	status	返回函数调用状态

被这些函数引用 ob2::context::set_device_removed_callback().

ob2_context_get_installed_device_count()

uint32_t ob2_context_get_installed_device_count	(	ob2_context_t	context_handle,
		ob2_status_t *	status
	)

获取已安装（上线）的设备数量

参数

[in]	context_handle	context 句柄
[out]	status	返回函数调用状态

返回

uint32_t 返回当前已安装的设备数量

被这些函数引用 ob2::context::get_installed_device_info_list().

ob2_context_get_installed_device_info()

ob2_device_installation_info_t ob2_context_get_installed_device_info	(	ob2_context_t	context_handle,
		uint32_t	index,
		ob2_status_t *	status
	)

通过索引号获取安装设备信息

注意

索引号 @index 范围为 [0, count-1] (count 通过 ob2_context_get_installed_device_count 返回），传入范围外的数值 将通过 @status 返回 OB2_STATUS_LOGIC_ERROR

安装设备信息仅有一些基础信息（PID、SN、URL 等），详细的设备信息需要打开设备后通过 ob2_device_get_info 接口获取

参数

[in]	context_handle	context 句柄
[in]	index	设备索引号
[out]	status	返回函数调用状态

返回

ob2_device_installation_info_t 返回当前已安装的设备信息

被这些函数引用 ob2::context::get_installed_device_info_list().

ob2_context_open_device()

ob2_device_t ob2_context_open_device	(	ob2_context_t	context_handle,
		uint32_t	index,
		ob2_status_t *	status
	)

通过索引号打开设备

设备代表着与物理设备的通信连接，可通过设备访问和控制物理设备。

注意

索引号 @index 范围为 [0, count-1] (count 通过 ob2_context_get_installed_device_count 返回），传入范围外的数值 将通过 @status 返回 OB2_STATUS_LOGIC_ERROR 。

通过索引号打开设备是不安全的，新设备安装或设备掉线都可能会导致索引号绑定的设备发生改变，甚至可能会导致 @index 超出范围而报错。 推荐使用 ob2_context_open_device_by_serial_number 和 ob2_context_open_device_by_url 接口。

成功打开设备后，如果不需要再对设备进行访问，需要调用 ob2_device_close 关闭并释放设备句柄，否则会导致内存泄漏。

参数

[in]	context_handle	context 句柄
[in]	index	设备索引号。可通过传入 OB2_DEFAULT_DEVICE 打开默认设备（已安装的设备中第一个设备）
[out]	status	返回函数调用状态

返回

ob2_device_t 返回已打开的设备句柄

被这些函数引用 ob2::context::open_device().

ob2_context_open_device_by_serial_number()

ob2_device_t ob2_context_open_device_by_serial_number	(	ob2_context_t	context_handle,
		const char *	serial_number,
		ob2_status_t *	status
	)

通过序列号打开设备

注意

如果已安装的设备中未找到与 @serial_number 相匹配的设备将会通过 @status 返回 OB2_STATUS_RUNTIME_ERROR ，同时返回设备句柄为 NULL。

成功打开设备后，如果不需要再对设备进行访问，需要调用 ob2_device_close 关闭并释放设备句柄，否则会导致内存泄漏。

参数

[in]	context_handle	context 句柄
[in]	serial_number	设备序列号，可通过设备安装信息获取或通过设备机身粘贴的序列号获取
[out]	status	返回函数调用状态

返回

ob2_device_t 返回已打开的设备句柄

被这些函数引用 ob2::context::open_device_by_serial_number().

ob2_context_open_device_by_url()

ob2_device_t ob2_context_open_device_by_url	(	ob2_context_t	context_handle,
		const char *	url,
		ob2_status_t *	status
	)

通过 URL 打开设备

注意

URL 是设备接入主机后由操作系统分配的路径，是再当前主机上已安装的设备的唯一标识。但是同一台设备在不同主机甚至同一台 主机不同时间和不同接口接入，URL 都可能会不一样。

如果已安装的设备中未找到与 @url 相匹配的设备将会通过 @status 返回 OB2_STATUS_RUNTIME_ERROR ，同时返回设备句柄为 NULL。

成功打开设备后，如果不需要再对设备进行访问，需要调用 ob2_device_close 关闭并释放设备句柄，否则会导致内存泄漏。

参数

[in]	context_handle	context 句柄
[in]	url	设备安装路径
[out]	status	返回函数调用状态

返回

ob2_device_t 返回已打开的设备句柄

被这些函数引用 ob2::context::open_device_by_url().

ob2_context_open_net_device()

ob2_device_t ob2_context_open_net_device	(	ob2_context_t	context_handle,
		const char *	address,
		uint32_t	port,
		ob2_status_t *	status
	)

打开网络设备

注意

网络设备不在已安装设备之列，不能通过已安装设备信息确定网络设备是否在线，所以需要用户自行确保设备已上线。

如果传入的 @address 和 @port 未能连接到设备，将会通过 @status 返回 OB2_STATUS_RUNTIME_ERROR ，同时返回设备句柄为 NULL。

成功打开设备后，如果不需要再对设备进行访问，需要调用 ob2_device_close 关闭并释放设备句柄，否则会导致内存泄漏。

参数

[in]	context_handle	context 句柄
[in]	address	网络设备地址，IPv4 协议 IP 地址字符串，格式如："192.168.1.10"
[in]	port	网络设备端口，设备默认端口为 8090
[out]	status	返回函数调用状态

返回

ob2_device_t 返回已打开的设备句柄

被这些函数引用 ob2::context::open_net_device().

ob2_device_close()

void ob2_device_close	(	ob2_device_t	device_handle,
		ob2_status_t *	status
	)

关闭设备

参数

[in]	device_handle	需要关闭的设备句柄
[out]	status	返回函数调用状态

被这些函数引用 ob2::device::~device().

ob2_device_get_info()

ob2_device_info_t ob2_device_get_info	(	ob2_device_t	device_handle,
		ob2_status_t *	status
	)

获取设备信息

相对于设备安装信息，本接口能够通过已打开的设备获取到更详细的信息（固件版本号、设备名称、设备技术类型等）

参数

[in]	device_handle	设备句柄
[out]	status	返回函数调用状态

返回

ob2_device_info_t 返回设备信息

被这些函数引用 ob2::device::get_info().

ob2_device_update_firmware()

void ob2_device_update_firmware	(	ob2_device_t	device_handle,
		const char *	firmware_file_path,
		ob2_firmware_update_state_cb_t	callback,
		void *	user_data,
		ob2_enable_ctrl_t	enable_async_mode,
		ob2_status_t *	status
	)

升级设备固件

注意

固件升级完后需要重启设备（部分设备会自动重启）

参数

[in]	device_handle	设备句柄
[in]	firmware_file_path	设备固件地址
[in]	callback	升级状态回调
[in]	user_data	用户自定义数据，会在调用回调函数时原样返回
[in]	enable_async_mode	异步模式使能（true：本接口调用会立即返回，SDK 内部会新开线程继续完成升级任务； false：本接口会阻塞式执行，直到升级任务完成或失败退出）
[out]	status	返回函数调用状态

被这些函数引用 ob2::device::update_firmware().

ob2_device_reboot()

void ob2_device_reboot	(	ob2_device_t	device_handle,
		ob2_status_t *	status
	)

设备重启

触发设备重启，会导致设备异常然后重新安装

注意

调用本接口后，设备会被移除，所以不要再对原设备句柄进行访问，而是立即关闭设备。 待设备重启完成后重新安装成功，再重新打开设备获取新的设备句柄。

参数

[in]	device_handle	设备句柄
[out]	status	返回函数调用状态

被这些函数引用 ob2::device::reboot().

ob2_device_sync_clock_with_host()

void ob2_device_sync_clock_with_host	(	ob2_device_t	device_handle,
		ob2_status_t *	status
	)

同步设备时钟

设备启动后，设备时钟会从零开始计时。通过本接口，可实现向设备授时，使设备时钟与主机时钟同步

注意

由于设备时钟精度问题，时钟同步后经过一定时间主机与设备的时钟同步误差可能会加大，所以建议依据应用场景， 可定时调用本接口同步设备时钟。

参数

device_handle	设备句柄
status	返回函数调用状态

被这些函数引用 ob2::device::sync_clock_with_host().