libplayersd
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" |
| #define | PLAYER_SD_DEVICE_TXTNAME "device" |
| #define | PLAYER_SD_NAME_MAXLEN 256 |
| #define | PLAYER_SD_TXT_MAXLEN 256 |
| typedef player_sd_dev | player_sd_dev_t |
| A device, represented by its name and address. | |
| typedef 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. |
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.