DNSSERVICEREGISTER(3DNS_SD)DNSSERVICEREGISTER(3DNS_SD)NAMEDNSServiceRegister - 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 ser‐
vice that uses DNS. The service is registered with multicast DNS if the
domain name is .local or the interface requested is local only. Other‐
wise, 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 ini‐
tialized sdRef to DNSServiceRefDeallocate(). The interfaceIndex when
non-zero specifies the interface on which the service should be regis‐
tered. Most applications pass 0 to register the service on all inter‐
faces. See the section "Constants for specifying an interface index" in
<dns_sd.h> for more details. The flags parameter determines the renam‐
ing 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, sepa‐
rated 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/Service‐
Types.html. The domain parameter specifies the domain on which a ser‐
vice is advertised. Most applications leave the domain parameter NULL
to register the service in default domains. The host parameter speci‐
fies 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 reg‐
ister 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 DNSSer‐
viceRegister 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 DNSServiceRefDeallo‐
cate().
The callback function argument sdRef is initialized by DNSServiceRegis‐
ter(). 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 suc‐
cess. 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:
┌────────────────────┬─────────────────┐
│ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
├────────────────────┼─────────────────┤
│Interface Stability │ Committed │
├────────────────────┼─────────────────┤
│MT-Level │ Safe │
└────────────────────┴─────────────────┘
SEE ALSODNSServiceRefDeallocate(3DNS_SD), attributes(5)
Aug 20, 2007 DNSSERVICEREGISTER(3DNS_SD)
