Registers a service.
- iOS 9.3+
- macOS 10.11.4+
- Mac Catalyst 13.0+
- tvOS 9.2+
- watchOS 2.2+
Indicates the renaming behavior on name conflict (most applications will pass 0). See flag definitions above for details.
If non-zero, specifies the interface on which to register the service (the index for a given interface is determined via the
iffamily of calls.) Most applications will pass 0 to register on all available interfaces. See "Constants for specifying an interface index" for more details.
If non-NULL, specifies the service name to be registered. Most applications will not specify a name, in which case the computer name is used (this name is communicated to the client via the callback). If a name is specified, it must be 1-63 bytes of UTF-8 text. If the name is longer than 63 bytes it will be automatically truncated to a legal length, unless the
Noflag is set, in which case
kwill be returned.
DNSService Err _Bad Param
The service type followed by the protocol, separated by a dot (for example, "_ftp._tcp"). The service type must be an underscore, followed by 1-15 characters, which may 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.
Additional subtypes of the primary service type (where a service type has defined subtypes) follow the primary service type in a comma-separated list, with no additional spaces. For example, "_primarytype._tcp,_subtype1,_subtype2,_subtype3" . Subtypes provide a mechanism for filtered browsing: A client browsing for "_primarytype._tcp" will discover all instances of this type; a client browsing for "_primarytype._tcp,_subtype2" will discover only those instances that were registered with "_subtype2" in their list of registered subtypes.
The subtype mechanism can be illustrated with some examples using the dns-sd command-line tool:
% dns-sd -R Simple _test._tcp "" 1001 & % dns-sd -R Better _test._tcp,HasFeatureA "" 1002 & % dns-sd -R Best _test._tcp,HasFeatureA,HasFeatureB "" 1003 &
% dns-sd -B _testwill find all three services,
% dns-sd -B _testfinds "Better" and "Best", and
._tcp,Has Feature A #
% dns-sd -B _testfinds only "Best"
._tcp,Has Feature B #
Subtype labels may be up to 63 bytes long, and may contain any eight- bit byte values, including zero bytes. However, due to the nature of using a C-string-based API, conventional DNS escaping must be used for dots ('.'), commas (','), backslashes ('') and zero bytes, as shown below:
% dns-sd -R Test '_test
._tcp,s .one,s,two,s\three,s000four' local 123
When a service is registered, all the clients browsing for the registered type ("regtype") will discover it. If the discovery should be restricted to a smaller set of well known peers, the service can be registered with additional data (group identifier) that is known only to a smaller set of peers. The group identifier should follow primary service type using a colon (":") as a delimiter. If subtypes are also present, it should be given before the subtype as shown below.
% dns-sd -R _test1 _http
._tcp: mygroup1 local 1001 % dns-sd -R _test2 _http ._tcp: mygroup2 local 1001 % dns-sd -R _test3 _http ._tcp: mygroup3,Has Feature A local 1001
% dns-sd -B _httpwill discover only test1,
% dns-sd -B _httpwill discover only test2 %, and
dns-sd -B _httpwill discover only test3.
._tcp:"mygroup3",Has Feature A #
By specifying the group information, only the members of that group are discovered.
The group identifier itself is not sent in clear. Only a hash of the group identifier is sent and the clients discover them anonymously. The group identifier may be up to 256 bytes long and may contain any eight bit values except comma which should be escaped.
If non-NULL, specifies the domain on which to advertise the service. Most applications will not specify a domain, instead automatically registering in the default domain(s).
If non-NULL, specifies the SRV target host name. Most applications will not specify a host, instead automatically using the machine's default host name(s). Note that specifying a non-NULL host does NOT create an address record for that host - the application is responsible for ensuring that the appropriate address record exists, or creating it via
The port, in network byte order, on which the service accepts connections. Pass 0 for a "placeholder" service (that is, a service that will not be discovered by browsing, but will cause a name conflict if another client tries to register that same name). Most clients will not use placeholder services.
The length of the
txt, in bytes. Must be zero if the
The TXT record
rdata. A non-NULL
txtMUST be a properly formatted DNS TXT record—that is, <length byte> <data> <length byte> <data> ... Passing
txtis allowed as a synonym for
txt—it creates a TXT record of length one containing a single empty string. RFC 1035 doesn't allow a TXT record to contain *zero* strings, so a single empty string is the smallest legal DNS TXT record. As with the other parameters, the DNSServiceRegister call copies the txtRecord data; for example, if you allocated the storage for the
Len=1, txt Record=""
malloc()then you can safely free that memory right after the DNSServiceRegister call returns.
The function to be called when the registration completes or asynchronously fails. The client may pass
NULLfor the callback; the client will not be notified of the default values picked on its behalf, and the client will not be notified of any asynchronous errors (for example, out of memory errors, and so forth) that may prevent the registration of the service. The client may not pass the
Noflag if the callback is
NULL. The client may still deregister the service at any time via
An application context pointer that is passed to the callback function (may be
k on success (any subsequent, asynchronous errors are delivered to the callback), otherwise returns an error code indicating the error that occurred (the callback is never invoked and the DNSServiceRef is not initialized).