## Zeroconf networking support

Zeroconf networking support — Gets information about available Zeroconf (aka RendezVous™) services on a local network.

## Synopsis

    void        (*GnomeVFSDNSSDResolveCallback) (GnomeVFSDNSSDResolveHandle *handle,
                                                 GnomeVFSResult result,
                                                 const GnomeVFSDNSSDService *service,
                                                 const char *host,
                                                 int port,
                                                 const GHashTable *text,
                                                 int text_raw_len,
                                                 const char *text_raw,
                                                 gpointer callback_data);
    enum        GnomeVFSDNSSDServiceStatus;
                GnomeVFSDNSSDService;
    void        (*GnomeVFSDNSSDBrowseCallback)  (GnomeVFSDNSSDBrowseHandle *handle,
                                                 GnomeVFSDNSSDServiceStatus status,
                                                 const GnomeVFSDNSSDService *service,
                                                 gpointer callback_data);
    GnomeVFSResult gnome_vfs_dns_sd_browse      (GnomeVFSDNSSDBrowseHandle **handle,
                                                 const char *domain,
                                                 const char *type,
                                                 GnomeVFSDNSSDBrowseCallback callback,
                                                 gpointer callback_data,
                                                 GDestroyNotify callback_data_destroy_func);
    GnomeVFSResult gnome_vfs_dns_sd_stop_browse (GnomeVFSDNSSDBrowseHandle *handle);
    GnomeVFSResult gnome_vfs_dns_sd_resolve     (GnomeVFSDNSSDResolveHandle **handle,
                                                 const char *name,
                                                 const char *type,
                                                 const char *domain,
                                                 int timeout,
                                                 GnomeVFSDNSSDResolveCallback callback,
                                                 gpointer callback_data,
                                                 GDestroyNotify callback_data_destroy_func);
    GnomeVFSResult gnome_vfs_dns_sd_cancel_resolve
                                                (GnomeVFSDNSSDResolveHandle *handle);
    GnomeVFSResult gnome_vfs_dns_sd_browse_sync (const char *domain,
                                                 const char *type,
                                                 int timeout_msec,
                                                 int *n_services,
                                                 GnomeVFSDNSSDService **services);
    GnomeVFSResult gnome_vfs_dns_sd_resolve_sync
                                                (const char *name,
                                                 const char *type,
                                                 const char *domain,
                                                 int timeout_msec,
                                                 char **host,
                                                 int *port,
                                                 GHashTable **text,
                                                 int *text_raw_len,
                                                 char **text_raw);
    void        gnome_vfs_dns_sd_service_list_free
                                                (GnomeVFSDNSSDService *services,
                                                 int n_services);
    GnomeVFSResult gnome_vfs_dns_sd_list_browse_domains_sync
                                                (const char *domain,
                                                 int timeout_msec,
                                                 GList **domains);
    GList*      gnome_vfs_get_default_browse_domains
                                                (void);

## Description

## Details

### GnomeVFSDNSSDResolveCallback ()

    void        (*GnomeVFSDNSSDResolveCallback) (GnomeVFSDNSSDResolveHandle *handle,
                                                 GnomeVFSResult result,
                                                 const GnomeVFSDNSSDService *service,
                                                 const char *host,
                                                 int port,
                                                 const GHashTable *text,
                                                 int text_raw_len,
                                                 const char *text_raw,
                                                 gpointer callback_data);

Callback for the `gnome_vfs_dns_sd_resolve()` function that is called when a service has been resolved.

The `host` and `port` can be used to contact the requested service, and `text` contains additional options as defined for the type requested.

To check for options being set in `text` without any value ("key" as opposed to "key=value") you must use `g_hash_table_lookup_extended()`, since they are stored in the hash table with a NULL value, and `g_hash_table_lookup()` can't tell that from the case where the key is not in the hash table.

`handle` : | handle of the operation generating the callback
`result` : | whether the resolve succeeded or not
`service` : | the service that was resolved
`host` : | the host name or ip of the host hosting the service
`port` : | the port number to use for the service
`text` : | a hash table giving additional options about the service
`text_raw_len` : | length of `text_raw`
`text_raw` : | raw version of the additional options in `text`
`callback_data` : | user data defined when the callback was established

### enum GnomeVFSDNSSDServiceStatus

    typedef enum {
    	GNOME_VFS_DNS_SD_SERVICE_ADDED,
    	GNOME_VFS_DNS_SD_SERVICE_REMOVED
    } GnomeVFSDNSSDServiceStatus;

### GnomeVFSDNSSDService

    typedef struct {
    	char *name;
    	char *type;
    	char *domain;
    } GnomeVFSDNSSDService;

### GnomeVFSDNSSDBrowseCallback ()

    void        (*GnomeVFSDNSSDBrowseCallback)  (GnomeVFSDNSSDBrowseHandle *handle,
                                                 GnomeVFSDNSSDServiceStatus status,
                                                 const GnomeVFSDNSSDService *service,
                                                 gpointer callback_data);

Callback for the `gnome_vfs_dns_sd_browse()` function that informs the user of services that are added or removed.

`handle` : | handle of the operation generating the callback
`status` : | whether a service addition or removal was detected
`service` : | the service that was discovered or removed
`callback_data` : | user data defined when the callback was established

### gnome_vfs_dns_sd_browse ()

    GnomeVFSResult gnome_vfs_dns_sd_browse      (GnomeVFSDNSSDBrowseHandle **handle,
                                                 const char *domain,
                                                 const char *type,
                                                 GnomeVFSDNSSDBrowseCallback callback,
                                                 gpointer callback_data,
                                                 GDestroyNotify callback_data_destroy_func);

Browses `domain` for services of the type `type`, calling `callback` whenever a new one is found or removed.

The domain to use can be "local" for multicast dns on the local network (known as mDNS), or it can be the domain of the current host. You can also use `gnome_vfs_dns_sd_list_browse_domains_sync()` to get a list of domain that are interesting for a domain.

The type is a string of the form "_type._tcp" or "_type._udp", where type is a service type registered at http://www.dns-sd.org/ServiceTypes.html.

`handle` : | A pointer to a pointer to a GnomeVFSDNSSDBrowseHandle object
`domain` : | The dns domain to browse, or "local" for multicast DNS
`type` : | The type of services to browse for
`callback` : | function to be called when services are discovered
`callback_data` : | data to pass `callback`
`callback_data_destroy_func` : | optional destructor function for `callback_data`
Returns : | An integer representing the result of the operation

### gnome_vfs_dns_sd_stop_browse ()

    GnomeVFSResult gnome_vfs_dns_sd_stop_browse (GnomeVFSDNSSDBrowseHandle *handle);

Stops browsing a domain stared with `gnome_vfs_dns_sd_browse()`

`handle` : | handle of the browse operation to be stopped
Returns : | An integer representing the result of the operation

### gnome_vfs_dns_sd_resolve ()

    GnomeVFSResult gnome_vfs_dns_sd_resolve     (GnomeVFSDNSSDResolveHandle **handle,
                                                 const char *name,
                                                 const char *type,
                                                 const char *domain,
                                                 int timeout,
                                                 GnomeVFSDNSSDResolveCallback callback,
                                                 gpointer callback_data,
                                                 GDestroyNotify callback_data_destroy_func);

Tries to resolve a specific service (typically recieved from `gnome_vfs_dns_sd_browse()`) into a hostname/ip, port number and additional options.

If you ever have to save a reference to a service you should store the unresolved name/type/domain tripplet, because the actual host for the service can change.

The `timeout` argument is primary useful for local resolves, since the host owning the service might no longer be around to answer.

`handle` : | A pointer to a pointer to a GnomeVFSDNSSDResolveHandle object
`name` : | Name of the service to resolve in UTF-8 encoding
`type` : | The type of services to resolve
`domain` : | The dns domain of the service to resolve, or "local" for multicast DNS
`timeout` : | maximum time (in milliseconds) to try to resolve, or zero if no maximum
`callback` : | function to be called when the services has been resolved
`callback_data` : | data to pass `callback`
`callback_data_destroy_func` : | optional destructor function for `callback_data`
Returns : | An integer representing the result of the operation

### gnome_vfs_dns_sd_cancel_resolve ()

    GnomeVFSResult gnome_vfs_dns_sd_cancel_resolve
                                                (GnomeVFSDNSSDResolveHandle *handle);

Cancels resolving a service started with `gnome_vfs_dns_sd_resolve()`

`handle` : | handle of the resolve operation to be cancelled
Returns : | An integer representing the result of the operation

### gnome_vfs_dns_sd_browse_sync ()

    GnomeVFSResult gnome_vfs_dns_sd_browse_sync (const char *domain,
                                                 const char *type,
                                                 int timeout_msec,
                                                 int *n_services,
                                                 GnomeVFSDNSSDService **services);

Browses `domain` for services of the type `type`, returning the result after blocking for the duration of the browse. For details about `domain` and `type`, see `gnome_vfs_dns_sd_browse()`.

`timeout` is essential for the "local" domain, since you can never really know when you've gotten the full set of return values when using multicast.

The returned list can be freed with `gnome_vfs_dns_sd_service_list_free()`

This is a synchronous version of `gnome_vfs_dns_sd_browse()`, see that for more details.

`domain` : | The dns domain to browse, or "local" for multicast DNS
`type` : | type of the service to browse for
`timeout_msec` : | maximum time to browse, in milliseconds
`n_services` : | pointer to location to store number of returned services
`services` : | pointer to location to store returned services
Returns : | An integer representing the result of the operation

### gnome_vfs_dns_sd_resolve_sync ()

    GnomeVFSResult gnome_vfs_dns_sd_resolve_sync
                                                (const char *name,
                                                 const char *type,
                                                 const char *domain,
                                                 int timeout_msec,
                                                 char **host,
                                                 int *port,
                                                 GHashTable **text,
                                                 int *text_raw_len,
                                                 char **text_raw);

Tries to resolve a specific service (typically recieved from `gnome_vfs_dns_sd_browse()`) into a hostname/ip, port number and additional options.

This is a synchronous version of `gnome_vfs_dns_sd_resolve()`, see that (and its callback `GnomeVFSDNSSDResolveCallback()`) for more details.

`name` : | Name of the service to resolve in UTF-8 encoding
`type` : | The type of services to resolve
`domain` : | The dns domain of the service to resolve, or "local" for multicast DNS
`timeout_msec` : | maximum time(in milliseconds) to try to resolve
`host` : | location to store the host name or ip of the host hosting the service
`port` : | location to store the port number to use for the service
`text` : | location to store a hash table giving additional options about the service
`text_raw_len` : | location to store length of `text_raw_out`
`text_raw` : | location to store raw version of the additional options in `text`
Returns : | An integer representing the result of the operation

### gnome_vfs_dns_sd_service_list_free ()

    void        gnome_vfs_dns_sd_service_list_free
                                                (GnomeVFSDNSSDService *services,
                                                 int n_services);

Frees a list of services as returned by `gnome_vfs_dns_sd_browse_sync()`

`services` : | the list of services to free
`n_services` : | the number of services to free

### gnome_vfs_dns_sd_list_browse_domains_sync ()

    GnomeVFSResult gnome_vfs_dns_sd_list_browse_domains_sync
                                                (const char *domain,
                                                 int timeout_msec,
                                                 GList **domains);

Lists the recommended browsing domains for a specific dns domain. This can be used to find interesting domains for the domain you are currently in. These can then be browsed with `gnome_vfs_dns_sd_browse()`.

`domain` : | the domain to list browsable domains in
`timeout_msec` : | maximum time to run, in milliseconds
`domains` : | location to store the returned list of domain names strings
Returns : | An integer representing the result of the operation

### gnome_vfs_get_default_browse_domains ()

    GList*      gnome_vfs_get_default_browse_domains
                                                (void);

Returns a list of domain names that is useful to browse for standard services. The list is generated by contacting the dns server of the domain part the hostname and asking for the list of browse domains. Then extra domains from a gconf setting is added.

The "local" domain is not normally returned by this. Care should be taken with local services so that its obvious that they are local, and cannot be confused with non-local services.

Returns : | A GList of domain name strings