The main prober that probes and manages found but not opened HMD devices that are connected to the system. More...

#include <xrt/xrt_prober.h>

Inheritance diagram for xrt_prober:

Collaboration diagram for xrt_prober:

[legend]

Public Member Functions
bool	u_prober_match_string (struct xrt_prober xp, struct xrt_prober_device dev, enum xrt_prober_string type, const char *to_match)
	Helper to match various strings of a xrt_prober_device to. More...

static xrt_result_t	xrt_prober_probe (struct xrt_prober *xp)
	Enumerate all connected devices, whether or not we have an associated driver. More...

static xrt_result_t	xrt_prober_lock_list (struct xrt_prober xp, struct xrt_prober_device *out_devices, size_t out_device_count)
	Locks the prober list of probed devices and returns it. More...

static xrt_result_t	xrt_prober_unlock_list (struct xrt_prober xp, struct xrt_prober_device **devices)
	Unlocks the list, allowing for xrt_prober::probe to be called. More...

static int	xrt_prober_dump (struct xrt_prober *xp, bool use_stdout)
	Dump a listing of all devices found on the system to logging system or platform dependent output (stdout). More...

static xrt_result_t	xrt_prober_create_system (struct xrt_prober xp, struct xrt_session_event_sink broadcast, struct xrt_system_devices out_xsysd, struct xrt_space_overseer out_xso)
	Create system devices. More...

static int	xrt_prober_select (struct xrt_prober xp, struct xrt_device *xdevs, size_t xdev_capacity)
	Iterate through drivers (by ID and auto-probers) checking to see if they can handle any connected devices from the last xrt_prober::probe call, opening those devices to create instances of xrt_device implementations. More...

static int	xrt_prober_open_hid_interface (struct xrt_prober xp, struct xrt_prober_device xpdev, int iface, struct os_hid_device **out_hid_dev)
	Open a HID (Human Interface Device) interface using native HID support. More...

static int	xrt_prober_get_string_descriptor (struct xrt_prober xp, struct xrt_prober_device xpdev, enum xrt_prober_string which_string, unsigned char *out_buffer, size_t max_length)
	Returns a string property on the device of the given type `which_string` in `out_buffer`. More...

static bool	xrt_prober_can_open (struct xrt_prober xp, struct xrt_prober_device xpdev)
	Determine whether a prober device can be opened. More...

static int	xrt_prober_open_video_device (struct xrt_prober xp, struct xrt_prober_device xpdev, struct xrt_frame_context xfctx, struct xrt_fs *out_xfs)
	Opens the selected video device and returns a xrt_fs, does not start it. More...

static int	xrt_prober_list_video_devices (struct xrt_prober xp, xrt_prober_list_video_func_t cb, void ptr)
	Iterate through available video devices, calling your callback `cb` with your userdata `ptr`. More...

static int	xrt_prober_get_builders (struct xrt_prober xp, size_t out_builder_count, struct xrt_builder **out_builders, size_t out_entry_count, struct xrt_prober_entry *out_entries, struct xrt_auto_prober *out_auto_probers)
	Retrieve the raw xrt_builder, xrt_prober_entry and xrt_auto_prober arrays. More...

static void	xrt_prober_destroy (struct xrt_prober **xp_ptr)
	Destroy the prober and set the pointer to null. More...

int	xrt_prober_create_with_lists (struct xrt_prober *out_xp, struct xrt_prober_entry_lists list)
	Create a prober with a list of known devices and autoprobers. More...

Data Fields
struct xrt_tracking_factory *	tracking
	Factory for producing tracked objects. More...

xrt_result_t(*	probe )(struct xrt_prober *xp)
	Enumerate all connected devices, whether or not we have an associated driver. More...

xrt_result_t(*	lock_list )(struct xrt_prober xp, struct xrt_prober_device *out_devices, size_t out_device_count)
	Locks the prober list of probed devices and returns it. More...

xrt_result_t(*	unlock_list )(struct xrt_prober xp, struct xrt_prober_device **devices)
	Unlocks the list, allowing for xrt_prober::probe to be called. More...

int(*	dump )(struct xrt_prober *xp, bool use_stdout)
	Dump a listing of all devices found on the system to logging system or platform dependent output (stdout). More...

xrt_result_t(*	create_system )(struct xrt_prober xp, struct xrt_session_event_sink broadcast, struct xrt_system_devices out_xsysd, struct xrt_space_overseer out_xso)
	Create system devices. More...

int(*	select )(struct xrt_prober xp, struct xrt_device *xdevs, size_t xdev_capacity)
	Iterate through drivers (by ID and auto-probers) checking to see if they can handle any connected devices from the last xrt_prober::probe call, opening those devices to create instances of xrt_device implementations. More...

int(*	open_hid_interface )(struct xrt_prober xp, struct xrt_prober_device xpdev, int iface, struct os_hid_device **out_hid_dev)
	Open a HID (Human Interface Device) interface using native HID support. More...

int(*	open_video_device )(struct xrt_prober xp, struct xrt_prober_device xpdev, struct xrt_frame_context xfctx, struct xrt_fs *out_xfs)
	Opens the selected video device and returns a xrt_fs, does not start it. More...

int(*	list_video_devices )(struct xrt_prober xp, xrt_prober_list_video_func_t cb, void ptr)
	Iterate through available video devices, calling your callback `cb` with your userdata `ptr`. More...

int(*	get_builders )(struct xrt_prober xp, size_t out_builder_count, struct xrt_builder **out_builders, size_t out_entry_count, struct xrt_prober_entry *out_entries, struct xrt_auto_prober *out_auto_probers)
	Retrieve the raw xrt_builder, xrt_prober_entry and xrt_auto_prober arrays. More...

int(*	get_string_descriptor )(struct xrt_prober xp, struct xrt_prober_device xpdev, enum xrt_prober_string which_string, unsigned char *out_buffer, size_t max_length)
	Returns a string property on the device of the given type `which_string` in `out_buffer`. More...

bool(*	can_open )(struct xrt_prober xp, struct xrt_prober_device xpdev)
	Determine whether a prober device can be opened. More...

void(*	destroy )(struct xrt_prober **xp_ptr)
	Destroy the prober and set the pointer to null. More...

Detailed Description

The main prober that probes and manages found but not opened HMD devices that are connected to the system.

Member Function Documentation

◆ u_prober_match_string()

bool u_prober_match_string	(	struct xrt_prober *	xp,
		struct xrt_prober_device *	dev,
		enum xrt_prober_string	type,
		const char *	to_match
	)

Helper to match various strings of a xrt_prober_device to.

◆ xrt_prober_can_open()

static bool xrt_prober_can_open	(	struct xrt_prober *	xp,
		struct xrt_prober_device *	xpdev
	)

inline

Determine whether a prober device can be opened.

Parameters

xp	Pointer to self
xpdev	prober device

Returns: true if xpdev can be opened.

Helper function for xrt_prober::can_open.

References can_open.

◆ xrt_prober_create_system()

static xrt_result_t xrt_prober_create_system	(	struct xrt_prober *	xp,
		struct xrt_session_event_sink *	broadcast,
		struct xrt_system_devices **	out_xsysd,
		struct xrt_space_overseer **	out_xso
	)

inline

Create system devices.

Parameters

[in]	xp	Prober self parameter.
[in]	broadcast	Event sink that broadcasts events to all sessions.
[out]	out_xsysd	Return of system devices, the pointed pointer must be NULL.
[out]	out_xso	Return of the xrt_space_overseer, the pointed pointer must be NULL.

Note: Code consuming this interface should use xrt_prober_create_system()

Helper function for xrt_prober::create_system.

References create_system.

Referenced by u_system_devices_create_from_prober().

◆ xrt_prober_create_with_lists()

int xrt_prober_create_with_lists	(	struct xrt_prober **	out_xp,
		struct xrt_prober_entry_lists *	list
	)

Create a prober with a list of known devices and autoprobers.

Typically used by xrt_instance_create implementations to create the prober, often with a shared list called target_list.

Parameters

[out]	out_xp	Pointer to xrt_prober pointer, will be populated with created xrt_prober instance.
[in]	list	Prober entry list

References U_TYPED_CALLOC.

◆ xrt_prober_destroy()

static void xrt_prober_destroy ( struct xrt_prober ** xp_ptr )

inline

Destroy the prober and set the pointer to null.

Code consuming this interface should use xrt_prober_destroy().

Parameters

xp_ptr pointer to self-pointer

Helper for calling through the function pointer: does a null check and sets xp_ptr to null if freed.

References destroy.

◆ xrt_prober_dump()

static int xrt_prober_dump	(	struct xrt_prober *	xp,
		bool	use_stdout
	)

inline

Dump a listing of all devices found on the system to logging system or platform dependent output (stdout).

Parameters

[in]	xp	Prober self parameter.
[in]	use_stdout	If true uses stdout instead of logging code.

Note: Code consuming this interface should use xrt_prober_dump()

Helper function for xrt_prober::dump.

References dump.

◆ xrt_prober_get_builders()

static int xrt_prober_get_builders	(	struct xrt_prober *	xp,
		size_t *	out_builder_count,
		struct xrt_builder ***	out_builders,
		size_t *	out_entry_count,
		struct xrt_prober_entry ***	out_entries,
		struct xrt_auto_prober ***	out_auto_probers
	)

inline

Retrieve the raw xrt_builder, xrt_prober_entry and xrt_auto_prober arrays.

Parameters

	xp	Pointer to self
[out]	out_builder_count	The size of `out_builders`
[out]	out_builders	An array of builders.
[out]	out_entry_count	The size of `out_entries`
[out]	out_entries	An array of prober entries
[out]	out_auto_probers	An array of up to XRT_MAX_AUTO_PROBERS auto-probers

Returns: 0 on success, <0 on error.

Helper function for xrt_prober::get_builders.

References get_builders.

◆ xrt_prober_get_string_descriptor()

static int xrt_prober_get_string_descriptor	(	struct xrt_prober *	xp,
		struct xrt_prober_device *	xpdev,
		enum xrt_prober_string	which_string,
		unsigned char *	out_buffer,
		size_t	max_length
	)

inline

Returns a string property on the device of the given type which_string in out_buffer.

Parameters

[in]	xp	Prober.
[in]	xpdev	Device to get string property from.
[in]	which_string	Which string property to query.
[in,out]	out_buffer	Target buffer.
[in]	max_length	Max length of the target buffer.

Returns: The length of the string, or negative on error.

Helper function for xrt_prober::get_string_descriptor.

References get_string_descriptor.

Referenced by hdk_found(), and pssense_found().

◆ xrt_prober_list_video_devices()

static int xrt_prober_list_video_devices	(	struct xrt_prober *	xp,
		xrt_prober_list_video_func_t	cb,
		void *	ptr
	)

inline

Iterate through available video devices, calling your callback cb with your userdata ptr.

Parameters

xp	Pointer to self
cb	Callback function
ptr	Opaque pointer for your userdata, passed through to the callback.

See also: xrt_prober_list_video_func_t

Returns: 0 on success, <0 on error.

Helper function for xrt_prober::list_video_devices.

References list_video_devices.

◆ xrt_prober_lock_list()

static xrt_result_t xrt_prober_lock_list	(	struct xrt_prober *	xp,
		struct xrt_prober_device ***	out_devices,
		size_t *	out_device_count
	)

inline

Locks the prober list of probed devices and returns it.

While locked, calling xrt_prober::probe is forbidden. Not thread safe.

See xrt_prober::probe for more detailed expected usage.

See also: xrt_prober::probe, xrt_prober::unlock_list

Helper function for xrt_prober::lock_list.

References lock_list.

Referenced by vive_builder_estimate().

◆ xrt_prober_open_hid_interface()

static int xrt_prober_open_hid_interface	(	struct xrt_prober *	xp,
		struct xrt_prober_device *	xpdev,
		int	iface,
		struct os_hid_device **	out_hid_dev
	)

inline

Open a HID (Human Interface Device) interface using native HID support.

Parameters

	xp	Pointer to self
	xpdev	prober device
	iface	HID interface number
[out]	out_hid_dev	instance of os_hid_device for the given interface

Returns: 0 on success, <0 on error.

Helper function for xrt_prober::open_hid_interface.

References open_hid_interface.

Referenced by psmv_device_create(), and pssense_found().

◆ xrt_prober_open_video_device()

static int xrt_prober_open_video_device	(	struct xrt_prober *	xp,
		struct xrt_prober_device *	xpdev,
		struct xrt_frame_context *	xfctx,
		struct xrt_fs **	out_xfs
	)

inline

Opens the selected video device and returns a xrt_fs, does not start it.

Helper function for xrt_prober::xrt_prober_open_video_device.

References open_video_device.

Referenced by p_factory_ensure_slam_frameserver().

◆ xrt_prober_probe()

static xrt_result_t xrt_prober_probe ( struct xrt_prober * xp )

inline

Enumerate all connected devices, whether or not we have an associated driver.

Cannot be called with the device list is locked xrt_prober::lock_list and xrt_prober::unlock_list.

This function along with lock/unlock allows a xrt_builder to re-probe the devices after having opened another device. A bit more detailed: It can get a list of devices, search it, open the enabling one, release the list, do a probe, get the list again and re-scan to detect any additional devices that may show up once the first device has been been started.

See also: xrt_prober::lock_list, xrt_prober::unlock_list

Helper function for xrt_prober::probe.

References probe.

Referenced by u_system_devices_create_from_prober().

◆ xrt_prober_select()

static int xrt_prober_select	(	struct xrt_prober *	xp,
		struct xrt_device **	xdevs,
		size_t	xdev_capacity
	)

inline

Iterate through drivers (by ID and auto-probers) checking to see if they can handle any connected devices from the last xrt_prober::probe call, opening those devices to create instances of xrt_device implementations.

If no HMD (not even a simulated HMD) is found, then no devices will be returned (all xdevs will be NULL). Otherwise, xdevs will be populated with the HMD in xdevs[0], and any subsequent non-NULL values referring to additional non-HMD devices.

Parameters

	xp	Pointer to self
[in,out]	xdevs	Pointer to xrt_device array. Array elements will be populated.
[in]	xdev_capacity	The capacity of the `xdevs` array.

Returns: 0 on success (including "no HMD found"), <0 on error.

Returned devices have their ownership transferred to the caller: all should be cleaned up with xrt_device_destroy().

Note: Code consuming this interface should use xrt_prober_select(). Typically used through an xrt_instance and the xrt_instance_select() method which usually calls xrt_prober_probe() and xrt_prober_select().

Helper function for xrt_prober::select.

References select.

◆ xrt_prober_unlock_list()

static xrt_result_t xrt_prober_unlock_list	(	struct xrt_prober *	xp,
		struct xrt_prober_device ***	devices
	)

inline

Unlocks the list, allowing for xrt_prober::probe to be called.

Takes a pointer to the list pointer and clears it. Not thread safe. See xrt_prober::probe for more detailed expected usage.

See also: xrt_prober::probe, xrt_prober::lock_list

Helper function for xrt_prober::unlock_list.

References unlock_list.

Field Documentation

◆ can_open

bool(* xrt_prober::can_open) (struct xrt_prober *xp, struct xrt_prober_device *xpdev)

Determine whether a prober device can be opened.

Parameters

xp	Pointer to self
xpdev	prober device

Returns: true if xpdev can be opened.

Referenced by xrt_prober_can_open().

◆ create_system

xrt_result_t(* xrt_prober::create_system) (struct xrt_prober *xp, struct xrt_session_event_sink *broadcast, struct xrt_system_devices **out_xsysd, struct xrt_space_overseer **out_xso)

Create system devices.

Parameters

[in]	xp	Prober self parameter.
[in]	broadcast	Event sink that broadcasts events to all sessions.
[out]	out_xsysd	Return of system devices, the pointed pointer must be NULL.
[out]	out_xso	Return of the xrt_space_overseer, the pointed pointer must be NULL.

Note: Code consuming this interface should use xrt_prober_create_system()

Referenced by xrt_prober_create_system().

◆ destroy

void(* xrt_prober::destroy) (struct xrt_prober **xp_ptr)

Destroy the prober and set the pointer to null.

Code consuming this interface should use xrt_prober_destroy().

Parameters

xp_ptr pointer to self-pointer

Referenced by xrt_prober_destroy().

◆ dump

int(* xrt_prober::dump) (struct xrt_prober *xp, bool use_stdout)

Dump a listing of all devices found on the system to logging system or platform dependent output (stdout).

Parameters

[in]	xp	Prober self parameter.
[in]	use_stdout	If true uses stdout instead of logging code.

Note: Code consuming this interface should use xrt_prober_dump()

Referenced by xrt_prober_dump().

◆ get_builders

int(* xrt_prober::get_builders) (struct xrt_prober *xp, size_t *out_builder_count, struct xrt_builder ***out_builders, size_t *out_entry_count, struct xrt_prober_entry ***out_entries, struct xrt_auto_prober ***out_auto_probers)

Retrieve the raw xrt_builder, xrt_prober_entry and xrt_auto_prober arrays.

Parameters

	xp	Pointer to self
[out]	out_builder_count	The size of `out_builders`
[out]	out_builders	An array of builders.
[out]	out_entry_count	The size of `out_entries`
[out]	out_entries	An array of prober entries
[out]	out_auto_probers	An array of up to XRT_MAX_AUTO_PROBERS auto-probers

Returns: 0 on success, <0 on error.

Referenced by xrt_prober_get_builders().

◆ get_string_descriptor

int(* xrt_prober::get_string_descriptor) (struct xrt_prober *xp, struct xrt_prober_device *xpdev, enum xrt_prober_string which_string, unsigned char *out_buffer, size_t max_length)

Returns a string property on the device of the given type which_string in out_buffer.

Parameters

[in]	xp	Prober.
[in]	xpdev	Device to get string property from.
[in]	which_string	Which string property to query.
[in,out]	out_buffer	Target buffer.
[in]	max_length	Max length of the target buffer.

Returns: The length of the string, or negative on error.

Referenced by xrt_prober_get_string_descriptor().

◆ list_video_devices

int(* xrt_prober::list_video_devices) (struct xrt_prober *xp, xrt_prober_list_video_func_t cb, void *ptr)

Iterate through available video devices, calling your callback cb with your userdata ptr.

Parameters

xp	Pointer to self
cb	Callback function
ptr	Opaque pointer for your userdata, passed through to the callback.

See also: xrt_prober_list_video_func_t

Returns: 0 on success, <0 on error.

Referenced by xrt_prober_list_video_devices().

◆ lock_list

xrt_result_t(* xrt_prober::lock_list) (struct xrt_prober *xp, struct xrt_prober_device ***out_devices, size_t *out_device_count)

Locks the prober list of probed devices and returns it.

While locked, calling xrt_prober::probe is forbidden. Not thread safe.

See xrt_prober::probe for more detailed expected usage.

See also: xrt_prober::probe, xrt_prober::unlock_list

Referenced by xrt_prober_lock_list().

◆ open_hid_interface

int(* xrt_prober::open_hid_interface) (struct xrt_prober *xp, struct xrt_prober_device *xpdev, int iface, struct os_hid_device **out_hid_dev)

Open a HID (Human Interface Device) interface using native HID support.

Parameters

	xp	Pointer to self
	xpdev	prober device
	iface	HID interface number
[out]	out_hid_dev	instance of os_hid_device for the given interface

Returns: 0 on success, <0 on error.

Referenced by hydra_found(), and xrt_prober_open_hid_interface().

◆ open_video_device

int(* xrt_prober::open_video_device) (struct xrt_prober *xp, struct xrt_prober_device *xpdev, struct xrt_frame_context *xfctx, struct xrt_fs **out_xfs)

Opens the selected video device and returns a xrt_fs, does not start it.

Referenced by xrt_prober_open_video_device().

◆ probe

xrt_result_t(* xrt_prober::probe) (struct xrt_prober *xp)

Enumerate all connected devices, whether or not we have an associated driver.

Cannot be called with the device list is locked xrt_prober::lock_list and xrt_prober::unlock_list.

This function along with lock/unlock allows a xrt_builder to re-probe the devices after having opened another device. A bit more detailed: It can get a list of devices, search it, open the enabling one, release the list, do a probe, get the list again and re-scan to detect any additional devices that may show up once the first device has been been started.

See also: xrt_prober::lock_list, xrt_prober::unlock_list

Referenced by xrt_prober_probe().

◆ select

int(* xrt_prober::select) (struct xrt_prober *xp, struct xrt_device **xdevs, size_t xdev_capacity)

Iterate through drivers (by ID and auto-probers) checking to see if they can handle any connected devices from the last xrt_prober::probe call, opening those devices to create instances of xrt_device implementations.

If no HMD (not even a simulated HMD) is found, then no devices will be returned (all xdevs will be NULL). Otherwise, xdevs will be populated with the HMD in xdevs[0], and any subsequent non-NULL values referring to additional non-HMD devices.

Parameters

	xp	Pointer to self
[in,out]	xdevs	Pointer to xrt_device array. Array elements will be populated.
[in]	xdev_capacity	The capacity of the `xdevs` array.

Returns: 0 on success (including "no HMD found"), <0 on error.

Returned devices have their ownership transferred to the caller: all should be cleaned up with xrt_device_destroy().

Note: Code consuming this interface should use xrt_prober_select(). Typically used through an xrt_instance and the xrt_instance_select() method which usually calls xrt_prober_probe() and xrt_prober_select().

Referenced by xrt_prober_select().

◆ tracking

struct xrt_tracking_factory* xrt_prober::tracking

Factory for producing tracked objects.

◆ unlock_list

xrt_result_t(* xrt_prober::unlock_list) (struct xrt_prober *xp, struct xrt_prober_device ***devices)

Unlocks the list, allowing for xrt_prober::probe to be called.

Takes a pointer to the list pointer and clears it. Not thread safe. See xrt_prober::probe for more detailed expected usage.

See also: xrt_prober::probe, xrt_prober::lock_list

Referenced by xrt_prober_unlock_list().

The documentation for this struct was generated from the following files:

xrt/xrt_prober.h
auxiliary/util/u_prober.h

Public Member Functions

Data Fields

Detailed Description

Member Function Documentation

◆ u_prober_match_string()

◆ xrt_prober_can_open()

◆ xrt_prober_create_system()

◆ xrt_prober_create_with_lists()

◆ xrt_prober_destroy()

◆ xrt_prober_dump()

◆ xrt_prober_get_builders()

◆ xrt_prober_get_string_descriptor()

◆ xrt_prober_list_video_devices()

◆ xrt_prober_lock_list()

◆ xrt_prober_open_hid_interface()

◆ xrt_prober_open_video_device()

◆ xrt_prober_probe()

◆ xrt_prober_select()

◆ xrt_prober_unlock_list()

Field Documentation

◆ can_open

◆ create_system

◆ destroy

◆ dump

◆ get_builders

◆ get_string_descriptor

◆ list_video_devices

◆ lock_list

◆ open_hid_interface

◆ open_video_device

◆ probe

◆ select

◆ tracking

◆ unlock_list