libplayersd

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

Typedef Documentation

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.