Zeroconf networking support

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

Functions

Types and Values

Description

Functions

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.

Parameters

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

 

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.

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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

Parameters

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.

Parameters

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.

Parameters

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

Parameters

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

Parameters

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.

Types and Values

enum GnomeVFSDNSSDServiceStatus

Members

GNOME_VFS_DNS_SD_SERVICE_ADDED

   

GNOME_VFS_DNS_SD_SERVICE_REMOVED

   

GnomeVFSDNSSDService

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