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.