14b22b933Srs /* -*- Mode: C; tab-width: 4 -*-
24b22b933Srs  *
33b436d06SToomas Soome  * Copyright (c) 2003-2018 Apple Inc. All rights reserved.
44b22b933Srs  *
55ffb0c9bSToomas Soome  * Redistribution and use in source and binary forms, with or without
64b22b933Srs  * modification, are permitted provided that the following conditions are met:
74b22b933Srs  *
85ffb0c9bSToomas Soome  * 1.  Redistributions of source code must retain the above copyright notice,
95ffb0c9bSToomas Soome  *     this list of conditions and the following disclaimer.
105ffb0c9bSToomas Soome  * 2.  Redistributions in binary form must reproduce the above copyright notice,
115ffb0c9bSToomas Soome  *     this list of conditions and the following disclaimer in the documentation
125ffb0c9bSToomas Soome  *     and/or other materials provided with the distribution.
13cda73f64SToomas Soome  * 3.  Neither the name of Apple Inc. ("Apple") nor the names of its
145ffb0c9bSToomas Soome  *     contributors may be used to endorse or promote products derived from this
155ffb0c9bSToomas Soome  *     software without specific prior written permission.
165ffb0c9bSToomas Soome  *
175ffb0c9bSToomas Soome  * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY
185ffb0c9bSToomas Soome  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
195ffb0c9bSToomas Soome  * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
205ffb0c9bSToomas Soome  * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY
215ffb0c9bSToomas Soome  * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
225ffb0c9bSToomas Soome  * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
235ffb0c9bSToomas Soome  * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
245ffb0c9bSToomas Soome  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
255ffb0c9bSToomas Soome  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
264b22b933Srs  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
274b22b933Srs  */
284b22b933Srs 
295ffb0c9bSToomas Soome 
305ffb0c9bSToomas Soome /*! @header     DNS Service Discovery
315ffb0c9bSToomas Soome  *
325ffb0c9bSToomas Soome  * @discussion  This section describes the functions, callbacks, and data structures
335ffb0c9bSToomas Soome  *              that make up the DNS Service Discovery API.
345ffb0c9bSToomas Soome  *
355ffb0c9bSToomas Soome  *              The DNS Service Discovery API is part of Bonjour, Apple's implementation
365ffb0c9bSToomas Soome  *              of zero-configuration networking (ZEROCONF).
375ffb0c9bSToomas Soome  *
385ffb0c9bSToomas Soome  *              Bonjour allows you to register a network service, such as a
395ffb0c9bSToomas Soome  *              printer or file server, so that it can be found by name or browsed
405ffb0c9bSToomas Soome  *              for by service type and domain. Using Bonjour, applications can
415ffb0c9bSToomas Soome  *              discover what services are available on the network, along with
425ffb0c9bSToomas Soome  *              all the information -- such as name, IP address, and port --
435ffb0c9bSToomas Soome  *              necessary to access a particular service.
445ffb0c9bSToomas Soome  *
455ffb0c9bSToomas Soome  *              In effect, Bonjour combines the functions of a local DNS server and
465ffb0c9bSToomas Soome  *              AppleTalk. Bonjour allows applications to provide user-friendly printer
475ffb0c9bSToomas Soome  *              and server browsing, among other things, over standard IP networks.
485ffb0c9bSToomas Soome  *              This behavior is a result of combining protocols such as multicast and
495ffb0c9bSToomas Soome  *              DNS to add new functionality to the network (such as multicast DNS).
505ffb0c9bSToomas Soome  *
515ffb0c9bSToomas Soome  *              Bonjour gives applications easy access to services over local IP
525ffb0c9bSToomas Soome  *              networks without requiring the service or the application to support
535ffb0c9bSToomas Soome  *              an AppleTalk or a Netbeui stack, and without requiring a DNS server
545ffb0c9bSToomas Soome  *              for the local network.
555ffb0c9bSToomas Soome  */
565ffb0c9bSToomas Soome 
575ffb0c9bSToomas Soome /* _DNS_SD_H contains the API version number for this header file
585ffb0c9bSToomas Soome  * The API version defined in this header file symbol allows for compile-time
595ffb0c9bSToomas Soome  * checking, so that C code building with earlier versions of the header file
605ffb0c9bSToomas Soome  * can avoid compile errors trying to use functions that aren't even defined
615ffb0c9bSToomas Soome  * in those earlier versions. Similar checks may also be performed at run-time:
625ffb0c9bSToomas Soome  *  => weak linking -- to avoid link failures if run with an earlier
635ffb0c9bSToomas Soome  *     version of the library that's missing some desired symbol, or
645ffb0c9bSToomas Soome  *  => DNSServiceGetProperty(DaemonVersion) -- to verify whether the running daemon
655ffb0c9bSToomas Soome  *     ("system service" on Windows) meets some required minimum functionality level.
665ffb0c9bSToomas Soome  */
674b22b933Srs 
684b22b933Srs #ifndef _DNS_SD_H
69*472cd20dSToomas Soome #define _DNS_SD_H 13108001
704b22b933Srs 
714b22b933Srs #ifdef  __cplusplus
725ffb0c9bSToomas Soome extern "C" {
734b22b933Srs #endif
744b22b933Srs 
755ffb0c9bSToomas Soome /* Set to 1 if libdispatch is supported
765ffb0c9bSToomas Soome  * Note: May also be set by project and/or Makefile
775ffb0c9bSToomas Soome  */
783b436d06SToomas Soome #if defined(__APPLE__)
793b436d06SToomas Soome #define _DNS_SD_LIBDISPATCH 1
803b436d06SToomas Soome #else
815ffb0c9bSToomas Soome #define _DNS_SD_LIBDISPATCH 0
823b436d06SToomas Soome #endif
835ffb0c9bSToomas Soome 
844b22b933Srs /* standard calling convention under Win32 is __stdcall */
854b22b933Srs /* Note: When compiling Intel EFI (Extensible Firmware Interface) under MS Visual Studio, the */
864b22b933Srs /* _WIN32 symbol is defined by the compiler even though it's NOT compiling code for Windows32 */
874b22b933Srs #if defined(_WIN32) && !defined(EFI32) && !defined(EFI64)
884b22b933Srs #define DNSSD_API __stdcall
894b22b933Srs #else
904b22b933Srs #define DNSSD_API
914b22b933Srs #endif
924b22b933Srs 
933b436d06SToomas Soome #if (defined(__GNUC__) && (__GNUC__ >= 4))
943b436d06SToomas Soome #define DNSSD_EXPORT __attribute__((visibility("default")))
953b436d06SToomas Soome #else
963b436d06SToomas Soome #define DNSSD_EXPORT
973b436d06SToomas Soome #endif
983b436d06SToomas Soome 
99c65ebfc7SToomas Soome #if defined(_WIN32)
100c65ebfc7SToomas Soome #include <winsock2.h>
101c65ebfc7SToomas Soome typedef SOCKET dnssd_sock_t;
102c65ebfc7SToomas Soome #else
103c65ebfc7SToomas Soome typedef int dnssd_sock_t;
104c65ebfc7SToomas Soome #endif
105c65ebfc7SToomas Soome 
1064b22b933Srs /* stdint.h does not exist on FreeBSD 4.x; its types are defined in sys/types.h instead */
1074b22b933Srs #if defined(__FreeBSD__) && (__FreeBSD__ < 5)
1084b22b933Srs #include <sys/types.h>
1094b22b933Srs 
1104b22b933Srs /* Likewise, on Sun, standard integer types are in sys/types.h */
1114b22b933Srs #elif defined(__sun__)
1124b22b933Srs #include <sys/types.h>
1134b22b933Srs 
1144b22b933Srs /* EFI does not have stdint.h, or anything else equivalent */
1155ffb0c9bSToomas Soome #elif defined(EFI32) || defined(EFI64) || defined(EFIX64)
1165ffb0c9bSToomas Soome #include "Tiano.h"
1175ffb0c9bSToomas Soome #if !defined(_STDINT_H_)
1185ffb0c9bSToomas Soome typedef UINT8 uint8_t;
1195ffb0c9bSToomas Soome typedef INT8 int8_t;
1205ffb0c9bSToomas Soome typedef UINT16 uint16_t;
1215ffb0c9bSToomas Soome typedef INT16 int16_t;
1225ffb0c9bSToomas Soome typedef UINT32 uint32_t;
1235ffb0c9bSToomas Soome typedef INT32 int32_t;
1245ffb0c9bSToomas Soome #endif
1254b22b933Srs /* Windows has its own differences */
1264b22b933Srs #elif defined(_WIN32)
1274b22b933Srs #include <windows.h>
1284b22b933Srs #define _UNUSED
1294b22b933Srs #ifndef _MSL_STDINT_H
1305ffb0c9bSToomas Soome typedef UINT8 uint8_t;
1315ffb0c9bSToomas Soome typedef INT8 int8_t;
1325ffb0c9bSToomas Soome typedef UINT16 uint16_t;
1335ffb0c9bSToomas Soome typedef INT16 int16_t;
1345ffb0c9bSToomas Soome typedef UINT32 uint32_t;
1355ffb0c9bSToomas Soome typedef INT32 int32_t;
1364b22b933Srs #endif
1374b22b933Srs 
1384b22b933Srs /* All other Posix platforms use stdint.h */
1394b22b933Srs #else
1404b22b933Srs #include <stdint.h>
1415ffb0c9bSToomas Soome #endif
1425ffb0c9bSToomas Soome 
1435ffb0c9bSToomas Soome #if _DNS_SD_LIBDISPATCH
1445ffb0c9bSToomas Soome #include <dispatch/dispatch.h>
1454b22b933Srs #endif
1464b22b933Srs 
1474b22b933Srs /* DNSServiceRef, DNSRecordRef
1484b22b933Srs  *
1494b22b933Srs  * Opaque internal data types.
1504b22b933Srs  * Note: client is responsible for serializing access to these structures if
1514b22b933Srs  * they are shared between concurrent threads.
1524b22b933Srs  */
1534b22b933Srs 
1544b22b933Srs typedef struct _DNSServiceRef_t *DNSServiceRef;
1554b22b933Srs typedef struct _DNSRecordRef_t *DNSRecordRef;
1564b22b933Srs 
1575ffb0c9bSToomas Soome struct sockaddr;
1585ffb0c9bSToomas Soome 
1595ffb0c9bSToomas Soome /*! @enum General flags
1605ffb0c9bSToomas Soome  * Most DNS-SD API functions and callbacks include a DNSServiceFlags parameter.
1615ffb0c9bSToomas Soome  * As a general rule, any given bit in the 32-bit flags field has a specific fixed meaning,
1625ffb0c9bSToomas Soome  * regardless of the function or callback being used. For any given function or callback,
1635ffb0c9bSToomas Soome  * typically only a subset of the possible flags are meaningful, and all others should be zero.
1645ffb0c9bSToomas Soome  * The discussion section for each API call describes which flags are valid for that call
1655ffb0c9bSToomas Soome  * and callback. In some cases, for a particular call, it may be that no flags are currently
1665ffb0c9bSToomas Soome  * defined, in which case the DNSServiceFlags parameter exists purely to allow future expansion.
1675ffb0c9bSToomas Soome  * In all cases, developers should expect that in future releases, it is possible that new flag
1685ffb0c9bSToomas Soome  * values will be defined, and write code with this in mind. For example, code that tests
1695ffb0c9bSToomas Soome  *     if (flags == kDNSServiceFlagsAdd) ...
1705ffb0c9bSToomas Soome  * will fail if, in a future release, another bit in the 32-bit flags field is also set.
1715ffb0c9bSToomas Soome  * The reliable way to test whether a particular bit is set is not with an equality test,
1725ffb0c9bSToomas Soome  * but with a bitwise mask:
1735ffb0c9bSToomas Soome  *     if (flags & kDNSServiceFlagsAdd) ...
174c65ebfc7SToomas Soome  * With the exception of kDNSServiceFlagsValidate, each flag can be valid(be set)
1755ffb0c9bSToomas Soome  * EITHER only as an input to one of the DNSService*() APIs OR only as an output
1765ffb0c9bSToomas Soome  * (provide status) through any of the callbacks used. For example, kDNSServiceFlagsAdd
1775ffb0c9bSToomas Soome  * can be set only as an output in the callback, whereas the kDNSServiceFlagsIncludeP2P
178c65ebfc7SToomas Soome  * can be set only as an input to the DNSService*() APIs. See comments on kDNSServiceFlagsValidate
1795ffb0c9bSToomas Soome  * defined in enum below.
1805ffb0c9bSToomas Soome  */
1814b22b933Srs enum
1825ffb0c9bSToomas Soome {
1834b22b933Srs     kDNSServiceFlagsMoreComing          = 0x1,
1844b22b933Srs     /* MoreComing indicates to a callback that at least one more result is
1854b22b933Srs      * queued and will be delivered following immediately after this one.
1865ffb0c9bSToomas Soome      * When the MoreComing flag is set, applications should not immediately
1875ffb0c9bSToomas Soome      * update their UI, because this can result in a great deal of ugly flickering
1885ffb0c9bSToomas Soome      * on the screen, and can waste a great deal of CPU time repeatedly updating
1895ffb0c9bSToomas Soome      * the screen with content that is then immediately erased, over and over.
1905ffb0c9bSToomas Soome      * Applications should wait until MoreComing is not set, and then
1915ffb0c9bSToomas Soome      * update their UI when no more changes are imminent.
1924b22b933Srs      * When MoreComing is not set, that doesn't mean there will be no more
1934b22b933Srs      * answers EVER, just that there are no more answers immediately
1944b22b933Srs      * available right now at this instant. If more answers become available
1954b22b933Srs      * in the future they will be delivered as usual.
1964b22b933Srs      */
1974b22b933Srs 
198c65ebfc7SToomas Soome     kDNSServiceFlagsAutoTrigger        = 0x1,
199c65ebfc7SToomas Soome     /* Valid for browses using kDNSServiceInterfaceIndexAny.
200*472cd20dSToomas Soome      * Will auto trigger the browse over AWDL as well once the service is discovered
201c65ebfc7SToomas Soome      * over BLE.
202c65ebfc7SToomas Soome      * This flag is an input value to DNSServiceBrowse(), which is why we can
203c65ebfc7SToomas Soome      * use the same value as kDNSServiceFlagsMoreComing, which is an output flag
204c65ebfc7SToomas Soome      * for various client callbacks.
205c65ebfc7SToomas Soome     */
206c65ebfc7SToomas Soome 
2074b22b933Srs     kDNSServiceFlagsAdd                 = 0x2,
2084b22b933Srs     kDNSServiceFlagsDefault             = 0x4,
2094b22b933Srs     /* Flags for domain enumeration and browse/query reply callbacks.
2104b22b933Srs      * "Default" applies only to enumeration and is only valid in
2115ffb0c9bSToomas Soome      * conjunction with "Add". An enumeration callback with the "Add"
2124b22b933Srs      * flag NOT set indicates a "Remove", i.e. the domain is no longer
2134b22b933Srs      * valid.
2144b22b933Srs      */
2154b22b933Srs 
2164b22b933Srs     kDNSServiceFlagsNoAutoRename        = 0x8,
2174b22b933Srs     /* Flag for specifying renaming behavior on name conflict when registering
2184b22b933Srs      * non-shared records. By default, name conflicts are automatically handled
2195ffb0c9bSToomas Soome      * by renaming the service. NoAutoRename overrides this behavior - with this
2205ffb0c9bSToomas Soome      * flag set, name conflicts will result in a callback. The NoAutorename flag
2214b22b933Srs      * is only valid if a name is explicitly specified when registering a service
2224b22b933Srs      * (i.e. the default name is not used.)
2234b22b933Srs      */
2244b22b933Srs 
2254b22b933Srs     kDNSServiceFlagsShared              = 0x10,
2264b22b933Srs     kDNSServiceFlagsUnique              = 0x20,
2274b22b933Srs     /* Flag for registering individual records on a connected
2285ffb0c9bSToomas Soome      * DNSServiceRef. Shared indicates that there may be multiple records
2295ffb0c9bSToomas Soome      * with this name on the network (e.g. PTR records). Unique indicates that the
2304b22b933Srs      * record's name is to be unique on the network (e.g. SRV records).
2314b22b933Srs      */
2324b22b933Srs 
2334b22b933Srs     kDNSServiceFlagsBrowseDomains       = 0x40,
2344b22b933Srs     kDNSServiceFlagsRegistrationDomains = 0x80,
2354b22b933Srs     /* Flags for specifying domain enumeration type in DNSServiceEnumerateDomains.
2364b22b933Srs      * BrowseDomains enumerates domains recommended for browsing, RegistrationDomains
2374b22b933Srs      * enumerates domains recommended for registration.
2384b22b933Srs      */
2394b22b933Srs 
2404b22b933Srs     kDNSServiceFlagsLongLivedQuery      = 0x100,
2414b22b933Srs     /* Flag for creating a long-lived unicast query for the DNSServiceQueryRecord call. */
2424b22b933Srs 
2434b22b933Srs     kDNSServiceFlagsAllowRemoteQuery    = 0x200,
2444b22b933Srs     /* Flag for creating a record for which we will answer remote queries
2454b22b933Srs      * (queries from hosts more than one hop away; hosts not directly connected to the local link).
2464b22b933Srs      */
2474b22b933Srs 
2484b22b933Srs     kDNSServiceFlagsForceMulticast      = 0x400,
2495ffb0c9bSToomas Soome     /* Flag for signifying that a query or registration should be performed exclusively via multicast
2505ffb0c9bSToomas Soome      * DNS, even for a name in a domain (e.g. foo.apple.com.) that would normally imply unicast DNS.
2515ffb0c9bSToomas Soome      */
2525ffb0c9bSToomas Soome 
2535ffb0c9bSToomas Soome     kDNSServiceFlagsForce               = 0x800,    // This flag is deprecated.
2545ffb0c9bSToomas Soome 
2555ffb0c9bSToomas Soome     kDNSServiceFlagsKnownUnique         = 0x800,
256c65ebfc7SToomas Soome     /*
2575ffb0c9bSToomas Soome      * Client guarantees that record names are unique, so we can skip sending out initial
2585ffb0c9bSToomas Soome      * probe messages.  Standard name conflict resolution is still done if a conflict is discovered.
2595ffb0c9bSToomas Soome      */
2605ffb0c9bSToomas Soome 
2615ffb0c9bSToomas Soome     kDNSServiceFlagsReturnIntermediates = 0x1000,
2625ffb0c9bSToomas Soome     /* Flag for returning intermediate results.
2635ffb0c9bSToomas Soome      * For example, if a query results in an authoritative NXDomain (name does not exist)
2645ffb0c9bSToomas Soome      * then that result is returned to the client. However the query is not implicitly
2655ffb0c9bSToomas Soome      * cancelled -- it remains active and if the answer subsequently changes
2665ffb0c9bSToomas Soome      * (e.g. because a VPN tunnel is subsequently established) then that positive
2675ffb0c9bSToomas Soome      * result will still be returned to the client.
2685ffb0c9bSToomas Soome      * Similarly, if a query results in a CNAME record, then in addition to following
2695ffb0c9bSToomas Soome      * the CNAME referral, the intermediate CNAME result is also returned to the client.
2705ffb0c9bSToomas Soome      * When this flag is not set, NXDomain errors are not returned, and CNAME records
2715ffb0c9bSToomas Soome      * are followed silently without informing the client of the intermediate steps.
2725ffb0c9bSToomas Soome      * (In earlier builds this flag was briefly calledkDNSServiceFlagsReturnCNAME)
2735ffb0c9bSToomas Soome      */
2745ffb0c9bSToomas Soome 
2755ffb0c9bSToomas Soome     kDNSServiceFlagsShareConnection     = 0x4000,
2765ffb0c9bSToomas Soome     /* For efficiency, clients that perform many concurrent operations may want to use a
2775ffb0c9bSToomas Soome      * single Unix Domain Socket connection with the background daemon, instead of having a
2785ffb0c9bSToomas Soome      * separate connection for each independent operation. To use this mode, clients first
279*472cd20dSToomas Soome      * call DNSServiceCreateConnection(&SharedRef) to initialize the main DNSServiceRef.
2805ffb0c9bSToomas Soome      * For each subsequent operation that is to share that same connection, the client copies
281*472cd20dSToomas Soome      * the SharedRef, and then passes the address of that copy, setting the ShareConnection flag
2825ffb0c9bSToomas Soome      * to tell the library that this DNSServiceRef is not a typical uninitialized DNSServiceRef;
2835ffb0c9bSToomas Soome      * it's a copy of an existing DNSServiceRef whose connection information should be reused.
2845ffb0c9bSToomas Soome      *
2855ffb0c9bSToomas Soome      * For example:
2865ffb0c9bSToomas Soome      *
2875ffb0c9bSToomas Soome      * DNSServiceErrorType error;
288*472cd20dSToomas Soome      * DNSServiceRef SharedRef;
289*472cd20dSToomas Soome      * error = DNSServiceCreateConnection(&SharedRef);
2905ffb0c9bSToomas Soome      * if (error) ...
291*472cd20dSToomas Soome      * DNSServiceRef BrowseRef = SharedRef;  // Important: COPY the primary DNSServiceRef first...
2925ffb0c9bSToomas Soome      * error = DNSServiceBrowse(&BrowseRef, kDNSServiceFlagsShareConnection, ...); // then use the copy
2935ffb0c9bSToomas Soome      * if (error) ...
2945ffb0c9bSToomas Soome      * ...
2955ffb0c9bSToomas Soome      * DNSServiceRefDeallocate(BrowseRef); // Terminate the browse operation
296*472cd20dSToomas Soome      * DNSServiceRefDeallocate(SharedRef); // Terminate the shared connection
2975ffb0c9bSToomas Soome      *
2985ffb0c9bSToomas Soome      * Notes:
2995ffb0c9bSToomas Soome      *
3005ffb0c9bSToomas Soome      * 1. Collective kDNSServiceFlagsMoreComing flag
3015ffb0c9bSToomas Soome      * When callbacks are invoked using a shared DNSServiceRef, the
3025ffb0c9bSToomas Soome      * kDNSServiceFlagsMoreComing flag applies collectively to *all* active
3035ffb0c9bSToomas Soome      * operations sharing the same parent DNSServiceRef. If the MoreComing flag is
3045ffb0c9bSToomas Soome      * set it means that there are more results queued on this parent DNSServiceRef,
3055ffb0c9bSToomas Soome      * but not necessarily more results for this particular callback function.
3065ffb0c9bSToomas Soome      * The implication of this for client programmers is that when a callback
3075ffb0c9bSToomas Soome      * is invoked with the MoreComing flag set, the code should update its
3085ffb0c9bSToomas Soome      * internal data structures with the new result, and set a variable indicating
3095ffb0c9bSToomas Soome      * that its UI needs to be updated. Then, later when a callback is eventually
3105ffb0c9bSToomas Soome      * invoked with the MoreComing flag not set, the code should update *all*
3115ffb0c9bSToomas Soome      * stale UI elements related to that shared parent DNSServiceRef that need
3125ffb0c9bSToomas Soome      * updating, not just the UI elements related to the particular callback
3135ffb0c9bSToomas Soome      * that happened to be the last one to be invoked.
3145ffb0c9bSToomas Soome      *
3155ffb0c9bSToomas Soome      * 2. Canceling operations and kDNSServiceFlagsMoreComing
3165ffb0c9bSToomas Soome      * Whenever you cancel any operation for which you had deferred UI updates
3175ffb0c9bSToomas Soome      * waiting because of a kDNSServiceFlagsMoreComing flag, you should perform
3185ffb0c9bSToomas Soome      * those deferred UI updates. This is because, after cancelling the operation,
3195ffb0c9bSToomas Soome      * you can no longer wait for a callback *without* MoreComing set, to tell
3205ffb0c9bSToomas Soome      * you do perform your deferred UI updates (the operation has been canceled,
3215ffb0c9bSToomas Soome      * so there will be no more callbacks). An implication of the collective
3225ffb0c9bSToomas Soome      * kDNSServiceFlagsMoreComing flag for shared connections is that this
3235ffb0c9bSToomas Soome      * guideline applies more broadly -- any time you cancel an operation on
3245ffb0c9bSToomas Soome      * a shared connection, you should perform all deferred UI updates for all
3255ffb0c9bSToomas Soome      * operations sharing that connection. This is because the MoreComing flag
3265ffb0c9bSToomas Soome      * might have been referring to events coming for the operation you canceled,
3275ffb0c9bSToomas Soome      * which will now not be coming because the operation has been canceled.
3285ffb0c9bSToomas Soome      *
3295ffb0c9bSToomas Soome      * 3. Only share DNSServiceRef's created with DNSServiceCreateConnection
3305ffb0c9bSToomas Soome      * Calling DNSServiceCreateConnection(&ref) creates a special shareable DNSServiceRef.
3315ffb0c9bSToomas Soome      * DNSServiceRef's created by other calls like DNSServiceBrowse() or DNSServiceResolve()
3325ffb0c9bSToomas Soome      * cannot be shared by copying them and using kDNSServiceFlagsShareConnection.
3335ffb0c9bSToomas Soome      *
334*472cd20dSToomas Soome      * 4. Don't Double-Deallocate
335*472cd20dSToomas Soome      * Calling DNSServiceRefDeallocate(OpRef) for a particular operation's DNSServiceRef terminates
336*472cd20dSToomas Soome      * just that operation. Calling DNSServiceRefDeallocate(SharedRef) for the main shared DNSServiceRef
337*472cd20dSToomas Soome      * (the parent DNSServiceRef, originally created by DNSServiceCreateConnection(&SharedRef))
338*472cd20dSToomas Soome      * automatically terminates the shared connection *and* all operations that were still using it.
3395ffb0c9bSToomas Soome      * After doing this, DO NOT then attempt to deallocate any remaining subordinate DNSServiceRef's.
3405ffb0c9bSToomas Soome      * The memory used by those subordinate DNSServiceRef's has already been freed, so any attempt
3415ffb0c9bSToomas Soome      * to do a DNSServiceRefDeallocate (or any other operation) on them will result in accesses
3425ffb0c9bSToomas Soome      * to freed memory, leading to crashes or other equally undesirable results.
343*472cd20dSToomas Soome      * You can deallocate individual operations first and then deallocate the parent DNSServiceRef last,
344*472cd20dSToomas Soome      * but if you deallocate the parent DNSServiceRef first, then all of the subordinate DNSServiceRef's
345*472cd20dSToomas Soome      * are implicitly deallocated, and explicitly deallocating them a second time will lead to crashes.
3465ffb0c9bSToomas Soome      *
3475ffb0c9bSToomas Soome      * 5. Thread Safety
3485ffb0c9bSToomas Soome      * The dns_sd.h API does not presuppose any particular threading model, and consequently
349c65ebfc7SToomas Soome      * does no locking internally (which would require linking with a specific threading library).
350c65ebfc7SToomas Soome      * If the client concurrently, from multiple threads (or contexts), calls API routines using
351c65ebfc7SToomas Soome      * the same DNSServiceRef, it is the client's responsibility to provide mutual exclusion for
352c65ebfc7SToomas Soome      * that DNSServiceRef.
353*472cd20dSToomas Soome      *
354c65ebfc7SToomas Soome      * For example, use of DNSServiceRefDeallocate requires caution. A common mistake is as follows:
355c65ebfc7SToomas Soome      * Thread B calls DNSServiceRefDeallocate to deallocate sdRef while Thread A is processing events
356c65ebfc7SToomas Soome      * using sdRef. Doing this will lead to intermittent crashes on thread A if the sdRef is used after
357c65ebfc7SToomas Soome      * it was deallocated.
358*472cd20dSToomas Soome      *
359c65ebfc7SToomas Soome      * A telltale sign of this crash type is to see DNSServiceProcessResult on the stack preceding the
360c65ebfc7SToomas Soome      * actual crash location.
361*472cd20dSToomas Soome      *
362c65ebfc7SToomas Soome      * To state this more explicitly, mDNSResponder does not queue DNSServiceRefDeallocate so
363c65ebfc7SToomas Soome      * that it occurs discretely before or after an event is handled.
3645ffb0c9bSToomas Soome      */
3655ffb0c9bSToomas Soome 
3665ffb0c9bSToomas Soome     kDNSServiceFlagsSuppressUnusable    = 0x8000,
3675ffb0c9bSToomas Soome     /*
3685ffb0c9bSToomas Soome      * This flag is meaningful only in DNSServiceQueryRecord which suppresses unusable queries on the
3695ffb0c9bSToomas Soome      * wire. If "hostname" is a wide-area unicast DNS hostname (i.e. not a ".local." name)
3705ffb0c9bSToomas Soome      * but this host has no routable IPv6 address, then the call will not try to look up IPv6 addresses
3715ffb0c9bSToomas Soome      * for "hostname", since any addresses it found would be unlikely to be of any use anyway. Similarly,
3725ffb0c9bSToomas Soome      * if this host has no routable IPv4 address, the call will not try to look up IPv4 addresses for
3735ffb0c9bSToomas Soome      * "hostname".
3745ffb0c9bSToomas Soome      */
3755ffb0c9bSToomas Soome 
3765ffb0c9bSToomas Soome     kDNSServiceFlagsTimeout            = 0x10000,
3775ffb0c9bSToomas Soome     /*
3785ffb0c9bSToomas Soome      * When kDNServiceFlagsTimeout is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo, the query is
3795ffb0c9bSToomas Soome      * stopped after a certain number of seconds have elapsed. The time at which the query will be stopped
3805ffb0c9bSToomas Soome      * is determined by the system and cannot be configured by the user. The query will be stopped irrespective
3815ffb0c9bSToomas Soome      * of whether a response was given earlier or not. When the query is stopped, the callback will be called
3825ffb0c9bSToomas Soome      * with an error code of kDNSServiceErr_Timeout and a NULL sockaddr will be returned for DNSServiceGetAddrInfo
3835ffb0c9bSToomas Soome      * and zero length rdata will be returned for DNSServiceQueryRecord.
3845ffb0c9bSToomas Soome      */
3855ffb0c9bSToomas Soome 
3865ffb0c9bSToomas Soome     kDNSServiceFlagsIncludeP2P          = 0x20000,
3875ffb0c9bSToomas Soome     /*
3885ffb0c9bSToomas Soome      * Include P2P interfaces when kDNSServiceInterfaceIndexAny is specified.
3895ffb0c9bSToomas Soome      * By default, specifying kDNSServiceInterfaceIndexAny does not include P2P interfaces.
3905ffb0c9bSToomas Soome      */
3915ffb0c9bSToomas Soome 
3925ffb0c9bSToomas Soome     kDNSServiceFlagsWakeOnResolve      = 0x40000,
3935ffb0c9bSToomas Soome     /*
3945ffb0c9bSToomas Soome     * This flag is meaningful only in DNSServiceResolve. When set, it tries to send a magic packet
3955ffb0c9bSToomas Soome     * to wake up the client.
3965ffb0c9bSToomas Soome     */
3975ffb0c9bSToomas Soome 
3985ffb0c9bSToomas Soome     kDNSServiceFlagsBackgroundTrafficClass  = 0x80000,
3995ffb0c9bSToomas Soome     /*
400c65ebfc7SToomas Soome     * This flag is meaningful for Unicast DNS queries. When set, it uses the background traffic
4015ffb0c9bSToomas Soome     * class for packets that service the request.
4025ffb0c9bSToomas Soome     */
4035ffb0c9bSToomas Soome 
4045ffb0c9bSToomas Soome     kDNSServiceFlagsIncludeAWDL      = 0x100000,
4055ffb0c9bSToomas Soome    /*
4065ffb0c9bSToomas Soome     * Include AWDL interface when kDNSServiceInterfaceIndexAny is specified.
4075ffb0c9bSToomas Soome     */
4085ffb0c9bSToomas Soome 
409*472cd20dSToomas Soome     kDNSServiceFlagsEnableDNSSEC           = 0x200000,
410*472cd20dSToomas Soome     /*
411*472cd20dSToomas Soome      * Perform DNSSEC validation on the client request when kDNSServiceFlagsEnableDNSSEC is specified
412*472cd20dSToomas Soome      * Since the client API has not been finalized, we will use it as a temporary flag to turn on the DNSSEC validation.
413*472cd20dSToomas Soome      */
414*472cd20dSToomas Soome 
4155ffb0c9bSToomas Soome     kDNSServiceFlagsValidate               = 0x200000,
4165ffb0c9bSToomas Soome    /*
417c65ebfc7SToomas Soome     * This flag is meaningful in DNSServiceGetAddrInfo and DNSServiceQueryRecord. This is the ONLY flag to be valid
4185ffb0c9bSToomas Soome     * as an input to the APIs and also an output through the callbacks in the APIs.
4195ffb0c9bSToomas Soome     *
420c65ebfc7SToomas Soome     * When this flag is passed to DNSServiceQueryRecord and DNSServiceGetAddrInfo to resolve unicast names,
421c65ebfc7SToomas Soome     * the response  will be validated using DNSSEC. The validation results are delivered using the flags field in
4225ffb0c9bSToomas Soome     * the callback and kDNSServiceFlagsValidate is marked in the flags to indicate that DNSSEC status is also available.
423c65ebfc7SToomas Soome     * When the callback is called to deliver the query results, the validation results may or may not be available.
4245ffb0c9bSToomas Soome     * If it is not delivered along with the results, the validation status is delivered when the validation completes.
425c65ebfc7SToomas Soome     *
4265ffb0c9bSToomas Soome     * When the validation results are delivered in the callback, it is indicated by marking the flags with
4275ffb0c9bSToomas Soome     * kDNSServiceFlagsValidate and kDNSServiceFlagsAdd along with the DNSSEC status flags (described below) and a NULL
4285ffb0c9bSToomas Soome     * sockaddr will be returned for DNSServiceGetAddrInfo and zero length rdata will be returned for DNSServiceQueryRecord.
4295ffb0c9bSToomas Soome     * DNSSEC validation results are for the whole RRSet and not just individual records delivered in the callback. When
430c65ebfc7SToomas Soome     * kDNSServiceFlagsAdd is not set in the flags, applications should implicitly assume that the DNSSEC status of the
4315ffb0c9bSToomas Soome     * RRSet that has been delivered up until that point is not valid anymore, till another callback is called with
4325ffb0c9bSToomas Soome     * kDNSServiceFlagsAdd and kDNSServiceFlagsValidate.
4335ffb0c9bSToomas Soome     *
4345ffb0c9bSToomas Soome     * The following four flags indicate the status of the DNSSEC validation and marked in the flags field of the callback.
435*472cd20dSToomas Soome     * When any of the four flags is set, kDNSServiceFlagsValidate will also be set. To check the validation status, the
436*472cd20dSToomas Soome     * other applicable output flags should be masked.
4375ffb0c9bSToomas Soome     */
4385ffb0c9bSToomas Soome 
4395ffb0c9bSToomas Soome     kDNSServiceFlagsSecure                 = 0x200010,
4405ffb0c9bSToomas Soome    /*
441c65ebfc7SToomas Soome     * The response has been validated by verifying all the signatures in the response and was able to
442c65ebfc7SToomas Soome     * build a successful authentication chain starting from a known trust anchor.
4435ffb0c9bSToomas Soome     */
4445ffb0c9bSToomas Soome 
4455ffb0c9bSToomas Soome     kDNSServiceFlagsInsecure               = 0x200020,
4465ffb0c9bSToomas Soome    /*
4475ffb0c9bSToomas Soome     * A chain of trust cannot be built starting from a known trust anchor to the response.
4485ffb0c9bSToomas Soome     */
4495ffb0c9bSToomas Soome 
4505ffb0c9bSToomas Soome     kDNSServiceFlagsBogus                  = 0x200040,
4515ffb0c9bSToomas Soome    /*
4525ffb0c9bSToomas Soome     * If the response cannot be verified to be secure due to expired signatures, missing signatures etc.,
4535ffb0c9bSToomas Soome     * then the results are considered to be bogus.
4545ffb0c9bSToomas Soome     */
4555ffb0c9bSToomas Soome 
4565ffb0c9bSToomas Soome     kDNSServiceFlagsIndeterminate          = 0x200080,
4575ffb0c9bSToomas Soome    /*
4585ffb0c9bSToomas Soome     * There is no valid trust anchor that can be used to determine whether a response is secure or not.
4595ffb0c9bSToomas Soome     */
4605ffb0c9bSToomas Soome 
4615ffb0c9bSToomas Soome     kDNSServiceFlagsUnicastResponse        = 0x400000,
4625ffb0c9bSToomas Soome    /*
4635ffb0c9bSToomas Soome     * Request unicast response to query.
4645ffb0c9bSToomas Soome     */
4655ffb0c9bSToomas Soome     kDNSServiceFlagsValidateOptional       = 0x800000,
4665ffb0c9bSToomas Soome 
4675ffb0c9bSToomas Soome     /*
4685ffb0c9bSToomas Soome      * This flag is identical to kDNSServiceFlagsValidate except for the case where the response
4695ffb0c9bSToomas Soome      * cannot be validated. If this flag is set in DNSServiceQueryRecord or DNSServiceGetAddrInfo,
4705ffb0c9bSToomas Soome      * the DNSSEC records will be requested for validation. If they cannot be received for some reason
4715ffb0c9bSToomas Soome      * during the validation (e.g., zone is not signed, zone is signed but cannot be traced back to
4725ffb0c9bSToomas Soome      * root, recursive server does not understand DNSSEC etc.), then this will fallback to the default
4735ffb0c9bSToomas Soome      * behavior where the validation will not be performed and no DNSSEC results will be provided.
4745ffb0c9bSToomas Soome      *
4755ffb0c9bSToomas Soome      * If the zone is signed and there is a valid path to a known trust anchor configured in the system
4765ffb0c9bSToomas Soome      * and the application requires DNSSEC validation irrespective of the DNSSEC awareness in the current
4775ffb0c9bSToomas Soome      * network, then this option MUST not be used. This is only intended to be used during the transition
4785ffb0c9bSToomas Soome      * period where the different nodes participating in the DNS resolution may not understand DNSSEC or
4795ffb0c9bSToomas Soome      * managed properly (e.g. missing DS record) but still want to be able to resolve DNS successfully.
4805ffb0c9bSToomas Soome      */
4815ffb0c9bSToomas Soome 
4825ffb0c9bSToomas Soome     kDNSServiceFlagsWakeOnlyService        = 0x1000000,
4835ffb0c9bSToomas Soome     /*
4845ffb0c9bSToomas Soome      * This flag is meaningful only in DNSServiceRegister. When set, the service will not be registered
4855ffb0c9bSToomas Soome      * with sleep proxy server during sleep.
4865ffb0c9bSToomas Soome      */
4875ffb0c9bSToomas Soome 
4885ffb0c9bSToomas Soome     kDNSServiceFlagsThresholdOne           = 0x2000000,
4895ffb0c9bSToomas Soome     kDNSServiceFlagsThresholdFinder        = 0x4000000,
4905ffb0c9bSToomas Soome     kDNSServiceFlagsThresholdReached       = kDNSServiceFlagsThresholdOne,
4915ffb0c9bSToomas Soome     /*
4925ffb0c9bSToomas Soome      * kDNSServiceFlagsThresholdOne is meaningful only in DNSServiceBrowse. When set,
4935ffb0c9bSToomas Soome      * the system will stop issuing browse queries on the network once the number
4945ffb0c9bSToomas Soome      * of answers returned is one or more.  It will issue queries on the network
4955ffb0c9bSToomas Soome      * again if the number of answers drops to zero.
4965ffb0c9bSToomas Soome      * This flag is for Apple internal use only. Third party developers
4975ffb0c9bSToomas Soome      * should not rely on this behavior being supported in any given software release.
4985ffb0c9bSToomas Soome      *
4995ffb0c9bSToomas Soome      * kDNSServiceFlagsThresholdFinder is meaningful only in DNSServiceBrowse. When set,
5005ffb0c9bSToomas Soome      * the system will stop issuing browse queries on the network once the number
5015ffb0c9bSToomas Soome      * of answers has reached the threshold set for Finder.
5025ffb0c9bSToomas Soome      * It will issue queries on the network again if the number of answers drops below
5035ffb0c9bSToomas Soome      * this threshold.
5045ffb0c9bSToomas Soome      * This flag is for Apple internal use only. Third party developers
5055ffb0c9bSToomas Soome      * should not rely on this behavior being supported in any given software release.
5065ffb0c9bSToomas Soome      *
5075ffb0c9bSToomas Soome      * When kDNSServiceFlagsThresholdReached is set in the client callback add or remove event,
508c65ebfc7SToomas Soome      * it indicates that the browse answer threshold has been reached and no
5095ffb0c9bSToomas Soome      * browse requests will be generated on the network until the number of answers falls
5105ffb0c9bSToomas Soome      * below the threshold value.  Add and remove events can still occur based
5115ffb0c9bSToomas Soome      * on incoming Bonjour traffic observed by the system.
512c65ebfc7SToomas Soome      * The set of services return to the client is not guaranteed to represent the
5135ffb0c9bSToomas Soome      * entire set of services present on the network once the threshold has been reached.
5145ffb0c9bSToomas Soome      *
5155ffb0c9bSToomas Soome      * Note, while kDNSServiceFlagsThresholdReached and kDNSServiceFlagsThresholdOne
5165ffb0c9bSToomas Soome      * have the same value, there  isn't a conflict because kDNSServiceFlagsThresholdReached
5175ffb0c9bSToomas Soome      * is only set in the callbacks and kDNSServiceFlagsThresholdOne is only set on
5185ffb0c9bSToomas Soome      * input to a DNSServiceBrowse call.
5195ffb0c9bSToomas Soome      */
520*472cd20dSToomas Soome      kDNSServiceFlagsPrivateOne          = 0x2000,
521*472cd20dSToomas Soome     /*
522*472cd20dSToomas Soome      * This flag is private and should not be used.
523*472cd20dSToomas Soome      */
524*472cd20dSToomas Soome 
525*472cd20dSToomas Soome      kDNSServiceFlagsPrivateTwo           = 0x8000000,
5265ffb0c9bSToomas Soome     /*
527c65ebfc7SToomas Soome      * This flag is private and should not be used.
5285ffb0c9bSToomas Soome      */
5295ffb0c9bSToomas Soome 
530*472cd20dSToomas Soome      kDNSServiceFlagsPrivateThree         = 0x10000000,
5315ffb0c9bSToomas Soome     /*
532c65ebfc7SToomas Soome      * This flag is private and should not be used.
5334b22b933Srs      */
5345ffb0c9bSToomas Soome 
535*472cd20dSToomas Soome      kDNSServiceFlagsPrivateFour          = 0x20000000,
5365ffb0c9bSToomas Soome     /*
537c65ebfc7SToomas Soome      * This flag is private and should not be used.
5384b22b933Srs      */
5395ffb0c9bSToomas Soome 
540*472cd20dSToomas Soome     kDNSServiceFlagsPrivateFive          = 0x40000000,
541cda73f64SToomas Soome     /*
542c65ebfc7SToomas Soome      * This flag is private and should not be used.
543cda73f64SToomas Soome      */
544cda73f64SToomas Soome 
545*472cd20dSToomas Soome 
546*472cd20dSToomas Soome     kDNSServiceFlagAnsweredFromCache     = 0x40000000,
547*472cd20dSToomas Soome     /*
548*472cd20dSToomas Soome      * When kDNSServiceFlagAnsweredFromCache is passed back in the flags parameter of DNSServiceQueryRecordReply or DNSServiceGetAddrInfoReply,
549*472cd20dSToomas Soome      * an answer will have this flag set if it was answered from the cache.
550*472cd20dSToomas Soome      */
551*472cd20dSToomas Soome 
5523b436d06SToomas Soome     kDNSServiceFlagsAllowExpiredAnswers   = 0x80000000,
5533b436d06SToomas Soome     /*
5543b436d06SToomas Soome      * When kDNSServiceFlagsAllowExpiredAnswers is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo,
5553b436d06SToomas Soome      * if there are matching expired records still in the cache, then they are immediately returned to the
5563b436d06SToomas Soome      * client, and in parallel a network query for that name is issued. All returned records from the query will
5573b436d06SToomas Soome      * remain in the cache after expiration.
5583b436d06SToomas Soome      */
5593b436d06SToomas Soome 
5603b436d06SToomas Soome     kDNSServiceFlagsExpiredAnswer         = 0x80000000
5613b436d06SToomas Soome     /*
5623b436d06SToomas Soome      * When kDNSServiceFlagsAllowExpiredAnswers is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo,
5633b436d06SToomas Soome      * an expired answer will have this flag set.
5643b436d06SToomas Soome      */
5653b436d06SToomas Soome 
5665ffb0c9bSToomas Soome };
5675ffb0c9bSToomas Soome 
5685ffb0c9bSToomas Soome /* Possible protocol values */
5695ffb0c9bSToomas Soome enum
5705ffb0c9bSToomas Soome {
5715ffb0c9bSToomas Soome     /* for DNSServiceGetAddrInfo() */
5725ffb0c9bSToomas Soome     kDNSServiceProtocol_IPv4 = 0x01,
5735ffb0c9bSToomas Soome     kDNSServiceProtocol_IPv6 = 0x02,
5745ffb0c9bSToomas Soome     /* 0x04 and 0x08 reserved for future internetwork protocols */
5755ffb0c9bSToomas Soome 
5765ffb0c9bSToomas Soome     /* for DNSServiceNATPortMappingCreate() */
5775ffb0c9bSToomas Soome     kDNSServiceProtocol_UDP  = 0x10,
5785ffb0c9bSToomas Soome     kDNSServiceProtocol_TCP  = 0x20
5795ffb0c9bSToomas Soome                                /* 0x40 and 0x80 reserved for future transport protocols, e.g. SCTP [RFC 2960]
5805ffb0c9bSToomas Soome                                 * or DCCP [RFC 4340]. If future NAT gateways are created that support port
5815ffb0c9bSToomas Soome                                 * mappings for these protocols, new constants will be defined here.
5825ffb0c9bSToomas Soome                                 */
5835ffb0c9bSToomas Soome };
5844b22b933Srs 
5854b22b933Srs /*
5864b22b933Srs  * The values for DNS Classes and Types are listed in RFC 1035, and are available
5874b22b933Srs  * on every OS in its DNS header file. Unfortunately every OS does not have the
5884b22b933Srs  * same header file containing DNS Class and Type constants, and the names of
5894b22b933Srs  * the constants are not consistent. For example, BIND 8 uses "T_A",
5904b22b933Srs  * BIND 9 uses "ns_t_a", Windows uses "DNS_TYPE_A", etc.
5914b22b933Srs  * For this reason, these constants are also listed here, so that code using
5924b22b933Srs  * the DNS-SD programming APIs can use these constants, so that the same code
5934b22b933Srs  * can compile on all our supported platforms.
5944b22b933Srs  */
5954b22b933Srs 
5964b22b933Srs enum
5975ffb0c9bSToomas Soome {
5984b22b933Srs     kDNSServiceClass_IN       = 1       /* Internet */
5995ffb0c9bSToomas Soome };
6004b22b933Srs 
6014b22b933Srs enum
6025ffb0c9bSToomas Soome {
6035ffb0c9bSToomas Soome     kDNSServiceType_A          = 1,      /* Host address. */
6045ffb0c9bSToomas Soome     kDNSServiceType_NS         = 2,      /* Authoritative server. */
6055ffb0c9bSToomas Soome     kDNSServiceType_MD         = 3,      /* Mail destination. */
6065ffb0c9bSToomas Soome     kDNSServiceType_MF         = 4,      /* Mail forwarder. */
6075ffb0c9bSToomas Soome     kDNSServiceType_CNAME      = 5,      /* Canonical name. */
6085ffb0c9bSToomas Soome     kDNSServiceType_SOA        = 6,      /* Start of authority zone. */
6095ffb0c9bSToomas Soome     kDNSServiceType_MB         = 7,      /* Mailbox domain name. */
6105ffb0c9bSToomas Soome     kDNSServiceType_MG         = 8,      /* Mail group member. */
6115ffb0c9bSToomas Soome     kDNSServiceType_MR         = 9,      /* Mail rename name. */
6125ffb0c9bSToomas Soome     kDNSServiceType_NULL       = 10,     /* Null resource record. */
6135ffb0c9bSToomas Soome     kDNSServiceType_WKS        = 11,     /* Well known service. */
6145ffb0c9bSToomas Soome     kDNSServiceType_PTR        = 12,     /* Domain name pointer. */
6155ffb0c9bSToomas Soome     kDNSServiceType_HINFO      = 13,     /* Host information. */
6165ffb0c9bSToomas Soome     kDNSServiceType_MINFO      = 14,     /* Mailbox information. */
6175ffb0c9bSToomas Soome     kDNSServiceType_MX         = 15,     /* Mail routing information. */
6185ffb0c9bSToomas Soome     kDNSServiceType_TXT        = 16,     /* One or more text strings (NOT "zero or more..."). */
6195ffb0c9bSToomas Soome     kDNSServiceType_RP         = 17,     /* Responsible person. */
6205ffb0c9bSToomas Soome     kDNSServiceType_AFSDB      = 18,     /* AFS cell database. */
6215ffb0c9bSToomas Soome     kDNSServiceType_X25        = 19,     /* X_25 calling address. */
6225ffb0c9bSToomas Soome     kDNSServiceType_ISDN       = 20,     /* ISDN calling address. */
6235ffb0c9bSToomas Soome     kDNSServiceType_RT         = 21,     /* Router. */
6245ffb0c9bSToomas Soome     kDNSServiceType_NSAP       = 22,     /* NSAP address. */
6255ffb0c9bSToomas Soome     kDNSServiceType_NSAP_PTR   = 23,     /* Reverse NSAP lookup (deprecated). */
6265ffb0c9bSToomas Soome     kDNSServiceType_SIG        = 24,     /* Security signature. */
6275ffb0c9bSToomas Soome     kDNSServiceType_KEY        = 25,     /* Security key. */
6285ffb0c9bSToomas Soome     kDNSServiceType_PX         = 26,     /* X.400 mail mapping. */
6295ffb0c9bSToomas Soome     kDNSServiceType_GPOS       = 27,     /* Geographical position (withdrawn). */
6305ffb0c9bSToomas Soome     kDNSServiceType_AAAA       = 28,     /* IPv6 Address. */
6315ffb0c9bSToomas Soome     kDNSServiceType_LOC        = 29,     /* Location Information. */
6325ffb0c9bSToomas Soome     kDNSServiceType_NXT        = 30,     /* Next domain (security). */
6335ffb0c9bSToomas Soome     kDNSServiceType_EID        = 31,     /* Endpoint identifier. */
6345ffb0c9bSToomas Soome     kDNSServiceType_NIMLOC     = 32,     /* Nimrod Locator. */
6355ffb0c9bSToomas Soome     kDNSServiceType_SRV        = 33,     /* Server Selection. */
6365ffb0c9bSToomas Soome     kDNSServiceType_ATMA       = 34,     /* ATM Address */
6375ffb0c9bSToomas Soome     kDNSServiceType_NAPTR      = 35,     /* Naming Authority PoinTeR */
6385ffb0c9bSToomas Soome     kDNSServiceType_KX         = 36,     /* Key Exchange */
6395ffb0c9bSToomas Soome     kDNSServiceType_CERT       = 37,     /* Certification record */
6405ffb0c9bSToomas Soome     kDNSServiceType_A6         = 38,     /* IPv6 Address (deprecated) */
6415ffb0c9bSToomas Soome     kDNSServiceType_DNAME      = 39,     /* Non-terminal DNAME (for IPv6) */
6425ffb0c9bSToomas Soome     kDNSServiceType_SINK       = 40,     /* Kitchen sink (experimental) */
6435ffb0c9bSToomas Soome     kDNSServiceType_OPT        = 41,     /* EDNS0 option (meta-RR) */
6445ffb0c9bSToomas Soome     kDNSServiceType_APL        = 42,     /* Address Prefix List */
6455ffb0c9bSToomas Soome     kDNSServiceType_DS         = 43,     /* Delegation Signer */
6465ffb0c9bSToomas Soome     kDNSServiceType_SSHFP      = 44,     /* SSH Key Fingerprint */
6475ffb0c9bSToomas Soome     kDNSServiceType_IPSECKEY   = 45,     /* IPSECKEY */
6485ffb0c9bSToomas Soome     kDNSServiceType_RRSIG      = 46,     /* RRSIG */
6495ffb0c9bSToomas Soome     kDNSServiceType_NSEC       = 47,     /* Denial of Existence */
6505ffb0c9bSToomas Soome     kDNSServiceType_DNSKEY     = 48,     /* DNSKEY */
6515ffb0c9bSToomas Soome     kDNSServiceType_DHCID      = 49,     /* DHCP Client Identifier */
6525ffb0c9bSToomas Soome     kDNSServiceType_NSEC3      = 50,     /* Hashed Authenticated Denial of Existence */
6535ffb0c9bSToomas Soome     kDNSServiceType_NSEC3PARAM = 51,     /* Hashed Authenticated Denial of Existence */
6545ffb0c9bSToomas Soome 
6555ffb0c9bSToomas Soome     kDNSServiceType_HIP        = 55,     /* Host Identity Protocol */
6565ffb0c9bSToomas Soome 
657*472cd20dSToomas Soome     kDNSServiceType_SVCB       = 64,     /* Service Binding. */
658*472cd20dSToomas Soome     kDNSServiceType_HTTPS      = 65,      /* HTTPS Service Binding. */
659*472cd20dSToomas Soome 
6605ffb0c9bSToomas Soome     kDNSServiceType_SPF        = 99,     /* Sender Policy Framework for E-Mail */
6615ffb0c9bSToomas Soome     kDNSServiceType_UINFO      = 100,    /* IANA-Reserved */
6625ffb0c9bSToomas Soome     kDNSServiceType_UID        = 101,    /* IANA-Reserved */
6635ffb0c9bSToomas Soome     kDNSServiceType_GID        = 102,    /* IANA-Reserved */
6645ffb0c9bSToomas Soome     kDNSServiceType_UNSPEC     = 103,    /* IANA-Reserved */
6655ffb0c9bSToomas Soome 
6665ffb0c9bSToomas Soome     kDNSServiceType_TKEY       = 249,    /* Transaction key */
6675ffb0c9bSToomas Soome     kDNSServiceType_TSIG       = 250,    /* Transaction signature. */
6685ffb0c9bSToomas Soome     kDNSServiceType_IXFR       = 251,    /* Incremental zone transfer. */
6695ffb0c9bSToomas Soome     kDNSServiceType_AXFR       = 252,    /* Transfer zone of authority. */
6705ffb0c9bSToomas Soome     kDNSServiceType_MAILB      = 253,    /* Transfer mailbox records. */
6715ffb0c9bSToomas Soome     kDNSServiceType_MAILA      = 254,    /* Transfer mail agent records. */
672*472cd20dSToomas Soome     kDNSServiceType_ANY        = 255    /* Wildcard match. */
6735ffb0c9bSToomas Soome };
6744b22b933Srs 
6754b22b933Srs /* possible error code values */
6764b22b933Srs enum
6775ffb0c9bSToomas Soome {
6785ffb0c9bSToomas Soome     kDNSServiceErr_NoError                   = 0,
6795ffb0c9bSToomas Soome     kDNSServiceErr_Unknown                   = -65537,  /* 0xFFFE FFFF */
6805ffb0c9bSToomas Soome     kDNSServiceErr_NoSuchName                = -65538,
6815ffb0c9bSToomas Soome     kDNSServiceErr_NoMemory                  = -65539,
6825ffb0c9bSToomas Soome     kDNSServiceErr_BadParam                  = -65540,
6835ffb0c9bSToomas Soome     kDNSServiceErr_BadReference              = -65541,
6845ffb0c9bSToomas Soome     kDNSServiceErr_BadState                  = -65542,
6855ffb0c9bSToomas Soome     kDNSServiceErr_BadFlags                  = -65543,
6865ffb0c9bSToomas Soome     kDNSServiceErr_Unsupported               = -65544,
6875ffb0c9bSToomas Soome     kDNSServiceErr_NotInitialized            = -65545,
6885ffb0c9bSToomas Soome     kDNSServiceErr_AlreadyRegistered         = -65547,
6895ffb0c9bSToomas Soome     kDNSServiceErr_NameConflict              = -65548,
6905ffb0c9bSToomas Soome     kDNSServiceErr_Invalid                   = -65549,
6915ffb0c9bSToomas Soome     kDNSServiceErr_Firewall                  = -65550,
6925ffb0c9bSToomas Soome     kDNSServiceErr_Incompatible              = -65551,  /* client library incompatible with daemon */
6935ffb0c9bSToomas Soome     kDNSServiceErr_BadInterfaceIndex         = -65552,
6945ffb0c9bSToomas Soome     kDNSServiceErr_Refused                   = -65553,
6955ffb0c9bSToomas Soome     kDNSServiceErr_NoSuchRecord              = -65554,
6965ffb0c9bSToomas Soome     kDNSServiceErr_NoAuth                    = -65555,
6975ffb0c9bSToomas Soome     kDNSServiceErr_NoSuchKey                 = -65556,
6985ffb0c9bSToomas Soome     kDNSServiceErr_NATTraversal              = -65557,
6995ffb0c9bSToomas Soome     kDNSServiceErr_DoubleNAT                 = -65558,
7005ffb0c9bSToomas Soome     kDNSServiceErr_BadTime                   = -65559,  /* Codes up to here existed in Tiger */
7015ffb0c9bSToomas Soome     kDNSServiceErr_BadSig                    = -65560,
7025ffb0c9bSToomas Soome     kDNSServiceErr_BadKey                    = -65561,
7035ffb0c9bSToomas Soome     kDNSServiceErr_Transient                 = -65562,
7045ffb0c9bSToomas Soome     kDNSServiceErr_ServiceNotRunning         = -65563,  /* Background daemon not running */
7055ffb0c9bSToomas Soome     kDNSServiceErr_NATPortMappingUnsupported = -65564,  /* NAT doesn't support PCP, NAT-PMP or UPnP */
7065ffb0c9bSToomas Soome     kDNSServiceErr_NATPortMappingDisabled    = -65565,  /* NAT supports PCP, NAT-PMP or UPnP, but it's disabled by the administrator */
7075ffb0c9bSToomas Soome     kDNSServiceErr_NoRouter                  = -65566,  /* No router currently configured (probably no network connectivity) */
7085ffb0c9bSToomas Soome     kDNSServiceErr_PollingMode               = -65567,
709*472cd20dSToomas Soome     kDNSServiceErr_Timeout                   = -65568,
710*472cd20dSToomas Soome     kDNSServiceErr_DefunctConnection         = -65569,  /* Connection to daemon returned a SO_ISDEFUNCT error result */
711*472cd20dSToomas Soome     kDNSServiceErr_PolicyDenied              = -65570
7125ffb0c9bSToomas Soome 
7135ffb0c9bSToomas Soome                                                /* mDNS Error codes are in the range
7145ffb0c9bSToomas Soome                                                 * FFFE FF00 (-65792) to FFFE FFFF (-65537) */
7155ffb0c9bSToomas Soome };
7164b22b933Srs 
7174b22b933Srs /* Maximum length, in bytes, of a service name represented as a */
7184b22b933Srs /* literal C-String, including the terminating NULL at the end. */
7194b22b933Srs 
7204b22b933Srs #define kDNSServiceMaxServiceName 64
7214b22b933Srs 
7224b22b933Srs /* Maximum length, in bytes, of a domain name represented as an *escaped* C-String */
7234b22b933Srs /* including the final trailing dot, and the C-String terminating NULL at the end. */
7244b22b933Srs 
7255ffb0c9bSToomas Soome #define kDNSServiceMaxDomainName 1009
7264b22b933Srs 
7274b22b933Srs /*
7284b22b933Srs  * Notes on DNS Name Escaping
7294b22b933Srs  *   -- or --
7305ffb0c9bSToomas Soome  * "Why is kDNSServiceMaxDomainName 1009, when the maximum legal domain name is 256 bytes?"
7314b22b933Srs  *
732c65ebfc7SToomas Soome  * All strings used in the DNS-SD APIs are UTF-8 strings.
733c65ebfc7SToomas Soome  * Apart from the exceptions noted below, the APIs expect the strings to be properly escaped, using the
734c65ebfc7SToomas Soome  * conventional DNS escaping rules, as used by the traditional DNS res_query() API, as described below:
735c65ebfc7SToomas Soome  *
736c65ebfc7SToomas Soome  * Generally all UTF-8 characters (which includes all US ASCII characters) represent themselves,
737*472cd20dSToomas Soome  * with three exceptions:
738*472cd20dSToomas Soome  * the dot ('.') character, which is the DNS label separator,
739*472cd20dSToomas Soome  * the backslash ('\') character, which is the DNS escape character, and
740*472cd20dSToomas Soome  * the ASCII NUL (0) byte value, which is the C-string terminator character.
741c65ebfc7SToomas Soome  * The escape character ('\') is interpreted as described below:
7424b22b933Srs  *
7434b22b933Srs  *   '\ddd', where ddd is a three-digit decimal value from 000 to 255,
744c65ebfc7SToomas Soome  *        represents a single literal byte with that value. Any byte value may be
745c65ebfc7SToomas Soome  *        represented in '\ddd' format, even characters that don't strictly need to be escaped.
746c65ebfc7SToomas Soome  *        For example, the ASCII code for 'w' is 119, and therefore '\119' is equivalent to 'w'.
747c65ebfc7SToomas Soome  *        Thus the command "ping '\119\119\119.apple.com'" is the equivalent to the command "ping 'www.apple.com'".
748c65ebfc7SToomas Soome  *        Nonprinting ASCII characters in the range 0-31 are often represented this way.
749*472cd20dSToomas Soome  *        In particular, the ASCII NUL character (0) cannot appear in a C-string because C uses it as the
750*472cd20dSToomas Soome  *        string terminator character, so ASCII NUL in a domain name has to be represented in a C-string as '\000'.
751c65ebfc7SToomas Soome  *        Other characters like space (ASCII code 32) are sometimes represented as '\032'
752*472cd20dSToomas Soome  *        in contexts where having an actual space character in a C-string would be inconvenient.
753*472cd20dSToomas Soome  *
754c65ebfc7SToomas Soome  *   Otherwise, for all cases where a '\' is followed by anything other than a three-digit decimal value
755c65ebfc7SToomas Soome  *        from 000 to 255, the character sequence '\x' represents a single literal occurrence of character 'x'.
756c65ebfc7SToomas Soome  *        This is legal for any character, so, for example, '\w' is equivalent to 'w'.
757c65ebfc7SToomas Soome  *        Thus the command "ping '\w\w\w.apple.com'" is the equivalent to the command "ping 'www.apple.com'".
758c65ebfc7SToomas Soome  *        However, this encoding is most useful when representing the characters '.' and '\',
759c65ebfc7SToomas Soome  *        which otherwise would have special meaning in DNS name strings.
760c65ebfc7SToomas Soome  *        This means that the following encodings are particularly common:
761c65ebfc7SToomas Soome  *        '\\' represents a single literal '\' in the name
762c65ebfc7SToomas Soome  *        '\.' represents a single literal '.' in the name
763c65ebfc7SToomas Soome  *
764c65ebfc7SToomas Soome  *   A lone escape character ('\') appearing at the end of a string is not allowed, since it is
765c65ebfc7SToomas Soome  *        followed by neither a three-digit decimal value from 000 to 255 nor a single character.
766c65ebfc7SToomas Soome  *        If a lone escape character ('\') does appear as the last character of a string, it is silently ignored.
7674b22b933Srs  *
768*472cd20dSToomas Soome  * The worse-case length for an escaped domain name is calculated as follows:
769*472cd20dSToomas Soome  * The longest legal domain name is 256 bytes in wire format (see RFC 6762, Appendix C, DNS Name Length).
770*472cd20dSToomas Soome  * For our calculation of the longest *escaped* domain name, we use
771*472cd20dSToomas Soome  * the longest legal domain name, with the most characters escaped.
772*472cd20dSToomas Soome  *
773*472cd20dSToomas Soome  * We consider a domain name of the form: "label63.label63.label63.label62."
774*472cd20dSToomas Soome  * where "label63" is a 63-byte label and "label62" is a 62-byte label.
775*472cd20dSToomas Soome  * Counting four label-length bytes, 251 bytes of label data, and the terminating zero,
776*472cd20dSToomas Soome  * this makes a total of 256 bytes in wire format, the longest legal domain name.
777*472cd20dSToomas Soome  *
778*472cd20dSToomas Soome  * If each one of the 251 bytes of label data is represented using '\ddd',
779*472cd20dSToomas Soome  * then it takes 251 * 4 = 1004 bytes to represent these in a C-string.
780*472cd20dSToomas Soome  * Adding four '.' characters as shown above, plus the C-string terminating
781*472cd20dSToomas Soome  * zero at the end, results in a maximum storage requirement of 1009 bytes.
782*472cd20dSToomas Soome  *
7834b22b933Srs  * The exceptions, that do not use escaping, are the routines where the full
7844b22b933Srs  * DNS name of a resource is broken, for convenience, into servicename/regtype/domain.
7854b22b933Srs  * In these routines, the "servicename" is NOT escaped. It does not need to be, since
7864b22b933Srs  * it is, by definition, just a single literal string. Any characters in that string
7874b22b933Srs  * represent exactly what they are. The "regtype" portion is, technically speaking,
788c65ebfc7SToomas Soome  * escaped, but since legal regtypes are only allowed to contain US ASCII letters,
789c65ebfc7SToomas Soome  * digits, and hyphens, there is nothing to escape, so the issue is moot.
790c65ebfc7SToomas Soome  * The "domain" portion is also escaped, though most domains in use on the public
791c65ebfc7SToomas Soome  * Internet today, like regtypes, don't contain any characters that need to be escaped.
7924b22b933Srs  * As DNS-SD becomes more popular, rich-text domains for service discovery will
7934b22b933Srs  * become common, so software should be written to cope with domains with escaping.
7944b22b933Srs  *
7954b22b933Srs  * The servicename may be up to 63 bytes of UTF-8 text (not counting the C-String
7964b22b933Srs  * terminating NULL at the end). The regtype is of the form _service._tcp or
7975ffb0c9bSToomas Soome  * _service._udp, where the "service" part is 1-15 characters, which may be
7984b22b933Srs  * letters, digits, or hyphens. The domain part of the three-part name may be
7994b22b933Srs  * any legal domain, providing that the resulting servicename+regtype+domain
8005ffb0c9bSToomas Soome  * name does not exceed 256 bytes.
8014b22b933Srs  *
8024b22b933Srs  * For most software, these issues are transparent. When browsing, the discovered
8034b22b933Srs  * servicenames should simply be displayed as-is. When resolving, the discovered
8044b22b933Srs  * servicename/regtype/domain are simply passed unchanged to DNSServiceResolve().
8054b22b933Srs  * When a DNSServiceResolve() succeeds, the returned fullname is already in
8064b22b933Srs  * the correct format to pass to standard system DNS APIs such as res_query().
8074b22b933Srs  * For converting from servicename/regtype/domain to a single properly-escaped
8084b22b933Srs  * full DNS name, the helper function DNSServiceConstructFullName() is provided.
8094b22b933Srs  *
8104b22b933Srs  * The following (highly contrived) example illustrates the escaping process.
811c65ebfc7SToomas Soome  * Suppose you have a service called "Dr. Smith\Dr. Johnson", of type "_ftp._tcp"
8124b22b933Srs  * in subdomain "4th. Floor" of subdomain "Building 2" of domain "apple.com."
8134b22b933Srs  * The full (escaped) DNS name of this service's SRV record would be:
8144b22b933Srs  * Dr\.\032Smith\\Dr\.\032Johnson._ftp._tcp.4th\.\032Floor.Building\0322.apple.com.
8154b22b933Srs  */
8164b22b933Srs 
8174b22b933Srs 
8185ffb0c9bSToomas Soome /*
8194b22b933Srs  * Constants for specifying an interface index
8204b22b933Srs  *
8214b22b933Srs  * Specific interface indexes are identified via a 32-bit unsigned integer returned
8224b22b933Srs  * by the if_nametoindex() family of calls.
8235ffb0c9bSToomas Soome  *
8244b22b933Srs  * If the client passes 0 for interface index, that means "do the right thing",
8254b22b933Srs  * which (at present) means, "if the name is in an mDNS local multicast domain
8264b22b933Srs  * (e.g. 'local.', '254.169.in-addr.arpa.', '{8,9,A,B}.E.F.ip6.arpa.') then multicast
8274b22b933Srs  * on all applicable interfaces, otherwise send via unicast to the appropriate
8284b22b933Srs  * DNS server." Normally, most clients will use 0 for interface index to
8294b22b933Srs  * automatically get the default sensible behaviour.
8305ffb0c9bSToomas Soome  *
831cda73f64SToomas Soome  * If the client passes a positive interface index, then that indicates to do the
832cda73f64SToomas Soome  * operation only on that one specified interface.
8335ffb0c9bSToomas Soome  *
8344b22b933Srs  * If the client passes kDNSServiceInterfaceIndexLocalOnly when registering
8354b22b933Srs  * a service, then that service will be found *only* by other local clients
8364b22b933Srs  * on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly
8374b22b933Srs  * or kDNSServiceInterfaceIndexAny.
8384b22b933Srs  * If a client has a 'private' service, accessible only to other processes
8394b22b933Srs  * running on the same machine, this allows the client to advertise that service
8404b22b933Srs  * in a way such that it does not inadvertently appear in service lists on
8414b22b933Srs  * all the other machines on the network.
8425ffb0c9bSToomas Soome  *
843c65ebfc7SToomas Soome  * If the client passes kDNSServiceInterfaceIndexLocalOnly when querying or
844c65ebfc7SToomas Soome  * browsing, then the LocalOnly authoritative records and /etc/hosts caches
845c65ebfc7SToomas Soome  * are searched and will find *all* records registered or configured on that
846c65ebfc7SToomas Soome  * same local machine.
847c65ebfc7SToomas Soome  *
848c65ebfc7SToomas Soome  * If interested in getting negative answers to local questions while querying
849c65ebfc7SToomas Soome  * or browsing, then set both the kDNSServiceInterfaceIndexLocalOnly and the
850c65ebfc7SToomas Soome  * kDNSServiceFlagsReturnIntermediates flags. If no local answers exist at this
851c65ebfc7SToomas Soome  * moment in time, then the reply will return an immediate negative answer. If
852c65ebfc7SToomas Soome  * local records are subsequently created that answer the question, then those
853c65ebfc7SToomas Soome  * answers will be delivered, for as long as the question is still active.
854c65ebfc7SToomas Soome  *
855c65ebfc7SToomas Soome  * If the kDNSServiceFlagsTimeout and kDNSServiceInterfaceIndexLocalOnly flags
856c65ebfc7SToomas Soome  * are set simultaneously when either DNSServiceQueryRecord or DNSServiceGetAddrInfo
857c65ebfc7SToomas Soome  * is called then both flags take effect. However, if DNSServiceQueryRecord is called
858c65ebfc7SToomas Soome  * with both the kDNSServiceFlagsSuppressUnusable and kDNSServiceInterfaceIndexLocalOnly
859c65ebfc7SToomas Soome  * flags set, then the kDNSServiceFlagsSuppressUnusable flag is ignored.
860c65ebfc7SToomas Soome  *
861c65ebfc7SToomas Soome  * Clients explicitly wishing to discover *only* LocalOnly services during a
862c65ebfc7SToomas Soome  * browse may do this, without flags, by inspecting the interfaceIndex of each
863c65ebfc7SToomas Soome  * service reported to a DNSServiceBrowseReply() callback function, and
864c65ebfc7SToomas Soome  * discarding those answers where the interface index is not set to
865c65ebfc7SToomas Soome  * kDNSServiceInterfaceIndexLocalOnly.
8665ffb0c9bSToomas Soome  *
8675ffb0c9bSToomas Soome  * kDNSServiceInterfaceIndexP2P is meaningful only in Browse, QueryRecord, Register,
8685ffb0c9bSToomas Soome  * and Resolve operations. It should not be used in other DNSService APIs.
8695ffb0c9bSToomas Soome  *
8705ffb0c9bSToomas Soome  * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceBrowse or
8715ffb0c9bSToomas Soome  *   DNSServiceQueryRecord, it restricts the operation to P2P.
8725ffb0c9bSToomas Soome  *
8735ffb0c9bSToomas Soome  * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceRegister, it is
8745ffb0c9bSToomas Soome  *   mapped internally to kDNSServiceInterfaceIndexAny with the kDNSServiceFlagsIncludeP2P
8755ffb0c9bSToomas Soome  *   set.
8765ffb0c9bSToomas Soome  *
8775ffb0c9bSToomas Soome  * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceResolve, it is
8785ffb0c9bSToomas Soome  *   mapped internally to kDNSServiceInterfaceIndexAny with the kDNSServiceFlagsIncludeP2P
879c65ebfc7SToomas Soome  *   set, because resolving a P2P service may create and/or enable an interface whose
8805ffb0c9bSToomas Soome  *   index is not known a priori. The resolve callback will indicate the index of the
8815ffb0c9bSToomas Soome  *   interface via which the service can be accessed.
8825ffb0c9bSToomas Soome  *
8835ffb0c9bSToomas Soome  * If applications pass kDNSServiceInterfaceIndexAny to DNSServiceBrowse
8845ffb0c9bSToomas Soome  * or DNSServiceQueryRecord, they must set the kDNSServiceFlagsIncludeP2P flag
8855ffb0c9bSToomas Soome  * to include P2P. In this case, if a service instance or the record being queried
8865ffb0c9bSToomas Soome  * is found over P2P, the resulting ADD event will indicate kDNSServiceInterfaceIndexP2P
8875ffb0c9bSToomas Soome  * as the interface index.
8884b22b933Srs  */
8894b22b933Srs 
8904b22b933Srs #define kDNSServiceInterfaceIndexAny 0
8915ffb0c9bSToomas Soome #define kDNSServiceInterfaceIndexLocalOnly ((uint32_t)-1)
8925ffb0c9bSToomas Soome #define kDNSServiceInterfaceIndexUnicast   ((uint32_t)-2)
8935ffb0c9bSToomas Soome #define kDNSServiceInterfaceIndexP2P       ((uint32_t)-3)
894c65ebfc7SToomas Soome #define kDNSServiceInterfaceIndexBLE       ((uint32_t)-4)
8954b22b933Srs 
8964b22b933Srs typedef uint32_t DNSServiceFlags;
8975ffb0c9bSToomas Soome typedef uint32_t DNSServiceProtocol;
8984b22b933Srs typedef int32_t DNSServiceErrorType;
8994b22b933Srs 
9004b22b933Srs 
9014b22b933Srs /*********************************************************************************************
9025ffb0c9bSToomas Soome *
9035ffb0c9bSToomas Soome * Version checking
9045ffb0c9bSToomas Soome *
9055ffb0c9bSToomas Soome *********************************************************************************************/
9065ffb0c9bSToomas Soome 
9075ffb0c9bSToomas Soome /* DNSServiceGetProperty() Parameters:
9084b22b933Srs  *
9095ffb0c9bSToomas Soome  * property:        The requested property.
9105ffb0c9bSToomas Soome  *                  Currently the only property defined is kDNSServiceProperty_DaemonVersion.
9114b22b933Srs  *
9125ffb0c9bSToomas Soome  * result:          Place to store result.
9135ffb0c9bSToomas Soome  *                  For retrieving DaemonVersion, this should be the address of a uint32_t.
9145ffb0c9bSToomas Soome  *
9155ffb0c9bSToomas Soome  * size:            Pointer to uint32_t containing size of the result location.
9165ffb0c9bSToomas Soome  *                  For retrieving DaemonVersion, this should be sizeof(uint32_t).
9175ffb0c9bSToomas Soome  *                  On return the uint32_t is updated to the size of the data returned.
9185ffb0c9bSToomas Soome  *                  For DaemonVersion, the returned size is always sizeof(uint32_t), but
9195ffb0c9bSToomas Soome  *                  future properties could be defined which return variable-sized results.
9205ffb0c9bSToomas Soome  *
9215ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success, or kDNSServiceErr_ServiceNotRunning
9225ffb0c9bSToomas Soome  *                  if the daemon (or "system service" on Windows) is not running.
9235ffb0c9bSToomas Soome  */
9245ffb0c9bSToomas Soome 
9253b436d06SToomas Soome DNSSD_EXPORT
9265ffb0c9bSToomas Soome DNSServiceErrorType DNSSD_API DNSServiceGetProperty
9275ffb0c9bSToomas Soome (
9285ffb0c9bSToomas Soome     const char *property,  /* Requested property (i.e. kDNSServiceProperty_DaemonVersion) */
9295ffb0c9bSToomas Soome     void       *result,    /* Pointer to place to store result */
9305ffb0c9bSToomas Soome     uint32_t   *size       /* size of result location */
9315ffb0c9bSToomas Soome );
9325ffb0c9bSToomas Soome 
9335ffb0c9bSToomas Soome /*
9345ffb0c9bSToomas Soome  * When requesting kDNSServiceProperty_DaemonVersion, the result pointer must point
9355ffb0c9bSToomas Soome  * to a 32-bit unsigned integer, and the size parameter must be set to sizeof(uint32_t).
9365ffb0c9bSToomas Soome  *
9375ffb0c9bSToomas Soome  * On return, the 32-bit unsigned integer contains the API version number
9385ffb0c9bSToomas Soome  *
9395ffb0c9bSToomas Soome  * For example, Mac OS X 10.4.9 has API version 1080400.
9405ffb0c9bSToomas Soome  * This allows applications to do simple greater-than and less-than comparisons:
9415ffb0c9bSToomas Soome  * e.g. an application that requires at least API version 1080400 can check:
9425ffb0c9bSToomas Soome  *   if (version >= 1080400) ...
9435ffb0c9bSToomas Soome  *
9445ffb0c9bSToomas Soome  * Example usage:
9455ffb0c9bSToomas Soome  * uint32_t version;
9465ffb0c9bSToomas Soome  * uint32_t size = sizeof(version);
9475ffb0c9bSToomas Soome  * DNSServiceErrorType err = DNSServiceGetProperty(kDNSServiceProperty_DaemonVersion, &version, &size);
9485ffb0c9bSToomas Soome  * if (!err) printf("DNS_SD API version is %d.%d\n", version / 10000, version / 100 % 100);
9495ffb0c9bSToomas Soome  */
9504b22b933Srs 
9515ffb0c9bSToomas Soome #define kDNSServiceProperty_DaemonVersion "DaemonVersion"
9525ffb0c9bSToomas Soome 
9535ffb0c9bSToomas Soome /*********************************************************************************************
9545ffb0c9bSToomas Soome *
9555ffb0c9bSToomas Soome * Unix Domain Socket access, DNSServiceRef deallocation, and data processing functions
9565ffb0c9bSToomas Soome *
9575ffb0c9bSToomas Soome *********************************************************************************************/
9584b22b933Srs 
9594b22b933Srs /* DNSServiceRefSockFD()
9604b22b933Srs  *
9614b22b933Srs  * Access underlying Unix domain socket for an initialized DNSServiceRef.
9625ffb0c9bSToomas Soome  * The DNS Service Discovery implementation uses this socket to communicate between the client and
9635ffb0c9bSToomas Soome  * the daemon. The application MUST NOT directly read from or write to this socket.
9645ffb0c9bSToomas Soome  * Access to the socket is provided so that it can be used as a kqueue event source, a CFRunLoop
9655ffb0c9bSToomas Soome  * event source, in a select() loop, etc. When the underlying event management subsystem (kqueue/
9665ffb0c9bSToomas Soome  * select/CFRunLoop etc.) indicates to the client that data is available for reading on the
9675ffb0c9bSToomas Soome  * socket, the client should call DNSServiceProcessResult(), which will extract the daemon's
9685ffb0c9bSToomas Soome  * reply from the socket, and pass it to the appropriate application callback. By using a run
9695ffb0c9bSToomas Soome  * loop or select(), results from the daemon can be processed asynchronously. Alternatively,
9705ffb0c9bSToomas Soome  * a client can choose to fork a thread and have it loop calling "DNSServiceProcessResult(ref);"
9715ffb0c9bSToomas Soome  * If DNSServiceProcessResult() is called when no data is available for reading on the socket, it
9725ffb0c9bSToomas Soome  * will block until data does become available, and then process the data and return to the caller.
973c65ebfc7SToomas Soome  * The application is responsible for checking the return value of DNSServiceProcessResult()
974c65ebfc7SToomas Soome  * to determine if the socket is valid and if it should continue to process data on the socket.
9755ffb0c9bSToomas Soome  * When data arrives on the socket, the client is responsible for calling DNSServiceProcessResult(ref)
9765ffb0c9bSToomas Soome  * in a timely fashion -- if the client allows a large backlog of data to build up the daemon
9775ffb0c9bSToomas Soome  * may terminate the connection.
9785ffb0c9bSToomas Soome  *
9795ffb0c9bSToomas Soome  * sdRef:           A DNSServiceRef initialized by any of the DNSService calls.
9804b22b933Srs  *
9814b22b933Srs  * return value:    The DNSServiceRef's underlying socket descriptor, or -1 on
9824b22b933Srs  *                  error.
9834b22b933Srs  */
9844b22b933Srs 
9853b436d06SToomas Soome DNSSD_EXPORT
986c65ebfc7SToomas Soome dnssd_sock_t DNSSD_API DNSServiceRefSockFD(DNSServiceRef sdRef);
9874b22b933Srs 
9884b22b933Srs 
9894b22b933Srs /* DNSServiceProcessResult()
9904b22b933Srs  *
9915ffb0c9bSToomas Soome  * Read a reply from the daemon, calling the appropriate application callback. This call will
9925ffb0c9bSToomas Soome  * block until the daemon's response is received. Use DNSServiceRefSockFD() in
9934b22b933Srs  * conjunction with a run loop or select() to determine the presence of a response from the
9945ffb0c9bSToomas Soome  * server before calling this function to process the reply without blocking. Call this function
9955ffb0c9bSToomas Soome  * at any point if it is acceptable to block until the daemon's response arrives. Note that the
9964b22b933Srs  * client is responsible for ensuring that DNSServiceProcessResult() is called whenever there is
9974b22b933Srs  * a reply from the daemon - the daemon may terminate its connection with a client that does not
9984b22b933Srs  * process the daemon's responses.
9994b22b933Srs  *
10004b22b933Srs  * sdRef:           A DNSServiceRef initialized by any of the DNSService calls
10014b22b933Srs  *                  that take a callback parameter.
10024b22b933Srs  *
10034b22b933Srs  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns
10044b22b933Srs  *                  an error code indicating the specific failure that occurred.
10054b22b933Srs  */
10064b22b933Srs 
10073b436d06SToomas Soome DNSSD_EXPORT
10084b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceProcessResult(DNSServiceRef sdRef);
10094b22b933Srs 
10104b22b933Srs 
10114b22b933Srs /* DNSServiceRefDeallocate()
10124b22b933Srs  *
10134b22b933Srs  * Terminate a connection with the daemon and free memory associated with the DNSServiceRef.
10144b22b933Srs  * Any services or records registered with this DNSServiceRef will be deregistered. Any
10154b22b933Srs  * Browse, Resolve, or Query operations called with this reference will be terminated.
10164b22b933Srs  *
10174b22b933Srs  * Note: If the reference's underlying socket is used in a run loop or select() call, it should
10184b22b933Srs  * be removed BEFORE DNSServiceRefDeallocate() is called, as this function closes the reference's
10194b22b933Srs  * socket.
10204b22b933Srs  *
10214b22b933Srs  * Note: If the reference was initialized with DNSServiceCreateConnection(), any DNSRecordRefs
10224b22b933Srs  * created via this reference will be invalidated by this call - the resource records are
10235ffb0c9bSToomas Soome  * deregistered, and their DNSRecordRefs may not be used in subsequent functions. Similarly,
10244b22b933Srs  * if the reference was initialized with DNSServiceRegister, and an extra resource record was
10254b22b933Srs  * added to the service via DNSServiceAddRecord(), the DNSRecordRef created by the Add() call
10264b22b933Srs  * is invalidated when this function is called - the DNSRecordRef may not be used in subsequent
10274b22b933Srs  * functions.
10284b22b933Srs  *
1029*472cd20dSToomas Soome  * If the reference was passed to DNSServiceSetDispatchQueue(), DNSServiceRefDeallocate() must
1030*472cd20dSToomas Soome  * be called on the same queue originally passed as an argument to DNSServiceSetDispatchQueue().
1031*472cd20dSToomas Soome  *
10325ffb0c9bSToomas Soome  * Note: This call is to be used only with the DNSServiceRef defined by this API.
10334b22b933Srs  *
10344b22b933Srs  * sdRef:           A DNSServiceRef initialized by any of the DNSService calls.
10354b22b933Srs  *
10364b22b933Srs  */
10374b22b933Srs 
10383b436d06SToomas Soome DNSSD_EXPORT
10394b22b933Srs void DNSSD_API DNSServiceRefDeallocate(DNSServiceRef sdRef);
10404b22b933Srs 
10414b22b933Srs 
10424b22b933Srs /*********************************************************************************************
10435ffb0c9bSToomas Soome *
10445ffb0c9bSToomas Soome * Domain Enumeration
10455ffb0c9bSToomas Soome *
10465ffb0c9bSToomas Soome *********************************************************************************************/
10474b22b933Srs 
10484b22b933Srs /* DNSServiceEnumerateDomains()
10494b22b933Srs  *
10504b22b933Srs  * Asynchronously enumerate domains available for browsing and registration.
10514b22b933Srs  *
10524b22b933Srs  * The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains
10534b22b933Srs  * are to be found.
10544b22b933Srs  *
10554b22b933Srs  * Note that the names returned are (like all of DNS-SD) UTF-8 strings,
10564b22b933Srs  * and are escaped using standard DNS escaping rules.
10574b22b933Srs  * (See "Notes on DNS Name Escaping" earlier in this file for more details.)
10584b22b933Srs  * A graphical browser displaying a hierarchical tree-structured view should cut
10594b22b933Srs  * the names at the bare dots to yield individual labels, then de-escape each
10604b22b933Srs  * label according to the escaping rules, and then display the resulting UTF-8 text.
10614b22b933Srs  *
10624b22b933Srs  * DNSServiceDomainEnumReply Callback Parameters:
10634b22b933Srs  *
10644b22b933Srs  * sdRef:           The DNSServiceRef initialized by DNSServiceEnumerateDomains().
10654b22b933Srs  *
10664b22b933Srs  * flags:           Possible values are:
10674b22b933Srs  *                  kDNSServiceFlagsMoreComing
10684b22b933Srs  *                  kDNSServiceFlagsAdd
10694b22b933Srs  *                  kDNSServiceFlagsDefault
10704b22b933Srs  *
10715ffb0c9bSToomas Soome  * interfaceIndex:  Specifies the interface on which the domain exists. (The index for a given
10724b22b933Srs  *                  interface is determined via the if_nametoindex() family of calls.)
10734b22b933Srs  *
10744b22b933Srs  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise indicates
10754b22b933Srs  *                  the failure that occurred (other parameters are undefined if errorCode is nonzero).
10764b22b933Srs  *
10774b22b933Srs  * replyDomain:     The name of the domain.
10784b22b933Srs  *
10794b22b933Srs  * context:         The context pointer passed to DNSServiceEnumerateDomains.
10804b22b933Srs  *
10814b22b933Srs  */
10824b22b933Srs 
10834b22b933Srs typedef void (DNSSD_API *DNSServiceDomainEnumReply)
10845ffb0c9bSToomas Soome (
10855ffb0c9bSToomas Soome     DNSServiceRef sdRef,
10865ffb0c9bSToomas Soome     DNSServiceFlags flags,
10875ffb0c9bSToomas Soome     uint32_t interfaceIndex,
10885ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
10894b22b933Srs     const char                          *replyDomain,
10904b22b933Srs     void                                *context
10915ffb0c9bSToomas Soome );
10924b22b933Srs 
10934b22b933Srs 
10944b22b933Srs /* DNSServiceEnumerateDomains() Parameters:
10954b22b933Srs  *
1096*472cd20dSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef
1097*472cd20dSToomas Soome  *                  (or, if the kDNSServiceFlagsShareConnection flag is used,
1098*472cd20dSToomas Soome  *                  a copy of the shared connection reference that is to be used).
1099*472cd20dSToomas Soome  *                  If the call succeeds then it initializes (or updates) the DNSServiceRef,
1100*472cd20dSToomas Soome  *                  returns kDNSServiceErr_NoError, and the enumeration operation
1101*472cd20dSToomas Soome  *                  will remain active indefinitely until the client terminates it
1102*472cd20dSToomas Soome  *                  by passing this DNSServiceRef to DNSServiceRefDeallocate()
1103*472cd20dSToomas Soome  *                  (or by closing the underlying shared connection, if used).
11044b22b933Srs  *
11054b22b933Srs  * flags:           Possible values are:
1106*472cd20dSToomas Soome  *                  kDNSServiceFlagsShareConnection to use a shared connection.
11074b22b933Srs  *                  kDNSServiceFlagsBrowseDomains to enumerate domains recommended for browsing.
11084b22b933Srs  *                  kDNSServiceFlagsRegistrationDomains to enumerate domains recommended
11094b22b933Srs  *                  for registration.
11104b22b933Srs  *
11114b22b933Srs  * interfaceIndex:  If non-zero, specifies the interface on which to look for domains.
11124b22b933Srs  *                  (the index for a given interface is determined via the if_nametoindex()
11135ffb0c9bSToomas Soome  *                  family of calls.) Most applications will pass 0 to enumerate domains on
11144b22b933Srs  *                  all interfaces. See "Constants for specifying an interface index" for more details.
11154b22b933Srs  *
11164b22b933Srs  * callBack:        The function to be called when a domain is found or the call asynchronously
11174b22b933Srs  *                  fails.
11184b22b933Srs  *
11194b22b933Srs  * context:         An application context pointer which is passed to the callback function
11204b22b933Srs  *                  (may be NULL).
11214b22b933Srs  *
11225ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
11234b22b933Srs  *                  errors are delivered to the callback), otherwise returns an error code indicating
11244b22b933Srs  *                  the error that occurred (the callback is not invoked and the DNSServiceRef
11255ffb0c9bSToomas Soome  *                  is not initialized).
11264b22b933Srs  */
11274b22b933Srs 
11283b436d06SToomas Soome DNSSD_EXPORT
11294b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceEnumerateDomains
11305ffb0c9bSToomas Soome (
11314b22b933Srs     DNSServiceRef                       *sdRef,
11325ffb0c9bSToomas Soome     DNSServiceFlags flags,
11335ffb0c9bSToomas Soome     uint32_t interfaceIndex,
11345ffb0c9bSToomas Soome     DNSServiceDomainEnumReply callBack,
11354b22b933Srs     void                                *context  /* may be NULL */
11365ffb0c9bSToomas Soome );
11374b22b933Srs 
11384b22b933Srs 
11394b22b933Srs /*********************************************************************************************
11405ffb0c9bSToomas Soome *
11415ffb0c9bSToomas Soome *  Service Registration
11425ffb0c9bSToomas Soome *
11435ffb0c9bSToomas Soome *********************************************************************************************/
11444b22b933Srs 
11454b22b933Srs /* Register a service that is discovered via Browse() and Resolve() calls.
11464b22b933Srs  *
11474b22b933Srs  * DNSServiceRegisterReply() Callback Parameters:
11484b22b933Srs  *
11494b22b933Srs  * sdRef:           The DNSServiceRef initialized by DNSServiceRegister().
11504b22b933Srs  *
11515ffb0c9bSToomas Soome  * flags:           When a name is successfully registered, the callback will be
11525ffb0c9bSToomas Soome  *                  invoked with the kDNSServiceFlagsAdd flag set. When Wide-Area
11535ffb0c9bSToomas Soome  *                  DNS-SD is in use, it is possible for a single service to get
11545ffb0c9bSToomas Soome  *                  more than one success callback (e.g. one in the "local" multicast
11555ffb0c9bSToomas Soome  *                  DNS domain, and another in a wide-area unicast DNS domain).
11565ffb0c9bSToomas Soome  *                  If a successfully-registered name later suffers a name conflict
11575ffb0c9bSToomas Soome  *                  or similar problem and has to be deregistered, the callback will
11585ffb0c9bSToomas Soome  *                  be invoked with the kDNSServiceFlagsAdd flag not set. The callback
11595ffb0c9bSToomas Soome  *                  is *not* invoked in the case where the caller explicitly terminates
11605ffb0c9bSToomas Soome  *                  the service registration by calling DNSServiceRefDeallocate(ref);
11614b22b933Srs  *
11624b22b933Srs  * errorCode:       Will be kDNSServiceErr_NoError on success, otherwise will
11634b22b933Srs  *                  indicate the failure that occurred (including name conflicts,
11644b22b933Srs  *                  if the kDNSServiceFlagsNoAutoRename flag was used when registering.)
11654b22b933Srs  *                  Other parameters are undefined if errorCode is nonzero.
11664b22b933Srs  *
11674b22b933Srs  * name:            The service name registered (if the application did not specify a name in
11684b22b933Srs  *                  DNSServiceRegister(), this indicates what name was automatically chosen).
11694b22b933Srs  *
11704b22b933Srs  * regtype:         The type of service registered, as it was passed to the callout.
11714b22b933Srs  *
11724b22b933Srs  * domain:          The domain on which the service was registered (if the application did not
11734b22b933Srs  *                  specify a domain in DNSServiceRegister(), this indicates the default domain
11744b22b933Srs  *                  on which the service was registered).
11754b22b933Srs  *
11764b22b933Srs  * context:         The context pointer that was passed to the callout.
11774b22b933Srs  *
11784b22b933Srs  */
11794b22b933Srs 
11804b22b933Srs typedef void (DNSSD_API *DNSServiceRegisterReply)
11815ffb0c9bSToomas Soome (
11825ffb0c9bSToomas Soome     DNSServiceRef sdRef,
11835ffb0c9bSToomas Soome     DNSServiceFlags flags,
11845ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
11854b22b933Srs     const char                          *name,
11864b22b933Srs     const char                          *regtype,
11874b22b933Srs     const char                          *domain,
11884b22b933Srs     void                                *context
11895ffb0c9bSToomas Soome );
11904b22b933Srs 
11914b22b933Srs 
11925ffb0c9bSToomas Soome /* DNSServiceRegister() Parameters:
11934b22b933Srs  *
1194*472cd20dSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef
1195*472cd20dSToomas Soome  *                  (or, if the kDNSServiceFlagsShareConnection flag is used,
1196*472cd20dSToomas Soome  *                  a copy of the shared connection reference that is to be used).
1197*472cd20dSToomas Soome  *                  If the call succeeds then it initializes (or updates) the DNSServiceRef,
1198*472cd20dSToomas Soome  *                  returns kDNSServiceErr_NoError, and the service registration
1199*472cd20dSToomas Soome  *                  will remain active indefinitely until the client terminates it
1200*472cd20dSToomas Soome  *                  by passing this DNSServiceRef to DNSServiceRefDeallocate()
1201*472cd20dSToomas Soome  *                  (or by closing the underlying shared connection, if used).
12024b22b933Srs  *
1203*472cd20dSToomas Soome  * flags:           Possible values are:
1204*472cd20dSToomas Soome  *                  kDNSServiceFlagsShareConnection to use a shared connection.
1205*472cd20dSToomas Soome  *                  Other flags indicate the renaming behavior on name conflict
1206*472cd20dSToomas Soome  *                  (not required for most applications).
1207*472cd20dSToomas Soome  *                  See flag definitions above for details.
1208c65ebfc7SToomas Soome  *
12094b22b933Srs  * interfaceIndex:  If non-zero, specifies the interface on which to register the service
12104b22b933Srs  *                  (the index for a given interface is determined via the if_nametoindex()
12115ffb0c9bSToomas Soome  *                  family of calls.) Most applications will pass 0 to register on all
12124b22b933Srs  *                  available interfaces. See "Constants for specifying an interface index" for more details.
12134b22b933Srs  *
12144b22b933Srs  * name:            If non-NULL, specifies the service name to be registered.
12154b22b933Srs  *                  Most applications will not specify a name, in which case the computer
12164b22b933Srs  *                  name is used (this name is communicated to the client via the callback).
12174b22b933Srs  *                  If a name is specified, it must be 1-63 bytes of UTF-8 text.
12184b22b933Srs  *                  If the name is longer than 63 bytes it will be automatically truncated
12194b22b933Srs  *                  to a legal length, unless the NoAutoRename flag is set,
12204b22b933Srs  *                  in which case kDNSServiceErr_BadParam will be returned.
12214b22b933Srs  *
12224b22b933Srs  * regtype:         The service type followed by the protocol, separated by a dot
12234b22b933Srs  *                  (e.g. "_ftp._tcp"). The service type must be an underscore, followed
12245ffb0c9bSToomas Soome  *                  by 1-15 characters, which may be letters, digits, or hyphens.
12254b22b933Srs  *                  The transport protocol must be "_tcp" or "_udp". New service types
12264b22b933Srs  *                  should be registered at <http://www.dns-sd.org/ServiceTypes.html>.
12274b22b933Srs  *
12285ffb0c9bSToomas Soome  *                  Additional subtypes of the primary service type (where a service
12295ffb0c9bSToomas Soome  *                  type has defined subtypes) follow the primary service type in a
12305ffb0c9bSToomas Soome  *                  comma-separated list, with no additional spaces, e.g.
12315ffb0c9bSToomas Soome  *                      "_primarytype._tcp,_subtype1,_subtype2,_subtype3"
12325ffb0c9bSToomas Soome  *                  Subtypes provide a mechanism for filtered browsing: A client browsing
12335ffb0c9bSToomas Soome  *                  for "_primarytype._tcp" will discover all instances of this type;
12345ffb0c9bSToomas Soome  *                  a client browsing for "_primarytype._tcp,_subtype2" will discover only
12355ffb0c9bSToomas Soome  *                  those instances that were registered with "_subtype2" in their list of
12365ffb0c9bSToomas Soome  *                  registered subtypes.
12375ffb0c9bSToomas Soome  *
12385ffb0c9bSToomas Soome  *                  The subtype mechanism can be illustrated with some examples using the
12395ffb0c9bSToomas Soome  *                  dns-sd command-line tool:
12405ffb0c9bSToomas Soome  *
12415ffb0c9bSToomas Soome  *                  % dns-sd -R Simple _test._tcp "" 1001 &
12425ffb0c9bSToomas Soome  *                  % dns-sd -R Better _test._tcp,HasFeatureA "" 1002 &
12435ffb0c9bSToomas Soome  *                  % dns-sd -R Best   _test._tcp,HasFeatureA,HasFeatureB "" 1003 &
12445ffb0c9bSToomas Soome  *
12455ffb0c9bSToomas Soome  *                  Now:
12465ffb0c9bSToomas Soome  *                  % dns-sd -B _test._tcp             # will find all three services
12475ffb0c9bSToomas Soome  *                  % dns-sd -B _test._tcp,HasFeatureA # finds "Better" and "Best"
12485ffb0c9bSToomas Soome  *                  % dns-sd -B _test._tcp,HasFeatureB # finds only "Best"
12495ffb0c9bSToomas Soome  *
12505ffb0c9bSToomas Soome  *                  Subtype labels may be up to 63 bytes long, and may contain any eight-
12515ffb0c9bSToomas Soome  *                  bit byte values, including zero bytes. However, due to the nature of
12525ffb0c9bSToomas Soome  *                  using a C-string-based API, conventional DNS escaping must be used for
12535ffb0c9bSToomas Soome  *                  dots ('.'), commas (','), backslashes ('\') and zero bytes, as shown below:
12545ffb0c9bSToomas Soome  *
12555ffb0c9bSToomas Soome  *                  % dns-sd -R Test '_test._tcp,s\.one,s\,two,s\\three,s\000four' local 123
12565ffb0c9bSToomas Soome  *
12574b22b933Srs  * domain:          If non-NULL, specifies the domain on which to advertise the service.
12584b22b933Srs  *                  Most applications will not specify a domain, instead automatically
12594b22b933Srs  *                  registering in the default domain(s).
12604b22b933Srs  *
12615ffb0c9bSToomas Soome  * host:            If non-NULL, specifies the SRV target host name. Most applications
12624b22b933Srs  *                  will not specify a host, instead automatically using the machine's
12635ffb0c9bSToomas Soome  *                  default host name(s). Note that specifying a non-NULL host does NOT
12644b22b933Srs  *                  create an address record for that host - the application is responsible
12654b22b933Srs  *                  for ensuring that the appropriate address record exists, or creating it
12664b22b933Srs  *                  via DNSServiceRegisterRecord().
12674b22b933Srs  *
12684b22b933Srs  * port:            The port, in network byte order, on which the service accepts connections.
12694b22b933Srs  *                  Pass 0 for a "placeholder" service (i.e. a service that will not be discovered
12704b22b933Srs  *                  by browsing, but will cause a name conflict if another client tries to
12715ffb0c9bSToomas Soome  *                  register that same name). Most clients will not use placeholder services.
12724b22b933Srs  *
12735ffb0c9bSToomas Soome  * txtLen:          The length of the txtRecord, in bytes. Must be zero if the txtRecord is NULL.
12744b22b933Srs  *
12754b22b933Srs  * txtRecord:       The TXT record rdata. A non-NULL txtRecord MUST be a properly formatted DNS
12764b22b933Srs  *                  TXT record, i.e. <length byte> <data> <length byte> <data> ...
12774b22b933Srs  *                  Passing NULL for the txtRecord is allowed as a synonym for txtLen=1, txtRecord="",
12784b22b933Srs  *                  i.e. it creates a TXT record of length one containing a single empty string.
12794b22b933Srs  *                  RFC 1035 doesn't allow a TXT record to contain *zero* strings, so a single empty
12804b22b933Srs  *                  string is the smallest legal DNS TXT record.
12814b22b933Srs  *                  As with the other parameters, the DNSServiceRegister call copies the txtRecord
12824b22b933Srs  *                  data; e.g. if you allocated the storage for the txtRecord parameter with malloc()
12834b22b933Srs  *                  then you can safely free that memory right after the DNSServiceRegister call returns.
12844b22b933Srs  *
12854b22b933Srs  * callBack:        The function to be called when the registration completes or asynchronously
12865ffb0c9bSToomas Soome  *                  fails. The client MAY pass NULL for the callback -  The client will NOT be notified
12874b22b933Srs  *                  of the default values picked on its behalf, and the client will NOT be notified of any
12884b22b933Srs  *                  asynchronous errors (e.g. out of memory errors, etc.) that may prevent the registration
12895ffb0c9bSToomas Soome  *                  of the service. The client may NOT pass the NoAutoRename flag if the callback is NULL.
12904b22b933Srs  *                  The client may still deregister the service at any time via DNSServiceRefDeallocate().
12914b22b933Srs  *
12924b22b933Srs  * context:         An application context pointer which is passed to the callback function
12934b22b933Srs  *                  (may be NULL).
12944b22b933Srs  *
12955ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
12964b22b933Srs  *                  errors are delivered to the callback), otherwise returns an error code indicating
12974b22b933Srs  *                  the error that occurred (the callback is never invoked and the DNSServiceRef
12985ffb0c9bSToomas Soome  *                  is not initialized).
12994b22b933Srs  */
13004b22b933Srs 
13013b436d06SToomas Soome DNSSD_EXPORT
13024b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceRegister
13035ffb0c9bSToomas Soome (
13044b22b933Srs     DNSServiceRef                       *sdRef,
13055ffb0c9bSToomas Soome     DNSServiceFlags flags,
13065ffb0c9bSToomas Soome     uint32_t interfaceIndex,
13074b22b933Srs     const char                          *name,         /* may be NULL */
13084b22b933Srs     const char                          *regtype,
13094b22b933Srs     const char                          *domain,       /* may be NULL */
13104b22b933Srs     const char                          *host,         /* may be NULL */
13115ffb0c9bSToomas Soome     uint16_t port,                                     /* In network byte order */
13125ffb0c9bSToomas Soome     uint16_t txtLen,
13134b22b933Srs     const void                          *txtRecord,    /* may be NULL */
13145ffb0c9bSToomas Soome     DNSServiceRegisterReply callBack,                  /* may be NULL */
13154b22b933Srs     void                                *context       /* may be NULL */
13165ffb0c9bSToomas Soome );
13174b22b933Srs 
13184b22b933Srs 
13194b22b933Srs /* DNSServiceAddRecord()
13204b22b933Srs  *
13215ffb0c9bSToomas Soome  * Add a record to a registered service. The name of the record will be the same as the
13224b22b933Srs  * registered service's name.
13234b22b933Srs  * The record can later be updated or deregistered by passing the RecordRef initialized
13244b22b933Srs  * by this function to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
13254b22b933Srs  *
13264b22b933Srs  * Note that the DNSServiceAddRecord/UpdateRecord/RemoveRecord are *NOT* thread-safe
13274b22b933Srs  * with respect to a single DNSServiceRef. If you plan to have multiple threads
13284b22b933Srs  * in your program simultaneously add, update, or remove records from the same
1329c65ebfc7SToomas Soome  * DNSServiceRef, then it's the caller's responsibility to use a mutex lock
13304b22b933Srs  * or take similar appropriate precautions to serialize those calls.
13314b22b933Srs  *
13324b22b933Srs  * Parameters;
13334b22b933Srs  *
13344b22b933Srs  * sdRef:           A DNSServiceRef initialized by DNSServiceRegister().
13354b22b933Srs  *
13365ffb0c9bSToomas Soome  * RecordRef:       A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this
13374b22b933Srs  *                  call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
13384b22b933Srs  *                  If the above DNSServiceRef is passed to DNSServiceRefDeallocate(), RecordRef is also
13394b22b933Srs  *                  invalidated and may not be used further.
13404b22b933Srs  *
13414b22b933Srs  * flags:           Currently ignored, reserved for future use.
13424b22b933Srs  *
13434b22b933Srs  * rrtype:          The type of the record (e.g. kDNSServiceType_TXT, kDNSServiceType_SRV, etc)
13444b22b933Srs  *
13454b22b933Srs  * rdlen:           The length, in bytes, of the rdata.
13464b22b933Srs  *
13474b22b933Srs  * rdata:           The raw rdata to be contained in the added resource record.
13484b22b933Srs  *
13495ffb0c9bSToomas Soome  * ttl:             The time to live of the resource record, in seconds.
13505ffb0c9bSToomas Soome  *                  Most clients should pass 0 to indicate that the system should
13515ffb0c9bSToomas Soome  *                  select a sensible default value.
13524b22b933Srs  *
13534b22b933Srs  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
13544b22b933Srs  *                  error code indicating the error that occurred (the RecordRef is not initialized).
13554b22b933Srs  */
13564b22b933Srs 
13573b436d06SToomas Soome DNSSD_EXPORT
13584b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceAddRecord
13595ffb0c9bSToomas Soome (
13605ffb0c9bSToomas Soome     DNSServiceRef sdRef,
13614b22b933Srs     DNSRecordRef                        *RecordRef,
13625ffb0c9bSToomas Soome     DNSServiceFlags flags,
13635ffb0c9bSToomas Soome     uint16_t rrtype,
13645ffb0c9bSToomas Soome     uint16_t rdlen,
13654b22b933Srs     const void                          *rdata,
13665ffb0c9bSToomas Soome     uint32_t ttl
13675ffb0c9bSToomas Soome );
13684b22b933Srs 
13694b22b933Srs 
13704b22b933Srs /* DNSServiceUpdateRecord
13714b22b933Srs  *
13725ffb0c9bSToomas Soome  * Update a registered resource record. The record must either be:
13734b22b933Srs  *   - The primary txt record of a service registered via DNSServiceRegister()
13744b22b933Srs  *   - A record added to a registered service via DNSServiceAddRecord()
13754b22b933Srs  *   - An individual record registered by DNSServiceRegisterRecord()
13764b22b933Srs  *
13774b22b933Srs  * Parameters:
13784b22b933Srs  *
13794b22b933Srs  * sdRef:           A DNSServiceRef that was initialized by DNSServiceRegister()
13804b22b933Srs  *                  or DNSServiceCreateConnection().
13814b22b933Srs  *
13824b22b933Srs  * RecordRef:       A DNSRecordRef initialized by DNSServiceAddRecord, or NULL to update the
13834b22b933Srs  *                  service's primary txt record.
13844b22b933Srs  *
13854b22b933Srs  * flags:           Currently ignored, reserved for future use.
13864b22b933Srs  *
13874b22b933Srs  * rdlen:           The length, in bytes, of the new rdata.
13884b22b933Srs  *
13894b22b933Srs  * rdata:           The new rdata to be contained in the updated resource record.
13904b22b933Srs  *
13914b22b933Srs  * ttl:             The time to live of the updated resource record, in seconds.
13925ffb0c9bSToomas Soome  *                  Most clients should pass 0 to indicate that the system should
13935ffb0c9bSToomas Soome  *                  select a sensible default value.
13944b22b933Srs  *
13954b22b933Srs  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
13964b22b933Srs  *                  error code indicating the error that occurred.
13974b22b933Srs  */
13984b22b933Srs 
13993b436d06SToomas Soome DNSSD_EXPORT
14004b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceUpdateRecord
14015ffb0c9bSToomas Soome (
14025ffb0c9bSToomas Soome     DNSServiceRef sdRef,
14035ffb0c9bSToomas Soome     DNSRecordRef RecordRef,                            /* may be NULL */
14045ffb0c9bSToomas Soome     DNSServiceFlags flags,
14055ffb0c9bSToomas Soome     uint16_t rdlen,
14064b22b933Srs     const void                          *rdata,
14075ffb0c9bSToomas Soome     uint32_t ttl
14085ffb0c9bSToomas Soome );
14094b22b933Srs 
14104b22b933Srs 
14114b22b933Srs /* DNSServiceRemoveRecord
14124b22b933Srs  *
14134b22b933Srs  * Remove a record previously added to a service record set via DNSServiceAddRecord(), or deregister
1414c65ebfc7SToomas Soome  * a record registered individually via DNSServiceRegisterRecord().
14154b22b933Srs  *
14164b22b933Srs  * Parameters:
14174b22b933Srs  *
14184b22b933Srs  * sdRef:           A DNSServiceRef initialized by DNSServiceRegister() (if the
14194b22b933Srs  *                  record being removed was registered via DNSServiceAddRecord()) or by
14204b22b933Srs  *                  DNSServiceCreateConnection() (if the record being removed was registered via
14214b22b933Srs  *                  DNSServiceRegisterRecord()).
14224b22b933Srs  *
14234b22b933Srs  * recordRef:       A DNSRecordRef initialized by a successful call to DNSServiceAddRecord()
14244b22b933Srs  *                  or DNSServiceRegisterRecord().
14254b22b933Srs  *
14264b22b933Srs  * flags:           Currently ignored, reserved for future use.
14274b22b933Srs  *
14284b22b933Srs  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
14294b22b933Srs  *                  error code indicating the error that occurred.
14304b22b933Srs  */
14314b22b933Srs 
14323b436d06SToomas Soome DNSSD_EXPORT
14334b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceRemoveRecord
14345ffb0c9bSToomas Soome (
14355ffb0c9bSToomas Soome     DNSServiceRef sdRef,
14365ffb0c9bSToomas Soome     DNSRecordRef RecordRef,
14375ffb0c9bSToomas Soome     DNSServiceFlags flags
14385ffb0c9bSToomas Soome );
14394b22b933Srs 
14404b22b933Srs 
14414b22b933Srs /*********************************************************************************************
14425ffb0c9bSToomas Soome *
14435ffb0c9bSToomas Soome *  Service Discovery
14445ffb0c9bSToomas Soome *
14455ffb0c9bSToomas Soome *********************************************************************************************/
14464b22b933Srs 
14474b22b933Srs /* Browse for instances of a service.
14484b22b933Srs  *
14494b22b933Srs  * DNSServiceBrowseReply() Parameters:
14504b22b933Srs  *
14514b22b933Srs  * sdRef:           The DNSServiceRef initialized by DNSServiceBrowse().
14524b22b933Srs  *
14534b22b933Srs  * flags:           Possible values are kDNSServiceFlagsMoreComing and kDNSServiceFlagsAdd.
14544b22b933Srs  *                  See flag definitions for details.
14554b22b933Srs  *
14565ffb0c9bSToomas Soome  * interfaceIndex:  The interface on which the service is advertised. This index should
14574b22b933Srs  *                  be passed to DNSServiceResolve() when resolving the service.
14584b22b933Srs  *
14594b22b933Srs  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise will
14605ffb0c9bSToomas Soome  *                  indicate the failure that occurred. Other parameters are undefined if
14614b22b933Srs  *                  the errorCode is nonzero.
14624b22b933Srs  *
14634b22b933Srs  * serviceName:     The discovered service name. This name should be displayed to the user,
14644b22b933Srs  *                  and stored for subsequent use in the DNSServiceResolve() call.
14654b22b933Srs  *
14664b22b933Srs  * regtype:         The service type, which is usually (but not always) the same as was passed
14674b22b933Srs  *                  to DNSServiceBrowse(). One case where the discovered service type may
14684b22b933Srs  *                  not be the same as the requested service type is when using subtypes:
14694b22b933Srs  *                  The client may want to browse for only those ftp servers that allow
14704b22b933Srs  *                  anonymous connections. The client will pass the string "_ftp._tcp,_anon"
14714b22b933Srs  *                  to DNSServiceBrowse(), but the type of the service that's discovered
14724b22b933Srs  *                  is simply "_ftp._tcp". The regtype for each discovered service instance
14734b22b933Srs  *                  should be stored along with the name, so that it can be passed to
14744b22b933Srs  *                  DNSServiceResolve() when the service is later resolved.
14754b22b933Srs  *
14764b22b933Srs  * domain:          The domain of the discovered service instance. This may or may not be the
14774b22b933Srs  *                  same as the domain that was passed to DNSServiceBrowse(). The domain for each
14784b22b933Srs  *                  discovered service instance should be stored along with the name, so that
14794b22b933Srs  *                  it can be passed to DNSServiceResolve() when the service is later resolved.
14804b22b933Srs  *
14814b22b933Srs  * context:         The context pointer that was passed to the callout.
14824b22b933Srs  *
14834b22b933Srs  */
14844b22b933Srs 
14854b22b933Srs typedef void (DNSSD_API *DNSServiceBrowseReply)
14865ffb0c9bSToomas Soome (
14875ffb0c9bSToomas Soome     DNSServiceRef sdRef,
14885ffb0c9bSToomas Soome     DNSServiceFlags flags,
14895ffb0c9bSToomas Soome     uint32_t interfaceIndex,
14905ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
14914b22b933Srs     const char                          *serviceName,
14924b22b933Srs     const char                          *regtype,
14934b22b933Srs     const char                          *replyDomain,
14944b22b933Srs     void                                *context
14955ffb0c9bSToomas Soome );
14964b22b933Srs 
14974b22b933Srs 
14984b22b933Srs /* DNSServiceBrowse() Parameters:
14994b22b933Srs  *
1500*472cd20dSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef
1501*472cd20dSToomas Soome  *                  (or, if the kDNSServiceFlagsShareConnection flag is used,
1502*472cd20dSToomas Soome  *                  a copy of the shared connection reference that is to be used).
1503*472cd20dSToomas Soome  *                  If the call succeeds then it initializes (or updates) the DNSServiceRef,
1504*472cd20dSToomas Soome  *                  returns kDNSServiceErr_NoError, and the browse operation
1505*472cd20dSToomas Soome  *                  will remain active indefinitely until the client terminates it
1506*472cd20dSToomas Soome  *                  by passing this DNSServiceRef to DNSServiceRefDeallocate()
1507*472cd20dSToomas Soome  *                  (or by closing the underlying shared connection, if used).
15084b22b933Srs  *
1509*472cd20dSToomas Soome  * flags:           Possible values are:
1510*472cd20dSToomas Soome  *                  kDNSServiceFlagsShareConnection to use a shared connection.
15114b22b933Srs  *
15124b22b933Srs  * interfaceIndex:  If non-zero, specifies the interface on which to browse for services
15134b22b933Srs  *                  (the index for a given interface is determined via the if_nametoindex()
15145ffb0c9bSToomas Soome  *                  family of calls.) Most applications will pass 0 to browse on all available
15154b22b933Srs  *                  interfaces. See "Constants for specifying an interface index" for more details.
15164b22b933Srs  *
15174b22b933Srs  * regtype:         The service type being browsed for followed by the protocol, separated by a
15185ffb0c9bSToomas Soome  *                  dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
15195ffb0c9bSToomas Soome  *                  A client may optionally specify a single subtype to perform filtered browsing:
15205ffb0c9bSToomas Soome  *                  e.g. browsing for "_primarytype._tcp,_subtype" will discover only those
15215ffb0c9bSToomas Soome  *                  instances of "_primarytype._tcp" that were registered specifying "_subtype"
1522*472cd20dSToomas Soome  *                  in their list of registered subtypes.
15234b22b933Srs  *
15244b22b933Srs  * domain:          If non-NULL, specifies the domain on which to browse for services.
15254b22b933Srs  *                  Most applications will not specify a domain, instead browsing on the
15264b22b933Srs  *                  default domain(s).
15274b22b933Srs  *
15284b22b933Srs  * callBack:        The function to be called when an instance of the service being browsed for
15294b22b933Srs  *                  is found, or if the call asynchronously fails.
15304b22b933Srs  *
15314b22b933Srs  * context:         An application context pointer which is passed to the callback function
15324b22b933Srs  *                  (may be NULL).
15334b22b933Srs  *
15345ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
15354b22b933Srs  *                  errors are delivered to the callback), otherwise returns an error code indicating
15364b22b933Srs  *                  the error that occurred (the callback is not invoked and the DNSServiceRef
15375ffb0c9bSToomas Soome  *                  is not initialized).
15384b22b933Srs  */
15394b22b933Srs 
15403b436d06SToomas Soome DNSSD_EXPORT
15414b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceBrowse
15425ffb0c9bSToomas Soome (
15434b22b933Srs     DNSServiceRef                       *sdRef,
15445ffb0c9bSToomas Soome     DNSServiceFlags flags,
15455ffb0c9bSToomas Soome     uint32_t interfaceIndex,
15464b22b933Srs     const char                          *regtype,
15474b22b933Srs     const char                          *domain,    /* may be NULL */
15485ffb0c9bSToomas Soome     DNSServiceBrowseReply callBack,
15494b22b933Srs     void                                *context    /* may be NULL */
15505ffb0c9bSToomas Soome );
15514b22b933Srs 
15524b22b933Srs 
15534b22b933Srs /* DNSServiceResolve()
15544b22b933Srs  *
15554b22b933Srs  * Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and
15564b22b933Srs  * txt record.
15574b22b933Srs  *
15584b22b933Srs  * Note: Applications should NOT use DNSServiceResolve() solely for txt record monitoring - use
15594b22b933Srs  * DNSServiceQueryRecord() instead, as it is more efficient for this task.
15604b22b933Srs  *
15614b22b933Srs  * Note: When the desired results have been returned, the client MUST terminate the resolve by calling
15624b22b933Srs  * DNSServiceRefDeallocate().
15634b22b933Srs  *
15644b22b933Srs  * Note: DNSServiceResolve() behaves correctly for typical services that have a single SRV record
15654b22b933Srs  * and a single TXT record. To resolve non-standard services with multiple SRV or TXT records,
15664b22b933Srs  * DNSServiceQueryRecord() should be used.
15674b22b933Srs  *
15684b22b933Srs  * DNSServiceResolveReply Callback Parameters:
15694b22b933Srs  *
15704b22b933Srs  * sdRef:           The DNSServiceRef initialized by DNSServiceResolve().
15714b22b933Srs  *
15725ffb0c9bSToomas Soome  * flags:           Possible values: kDNSServiceFlagsMoreComing
15734b22b933Srs  *
15744b22b933Srs  * interfaceIndex:  The interface on which the service was resolved.
15754b22b933Srs  *
15764b22b933Srs  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise will
15775ffb0c9bSToomas Soome  *                  indicate the failure that occurred. Other parameters are undefined if
15784b22b933Srs  *                  the errorCode is nonzero.
15794b22b933Srs  *
15804b22b933Srs  * fullname:        The full service domain name, in the form <servicename>.<protocol>.<domain>.
15814b22b933Srs  *                  (This name is escaped following standard DNS rules, making it suitable for
15824b22b933Srs  *                  passing to standard system DNS APIs such as res_query(), or to the
15834b22b933Srs  *                  special-purpose functions included in this API that take fullname parameters.
15844b22b933Srs  *                  See "Notes on DNS Name Escaping" earlier in this file for more details.)
15854b22b933Srs  *
15865ffb0c9bSToomas Soome  * hosttarget:      The target hostname of the machine providing the service. This name can
15874b22b933Srs  *                  be passed to functions like gethostbyname() to identify the host's IP address.
15884b22b933Srs  *
15894b22b933Srs  * port:            The port, in network byte order, on which connections are accepted for this service.
15904b22b933Srs  *
15914b22b933Srs  * txtLen:          The length of the txt record, in bytes.
15924b22b933Srs  *
15934b22b933Srs  * txtRecord:       The service's primary txt record, in standard txt record format.
15944b22b933Srs  *
15954b22b933Srs  * context:         The context pointer that was passed to the callout.
15964b22b933Srs  *
15974b22b933Srs  * NOTE: In earlier versions of this header file, the txtRecord parameter was declared "const char *"
15984b22b933Srs  * This is incorrect, since it contains length bytes which are values in the range 0 to 255, not -128 to +127.
15994b22b933Srs  * Depending on your compiler settings, this change may cause signed/unsigned mismatch warnings.
16004b22b933Srs  * These should be fixed by updating your own callback function definition to match the corrected
16014b22b933Srs  * function signature using "const unsigned char *txtRecord". Making this change may also fix inadvertent
16024b22b933Srs  * bugs in your callback function, where it could have incorrectly interpreted a length byte with value 250
16034b22b933Srs  * as being -6 instead, with various bad consequences ranging from incorrect operation to software crashes.
16044b22b933Srs  * If you need to maintain portable code that will compile cleanly with both the old and new versions of
16054b22b933Srs  * this header file, you should update your callback function definition to use the correct unsigned value,
16064b22b933Srs  * and then in the place where you pass your callback function to DNSServiceResolve(), use a cast to eliminate
16074b22b933Srs  * the compiler warning, e.g.:
16084b22b933Srs  *   DNSServiceResolve(sd, flags, index, name, regtype, domain, (DNSServiceResolveReply)MyCallback, context);
16094b22b933Srs  * This will ensure that your code compiles cleanly without warnings (and more importantly, works correctly)
16104b22b933Srs  * with both the old header and with the new corrected version.
16114b22b933Srs  *
16124b22b933Srs  */
16134b22b933Srs 
16144b22b933Srs typedef void (DNSSD_API *DNSServiceResolveReply)
16155ffb0c9bSToomas Soome (
16165ffb0c9bSToomas Soome     DNSServiceRef sdRef,
16175ffb0c9bSToomas Soome     DNSServiceFlags flags,
16185ffb0c9bSToomas Soome     uint32_t interfaceIndex,
16195ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
16204b22b933Srs     const char                          *fullname,
16214b22b933Srs     const char                          *hosttarget,
16225ffb0c9bSToomas Soome     uint16_t port,                                   /* In network byte order */
16235ffb0c9bSToomas Soome     uint16_t txtLen,
16244b22b933Srs     const unsigned char                 *txtRecord,
16254b22b933Srs     void                                *context
16265ffb0c9bSToomas Soome );
16274b22b933Srs 
16284b22b933Srs 
16294b22b933Srs /* DNSServiceResolve() Parameters
16304b22b933Srs  *
1631*472cd20dSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef
1632*472cd20dSToomas Soome  *                  (or, if the kDNSServiceFlagsShareConnection flag is used,
1633*472cd20dSToomas Soome  *                  a copy of the shared connection reference that is to be used).
1634*472cd20dSToomas Soome  *                  If the call succeeds then it initializes (or updates) the DNSServiceRef,
1635*472cd20dSToomas Soome  *                  returns kDNSServiceErr_NoError, and the resolve operation
1636*472cd20dSToomas Soome  *                  will remain active indefinitely until the client terminates it
1637*472cd20dSToomas Soome  *                  by passing this DNSServiceRef to DNSServiceRefDeallocate()
1638*472cd20dSToomas Soome  *                  (or by closing the underlying shared connection, if used).
16394b22b933Srs  *
1640*472cd20dSToomas Soome  * flags:           Possible values are:
1641*472cd20dSToomas Soome  *                  kDNSServiceFlagsShareConnection to use a shared connection.
1642*472cd20dSToomas Soome  *                  Specifying kDNSServiceFlagsForceMulticast will cause query to be
16435ffb0c9bSToomas Soome  *                  performed with a link-local mDNS query, even if the name is an
16445ffb0c9bSToomas Soome  *                  apparently non-local name (i.e. a name not ending in ".local.")
16454b22b933Srs  *
16464b22b933Srs  * interfaceIndex:  The interface on which to resolve the service. If this resolve call is
16474b22b933Srs  *                  as a result of a currently active DNSServiceBrowse() operation, then the
16484b22b933Srs  *                  interfaceIndex should be the index reported in the DNSServiceBrowseReply
16494b22b933Srs  *                  callback. If this resolve call is using information previously saved
16504b22b933Srs  *                  (e.g. in a preference file) for later use, then use interfaceIndex 0, because
16514b22b933Srs  *                  the desired service may now be reachable via a different physical interface.
16524b22b933Srs  *                  See "Constants for specifying an interface index" for more details.
16534b22b933Srs  *
16544b22b933Srs  * name:            The name of the service instance to be resolved, as reported to the
16554b22b933Srs  *                  DNSServiceBrowseReply() callback.
16564b22b933Srs  *
16574b22b933Srs  * regtype:         The type of the service instance to be resolved, as reported to the
16584b22b933Srs  *                  DNSServiceBrowseReply() callback.
16594b22b933Srs  *
16604b22b933Srs  * domain:          The domain of the service instance to be resolved, as reported to the
16614b22b933Srs  *                  DNSServiceBrowseReply() callback.
16624b22b933Srs  *
16634b22b933Srs  * callBack:        The function to be called when a result is found, or if the call
16644b22b933Srs  *                  asynchronously fails.
16654b22b933Srs  *
16664b22b933Srs  * context:         An application context pointer which is passed to the callback function
16674b22b933Srs  *                  (may be NULL).
16684b22b933Srs  *
16695ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
16704b22b933Srs  *                  errors are delivered to the callback), otherwise returns an error code indicating
16714b22b933Srs  *                  the error that occurred (the callback is never invoked and the DNSServiceRef
16725ffb0c9bSToomas Soome  *                  is not initialized).
16734b22b933Srs  */
16744b22b933Srs 
16753b436d06SToomas Soome DNSSD_EXPORT
16764b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceResolve
16775ffb0c9bSToomas Soome (
16784b22b933Srs     DNSServiceRef                       *sdRef,
16795ffb0c9bSToomas Soome     DNSServiceFlags flags,
16805ffb0c9bSToomas Soome     uint32_t interfaceIndex,
16814b22b933Srs     const char                          *name,
16824b22b933Srs     const char                          *regtype,
16834b22b933Srs     const char                          *domain,
16845ffb0c9bSToomas Soome     DNSServiceResolveReply callBack,
16854b22b933Srs     void                                *context  /* may be NULL */
16865ffb0c9bSToomas Soome );
16874b22b933Srs 
16884b22b933Srs 
16894b22b933Srs /*********************************************************************************************
16905ffb0c9bSToomas Soome *
16915ffb0c9bSToomas Soome *  Querying Individual Specific Records
16925ffb0c9bSToomas Soome *
16935ffb0c9bSToomas Soome *********************************************************************************************/
16945ffb0c9bSToomas Soome 
16955ffb0c9bSToomas Soome /* DNSServiceQueryRecord
16965ffb0c9bSToomas Soome  *
16975ffb0c9bSToomas Soome  * Query for an arbitrary DNS record.
16985ffb0c9bSToomas Soome  *
16995ffb0c9b