libplayersd

Player service discovery library. More...

#define	PLAYER_SD_SERVICENAME   "_player21._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.
player_sd_t *	player_sd_init (void)
	Initialize service discovery, passing back a pointer that will be passed into all future calls.
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.
int	player_sd_unregister (player_sd_t *sd, const char *name)
	Unregister (terminate) the named device.
int	player_sd_browse (player_sd_t *sd, double timeout, int keepalive, player_sd_browse_callback_fn_t cb)
	Browse for player devices.
int	player_sd_update (player_sd_t *sd, double timeout)
	Check for new device updates, waiting for timeout s.
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.
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.
player_sd_dev_t *	_player_sd_add_device (player_sd_t *sd, const char *name)
	Add a device to the local cache.
void	player_sd_printcache (player_sd_t *sd)
	Print the contents of the local device cache to the console.

---

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.

---

Typedef Documentation

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_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.

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.

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_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_t* player_sd_init

(

void

)

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

Returns NULL on failure.

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.

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

Unregister (terminate) the named device.

Returns 0 on success, non-zero on error.

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.