Player service discovery library. More...

Detailed Description

Player service discovery library.

This library provides service discovery capabilities for Player devices. This library is currently in an alpha state, and is not ready for regular use.

#define	PLAYER_SD_SERVICENAME "_player31._tcp"
	A device, represented by its name and address.

#define	PLAYER_SD_DEVICE_TXTNAME "device"
	A device, represented by its name and address.

#define	PLAYER_SD_NAME_MAXLEN 256
	A device, represented by its name and address.

#define	PLAYER_SD_TXT_MAXLEN 256
	A device, represented by its name and address.

typedef struct player_sd_dev	player_sd_dev_t
	A device, represented by its name and address.

typedef struct player_sd	player_sd_t
	Service discovery object.

typedef void(*	player_sd_browse_callback_fn_t) (player_sd_t sd, player_sd_dev_t dev)
	Prototype for a callback function that can be invoked when devices are added or removed. More...

player_sd_t *	player_sd_init (void)
	Initialize service discovery, passing back a pointer that will be passed into all future calls. More...

void	player_sd_fini (player_sd_t *sd)
	Finalize service discovery, freeing associated resources.

void	player_sd_lock (player_sd_t *sd)
	Lock access to playersd structures, such as the local device cache.

void	player_sd_unlock (player_sd_t *sd)
	Unlock access to playersd structures, such as the local device cache.

int	player_sd_register (player_sd_t sd, const char name, player_devaddr_t addr)
	Register the named device. More...

int	player_sd_unregister (player_sd_t sd, const char name)
	Unregister (terminate) the named device. More...

int	player_sd_browse (player_sd_t *sd, double timeout, int keepalive, player_sd_browse_callback_fn_t cb)
	Browse for player devices. More...

int	player_sd_update (player_sd_t *sd, double timeout)
	Check for new device updates, waiting for timeout s. More...

int	player_sd_browse_stop (player_sd_t *sd)
	Stop browsing. Returns 0 on success, non-zero on error.

player_sd_dev_t *	player_sd_get_device (player_sd_t sd, const char name)
	Look up a device by name. More...

int	player_sd_find_devices (player_sd_t sd, player_sd_dev_t result, size_t result_len, const char name, const char hostname, int robot, int interf, int index)
	Find a device in the local cache that matches the given criteria. More...

player_sd_dev_t *	_player_sd_add_device (player_sd_t sd, const char name)
	Add a device to the local cache. More...

void	player_sd_printcache (player_sd_t *sd)
	Print the contents of the local device cache to the console.

Typedef Documentation

◆ player_sd_browse_callback_fn_t

typedef void(* player_sd_browse_callback_fn_t) (player_sd_t *sd, player_sd_dev_t *dev)

Prototype for a callback function that can be invoked when devices are added or removed.

Function Documentation

◆ _player_sd_add_device()

player_sd_dev_t* _player_sd_add_device	(	player_sd_t *	sd,
		const char *	name
	)

Add a device to the local cache.

The user should not call this function. It will be invoked by the playersd implementation.

◆ player_sd_browse()

int player_sd_browse	(	player_sd_t *	sd,
		double	timeout,
		int	keepalive,
		player_sd_browse_callback_fn_t	cb
	)

Browse for player devices.

Browses for timeout s, accruing the results into the sd object. If keepalive is non-zero, then the browsing session is left open and can be updated by future calls to player_sd_update(). Otherwise, the browsing session is closed before returning. If cb is non-NULL, then it is registered and invoked whenever new device notifications are received (call player_sd_update to give this a chance to happen).

NOTE: Because device hostnames are resolved as they are discovered, this call may block for an unpredictable amount of time.

Returns 0 on success, non-zero on error.

◆ player_sd_find_devices()

int player_sd_find_devices	(	player_sd_t *	sd,
		player_sd_dev_t *	result,
		size_t	result_len,
		const char *	name,
		const char *	hostname,
		int	robot,
		int	interf,
		int	index
	)

Find a device in the local cache that matches the given criteria.

sd: a player_sd_t* returned by player_sd_init()
result: a caller-supplied array to store the matching device(s) in
result_len: the length of the result array
name: the Zeroconf name of the device; NULL for don't care
hostname: the hostname where the device resides; NULL for don't care
robot: the 'robot' field of the Player address; -1 for don't care
interf: the 'interf' field of the Player address; -1 for don't care
index: the 'index' field of the Player address; -1 for don't care

The first result_len devices in the local cache that match the criteria are copied into the result array.

Returns: the number of devices copied into result.

◆ player_sd_get_device()

player_sd_dev_t* player_sd_get_device	(	player_sd_t *	sd,
		const char *	name
	)

Look up a device by name.

This functions only consults the local cache of registered devices, which was filled by player_sd_browse().

◆ player_sd_init()

player_sd_t* player_sd_init ( void )

Initialize service discovery, passing back a pointer that will be passed into all future calls.

Returns NULL on failure.

◆ player_sd_register()

int player_sd_register	(	player_sd_t *	sd,
		const char *	name,
		player_devaddr_t	addr
	)

Register the named device.

Returns 0 on success, non-zero on error. Name may be automatically changed in case of conflict.

◆ player_sd_unregister()

int player_sd_unregister	(	player_sd_t *	sd,
		const char *	name
	)

Unregister (terminate) the named device.

Returns 0 on success, non-zero on error.

◆ player_sd_update()

int player_sd_update	(	player_sd_t *	sd,
		double	timeout
	)

Check for new device updates, waiting for timeout s.

Contents of sd are updated, and if a callback was passed to player_sd_browse, then this function is also called for each discovered device. Only makes sense to call this function after a call to player_sd_browse.

NOTE: Because device hostnames are resolved as they are discovered, this call may block for an unpredictable amount of time.

Returns 0 on success, non-zero on error.