DNSServiceRegister

- register service with DNS

Synopsis

cc [ flag ... ] file ... -ldns_sd [ library ... ]
#include <dns_sd.h>

DNSServiceErrorType DNSServiceRegister(DNSServiceRef *sdRef,
     DNSServiceFlags flags, uint32_t interfaceIndex,
     const char *name, const char *regtype,
     const char *domain, const char *host,
     uint16_t port, uint16_t *txtLen, const void *txtRecord
     DNSServiceServiceRegisterReply callBack
     void *context);

typedef void(*DNSServiceRegisterReply)(DNSServiceRef sdRef,
     DNSServiceFlags flags, DNSServiceErrorType errorCode,
     const char *name, const char *regtype,
     const char *domain, void *context);

Description

The DNSServiceRegister function is used by clients to advertise a service that uses DNS. The service is registered with multicast DNS if the domain name is .local or the interface requested is local only. Otherwise, the service registration is attempted with the unicast DNS server. The callback argument should point to a function of type DNSServiceRegisterReply listed above.

The sdRef parameter points to an uninitialized DNSServiceRef instance. If the DNSServiceRegister() call succeeds, sdRef is initialized and kDNSServiceErr_NoError is returned. The service registration remains active until the client terminates the registration by passing the initialized sdRef to DNSServiceRefDeallocate(). The interfaceIndex when non-zero specifies the interface on which the service should be registered. Most applications pass 0 to register the service on all interfaces. See the section “Constants for specifying an interface index” in <dns_sd.h> for more details. The flags parameter determines the renaming behavior on a service name conflict. Most applications pass 0 to allow auto-rename of the service name in case of a name conflict. Applications can pass the flag kDNSServiceFlagsNoAutoRename defined in <dns_sd.h> to disable auto-rename.

The regtype indicates the service type followed by the protocol, separated by a dot, for example “_ftp._tcp.”. The service type must be an underscore that is followed by 1 to 14 characters that can be letters, digits, or hyphens. The transport protocol must be _tcp or _udp. New service types should be registered at http://www.dns-sd.org/ServiceTypes.html. The domain parameter specifies the domain on which a service is advertised. Most applications leave the domain parameter NULL to register the service in default domains. The host parameter specifies the SRV target host name. Most applications do not specify the host parameter value. Instead, the default host name of the machine is used. The port value on which the service accepts connections must be passed in network byte order. A value of 0 for a port is passed to register placeholder services. Placeholder services are not found when browsing, but other clients cannot register with the same name as the placeholder service.

The txtLen parameter specifies the length of the passed txtRecord in bytes. The value must be zero if the txtRecord passed is NULL. The txtRecord points to the TXT record rdata. A non-NULL txtRecord must be a properly formatted DNSTXT record. For more details see the DNSServiceRegister call defined in <dns_sd.h>. The callback argument points to a function to be called when registration completes or when the call asynchronously fails. The client can pass NULL for the callback and not be notified of the registration results or asynchronous errors. The client may not pass the NoAutoRename flag if the callback is NULL. The client can unregister the service at any time via DNSServiceRefDeallocate().

The callback function argument sdRef is initialized by DNSServiceRegister(). The flags argument in the callback function is currently unused and reserved for future use. The error code returned to the callback is kDNSServiceErr_NoError on success. Otherwise, an error code defined in <dns_sd.h> is returned to indicate an error condition such as a name conflict in kDNSServiceFlagsNoAutoRename mode. The name argument holds the registered service name and the regtype argument is the registered service type passed to DNSServiceRegister(). The domain argument returned in the callback indicates the domain on which the service was registered.

Return Values

The DNSServiceRegister function returns kDNSServiceErr_NoError on success. Otherwise, an error code defined in <dns_sd.h> is returned. Upon registration, any subsequent asynchronous errors are delivered to the callback.

Attributes

See attributes(5) for description of the following attributes:

See Also

DNSServiceRefDeallocate(3DNS_SD), attributes(5)