Zeroconf networking support

## 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_out,
                                                             char **text_raw_out);
    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 service 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 domains that are interested in a particular 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` : | pointer to a pointer to a GnomeVFSDNSSDBrowseHandle object.
`domain` : | dns domain to browse, or "local" for multicast DNS.
`type` : | type of service to browse for.
`callback` : | function to be called when service is discovered.
`callback_data` : | data to pass to `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 started 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 primarily useful for local resolves, since the host owning the service might no longer be around to answer.

`handle` : | pointer to a pointer to a GnomeVFSDNSSDResolveHandle object.
`name` : | name of the service to resolve in UTF-8 encoding.
`type` : | type of the service to resolve.
`domain` : | 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 service has been resolved.
`callback_data` : | data to pass to `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 service 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_out,
                                                             char **text_raw_out);

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` : | type of the service to resolve.
`domain` : | 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_out` : | location to store length of `text_raw_out`.
`text_raw_out` : | 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.