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

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

Last updated 12 September 2005 21:38:45