14b22b933Srs /* -*- Mode: C; tab-width: 4 -*-
24b22b933Srs  *
3*3b436d06SToomas 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*3b436d06SToomas Soome #define _DNS_SD_H 8806001
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  */
78*3b436d06SToomas Soome #if defined(__APPLE__)
79*3b436d06SToomas Soome #define _DNS_SD_LIBDISPATCH 1
80*3b436d06SToomas Soome #else
815ffb0c9bSToomas Soome #define _DNS_SD_LIBDISPATCH 0
82*3b436d06SToomas 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 
93*3b436d06SToomas Soome #if (defined(__GNUC__) && (__GNUC__ >= 4))
94*3b436d06SToomas Soome #define DNSSD_EXPORT __attribute__((visibility("default")))
95*3b436d06SToomas Soome #else
96*3b436d06SToomas Soome #define DNSSD_EXPORT
97*3b436d06SToomas Soome #endif
98*3b436d06SToomas 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.
200c65ebfc7SToomas Soome      * Will auto trigger the browse over AWDL as well once the service is discoveryed
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      * Currently only valid for a DNSServiceRegister call.
2605ffb0c9bSToomas Soome      */
2615ffb0c9bSToomas Soome 
2625ffb0c9bSToomas Soome     kDNSServiceFlagsReturnIntermediates = 0x1000,
2635ffb0c9bSToomas Soome     /* Flag for returning intermediate results.
2645ffb0c9bSToomas Soome      * For example, if a query results in an authoritative NXDomain (name does not exist)
2655ffb0c9bSToomas Soome      * then that result is returned to the client. However the query is not implicitly
2665ffb0c9bSToomas Soome      * cancelled -- it remains active and if the answer subsequently changes
2675ffb0c9bSToomas Soome      * (e.g. because a VPN tunnel is subsequently established) then that positive
2685ffb0c9bSToomas Soome      * result will still be returned to the client.
2695ffb0c9bSToomas Soome      * Similarly, if a query results in a CNAME record, then in addition to following
2705ffb0c9bSToomas Soome      * the CNAME referral, the intermediate CNAME result is also returned to the client.
2715ffb0c9bSToomas Soome      * When this flag is not set, NXDomain errors are not returned, and CNAME records
2725ffb0c9bSToomas Soome      * are followed silently without informing the client of the intermediate steps.
2735ffb0c9bSToomas Soome      * (In earlier builds this flag was briefly calledkDNSServiceFlagsReturnCNAME)
2745ffb0c9bSToomas Soome      */
2755ffb0c9bSToomas Soome 
2765ffb0c9bSToomas Soome     kDNSServiceFlagsNonBrowsable        = 0x2000,
2775ffb0c9bSToomas Soome     /* A service registered with the NonBrowsable flag set can be resolved using
2785ffb0c9bSToomas Soome      * DNSServiceResolve(), but will not be discoverable using DNSServiceBrowse().
2795ffb0c9bSToomas Soome      * This is for cases where the name is actually a GUID; it is found by other means;
2805ffb0c9bSToomas Soome      * there is no end-user benefit to browsing to find a long list of opaque GUIDs.
2815ffb0c9bSToomas Soome      * Using the NonBrowsable flag creates SRV+TXT without the cost of also advertising
2825ffb0c9bSToomas Soome      * an associated PTR record.
2835ffb0c9bSToomas Soome      */
2845ffb0c9bSToomas Soome 
2855ffb0c9bSToomas Soome     kDNSServiceFlagsShareConnection     = 0x4000,
2865ffb0c9bSToomas Soome     /* For efficiency, clients that perform many concurrent operations may want to use a
2875ffb0c9bSToomas Soome      * single Unix Domain Socket connection with the background daemon, instead of having a
2885ffb0c9bSToomas Soome      * separate connection for each independent operation. To use this mode, clients first
2895ffb0c9bSToomas Soome      * call DNSServiceCreateConnection(&MainRef) to initialize the main DNSServiceRef.
2905ffb0c9bSToomas Soome      * For each subsequent operation that is to share that same connection, the client copies
2915ffb0c9bSToomas Soome      * the MainRef, and then passes the address of that copy, setting the ShareConnection flag
2925ffb0c9bSToomas Soome      * to tell the library that this DNSServiceRef is not a typical uninitialized DNSServiceRef;
2935ffb0c9bSToomas Soome      * it's a copy of an existing DNSServiceRef whose connection information should be reused.
2945ffb0c9bSToomas Soome      *
2955ffb0c9bSToomas Soome      * For example:
2965ffb0c9bSToomas Soome      *
2975ffb0c9bSToomas Soome      * DNSServiceErrorType error;
2985ffb0c9bSToomas Soome      * DNSServiceRef MainRef;
2995ffb0c9bSToomas Soome      * error = DNSServiceCreateConnection(&MainRef);
3005ffb0c9bSToomas Soome      * if (error) ...
3015ffb0c9bSToomas Soome      * DNSServiceRef BrowseRef = MainRef;  // Important: COPY the primary DNSServiceRef first...
3025ffb0c9bSToomas Soome      * error = DNSServiceBrowse(&BrowseRef, kDNSServiceFlagsShareConnection, ...); // then use the copy
3035ffb0c9bSToomas Soome      * if (error) ...
3045ffb0c9bSToomas Soome      * ...
3055ffb0c9bSToomas Soome      * DNSServiceRefDeallocate(BrowseRef); // Terminate the browse operation
3065ffb0c9bSToomas Soome      * DNSServiceRefDeallocate(MainRef);   // Terminate the shared connection
3075ffb0c9bSToomas Soome      * Also see Point 4.(Don't Double-Deallocate if the MainRef has been Deallocated) in Notes below:
3085ffb0c9bSToomas Soome      *
3095ffb0c9bSToomas Soome      * Notes:
3105ffb0c9bSToomas Soome      *
3115ffb0c9bSToomas Soome      * 1. Collective kDNSServiceFlagsMoreComing flag
3125ffb0c9bSToomas Soome      * When callbacks are invoked using a shared DNSServiceRef, the
3135ffb0c9bSToomas Soome      * kDNSServiceFlagsMoreComing flag applies collectively to *all* active
3145ffb0c9bSToomas Soome      * operations sharing the same parent DNSServiceRef. If the MoreComing flag is
3155ffb0c9bSToomas Soome      * set it means that there are more results queued on this parent DNSServiceRef,
3165ffb0c9bSToomas Soome      * but not necessarily more results for this particular callback function.
3175ffb0c9bSToomas Soome      * The implication of this for client programmers is that when a callback
3185ffb0c9bSToomas Soome      * is invoked with the MoreComing flag set, the code should update its
3195ffb0c9bSToomas Soome      * internal data structures with the new result, and set a variable indicating
3205ffb0c9bSToomas Soome      * that its UI needs to be updated. Then, later when a callback is eventually
3215ffb0c9bSToomas Soome      * invoked with the MoreComing flag not set, the code should update *all*
3225ffb0c9bSToomas Soome      * stale UI elements related to that shared parent DNSServiceRef that need
3235ffb0c9bSToomas Soome      * updating, not just the UI elements related to the particular callback
3245ffb0c9bSToomas Soome      * that happened to be the last one to be invoked.
3255ffb0c9bSToomas Soome      *
3265ffb0c9bSToomas Soome      * 2. Canceling operations and kDNSServiceFlagsMoreComing
3275ffb0c9bSToomas Soome      * Whenever you cancel any operation for which you had deferred UI updates
3285ffb0c9bSToomas Soome      * waiting because of a kDNSServiceFlagsMoreComing flag, you should perform
3295ffb0c9bSToomas Soome      * those deferred UI updates. This is because, after cancelling the operation,
3305ffb0c9bSToomas Soome      * you can no longer wait for a callback *without* MoreComing set, to tell
3315ffb0c9bSToomas Soome      * you do perform your deferred UI updates (the operation has been canceled,
3325ffb0c9bSToomas Soome      * so there will be no more callbacks). An implication of the collective
3335ffb0c9bSToomas Soome      * kDNSServiceFlagsMoreComing flag for shared connections is that this
3345ffb0c9bSToomas Soome      * guideline applies more broadly -- any time you cancel an operation on
3355ffb0c9bSToomas Soome      * a shared connection, you should perform all deferred UI updates for all
3365ffb0c9bSToomas Soome      * operations sharing that connection. This is because the MoreComing flag
3375ffb0c9bSToomas Soome      * might have been referring to events coming for the operation you canceled,
3385ffb0c9bSToomas Soome      * which will now not be coming because the operation has been canceled.
3395ffb0c9bSToomas Soome      *
3405ffb0c9bSToomas Soome      * 3. Only share DNSServiceRef's created with DNSServiceCreateConnection
3415ffb0c9bSToomas Soome      * Calling DNSServiceCreateConnection(&ref) creates a special shareable DNSServiceRef.
3425ffb0c9bSToomas Soome      * DNSServiceRef's created by other calls like DNSServiceBrowse() or DNSServiceResolve()
3435ffb0c9bSToomas Soome      * cannot be shared by copying them and using kDNSServiceFlagsShareConnection.
3445ffb0c9bSToomas Soome      *
3455ffb0c9bSToomas Soome      * 4. Don't Double-Deallocate if the MainRef has been Deallocated
3465ffb0c9bSToomas Soome      * Calling DNSServiceRefDeallocate(ref) for a particular operation's DNSServiceRef terminates
3475ffb0c9bSToomas Soome      * just that operation. Calling DNSServiceRefDeallocate(ref) for the main shared DNSServiceRef
3485ffb0c9bSToomas Soome      * (the parent DNSServiceRef, originally created by DNSServiceCreateConnection(&ref))
3495ffb0c9bSToomas Soome      * automatically terminates the shared connection and all operations that were still using it.
3505ffb0c9bSToomas Soome      * After doing this, DO NOT then attempt to deallocate any remaining subordinate DNSServiceRef's.
3515ffb0c9bSToomas Soome      * The memory used by those subordinate DNSServiceRef's has already been freed, so any attempt
3525ffb0c9bSToomas Soome      * to do a DNSServiceRefDeallocate (or any other operation) on them will result in accesses
3535ffb0c9bSToomas Soome      * to freed memory, leading to crashes or other equally undesirable results.
3545ffb0c9bSToomas Soome      *
3555ffb0c9bSToomas Soome      * 5. Thread Safety
3565ffb0c9bSToomas Soome      * The dns_sd.h API does not presuppose any particular threading model, and consequently
357c65ebfc7SToomas Soome      * does no locking internally (which would require linking with a specific threading library).
358c65ebfc7SToomas Soome      * If the client concurrently, from multiple threads (or contexts), calls API routines using
359c65ebfc7SToomas Soome      * the same DNSServiceRef, it is the client's responsibility to provide mutual exclusion for
360c65ebfc7SToomas Soome      * that DNSServiceRef.
361c65ebfc7SToomas Soome 
362c65ebfc7SToomas Soome      * For example, use of DNSServiceRefDeallocate requires caution. A common mistake is as follows:
363c65ebfc7SToomas Soome      * Thread B calls DNSServiceRefDeallocate to deallocate sdRef while Thread A is processing events
364c65ebfc7SToomas Soome      * using sdRef. Doing this will lead to intermittent crashes on thread A if the sdRef is used after
365c65ebfc7SToomas Soome      * it was deallocated.
366c65ebfc7SToomas Soome 
367c65ebfc7SToomas Soome      * A telltale sign of this crash type is to see DNSServiceProcessResult on the stack preceding the
368c65ebfc7SToomas Soome      * actual crash location.
369c65ebfc7SToomas Soome 
370c65ebfc7SToomas Soome      * To state this more explicitly, mDNSResponder does not queue DNSServiceRefDeallocate so
371c65ebfc7SToomas Soome      * that it occurs discretely before or after an event is handled.
3725ffb0c9bSToomas Soome      */
3735ffb0c9bSToomas Soome 
3745ffb0c9bSToomas Soome     kDNSServiceFlagsSuppressUnusable    = 0x8000,
3755ffb0c9bSToomas Soome     /*
3765ffb0c9bSToomas Soome      * This flag is meaningful only in DNSServiceQueryRecord which suppresses unusable queries on the
3775ffb0c9bSToomas Soome      * wire. If "hostname" is a wide-area unicast DNS hostname (i.e. not a ".local." name)
3785ffb0c9bSToomas Soome      * but this host has no routable IPv6 address, then the call will not try to look up IPv6 addresses
3795ffb0c9bSToomas Soome      * for "hostname", since any addresses it found would be unlikely to be of any use anyway. Similarly,
3805ffb0c9bSToomas Soome      * if this host has no routable IPv4 address, the call will not try to look up IPv4 addresses for
3815ffb0c9bSToomas Soome      * "hostname".
3825ffb0c9bSToomas Soome      */
3835ffb0c9bSToomas Soome 
3845ffb0c9bSToomas Soome     kDNSServiceFlagsTimeout            = 0x10000,
3855ffb0c9bSToomas Soome     /*
3865ffb0c9bSToomas Soome      * When kDNServiceFlagsTimeout is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo, the query is
3875ffb0c9bSToomas Soome      * stopped after a certain number of seconds have elapsed. The time at which the query will be stopped
3885ffb0c9bSToomas Soome      * is determined by the system and cannot be configured by the user. The query will be stopped irrespective
3895ffb0c9bSToomas Soome      * of whether a response was given earlier or not. When the query is stopped, the callback will be called
3905ffb0c9bSToomas Soome      * with an error code of kDNSServiceErr_Timeout and a NULL sockaddr will be returned for DNSServiceGetAddrInfo
3915ffb0c9bSToomas Soome      * and zero length rdata will be returned for DNSServiceQueryRecord.
3925ffb0c9bSToomas Soome      */
3935ffb0c9bSToomas Soome 
3945ffb0c9bSToomas Soome     kDNSServiceFlagsIncludeP2P          = 0x20000,
3955ffb0c9bSToomas Soome     /*
3965ffb0c9bSToomas Soome      * Include P2P interfaces when kDNSServiceInterfaceIndexAny is specified.
3975ffb0c9bSToomas Soome      * By default, specifying kDNSServiceInterfaceIndexAny does not include P2P interfaces.
3985ffb0c9bSToomas Soome      */
3995ffb0c9bSToomas Soome 
4005ffb0c9bSToomas Soome     kDNSServiceFlagsWakeOnResolve      = 0x40000,
4015ffb0c9bSToomas Soome     /*
4025ffb0c9bSToomas Soome     * This flag is meaningful only in DNSServiceResolve. When set, it tries to send a magic packet
4035ffb0c9bSToomas Soome     * to wake up the client.
4045ffb0c9bSToomas Soome     */
4055ffb0c9bSToomas Soome 
4065ffb0c9bSToomas Soome     kDNSServiceFlagsBackgroundTrafficClass  = 0x80000,
4075ffb0c9bSToomas Soome     /*
408c65ebfc7SToomas Soome     * This flag is meaningful for Unicast DNS queries. When set, it uses the background traffic
4095ffb0c9bSToomas Soome     * class for packets that service the request.
4105ffb0c9bSToomas Soome     */
4115ffb0c9bSToomas Soome 
4125ffb0c9bSToomas Soome     kDNSServiceFlagsIncludeAWDL      = 0x100000,
4135ffb0c9bSToomas Soome    /*
4145ffb0c9bSToomas Soome     * Include AWDL interface when kDNSServiceInterfaceIndexAny is specified.
4155ffb0c9bSToomas Soome     */
4165ffb0c9bSToomas Soome 
4175ffb0c9bSToomas Soome     kDNSServiceFlagsValidate               = 0x200000,
4185ffb0c9bSToomas Soome    /*
419c65ebfc7SToomas Soome     * This flag is meaningful in DNSServiceGetAddrInfo and DNSServiceQueryRecord. This is the ONLY flag to be valid
4205ffb0c9bSToomas Soome     * as an input to the APIs and also an output through the callbacks in the APIs.
4215ffb0c9bSToomas Soome     *
422c65ebfc7SToomas Soome     * When this flag is passed to DNSServiceQueryRecord and DNSServiceGetAddrInfo to resolve unicast names,
423c65ebfc7SToomas Soome     * the response  will be validated using DNSSEC. The validation results are delivered using the flags field in
4245ffb0c9bSToomas Soome     * the callback and kDNSServiceFlagsValidate is marked in the flags to indicate that DNSSEC status is also available.
425c65ebfc7SToomas Soome     * When the callback is called to deliver the query results, the validation results may or may not be available.
4265ffb0c9bSToomas Soome     * If it is not delivered along with the results, the validation status is delivered when the validation completes.
427c65ebfc7SToomas Soome     *
4285ffb0c9bSToomas Soome     * When the validation results are delivered in the callback, it is indicated by marking the flags with
4295ffb0c9bSToomas Soome     * kDNSServiceFlagsValidate and kDNSServiceFlagsAdd along with the DNSSEC status flags (described below) and a NULL
4305ffb0c9bSToomas Soome     * sockaddr will be returned for DNSServiceGetAddrInfo and zero length rdata will be returned for DNSServiceQueryRecord.
4315ffb0c9bSToomas Soome     * DNSSEC validation results are for the whole RRSet and not just individual records delivered in the callback. When
432c65ebfc7SToomas Soome     * kDNSServiceFlagsAdd is not set in the flags, applications should implicitly assume that the DNSSEC status of the
4335ffb0c9bSToomas Soome     * RRSet that has been delivered up until that point is not valid anymore, till another callback is called with
4345ffb0c9bSToomas Soome     * kDNSServiceFlagsAdd and kDNSServiceFlagsValidate.
4355ffb0c9bSToomas Soome     *
4365ffb0c9bSToomas Soome     * The following four flags indicate the status of the DNSSEC validation and marked in the flags field of the callback.
437c65ebfc7SToomas Soome     * When any of the four flags is set, kDNSServiceFlagsValidate will also be set. To check the validation status, the
4385ffb0c9bSToomas Soome     * other applicable output flags should be masked. See kDNSServiceOutputFlags below.
4395ffb0c9bSToomas Soome     */
4405ffb0c9bSToomas Soome 
4415ffb0c9bSToomas Soome     kDNSServiceFlagsSecure                 = 0x200010,
4425ffb0c9bSToomas Soome    /*
443c65ebfc7SToomas Soome     * The response has been validated by verifying all the signatures in the response and was able to
444c65ebfc7SToomas Soome     * build a successful authentication chain starting from a known trust anchor.
4455ffb0c9bSToomas Soome     */
4465ffb0c9bSToomas Soome 
4475ffb0c9bSToomas Soome     kDNSServiceFlagsInsecure               = 0x200020,
4485ffb0c9bSToomas Soome    /*
4495ffb0c9bSToomas Soome     * A chain of trust cannot be built starting from a known trust anchor to the response.
4505ffb0c9bSToomas Soome     */
4515ffb0c9bSToomas Soome 
4525ffb0c9bSToomas Soome     kDNSServiceFlagsBogus                  = 0x200040,
4535ffb0c9bSToomas Soome    /*
4545ffb0c9bSToomas Soome     * If the response cannot be verified to be secure due to expired signatures, missing signatures etc.,
4555ffb0c9bSToomas Soome     * then the results are considered to be bogus.
4565ffb0c9bSToomas Soome     */
4575ffb0c9bSToomas Soome 
4585ffb0c9bSToomas Soome     kDNSServiceFlagsIndeterminate          = 0x200080,
4595ffb0c9bSToomas Soome    /*
4605ffb0c9bSToomas Soome     * There is no valid trust anchor that can be used to determine whether a response is secure or not.
4615ffb0c9bSToomas Soome     */
4625ffb0c9bSToomas Soome 
4635ffb0c9bSToomas Soome     kDNSServiceFlagsUnicastResponse        = 0x400000,
4645ffb0c9bSToomas Soome    /*
4655ffb0c9bSToomas Soome     * Request unicast response to query.
4665ffb0c9bSToomas Soome     */
4675ffb0c9bSToomas Soome     kDNSServiceFlagsValidateOptional       = 0x800000,
4685ffb0c9bSToomas Soome 
4695ffb0c9bSToomas Soome     /*
4705ffb0c9bSToomas Soome      * This flag is identical to kDNSServiceFlagsValidate except for the case where the response
4715ffb0c9bSToomas Soome      * cannot be validated. If this flag is set in DNSServiceQueryRecord or DNSServiceGetAddrInfo,
4725ffb0c9bSToomas Soome      * the DNSSEC records will be requested for validation. If they cannot be received for some reason
4735ffb0c9bSToomas Soome      * during the validation (e.g., zone is not signed, zone is signed but cannot be traced back to
4745ffb0c9bSToomas Soome      * root, recursive server does not understand DNSSEC etc.), then this will fallback to the default
4755ffb0c9bSToomas Soome      * behavior where the validation will not be performed and no DNSSEC results will be provided.
4765ffb0c9bSToomas Soome      *
4775ffb0c9bSToomas Soome      * If the zone is signed and there is a valid path to a known trust anchor configured in the system
4785ffb0c9bSToomas Soome      * and the application requires DNSSEC validation irrespective of the DNSSEC awareness in the current
4795ffb0c9bSToomas Soome      * network, then this option MUST not be used. This is only intended to be used during the transition
4805ffb0c9bSToomas Soome      * period where the different nodes participating in the DNS resolution may not understand DNSSEC or
4815ffb0c9bSToomas Soome      * managed properly (e.g. missing DS record) but still want to be able to resolve DNS successfully.
4825ffb0c9bSToomas Soome      */
4835ffb0c9bSToomas Soome 
4845ffb0c9bSToomas Soome     kDNSServiceFlagsWakeOnlyService        = 0x1000000,
4855ffb0c9bSToomas Soome     /*
4865ffb0c9bSToomas Soome      * This flag is meaningful only in DNSServiceRegister. When set, the service will not be registered
4875ffb0c9bSToomas Soome      * with sleep proxy server during sleep.
4885ffb0c9bSToomas Soome      */
4895ffb0c9bSToomas Soome 
4905ffb0c9bSToomas Soome     kDNSServiceFlagsThresholdOne           = 0x2000000,
4915ffb0c9bSToomas Soome     kDNSServiceFlagsThresholdFinder        = 0x4000000,
4925ffb0c9bSToomas Soome     kDNSServiceFlagsThresholdReached       = kDNSServiceFlagsThresholdOne,
4935ffb0c9bSToomas Soome     /*
4945ffb0c9bSToomas Soome      * kDNSServiceFlagsThresholdOne is meaningful only in DNSServiceBrowse. When set,
4955ffb0c9bSToomas Soome      * the system will stop issuing browse queries on the network once the number
4965ffb0c9bSToomas Soome      * of answers returned is one or more.  It will issue queries on the network
4975ffb0c9bSToomas Soome      * again if the number of answers drops to zero.
4985ffb0c9bSToomas Soome      * This flag is for Apple internal use only. Third party developers
4995ffb0c9bSToomas Soome      * should not rely on this behavior being supported in any given software release.
5005ffb0c9bSToomas Soome      *
5015ffb0c9bSToomas Soome      * kDNSServiceFlagsThresholdFinder is meaningful only in DNSServiceBrowse. When set,
5025ffb0c9bSToomas Soome      * the system will stop issuing browse queries on the network once the number
5035ffb0c9bSToomas Soome      * of answers has reached the threshold set for Finder.
5045ffb0c9bSToomas Soome      * It will issue queries on the network again if the number of answers drops below
5055ffb0c9bSToomas Soome      * this threshold.
5065ffb0c9bSToomas Soome      * This flag is for Apple internal use only. Third party developers
5075ffb0c9bSToomas Soome      * should not rely on this behavior being supported in any given software release.
5085ffb0c9bSToomas Soome      *
5095ffb0c9bSToomas Soome      * When kDNSServiceFlagsThresholdReached is set in the client callback add or remove event,
510c65ebfc7SToomas Soome      * it indicates that the browse answer threshold has been reached and no
5115ffb0c9bSToomas Soome      * browse requests will be generated on the network until the number of answers falls
5125ffb0c9bSToomas Soome      * below the threshold value.  Add and remove events can still occur based
5135ffb0c9bSToomas Soome      * on incoming Bonjour traffic observed by the system.
514c65ebfc7SToomas Soome      * The set of services return to the client is not guaranteed to represent the
5155ffb0c9bSToomas Soome      * entire set of services present on the network once the threshold has been reached.
5165ffb0c9bSToomas Soome      *
5175ffb0c9bSToomas Soome      * Note, while kDNSServiceFlagsThresholdReached and kDNSServiceFlagsThresholdOne
5185ffb0c9bSToomas Soome      * have the same value, there  isn't a conflict because kDNSServiceFlagsThresholdReached
5195ffb0c9bSToomas Soome      * is only set in the callbacks and kDNSServiceFlagsThresholdOne is only set on
5205ffb0c9bSToomas Soome      * input to a DNSServiceBrowse call.
5215ffb0c9bSToomas Soome      */
522c65ebfc7SToomas Soome      kDNSServiceFlagsPrivateOne          = 0x8000000,
5235ffb0c9bSToomas Soome     /*
524c65ebfc7SToomas Soome      * This flag is private and should not be used.
5255ffb0c9bSToomas Soome      */
5265ffb0c9bSToomas Soome 
527c65ebfc7SToomas Soome      kDNSServiceFlagsPrivateTwo           = 0x10000000,
5285ffb0c9bSToomas Soome     /*
529c65ebfc7SToomas Soome      * This flag is private and should not be used.
5304b22b933Srs      */
5315ffb0c9bSToomas Soome 
532c65ebfc7SToomas Soome      kDNSServiceFlagsPrivateThree         = 0x20000000,
5335ffb0c9bSToomas Soome     /*
534c65ebfc7SToomas Soome      * This flag is private and should not be used.
5354b22b933Srs      */
5365ffb0c9bSToomas Soome 
537*3b436d06SToomas Soome      kDNSServiceFlagsPrivateFour          = 0x40000000,
538cda73f64SToomas Soome     /*
539c65ebfc7SToomas Soome      * This flag is private and should not be used.
540cda73f64SToomas Soome      */
541cda73f64SToomas Soome 
542*3b436d06SToomas Soome     kDNSServiceFlagsAllowExpiredAnswers   = 0x80000000,
543*3b436d06SToomas Soome     /*
544*3b436d06SToomas Soome      * When kDNSServiceFlagsAllowExpiredAnswers is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo,
545*3b436d06SToomas Soome      * if there are matching expired records still in the cache, then they are immediately returned to the
546*3b436d06SToomas Soome      * client, and in parallel a network query for that name is issued. All returned records from the query will
547*3b436d06SToomas Soome      * remain in the cache after expiration.
548*3b436d06SToomas Soome      */
549*3b436d06SToomas Soome 
550*3b436d06SToomas Soome     kDNSServiceFlagsExpiredAnswer         = 0x80000000
551*3b436d06SToomas Soome     /*
552*3b436d06SToomas Soome      * When kDNSServiceFlagsAllowExpiredAnswers is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo,
553*3b436d06SToomas Soome      * an expired answer will have this flag set.
554*3b436d06SToomas Soome      */
555*3b436d06SToomas Soome 
5565ffb0c9bSToomas Soome };
5575ffb0c9bSToomas Soome 
5585ffb0c9bSToomas Soome #define kDNSServiceOutputFlags (kDNSServiceFlagsValidate | kDNSServiceFlagsValidateOptional | kDNSServiceFlagsMoreComing | kDNSServiceFlagsAdd | kDNSServiceFlagsDefault)
5595ffb0c9bSToomas Soome    /* All the output flags excluding the DNSSEC Status flags. Typically used to check DNSSEC Status */
5605ffb0c9bSToomas Soome 
5615ffb0c9bSToomas Soome /* Possible protocol values */
5625ffb0c9bSToomas Soome enum
5635ffb0c9bSToomas Soome {
5645ffb0c9bSToomas Soome     /* for DNSServiceGetAddrInfo() */
5655ffb0c9bSToomas Soome     kDNSServiceProtocol_IPv4 = 0x01,
5665ffb0c9bSToomas Soome     kDNSServiceProtocol_IPv6 = 0x02,
5675ffb0c9bSToomas Soome     /* 0x04 and 0x08 reserved for future internetwork protocols */
5685ffb0c9bSToomas Soome 
5695ffb0c9bSToomas Soome     /* for DNSServiceNATPortMappingCreate() */
5705ffb0c9bSToomas Soome     kDNSServiceProtocol_UDP  = 0x10,
5715ffb0c9bSToomas Soome     kDNSServiceProtocol_TCP  = 0x20
5725ffb0c9bSToomas Soome                                /* 0x40 and 0x80 reserved for future transport protocols, e.g. SCTP [RFC 2960]
5735ffb0c9bSToomas Soome                                 * or DCCP [RFC 4340]. If future NAT gateways are created that support port
5745ffb0c9bSToomas Soome                                 * mappings for these protocols, new constants will be defined here.
5755ffb0c9bSToomas Soome                                 */
5765ffb0c9bSToomas Soome };
5774b22b933Srs 
5784b22b933Srs /*
5794b22b933Srs  * The values for DNS Classes and Types are listed in RFC 1035, and are available
5804b22b933Srs  * on every OS in its DNS header file. Unfortunately every OS does not have the
5814b22b933Srs  * same header file containing DNS Class and Type constants, and the names of
5824b22b933Srs  * the constants are not consistent. For example, BIND 8 uses "T_A",
5834b22b933Srs  * BIND 9 uses "ns_t_a", Windows uses "DNS_TYPE_A", etc.
5844b22b933Srs  * For this reason, these constants are also listed here, so that code using
5854b22b933Srs  * the DNS-SD programming APIs can use these constants, so that the same code
5864b22b933Srs  * can compile on all our supported platforms.
5874b22b933Srs  */
5884b22b933Srs 
5894b22b933Srs enum
5905ffb0c9bSToomas Soome {
5914b22b933Srs     kDNSServiceClass_IN       = 1       /* Internet */
5925ffb0c9bSToomas Soome };
5934b22b933Srs 
5944b22b933Srs enum
5955ffb0c9bSToomas Soome {
5965ffb0c9bSToomas Soome     kDNSServiceType_A          = 1,      /* Host address. */
5975ffb0c9bSToomas Soome     kDNSServiceType_NS         = 2,      /* Authoritative server. */
5985ffb0c9bSToomas Soome     kDNSServiceType_MD         = 3,      /* Mail destination. */
5995ffb0c9bSToomas Soome     kDNSServiceType_MF         = 4,      /* Mail forwarder. */
6005ffb0c9bSToomas Soome     kDNSServiceType_CNAME      = 5,      /* Canonical name. */
6015ffb0c9bSToomas Soome     kDNSServiceType_SOA        = 6,      /* Start of authority zone. */
6025ffb0c9bSToomas Soome     kDNSServiceType_MB         = 7,      /* Mailbox domain name. */
6035ffb0c9bSToomas Soome     kDNSServiceType_MG         = 8,      /* Mail group member. */
6045ffb0c9bSToomas Soome     kDNSServiceType_MR         = 9,      /* Mail rename name. */
6055ffb0c9bSToomas Soome     kDNSServiceType_NULL       = 10,     /* Null resource record. */
6065ffb0c9bSToomas Soome     kDNSServiceType_WKS        = 11,     /* Well known service. */
6075ffb0c9bSToomas Soome     kDNSServiceType_PTR        = 12,     /* Domain name pointer. */
6085ffb0c9bSToomas Soome     kDNSServiceType_HINFO      = 13,     /* Host information. */
6095ffb0c9bSToomas Soome     kDNSServiceType_MINFO      = 14,     /* Mailbox information. */
6105ffb0c9bSToomas Soome     kDNSServiceType_MX         = 15,     /* Mail routing information. */
6115ffb0c9bSToomas Soome     kDNSServiceType_TXT        = 16,     /* One or more text strings (NOT "zero or more..."). */
6125ffb0c9bSToomas Soome     kDNSServiceType_RP         = 17,     /* Responsible person. */
6135ffb0c9bSToomas Soome     kDNSServiceType_AFSDB      = 18,     /* AFS cell database. */
6145ffb0c9bSToomas Soome     kDNSServiceType_X25        = 19,     /* X_25 calling address. */
6155ffb0c9bSToomas Soome     kDNSServiceType_ISDN       = 20,     /* ISDN calling address. */
6165ffb0c9bSToomas Soome     kDNSServiceType_RT         = 21,     /* Router. */
6175ffb0c9bSToomas Soome     kDNSServiceType_NSAP       = 22,     /* NSAP address. */
6185ffb0c9bSToomas Soome     kDNSServiceType_NSAP_PTR   = 23,     /* Reverse NSAP lookup (deprecated). */
6195ffb0c9bSToomas Soome     kDNSServiceType_SIG        = 24,     /* Security signature. */
6205ffb0c9bSToomas Soome     kDNSServiceType_KEY        = 25,     /* Security key. */
6215ffb0c9bSToomas Soome     kDNSServiceType_PX         = 26,     /* X.400 mail mapping. */
6225ffb0c9bSToomas Soome     kDNSServiceType_GPOS       = 27,     /* Geographical position (withdrawn). */
6235ffb0c9bSToomas Soome     kDNSServiceType_AAAA       = 28,     /* IPv6 Address. */
6245ffb0c9bSToomas Soome     kDNSServiceType_LOC        = 29,     /* Location Information. */
6255ffb0c9bSToomas Soome     kDNSServiceType_NXT        = 30,     /* Next domain (security). */
6265ffb0c9bSToomas Soome     kDNSServiceType_EID        = 31,     /* Endpoint identifier. */
6275ffb0c9bSToomas Soome     kDNSServiceType_NIMLOC     = 32,     /* Nimrod Locator. */
6285ffb0c9bSToomas Soome     kDNSServiceType_SRV        = 33,     /* Server Selection. */
6295ffb0c9bSToomas Soome     kDNSServiceType_ATMA       = 34,     /* ATM Address */
6305ffb0c9bSToomas Soome     kDNSServiceType_NAPTR      = 35,     /* Naming Authority PoinTeR */
6315ffb0c9bSToomas Soome     kDNSServiceType_KX         = 36,     /* Key Exchange */
6325ffb0c9bSToomas Soome     kDNSServiceType_CERT       = 37,     /* Certification record */
6335ffb0c9bSToomas Soome     kDNSServiceType_A6         = 38,     /* IPv6 Address (deprecated) */
6345ffb0c9bSToomas Soome     kDNSServiceType_DNAME      = 39,     /* Non-terminal DNAME (for IPv6) */
6355ffb0c9bSToomas Soome     kDNSServiceType_SINK       = 40,     /* Kitchen sink (experimental) */
6365ffb0c9bSToomas Soome     kDNSServiceType_OPT        = 41,     /* EDNS0 option (meta-RR) */
6375ffb0c9bSToomas Soome     kDNSServiceType_APL        = 42,     /* Address Prefix List */
6385ffb0c9bSToomas Soome     kDNSServiceType_DS         = 43,     /* Delegation Signer */
6395ffb0c9bSToomas Soome     kDNSServiceType_SSHFP      = 44,     /* SSH Key Fingerprint */
6405ffb0c9bSToomas Soome     kDNSServiceType_IPSECKEY   = 45,     /* IPSECKEY */
6415ffb0c9bSToomas Soome     kDNSServiceType_RRSIG      = 46,     /* RRSIG */
6425ffb0c9bSToomas Soome     kDNSServiceType_NSEC       = 47,     /* Denial of Existence */
6435ffb0c9bSToomas Soome     kDNSServiceType_DNSKEY     = 48,     /* DNSKEY */
6445ffb0c9bSToomas Soome     kDNSServiceType_DHCID      = 49,     /* DHCP Client Identifier */
6455ffb0c9bSToomas Soome     kDNSServiceType_NSEC3      = 50,     /* Hashed Authenticated Denial of Existence */
6465ffb0c9bSToomas Soome     kDNSServiceType_NSEC3PARAM = 51,     /* Hashed Authenticated Denial of Existence */
6475ffb0c9bSToomas Soome 
6485ffb0c9bSToomas Soome     kDNSServiceType_HIP        = 55,     /* Host Identity Protocol */
6495ffb0c9bSToomas Soome 
6505ffb0c9bSToomas Soome     kDNSServiceType_SPF        = 99,     /* Sender Policy Framework for E-Mail */
6515ffb0c9bSToomas Soome     kDNSServiceType_UINFO      = 100,    /* IANA-Reserved */
6525ffb0c9bSToomas Soome     kDNSServiceType_UID        = 101,    /* IANA-Reserved */
6535ffb0c9bSToomas Soome     kDNSServiceType_GID        = 102,    /* IANA-Reserved */
6545ffb0c9bSToomas Soome     kDNSServiceType_UNSPEC     = 103,    /* IANA-Reserved */
6555ffb0c9bSToomas Soome 
6565ffb0c9bSToomas Soome     kDNSServiceType_TKEY       = 249,    /* Transaction key */
6575ffb0c9bSToomas Soome     kDNSServiceType_TSIG       = 250,    /* Transaction signature. */
6585ffb0c9bSToomas Soome     kDNSServiceType_IXFR       = 251,    /* Incremental zone transfer. */
6595ffb0c9bSToomas Soome     kDNSServiceType_AXFR       = 252,    /* Transfer zone of authority. */
6605ffb0c9bSToomas Soome     kDNSServiceType_MAILB      = 253,    /* Transfer mailbox records. */
6615ffb0c9bSToomas Soome     kDNSServiceType_MAILA      = 254,    /* Transfer mail agent records. */
6625ffb0c9bSToomas Soome     kDNSServiceType_ANY        = 255     /* Wildcard match. */
6635ffb0c9bSToomas Soome };
6644b22b933Srs 
6654b22b933Srs /* possible error code values */
6664b22b933Srs enum
6675ffb0c9bSToomas Soome {
6685ffb0c9bSToomas Soome     kDNSServiceErr_NoError                   = 0,
6695ffb0c9bSToomas Soome     kDNSServiceErr_Unknown                   = -65537,  /* 0xFFFE FFFF */
6705ffb0c9bSToomas Soome     kDNSServiceErr_NoSuchName                = -65538,
6715ffb0c9bSToomas Soome     kDNSServiceErr_NoMemory                  = -65539,
6725ffb0c9bSToomas Soome     kDNSServiceErr_BadParam                  = -65540,
6735ffb0c9bSToomas Soome     kDNSServiceErr_BadReference              = -65541,
6745ffb0c9bSToomas Soome     kDNSServiceErr_BadState                  = -65542,
6755ffb0c9bSToomas Soome     kDNSServiceErr_BadFlags                  = -65543,
6765ffb0c9bSToomas Soome     kDNSServiceErr_Unsupported               = -65544,
6775ffb0c9bSToomas Soome     kDNSServiceErr_NotInitialized            = -65545,
6785ffb0c9bSToomas Soome     kDNSServiceErr_AlreadyRegistered         = -65547,
6795ffb0c9bSToomas Soome     kDNSServiceErr_NameConflict              = -65548,
6805ffb0c9bSToomas Soome     kDNSServiceErr_Invalid                   = -65549,
6815ffb0c9bSToomas Soome     kDNSServiceErr_Firewall                  = -65550,
6825ffb0c9bSToomas Soome     kDNSServiceErr_Incompatible              = -65551,  /* client library incompatible with daemon */
6835ffb0c9bSToomas Soome     kDNSServiceErr_BadInterfaceIndex         = -65552,
6845ffb0c9bSToomas Soome     kDNSServiceErr_Refused                   = -65553,
6855ffb0c9bSToomas Soome     kDNSServiceErr_NoSuchRecord              = -65554,
6865ffb0c9bSToomas Soome     kDNSServiceErr_NoAuth                    = -65555,
6875ffb0c9bSToomas Soome     kDNSServiceErr_NoSuchKey                 = -65556,
6885ffb0c9bSToomas Soome     kDNSServiceErr_NATTraversal              = -65557,
6895ffb0c9bSToomas Soome     kDNSServiceErr_DoubleNAT                 = -65558,
6905ffb0c9bSToomas Soome     kDNSServiceErr_BadTime                   = -65559,  /* Codes up to here existed in Tiger */
6915ffb0c9bSToomas Soome     kDNSServiceErr_BadSig                    = -65560,
6925ffb0c9bSToomas Soome     kDNSServiceErr_BadKey                    = -65561,
6935ffb0c9bSToomas Soome     kDNSServiceErr_Transient                 = -65562,
6945ffb0c9bSToomas Soome     kDNSServiceErr_ServiceNotRunning         = -65563,  /* Background daemon not running */
6955ffb0c9bSToomas Soome     kDNSServiceErr_NATPortMappingUnsupported = -65564,  /* NAT doesn't support PCP, NAT-PMP or UPnP */
6965ffb0c9bSToomas Soome     kDNSServiceErr_NATPortMappingDisabled    = -65565,  /* NAT supports PCP, NAT-PMP or UPnP, but it's disabled by the administrator */
6975ffb0c9bSToomas Soome     kDNSServiceErr_NoRouter                  = -65566,  /* No router currently configured (probably no network connectivity) */
6985ffb0c9bSToomas Soome     kDNSServiceErr_PollingMode               = -65567,
6995ffb0c9bSToomas Soome     kDNSServiceErr_Timeout                   = -65568
7005ffb0c9bSToomas Soome 
7015ffb0c9bSToomas Soome                                                /* mDNS Error codes are in the range
7025ffb0c9bSToomas Soome                                                 * FFFE FF00 (-65792) to FFFE FFFF (-65537) */
7035ffb0c9bSToomas Soome };
7044b22b933Srs 
7054b22b933Srs /* Maximum length, in bytes, of a service name represented as a */
7064b22b933Srs /* literal C-String, including the terminating NULL at the end. */
7074b22b933Srs 
7084b22b933Srs #define kDNSServiceMaxServiceName 64
7094b22b933Srs 
7104b22b933Srs /* Maximum length, in bytes, of a domain name represented as an *escaped* C-String */
7114b22b933Srs /* including the final trailing dot, and the C-String terminating NULL at the end. */
7124b22b933Srs 
7135ffb0c9bSToomas Soome #define kDNSServiceMaxDomainName 1009
7144b22b933Srs 
7154b22b933Srs /*
7164b22b933Srs  * Notes on DNS Name Escaping
7174b22b933Srs  *   -- or --
7185ffb0c9bSToomas Soome  * "Why is kDNSServiceMaxDomainName 1009, when the maximum legal domain name is 256 bytes?"
7194b22b933Srs  *
720c65ebfc7SToomas Soome  * All strings used in the DNS-SD APIs are UTF-8 strings.
721c65ebfc7SToomas Soome  * Apart from the exceptions noted below, the APIs expect the strings to be properly escaped, using the
722c65ebfc7SToomas Soome  * conventional DNS escaping rules, as used by the traditional DNS res_query() API, as described below:
723c65ebfc7SToomas Soome  *
724c65ebfc7SToomas Soome  * Generally all UTF-8 characters (which includes all US ASCII characters) represent themselves,
725c65ebfc7SToomas Soome  * with two exceptions, the dot ('.') character, which is the label separator,
726c65ebfc7SToomas Soome  * and the backslash ('\') character, which is the escape character.
727c65ebfc7SToomas Soome  * The escape character ('\') is interpreted as described below:
7284b22b933Srs  *
7294b22b933Srs  *   '\ddd', where ddd is a three-digit decimal value from 000 to 255,
730c65ebfc7SToomas Soome  *        represents a single literal byte with that value. Any byte value may be
731c65ebfc7SToomas Soome  *        represented in '\ddd' format, even characters that don't strictly need to be escaped.
732c65ebfc7SToomas Soome  *        For example, the ASCII code for 'w' is 119, and therefore '\119' is equivalent to 'w'.
733c65ebfc7SToomas Soome  *        Thus the command "ping '\119\119\119.apple.com'" is the equivalent to the command "ping 'www.apple.com'".
734c65ebfc7SToomas Soome  *        Nonprinting ASCII characters in the range 0-31 are often represented this way.
735c65ebfc7SToomas Soome  *        In particular, the ASCII NUL character (0) cannot appear in a C string because C uses it as the
736c65ebfc7SToomas Soome  *        string terminator character, so ASCII NUL in a domain name has to be represented in a C string as '\000'.
737c65ebfc7SToomas Soome  *        Other characters like space (ASCII code 32) are sometimes represented as '\032'
738c65ebfc7SToomas Soome  *        in contexts where having an actual space character in a C string would be inconvenient.
739c65ebfc7SToomas Soome  *
740c65ebfc7SToomas Soome  *   Otherwise, for all cases where a '\' is followed by anything other than a three-digit decimal value
741c65ebfc7SToomas Soome  *        from 000 to 255, the character sequence '\x' represents a single literal occurrence of character 'x'.
742c65ebfc7SToomas Soome  *        This is legal for any character, so, for example, '\w' is equivalent to 'w'.
743c65ebfc7SToomas Soome  *        Thus the command "ping '\w\w\w.apple.com'" is the equivalent to the command "ping 'www.apple.com'".
744c65ebfc7SToomas Soome  *        However, this encoding is most useful when representing the characters '.' and '\',
745c65ebfc7SToomas Soome  *        which otherwise would have special meaning in DNS name strings.
746c65ebfc7SToomas Soome  *        This means that the following encodings are particularly common:
747c65ebfc7SToomas Soome  *        '\\' represents a single literal '\' in the name
748c65ebfc7SToomas Soome  *        '\.' represents a single literal '.' in the name
749c65ebfc7SToomas Soome  *
750c65ebfc7SToomas Soome  *   A lone escape character ('\') appearing at the end of a string is not allowed, since it is
751c65ebfc7SToomas Soome  *        followed by neither a three-digit decimal value from 000 to 255 nor a single character.
752c65ebfc7SToomas Soome  *        If a lone escape character ('\') does appear as the last character of a string, it is silently ignored.
7534b22b933Srs  *
7544b22b933Srs  * The exceptions, that do not use escaping, are the routines where the full
7554b22b933Srs  * DNS name of a resource is broken, for convenience, into servicename/regtype/domain.
7564b22b933Srs  * In these routines, the "servicename" is NOT escaped. It does not need to be, since
7574b22b933Srs  * it is, by definition, just a single literal string. Any characters in that string
7584b22b933Srs  * represent exactly what they are. The "regtype" portion is, technically speaking,
759c65ebfc7SToomas Soome  * escaped, but since legal regtypes are only allowed to contain US ASCII letters,
760c65ebfc7SToomas Soome  * digits, and hyphens, there is nothing to escape, so the issue is moot.
761c65ebfc7SToomas Soome  * The "domain" portion is also escaped, though most domains in use on the public
762c65ebfc7SToomas Soome  * Internet today, like regtypes, don't contain any characters that need to be escaped.
7634b22b933Srs  * As DNS-SD becomes more popular, rich-text domains for service discovery will
7644b22b933Srs  * become common, so software should be written to cope with domains with escaping.
7654b22b933Srs  *
7664b22b933Srs  * The servicename may be up to 63 bytes of UTF-8 text (not counting the C-String
7674b22b933Srs  * terminating NULL at the end). The regtype is of the form _service._tcp or
7685ffb0c9bSToomas Soome  * _service._udp, where the "service" part is 1-15 characters, which may be
7694b22b933Srs  * letters, digits, or hyphens. The domain part of the three-part name may be
7704b22b933Srs  * any legal domain, providing that the resulting servicename+regtype+domain
7715ffb0c9bSToomas Soome  * name does not exceed 256 bytes.
7724b22b933Srs  *
7734b22b933Srs  * For most software, these issues are transparent. When browsing, the discovered
7744b22b933Srs  * servicenames should simply be displayed as-is. When resolving, the discovered
7754b22b933Srs  * servicename/regtype/domain are simply passed unchanged to DNSServiceResolve().
7764b22b933Srs  * When a DNSServiceResolve() succeeds, the returned fullname is already in
7774b22b933Srs  * the correct format to pass to standard system DNS APIs such as res_query().
7784b22b933Srs  * For converting from servicename/regtype/domain to a single properly-escaped
7794b22b933Srs  * full DNS name, the helper function DNSServiceConstructFullName() is provided.
7804b22b933Srs  *
7814b22b933Srs  * The following (highly contrived) example illustrates the escaping process.
782c65ebfc7SToomas Soome  * Suppose you have a service called "Dr. Smith\Dr. Johnson", of type "_ftp._tcp"
7834b22b933Srs  * in subdomain "4th. Floor" of subdomain "Building 2" of domain "apple.com."
7844b22b933Srs  * The full (escaped) DNS name of this service's SRV record would be:
7854b22b933Srs  * Dr\.\032Smith\\Dr\.\032Johnson._ftp._tcp.4th\.\032Floor.Building\0322.apple.com.
7864b22b933Srs  */
7874b22b933Srs 
7884b22b933Srs 
7895ffb0c9bSToomas Soome /*
7904b22b933Srs  * Constants for specifying an interface index
7914b22b933Srs  *
7924b22b933Srs  * Specific interface indexes are identified via a 32-bit unsigned integer returned
7934b22b933Srs  * by the if_nametoindex() family of calls.
7945ffb0c9bSToomas Soome  *
7954b22b933Srs  * If the client passes 0 for interface index, that means "do the right thing",
7964b22b933Srs  * which (at present) means, "if the name is in an mDNS local multicast domain
7974b22b933Srs  * (e.g. 'local.', '254.169.in-addr.arpa.', '{8,9,A,B}.E.F.ip6.arpa.') then multicast
7984b22b933Srs  * on all applicable interfaces, otherwise send via unicast to the appropriate
7994b22b933Srs  * DNS server." Normally, most clients will use 0 for interface index to
8004b22b933Srs  * automatically get the default sensible behaviour.
8015ffb0c9bSToomas Soome  *
802cda73f64SToomas Soome  * If the client passes a positive interface index, then that indicates to do the
803cda73f64SToomas Soome  * operation only on that one specified interface.
8045ffb0c9bSToomas Soome  *
8054b22b933Srs  * If the client passes kDNSServiceInterfaceIndexLocalOnly when registering
8064b22b933Srs  * a service, then that service will be found *only* by other local clients
8074b22b933Srs  * on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly
8084b22b933Srs  * or kDNSServiceInterfaceIndexAny.
8094b22b933Srs  * If a client has a 'private' service, accessible only to other processes
8104b22b933Srs  * running on the same machine, this allows the client to advertise that service
8114b22b933Srs  * in a way such that it does not inadvertently appear in service lists on
8124b22b933Srs  * all the other machines on the network.
8135ffb0c9bSToomas Soome  *
814c65ebfc7SToomas Soome  * If the client passes kDNSServiceInterfaceIndexLocalOnly when querying or
815c65ebfc7SToomas Soome  * browsing, then the LocalOnly authoritative records and /etc/hosts caches
816c65ebfc7SToomas Soome  * are searched and will find *all* records registered or configured on that
817c65ebfc7SToomas Soome  * same local machine.
818c65ebfc7SToomas Soome  *
819c65ebfc7SToomas Soome  * If interested in getting negative answers to local questions while querying
820c65ebfc7SToomas Soome  * or browsing, then set both the kDNSServiceInterfaceIndexLocalOnly and the
821c65ebfc7SToomas Soome  * kDNSServiceFlagsReturnIntermediates flags. If no local answers exist at this
822c65ebfc7SToomas Soome  * moment in time, then the reply will return an immediate negative answer. If
823c65ebfc7SToomas Soome  * local records are subsequently created that answer the question, then those
824c65ebfc7SToomas Soome  * answers will be delivered, for as long as the question is still active.
825c65ebfc7SToomas Soome  *
826c65ebfc7SToomas Soome  * If the kDNSServiceFlagsTimeout and kDNSServiceInterfaceIndexLocalOnly flags
827c65ebfc7SToomas Soome  * are set simultaneously when either DNSServiceQueryRecord or DNSServiceGetAddrInfo
828c65ebfc7SToomas Soome  * is called then both flags take effect. However, if DNSServiceQueryRecord is called
829c65ebfc7SToomas Soome  * with both the kDNSServiceFlagsSuppressUnusable and kDNSServiceInterfaceIndexLocalOnly
830c65ebfc7SToomas Soome  * flags set, then the kDNSServiceFlagsSuppressUnusable flag is ignored.
831c65ebfc7SToomas Soome  *
832c65ebfc7SToomas Soome  * Clients explicitly wishing to discover *only* LocalOnly services during a
833c65ebfc7SToomas Soome  * browse may do this, without flags, by inspecting the interfaceIndex of each
834c65ebfc7SToomas Soome  * service reported to a DNSServiceBrowseReply() callback function, and
835c65ebfc7SToomas Soome  * discarding those answers where the interface index is not set to
836c65ebfc7SToomas Soome  * kDNSServiceInterfaceIndexLocalOnly.
8375ffb0c9bSToomas Soome  *
8385ffb0c9bSToomas Soome  * kDNSServiceInterfaceIndexP2P is meaningful only in Browse, QueryRecord, Register,
8395ffb0c9bSToomas Soome  * and Resolve operations. It should not be used in other DNSService APIs.
8405ffb0c9bSToomas Soome  *
8415ffb0c9bSToomas Soome  * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceBrowse or
8425ffb0c9bSToomas Soome  *   DNSServiceQueryRecord, it restricts the operation to P2P.
8435ffb0c9bSToomas Soome  *
8445ffb0c9bSToomas Soome  * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceRegister, it is
8455ffb0c9bSToomas Soome  *   mapped internally to kDNSServiceInterfaceIndexAny with the kDNSServiceFlagsIncludeP2P
8465ffb0c9bSToomas Soome  *   set.
8475ffb0c9bSToomas Soome  *
8485ffb0c9bSToomas Soome  * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceResolve, it is
8495ffb0c9bSToomas Soome  *   mapped internally to kDNSServiceInterfaceIndexAny with the kDNSServiceFlagsIncludeP2P
850c65ebfc7SToomas Soome  *   set, because resolving a P2P service may create and/or enable an interface whose
8515ffb0c9bSToomas Soome  *   index is not known a priori. The resolve callback will indicate the index of the
8525ffb0c9bSToomas Soome  *   interface via which the service can be accessed.
8535ffb0c9bSToomas Soome  *
8545ffb0c9bSToomas Soome  * If applications pass kDNSServiceInterfaceIndexAny to DNSServiceBrowse
8555ffb0c9bSToomas Soome  * or DNSServiceQueryRecord, they must set the kDNSServiceFlagsIncludeP2P flag
8565ffb0c9bSToomas Soome  * to include P2P. In this case, if a service instance or the record being queried
8575ffb0c9bSToomas Soome  * is found over P2P, the resulting ADD event will indicate kDNSServiceInterfaceIndexP2P
8585ffb0c9bSToomas Soome  * as the interface index.
8594b22b933Srs  */
8604b22b933Srs 
8614b22b933Srs #define kDNSServiceInterfaceIndexAny 0
8625ffb0c9bSToomas Soome #define kDNSServiceInterfaceIndexLocalOnly ((uint32_t)-1)
8635ffb0c9bSToomas Soome #define kDNSServiceInterfaceIndexUnicast   ((uint32_t)-2)
8645ffb0c9bSToomas Soome #define kDNSServiceInterfaceIndexP2P       ((uint32_t)-3)
865c65ebfc7SToomas Soome #define kDNSServiceInterfaceIndexBLE       ((uint32_t)-4)
8664b22b933Srs 
8674b22b933Srs typedef uint32_t DNSServiceFlags;
8685ffb0c9bSToomas Soome typedef uint32_t DNSServiceProtocol;
8694b22b933Srs typedef int32_t DNSServiceErrorType;
8704b22b933Srs 
8714b22b933Srs 
8724b22b933Srs /*********************************************************************************************
8735ffb0c9bSToomas Soome *
8745ffb0c9bSToomas Soome * Version checking
8755ffb0c9bSToomas Soome *
8765ffb0c9bSToomas Soome *********************************************************************************************/
8775ffb0c9bSToomas Soome 
8785ffb0c9bSToomas Soome /* DNSServiceGetProperty() Parameters:
8794b22b933Srs  *
8805ffb0c9bSToomas Soome  * property:        The requested property.
8815ffb0c9bSToomas Soome  *                  Currently the only property defined is kDNSServiceProperty_DaemonVersion.
8824b22b933Srs  *
8835ffb0c9bSToomas Soome  * result:          Place to store result.
8845ffb0c9bSToomas Soome  *                  For retrieving DaemonVersion, this should be the address of a uint32_t.
8855ffb0c9bSToomas Soome  *
8865ffb0c9bSToomas Soome  * size:            Pointer to uint32_t containing size of the result location.
8875ffb0c9bSToomas Soome  *                  For retrieving DaemonVersion, this should be sizeof(uint32_t).
8885ffb0c9bSToomas Soome  *                  On return the uint32_t is updated to the size of the data returned.
8895ffb0c9bSToomas Soome  *                  For DaemonVersion, the returned size is always sizeof(uint32_t), but
8905ffb0c9bSToomas Soome  *                  future properties could be defined which return variable-sized results.
8915ffb0c9bSToomas Soome  *
8925ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success, or kDNSServiceErr_ServiceNotRunning
8935ffb0c9bSToomas Soome  *                  if the daemon (or "system service" on Windows) is not running.
8945ffb0c9bSToomas Soome  */
8955ffb0c9bSToomas Soome 
896*3b436d06SToomas Soome DNSSD_EXPORT
8975ffb0c9bSToomas Soome DNSServiceErrorType DNSSD_API DNSServiceGetProperty
8985ffb0c9bSToomas Soome (
8995ffb0c9bSToomas Soome     const char *property,  /* Requested property (i.e. kDNSServiceProperty_DaemonVersion) */
9005ffb0c9bSToomas Soome     void       *result,    /* Pointer to place to store result */
9015ffb0c9bSToomas Soome     uint32_t   *size       /* size of result location */
9025ffb0c9bSToomas Soome );
9035ffb0c9bSToomas Soome 
9045ffb0c9bSToomas Soome /*
9055ffb0c9bSToomas Soome  * When requesting kDNSServiceProperty_DaemonVersion, the result pointer must point
9065ffb0c9bSToomas Soome  * to a 32-bit unsigned integer, and the size parameter must be set to sizeof(uint32_t).
9075ffb0c9bSToomas Soome  *
9085ffb0c9bSToomas Soome  * On return, the 32-bit unsigned integer contains the API version number
9095ffb0c9bSToomas Soome  *
9105ffb0c9bSToomas Soome  * For example, Mac OS X 10.4.9 has API version 1080400.
9115ffb0c9bSToomas Soome  * This allows applications to do simple greater-than and less-than comparisons:
9125ffb0c9bSToomas Soome  * e.g. an application that requires at least API version 1080400 can check:
9135ffb0c9bSToomas Soome  *   if (version >= 1080400) ...
9145ffb0c9bSToomas Soome  *
9155ffb0c9bSToomas Soome  * Example usage:
9165ffb0c9bSToomas Soome  * uint32_t version;
9175ffb0c9bSToomas Soome  * uint32_t size = sizeof(version);
9185ffb0c9bSToomas Soome  * DNSServiceErrorType err = DNSServiceGetProperty(kDNSServiceProperty_DaemonVersion, &version, &size);
9195ffb0c9bSToomas Soome  * if (!err) printf("DNS_SD API version is %d.%d\n", version / 10000, version / 100 % 100);
9205ffb0c9bSToomas Soome  */
9214b22b933Srs 
9225ffb0c9bSToomas Soome #define kDNSServiceProperty_DaemonVersion "DaemonVersion"
9235ffb0c9bSToomas Soome 
9245ffb0c9bSToomas Soome /*********************************************************************************************
9255ffb0c9bSToomas Soome *
9265ffb0c9bSToomas Soome * Unix Domain Socket access, DNSServiceRef deallocation, and data processing functions
9275ffb0c9bSToomas Soome *
9285ffb0c9bSToomas Soome *********************************************************************************************/
9294b22b933Srs 
9304b22b933Srs /* DNSServiceRefSockFD()
9314b22b933Srs  *
9324b22b933Srs  * Access underlying Unix domain socket for an initialized DNSServiceRef.
9335ffb0c9bSToomas Soome  * The DNS Service Discovery implementation uses this socket to communicate between the client and
9345ffb0c9bSToomas Soome  * the daemon. The application MUST NOT directly read from or write to this socket.
9355ffb0c9bSToomas Soome  * Access to the socket is provided so that it can be used as a kqueue event source, a CFRunLoop
9365ffb0c9bSToomas Soome  * event source, in a select() loop, etc. When the underlying event management subsystem (kqueue/
9375ffb0c9bSToomas Soome  * select/CFRunLoop etc.) indicates to the client that data is available for reading on the
9385ffb0c9bSToomas Soome  * socket, the client should call DNSServiceProcessResult(), which will extract the daemon's
9395ffb0c9bSToomas Soome  * reply from the socket, and pass it to the appropriate application callback. By using a run
9405ffb0c9bSToomas Soome  * loop or select(), results from the daemon can be processed asynchronously. Alternatively,
9415ffb0c9bSToomas Soome  * a client can choose to fork a thread and have it loop calling "DNSServiceProcessResult(ref);"
9425ffb0c9bSToomas Soome  * If DNSServiceProcessResult() is called when no data is available for reading on the socket, it
9435ffb0c9bSToomas Soome  * will block until data does become available, and then process the data and return to the caller.
944c65ebfc7SToomas Soome  * The application is responsible for checking the return value of DNSServiceProcessResult()
945c65ebfc7SToomas Soome  * to determine if the socket is valid and if it should continue to process data on the socket.
9465ffb0c9bSToomas Soome  * When data arrives on the socket, the client is responsible for calling DNSServiceProcessResult(ref)
9475ffb0c9bSToomas Soome  * in a timely fashion -- if the client allows a large backlog of data to build up the daemon
9485ffb0c9bSToomas Soome  * may terminate the connection.
9495ffb0c9bSToomas Soome  *
9505ffb0c9bSToomas Soome  * sdRef:           A DNSServiceRef initialized by any of the DNSService calls.
9514b22b933Srs  *
9524b22b933Srs  * return value:    The DNSServiceRef's underlying socket descriptor, or -1 on
9534b22b933Srs  *                  error.
9544b22b933Srs  */
9554b22b933Srs 
956*3b436d06SToomas Soome DNSSD_EXPORT
957c65ebfc7SToomas Soome dnssd_sock_t DNSSD_API DNSServiceRefSockFD(DNSServiceRef sdRef);
9584b22b933Srs 
9594b22b933Srs 
9604b22b933Srs /* DNSServiceProcessResult()
9614b22b933Srs  *
9625ffb0c9bSToomas Soome  * Read a reply from the daemon, calling the appropriate application callback. This call will
9635ffb0c9bSToomas Soome  * block until the daemon's response is received. Use DNSServiceRefSockFD() in
9644b22b933Srs  * conjunction with a run loop or select() to determine the presence of a response from the
9655ffb0c9bSToomas Soome  * server before calling this function to process the reply without blocking. Call this function
9665ffb0c9bSToomas Soome  * at any point if it is acceptable to block until the daemon's response arrives. Note that the
9674b22b933Srs  * client is responsible for ensuring that DNSServiceProcessResult() is called whenever there is
9684b22b933Srs  * a reply from the daemon - the daemon may terminate its connection with a client that does not
9694b22b933Srs  * process the daemon's responses.
9704b22b933Srs  *
9714b22b933Srs  * sdRef:           A DNSServiceRef initialized by any of the DNSService calls
9724b22b933Srs  *                  that take a callback parameter.
9734b22b933Srs  *
9744b22b933Srs  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns
9754b22b933Srs  *                  an error code indicating the specific failure that occurred.
9764b22b933Srs  */
9774b22b933Srs 
978*3b436d06SToomas Soome DNSSD_EXPORT
9794b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceProcessResult(DNSServiceRef sdRef);
9804b22b933Srs 
9814b22b933Srs 
9824b22b933Srs /* DNSServiceRefDeallocate()
9834b22b933Srs  *
9844b22b933Srs  * Terminate a connection with the daemon and free memory associated with the DNSServiceRef.
9854b22b933Srs  * Any services or records registered with this DNSServiceRef will be deregistered. Any
9864b22b933Srs  * Browse, Resolve, or Query operations called with this reference will be terminated.
9874b22b933Srs  *
9884b22b933Srs  * Note: If the reference's underlying socket is used in a run loop or select() call, it should
9894b22b933Srs  * be removed BEFORE DNSServiceRefDeallocate() is called, as this function closes the reference's
9904b22b933Srs  * socket.
9914b22b933Srs  *
9924b22b933Srs  * Note: If the reference was initialized with DNSServiceCreateConnection(), any DNSRecordRefs
9934b22b933Srs  * created via this reference will be invalidated by this call - the resource records are
9945ffb0c9bSToomas Soome  * deregistered, and their DNSRecordRefs may not be used in subsequent functions. Similarly,
9954b22b933Srs  * if the reference was initialized with DNSServiceRegister, and an extra resource record was
9964b22b933Srs  * added to the service via DNSServiceAddRecord(), the DNSRecordRef created by the Add() call
9974b22b933Srs  * is invalidated when this function is called - the DNSRecordRef may not be used in subsequent
9984b22b933Srs  * functions.
9994b22b933Srs  *
10005ffb0c9bSToomas Soome  * Note: This call is to be used only with the DNSServiceRef defined by this API.
10014b22b933Srs  *
10024b22b933Srs  * sdRef:           A DNSServiceRef initialized by any of the DNSService calls.
10034b22b933Srs  *
10044b22b933Srs  */
10054b22b933Srs 
1006*3b436d06SToomas Soome DNSSD_EXPORT
10074b22b933Srs void DNSSD_API DNSServiceRefDeallocate(DNSServiceRef sdRef);
10084b22b933Srs 
10094b22b933Srs 
10104b22b933Srs /*********************************************************************************************
10115ffb0c9bSToomas Soome *
10125ffb0c9bSToomas Soome * Domain Enumeration
10135ffb0c9bSToomas Soome *
10145ffb0c9bSToomas Soome *********************************************************************************************/
10154b22b933Srs 
10164b22b933Srs /* DNSServiceEnumerateDomains()
10174b22b933Srs  *
10184b22b933Srs  * Asynchronously enumerate domains available for browsing and registration.
10194b22b933Srs  *
10204b22b933Srs  * The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains
10214b22b933Srs  * are to be found.
10224b22b933Srs  *
10234b22b933Srs  * Note that the names returned are (like all of DNS-SD) UTF-8 strings,
10244b22b933Srs  * and are escaped using standard DNS escaping rules.
10254b22b933Srs  * (See "Notes on DNS Name Escaping" earlier in this file for more details.)
10264b22b933Srs  * A graphical browser displaying a hierarchical tree-structured view should cut
10274b22b933Srs  * the names at the bare dots to yield individual labels, then de-escape each
10284b22b933Srs  * label according to the escaping rules, and then display the resulting UTF-8 text.
10294b22b933Srs  *
10304b22b933Srs  * DNSServiceDomainEnumReply Callback Parameters:
10314b22b933Srs  *
10324b22b933Srs  * sdRef:           The DNSServiceRef initialized by DNSServiceEnumerateDomains().
10334b22b933Srs  *
10344b22b933Srs  * flags:           Possible values are:
10354b22b933Srs  *                  kDNSServiceFlagsMoreComing
10364b22b933Srs  *                  kDNSServiceFlagsAdd
10374b22b933Srs  *                  kDNSServiceFlagsDefault
10384b22b933Srs  *
10395ffb0c9bSToomas Soome  * interfaceIndex:  Specifies the interface on which the domain exists. (The index for a given
10404b22b933Srs  *                  interface is determined via the if_nametoindex() family of calls.)
10414b22b933Srs  *
10424b22b933Srs  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise indicates
10434b22b933Srs  *                  the failure that occurred (other parameters are undefined if errorCode is nonzero).
10444b22b933Srs  *
10454b22b933Srs  * replyDomain:     The name of the domain.
10464b22b933Srs  *
10474b22b933Srs  * context:         The context pointer passed to DNSServiceEnumerateDomains.
10484b22b933Srs  *
10494b22b933Srs  */
10504b22b933Srs 
10514b22b933Srs typedef void (DNSSD_API *DNSServiceDomainEnumReply)
10525ffb0c9bSToomas Soome (
10535ffb0c9bSToomas Soome     DNSServiceRef sdRef,
10545ffb0c9bSToomas Soome     DNSServiceFlags flags,
10555ffb0c9bSToomas Soome     uint32_t interfaceIndex,
10565ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
10574b22b933Srs     const char                          *replyDomain,
10584b22b933Srs     void                                *context
10595ffb0c9bSToomas Soome );
10604b22b933Srs 
10614b22b933Srs 
10624b22b933Srs /* DNSServiceEnumerateDomains() Parameters:
10634b22b933Srs  *
10645ffb0c9bSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef. If the call succeeds
10654b22b933Srs  *                  then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
10664b22b933Srs  *                  and the enumeration operation will run indefinitely until the client
10674b22b933Srs  *                  terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
10684b22b933Srs  *
10694b22b933Srs  * flags:           Possible values are:
10704b22b933Srs  *                  kDNSServiceFlagsBrowseDomains to enumerate domains recommended for browsing.
10714b22b933Srs  *                  kDNSServiceFlagsRegistrationDomains to enumerate domains recommended
10724b22b933Srs  *                  for registration.
10734b22b933Srs  *
10744b22b933Srs  * interfaceIndex:  If non-zero, specifies the interface on which to look for domains.
10754b22b933Srs  *                  (the index for a given interface is determined via the if_nametoindex()
10765ffb0c9bSToomas Soome  *                  family of calls.) Most applications will pass 0 to enumerate domains on
10774b22b933Srs  *                  all interfaces. See "Constants for specifying an interface index" for more details.
10784b22b933Srs  *
10794b22b933Srs  * callBack:        The function to be called when a domain is found or the call asynchronously
10804b22b933Srs  *                  fails.
10814b22b933Srs  *
10824b22b933Srs  * context:         An application context pointer which is passed to the callback function
10834b22b933Srs  *                  (may be NULL).
10844b22b933Srs  *
10855ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
10864b22b933Srs  *                  errors are delivered to the callback), otherwise returns an error code indicating
10874b22b933Srs  *                  the error that occurred (the callback is not invoked and the DNSServiceRef
10885ffb0c9bSToomas Soome  *                  is not initialized).
10894b22b933Srs  */
10904b22b933Srs 
1091*3b436d06SToomas Soome DNSSD_EXPORT
10924b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceEnumerateDomains
10935ffb0c9bSToomas Soome (
10944b22b933Srs     DNSServiceRef                       *sdRef,
10955ffb0c9bSToomas Soome     DNSServiceFlags flags,
10965ffb0c9bSToomas Soome     uint32_t interfaceIndex,
10975ffb0c9bSToomas Soome     DNSServiceDomainEnumReply callBack,
10984b22b933Srs     void                                *context  /* may be NULL */
10995ffb0c9bSToomas Soome );
11004b22b933Srs 
11014b22b933Srs 
11024b22b933Srs /*********************************************************************************************
11035ffb0c9bSToomas Soome *
11045ffb0c9bSToomas Soome *  Service Registration
11055ffb0c9bSToomas Soome *
11065ffb0c9bSToomas Soome *********************************************************************************************/
11074b22b933Srs 
11084b22b933Srs /* Register a service that is discovered via Browse() and Resolve() calls.
11094b22b933Srs  *
11104b22b933Srs  * DNSServiceRegisterReply() Callback Parameters:
11114b22b933Srs  *
11124b22b933Srs  * sdRef:           The DNSServiceRef initialized by DNSServiceRegister().
11134b22b933Srs  *
11145ffb0c9bSToomas Soome  * flags:           When a name is successfully registered, the callback will be
11155ffb0c9bSToomas Soome  *                  invoked with the kDNSServiceFlagsAdd flag set. When Wide-Area
11165ffb0c9bSToomas Soome  *                  DNS-SD is in use, it is possible for a single service to get
11175ffb0c9bSToomas Soome  *                  more than one success callback (e.g. one in the "local" multicast
11185ffb0c9bSToomas Soome  *                  DNS domain, and another in a wide-area unicast DNS domain).
11195ffb0c9bSToomas Soome  *                  If a successfully-registered name later suffers a name conflict
11205ffb0c9bSToomas Soome  *                  or similar problem and has to be deregistered, the callback will
11215ffb0c9bSToomas Soome  *                  be invoked with the kDNSServiceFlagsAdd flag not set. The callback
11225ffb0c9bSToomas Soome  *                  is *not* invoked in the case where the caller explicitly terminates
11235ffb0c9bSToomas Soome  *                  the service registration by calling DNSServiceRefDeallocate(ref);
11244b22b933Srs  *
11254b22b933Srs  * errorCode:       Will be kDNSServiceErr_NoError on success, otherwise will
11264b22b933Srs  *                  indicate the failure that occurred (including name conflicts,
11274b22b933Srs  *                  if the kDNSServiceFlagsNoAutoRename flag was used when registering.)
11284b22b933Srs  *                  Other parameters are undefined if errorCode is nonzero.
11294b22b933Srs  *
11304b22b933Srs  * name:            The service name registered (if the application did not specify a name in
11314b22b933Srs  *                  DNSServiceRegister(), this indicates what name was automatically chosen).
11324b22b933Srs  *
11334b22b933Srs  * regtype:         The type of service registered, as it was passed to the callout.
11344b22b933Srs  *
11354b22b933Srs  * domain:          The domain on which the service was registered (if the application did not
11364b22b933Srs  *                  specify a domain in DNSServiceRegister(), this indicates the default domain
11374b22b933Srs  *                  on which the service was registered).
11384b22b933Srs  *
11394b22b933Srs  * context:         The context pointer that was passed to the callout.
11404b22b933Srs  *
11414b22b933Srs  */
11424b22b933Srs 
11434b22b933Srs typedef void (DNSSD_API *DNSServiceRegisterReply)
11445ffb0c9bSToomas Soome (
11455ffb0c9bSToomas Soome     DNSServiceRef sdRef,
11465ffb0c9bSToomas Soome     DNSServiceFlags flags,
11475ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
11484b22b933Srs     const char                          *name,
11494b22b933Srs     const char                          *regtype,
11504b22b933Srs     const char                          *domain,
11514b22b933Srs     void                                *context
11525ffb0c9bSToomas Soome );
11534b22b933Srs 
11544b22b933Srs 
11555ffb0c9bSToomas Soome /* DNSServiceRegister() Parameters:
11564b22b933Srs  *
11575ffb0c9bSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef. If the call succeeds
11584b22b933Srs  *                  then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
11594b22b933Srs  *                  and the registration will remain active indefinitely until the client
11604b22b933Srs  *                  terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
11614b22b933Srs  *
1162c65ebfc7SToomas Soome  * flags:           Indicates the renaming behavior on name conflict (most applications
1163c65ebfc7SToomas Soome  *                  will pass 0). See flag definitions above for details.
1164c65ebfc7SToomas Soome  *
11654b22b933Srs  * interfaceIndex:  If non-zero, specifies the interface on which to register the service
11664b22b933Srs  *                  (the index for a given interface is determined via the if_nametoindex()
11675ffb0c9bSToomas Soome  *                  family of calls.) Most applications will pass 0 to register on all
11684b22b933Srs  *                  available interfaces. See "Constants for specifying an interface index" for more details.
11694b22b933Srs  *
11704b22b933Srs  * name:            If non-NULL, specifies the service name to be registered.
11714b22b933Srs  *                  Most applications will not specify a name, in which case the computer
11724b22b933Srs  *                  name is used (this name is communicated to the client via the callback).
11734b22b933Srs  *                  If a name is specified, it must be 1-63 bytes of UTF-8 text.
11744b22b933Srs  *                  If the name is longer than 63 bytes it will be automatically truncated
11754b22b933Srs  *                  to a legal length, unless the NoAutoRename flag is set,
11764b22b933Srs  *                  in which case kDNSServiceErr_BadParam will be returned.
11774b22b933Srs  *
11784b22b933Srs  * regtype:         The service type followed by the protocol, separated by a dot
11794b22b933Srs  *                  (e.g. "_ftp._tcp"). The service type must be an underscore, followed
11805ffb0c9bSToomas Soome  *                  by 1-15 characters, which may be letters, digits, or hyphens.
11814b22b933Srs  *                  The transport protocol must be "_tcp" or "_udp". New service types
11824b22b933Srs  *                  should be registered at <http://www.dns-sd.org/ServiceTypes.html>.
11834b22b933Srs  *
11845ffb0c9bSToomas Soome  *                  Additional subtypes of the primary service type (where a service
11855ffb0c9bSToomas Soome  *                  type has defined subtypes) follow the primary service type in a
11865ffb0c9bSToomas Soome  *                  comma-separated list, with no additional spaces, e.g.
11875ffb0c9bSToomas Soome  *                      "_primarytype._tcp,_subtype1,_subtype2,_subtype3"
11885ffb0c9bSToomas Soome  *                  Subtypes provide a mechanism for filtered browsing: A client browsing
11895ffb0c9bSToomas Soome  *                  for "_primarytype._tcp" will discover all instances of this type;
11905ffb0c9bSToomas Soome  *                  a client browsing for "_primarytype._tcp,_subtype2" will discover only
11915ffb0c9bSToomas Soome  *                  those instances that were registered with "_subtype2" in their list of
11925ffb0c9bSToomas Soome  *                  registered subtypes.
11935ffb0c9bSToomas Soome  *
11945ffb0c9bSToomas Soome  *                  The subtype mechanism can be illustrated with some examples using the
11955ffb0c9bSToomas Soome  *                  dns-sd command-line tool:
11965ffb0c9bSToomas Soome  *
11975ffb0c9bSToomas Soome  *                  % dns-sd -R Simple _test._tcp "" 1001 &
11985ffb0c9bSToomas Soome  *                  % dns-sd -R Better _test._tcp,HasFeatureA "" 1002 &
11995ffb0c9bSToomas Soome  *                  % dns-sd -R Best   _test._tcp,HasFeatureA,HasFeatureB "" 1003 &
12005ffb0c9bSToomas Soome  *
12015ffb0c9bSToomas Soome  *                  Now:
12025ffb0c9bSToomas Soome  *                  % dns-sd -B _test._tcp             # will find all three services
12035ffb0c9bSToomas Soome  *                  % dns-sd -B _test._tcp,HasFeatureA # finds "Better" and "Best"
12045ffb0c9bSToomas Soome  *                  % dns-sd -B _test._tcp,HasFeatureB # finds only "Best"
12055ffb0c9bSToomas Soome  *
12065ffb0c9bSToomas Soome  *                  Subtype labels may be up to 63 bytes long, and may contain any eight-
12075ffb0c9bSToomas Soome  *                  bit byte values, including zero bytes. However, due to the nature of
12085ffb0c9bSToomas Soome  *                  using a C-string-based API, conventional DNS escaping must be used for
12095ffb0c9bSToomas Soome  *                  dots ('.'), commas (','), backslashes ('\') and zero bytes, as shown below:
12105ffb0c9bSToomas Soome  *
12115ffb0c9bSToomas Soome  *                  % dns-sd -R Test '_test._tcp,s\.one,s\,two,s\\three,s\000four' local 123
12125ffb0c9bSToomas Soome  *
12135ffb0c9bSToomas Soome  *                  When a service is registered, all the clients browsing for the registered
12145ffb0c9bSToomas Soome  *                  type ("regtype") will discover it. If the discovery should be
12155ffb0c9bSToomas Soome  *                  restricted to a smaller set of well known peers, the service can be
12165ffb0c9bSToomas Soome  *                  registered with additional data (group identifier) that is known
12175ffb0c9bSToomas Soome  *                  only to a smaller set of peers. The group identifier should follow primary
12185ffb0c9bSToomas Soome  *                  service type using a colon (":") as a delimeter. If subtypes are also present,
12195ffb0c9bSToomas Soome  *                  it should be given before the subtype as shown below.
12205ffb0c9bSToomas Soome  *
1221c65ebfc7SToomas Soome  *                  % dns-sd -R _test1 _http._tcp:mygroup1 local 1001
1222c65ebfc7SToomas Soome  *                  % dns-sd -R _test2 _http._tcp:mygroup2 local 1001
1223c65ebfc7SToomas Soome  *                  % dns-sd -R _test3 _http._tcp:mygroup3,HasFeatureA local 1001
12245ffb0c9bSToomas Soome  *
12255ffb0c9bSToomas Soome  *                  Now:
12265ffb0c9bSToomas Soome  *                  % dns-sd -B _http._tcp:"mygroup1"                # will discover only test1
12275ffb0c9bSToomas Soome  *                  % dns-sd -B _http._tcp:"mygroup2"                # will discover only test2
12285ffb0c9bSToomas Soome  *                  % dns-sd -B _http._tcp:"mygroup3",HasFeatureA    # will discover only test3
1229c65ebfc7SToomas Soome  *
12305ffb0c9bSToomas Soome  *                  By specifying the group information, only the members of that group are
12315ffb0c9bSToomas Soome  *                  discovered.
12325ffb0c9bSToomas Soome  *
12335ffb0c9bSToomas Soome  *                  The group identifier itself is not sent in clear. Only a hash of the group
12345ffb0c9bSToomas Soome  *                  identifier is sent and the clients discover them anonymously. The group identifier
12355ffb0c9bSToomas Soome  *                  may be up to 256 bytes long and may contain any eight bit values except comma which
12365ffb0c9bSToomas Soome  *                  should be escaped.
12375ffb0c9bSToomas Soome  *
12384b22b933Srs  * domain:          If non-NULL, specifies the domain on which to advertise the service.
12394b22b933Srs  *                  Most applications will not specify a domain, instead automatically
12404b22b933Srs  *                  registering in the default domain(s).
12414b22b933Srs  *
12425ffb0c9bSToomas Soome  * host:            If non-NULL, specifies the SRV target host name. Most applications
12434b22b933Srs  *                  will not specify a host, instead automatically using the machine's
12445ffb0c9bSToomas Soome  *                  default host name(s). Note that specifying a non-NULL host does NOT
12454b22b933Srs  *                  create an address record for that host - the application is responsible
12464b22b933Srs  *                  for ensuring that the appropriate address record exists, or creating it
12474b22b933Srs  *                  via DNSServiceRegisterRecord().
12484b22b933Srs  *
12494b22b933Srs  * port:            The port, in network byte order, on which the service accepts connections.
12504b22b933Srs  *                  Pass 0 for a "placeholder" service (i.e. a service that will not be discovered
12514b22b933Srs  *                  by browsing, but will cause a name conflict if another client tries to
12525ffb0c9bSToomas Soome  *                  register that same name). Most clients will not use placeholder services.
12534b22b933Srs  *
12545ffb0c9bSToomas Soome  * txtLen:          The length of the txtRecord, in bytes. Must be zero if the txtRecord is NULL.
12554b22b933Srs  *
12564b22b933Srs  * txtRecord:       The TXT record rdata. A non-NULL txtRecord MUST be a properly formatted DNS
12574b22b933Srs  *                  TXT record, i.e. <length byte> <data> <length byte> <data> ...
12584b22b933Srs  *                  Passing NULL for the txtRecord is allowed as a synonym for txtLen=1, txtRecord="",
12594b22b933Srs  *                  i.e. it creates a TXT record of length one containing a single empty string.
12604b22b933Srs  *                  RFC 1035 doesn't allow a TXT record to contain *zero* strings, so a single empty
12614b22b933Srs  *                  string is the smallest legal DNS TXT record.
12624b22b933Srs  *                  As with the other parameters, the DNSServiceRegister call copies the txtRecord
12634b22b933Srs  *                  data; e.g. if you allocated the storage for the txtRecord parameter with malloc()
12644b22b933Srs  *                  then you can safely free that memory right after the DNSServiceRegister call returns.
12654b22b933Srs  *
12664b22b933Srs  * callBack:        The function to be called when the registration completes or asynchronously
12675ffb0c9bSToomas Soome  *                  fails. The client MAY pass NULL for the callback -  The client will NOT be notified
12684b22b933Srs  *                  of the default values picked on its behalf, and the client will NOT be notified of any
12694b22b933Srs  *                  asynchronous errors (e.g. out of memory errors, etc.) that may prevent the registration
12705ffb0c9bSToomas Soome  *                  of the service. The client may NOT pass the NoAutoRename flag if the callback is NULL.
12714b22b933Srs  *                  The client may still deregister the service at any time via DNSServiceRefDeallocate().
12724b22b933Srs  *
12734b22b933Srs  * context:         An application context pointer which is passed to the callback function
12744b22b933Srs  *                  (may be NULL).
12754b22b933Srs  *
12765ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
12774b22b933Srs  *                  errors are delivered to the callback), otherwise returns an error code indicating
12784b22b933Srs  *                  the error that occurred (the callback is never invoked and the DNSServiceRef
12795ffb0c9bSToomas Soome  *                  is not initialized).
12804b22b933Srs  */
12814b22b933Srs 
1282*3b436d06SToomas Soome DNSSD_EXPORT
12834b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceRegister
12845ffb0c9bSToomas Soome (
12854b22b933Srs     DNSServiceRef                       *sdRef,
12865ffb0c9bSToomas Soome     DNSServiceFlags flags,
12875ffb0c9bSToomas Soome     uint32_t interfaceIndex,
12884b22b933Srs     const char                          *name,         /* may be NULL */
12894b22b933Srs     const char                          *regtype,
12904b22b933Srs     const char                          *domain,       /* may be NULL */
12914b22b933Srs     const char                          *host,         /* may be NULL */
12925ffb0c9bSToomas Soome     uint16_t port,                                     /* In network byte order */
12935ffb0c9bSToomas Soome     uint16_t txtLen,
12944b22b933Srs     const void                          *txtRecord,    /* may be NULL */
12955ffb0c9bSToomas Soome     DNSServiceRegisterReply callBack,                  /* may be NULL */
12964b22b933Srs     void                                *context       /* may be NULL */
12975ffb0c9bSToomas Soome );
12984b22b933Srs 
12994b22b933Srs 
13004b22b933Srs /* DNSServiceAddRecord()
13014b22b933Srs  *
13025ffb0c9bSToomas Soome  * Add a record to a registered service. The name of the record will be the same as the
13034b22b933Srs  * registered service's name.
13044b22b933Srs  * The record can later be updated or deregistered by passing the RecordRef initialized
13054b22b933Srs  * by this function to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
13064b22b933Srs  *
13074b22b933Srs  * Note that the DNSServiceAddRecord/UpdateRecord/RemoveRecord are *NOT* thread-safe
13084b22b933Srs  * with respect to a single DNSServiceRef. If you plan to have multiple threads
13094b22b933Srs  * in your program simultaneously add, update, or remove records from the same
1310c65ebfc7SToomas Soome  * DNSServiceRef, then it's the caller's responsibility to use a mutex lock
13114b22b933Srs  * or take similar appropriate precautions to serialize those calls.
13124b22b933Srs  *
13134b22b933Srs  * Parameters;
13144b22b933Srs  *
13154b22b933Srs  * sdRef:           A DNSServiceRef initialized by DNSServiceRegister().
13164b22b933Srs  *
13175ffb0c9bSToomas Soome  * RecordRef:       A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this
13184b22b933Srs  *                  call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord().
13194b22b933Srs  *                  If the above DNSServiceRef is passed to DNSServiceRefDeallocate(), RecordRef is also
13204b22b933Srs  *                  invalidated and may not be used further.
13214b22b933Srs  *
13224b22b933Srs  * flags:           Currently ignored, reserved for future use.
13234b22b933Srs  *
13244b22b933Srs  * rrtype:          The type of the record (e.g. kDNSServiceType_TXT, kDNSServiceType_SRV, etc)
13254b22b933Srs  *
13264b22b933Srs  * rdlen:           The length, in bytes, of the rdata.
13274b22b933Srs  *
13284b22b933Srs  * rdata:           The raw rdata to be contained in the added resource record.
13294b22b933Srs  *
13305ffb0c9bSToomas Soome  * ttl:             The time to live of the resource record, in seconds.
13315ffb0c9bSToomas Soome  *                  Most clients should pass 0 to indicate that the system should
13325ffb0c9bSToomas Soome  *                  select a sensible default value.
13334b22b933Srs  *
13344b22b933Srs  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
13354b22b933Srs  *                  error code indicating the error that occurred (the RecordRef is not initialized).
13364b22b933Srs  */
13374b22b933Srs 
1338*3b436d06SToomas Soome DNSSD_EXPORT
13394b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceAddRecord
13405ffb0c9bSToomas Soome (
13415ffb0c9bSToomas Soome     DNSServiceRef sdRef,
13424b22b933Srs     DNSRecordRef                        *RecordRef,
13435ffb0c9bSToomas Soome     DNSServiceFlags flags,
13445ffb0c9bSToomas Soome     uint16_t rrtype,
13455ffb0c9bSToomas Soome     uint16_t rdlen,
13464b22b933Srs     const void                          *rdata,
13475ffb0c9bSToomas Soome     uint32_t ttl
13485ffb0c9bSToomas Soome );
13494b22b933Srs 
13504b22b933Srs 
13514b22b933Srs /* DNSServiceUpdateRecord
13524b22b933Srs  *
13535ffb0c9bSToomas Soome  * Update a registered resource record. The record must either be:
13544b22b933Srs  *   - The primary txt record of a service registered via DNSServiceRegister()
13554b22b933Srs  *   - A record added to a registered service via DNSServiceAddRecord()
13564b22b933Srs  *   - An individual record registered by DNSServiceRegisterRecord()
13574b22b933Srs  *
13584b22b933Srs  * Parameters:
13594b22b933Srs  *
13604b22b933Srs  * sdRef:           A DNSServiceRef that was initialized by DNSServiceRegister()
13614b22b933Srs  *                  or DNSServiceCreateConnection().
13624b22b933Srs  *
13634b22b933Srs  * RecordRef:       A DNSRecordRef initialized by DNSServiceAddRecord, or NULL to update the
13644b22b933Srs  *                  service's primary txt record.
13654b22b933Srs  *
13664b22b933Srs  * flags:           Currently ignored, reserved for future use.
13674b22b933Srs  *
13684b22b933Srs  * rdlen:           The length, in bytes, of the new rdata.
13694b22b933Srs  *
13704b22b933Srs  * rdata:           The new rdata to be contained in the updated resource record.
13714b22b933Srs  *
13724b22b933Srs  * ttl:             The time to live of the updated resource record, in seconds.
13735ffb0c9bSToomas Soome  *                  Most clients should pass 0 to indicate that the system should
13745ffb0c9bSToomas Soome  *                  select a sensible default value.
13754b22b933Srs  *
13764b22b933Srs  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
13774b22b933Srs  *                  error code indicating the error that occurred.
13784b22b933Srs  */
13794b22b933Srs 
1380*3b436d06SToomas Soome DNSSD_EXPORT
13814b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceUpdateRecord
13825ffb0c9bSToomas Soome (
13835ffb0c9bSToomas Soome     DNSServiceRef sdRef,
13845ffb0c9bSToomas Soome     DNSRecordRef RecordRef,                            /* may be NULL */
13855ffb0c9bSToomas Soome     DNSServiceFlags flags,
13865ffb0c9bSToomas Soome     uint16_t rdlen,
13874b22b933Srs     const void                          *rdata,
13885ffb0c9bSToomas Soome     uint32_t ttl
13895ffb0c9bSToomas Soome );
13904b22b933Srs 
13914b22b933Srs 
13924b22b933Srs /* DNSServiceRemoveRecord
13934b22b933Srs  *
13944b22b933Srs  * Remove a record previously added to a service record set via DNSServiceAddRecord(), or deregister
1395c65ebfc7SToomas Soome  * a record registered individually via DNSServiceRegisterRecord().
13964b22b933Srs  *
13974b22b933Srs  * Parameters:
13984b22b933Srs  *
13994b22b933Srs  * sdRef:           A DNSServiceRef initialized by DNSServiceRegister() (if the
14004b22b933Srs  *                  record being removed was registered via DNSServiceAddRecord()) or by
14014b22b933Srs  *                  DNSServiceCreateConnection() (if the record being removed was registered via
14024b22b933Srs  *                  DNSServiceRegisterRecord()).
14034b22b933Srs  *
14044b22b933Srs  * recordRef:       A DNSRecordRef initialized by a successful call to DNSServiceAddRecord()
14054b22b933Srs  *                  or DNSServiceRegisterRecord().
14064b22b933Srs  *
14074b22b933Srs  * flags:           Currently ignored, reserved for future use.
14084b22b933Srs  *
14094b22b933Srs  * return value:    Returns kDNSServiceErr_NoError on success, otherwise returns an
14104b22b933Srs  *                  error code indicating the error that occurred.
14114b22b933Srs  */
14124b22b933Srs 
1413*3b436d06SToomas Soome DNSSD_EXPORT
14144b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceRemoveRecord
14155ffb0c9bSToomas Soome (
14165ffb0c9bSToomas Soome     DNSServiceRef sdRef,
14175ffb0c9bSToomas Soome     DNSRecordRef RecordRef,
14185ffb0c9bSToomas Soome     DNSServiceFlags flags
14195ffb0c9bSToomas Soome );
14204b22b933Srs 
14214b22b933Srs 
14224b22b933Srs /*********************************************************************************************
14235ffb0c9bSToomas Soome *
14245ffb0c9bSToomas Soome *  Service Discovery
14255ffb0c9bSToomas Soome *
14265ffb0c9bSToomas Soome *********************************************************************************************/
14274b22b933Srs 
14284b22b933Srs /* Browse for instances of a service.
14294b22b933Srs  *
14304b22b933Srs  * DNSServiceBrowseReply() Parameters:
14314b22b933Srs  *
14324b22b933Srs  * sdRef:           The DNSServiceRef initialized by DNSServiceBrowse().
14334b22b933Srs  *
14344b22b933Srs  * flags:           Possible values are kDNSServiceFlagsMoreComing and kDNSServiceFlagsAdd.
14354b22b933Srs  *                  See flag definitions for details.
14364b22b933Srs  *
14375ffb0c9bSToomas Soome  * interfaceIndex:  The interface on which the service is advertised. This index should
14384b22b933Srs  *                  be passed to DNSServiceResolve() when resolving the service.
14394b22b933Srs  *
14404b22b933Srs  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise will
14415ffb0c9bSToomas Soome  *                  indicate the failure that occurred. Other parameters are undefined if
14424b22b933Srs  *                  the errorCode is nonzero.
14434b22b933Srs  *
14444b22b933Srs  * serviceName:     The discovered service name. This name should be displayed to the user,
14454b22b933Srs  *                  and stored for subsequent use in the DNSServiceResolve() call.
14464b22b933Srs  *
14474b22b933Srs  * regtype:         The service type, which is usually (but not always) the same as was passed
14484b22b933Srs  *                  to DNSServiceBrowse(). One case where the discovered service type may
14494b22b933Srs  *                  not be the same as the requested service type is when using subtypes:
14504b22b933Srs  *                  The client may want to browse for only those ftp servers that allow
14514b22b933Srs  *                  anonymous connections. The client will pass the string "_ftp._tcp,_anon"
14524b22b933Srs  *                  to DNSServiceBrowse(), but the type of the service that's discovered
14534b22b933Srs  *                  is simply "_ftp._tcp". The regtype for each discovered service instance
14544b22b933Srs  *                  should be stored along with the name, so that it can be passed to
14554b22b933Srs  *                  DNSServiceResolve() when the service is later resolved.
14564b22b933Srs  *
14574b22b933Srs  * domain:          The domain of the discovered service instance. This may or may not be the
14584b22b933Srs  *                  same as the domain that was passed to DNSServiceBrowse(). The domain for each
14594b22b933Srs  *                  discovered service instance should be stored along with the name, so that
14604b22b933Srs  *                  it can be passed to DNSServiceResolve() when the service is later resolved.
14614b22b933Srs  *
14624b22b933Srs  * context:         The context pointer that was passed to the callout.
14634b22b933Srs  *
14644b22b933Srs  */
14654b22b933Srs 
14664b22b933Srs typedef void (DNSSD_API *DNSServiceBrowseReply)
14675ffb0c9bSToomas Soome (
14685ffb0c9bSToomas Soome     DNSServiceRef sdRef,
14695ffb0c9bSToomas Soome     DNSServiceFlags flags,
14705ffb0c9bSToomas Soome     uint32_t interfaceIndex,
14715ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
14724b22b933Srs     const char                          *serviceName,
14734b22b933Srs     const char                          *regtype,
14744b22b933Srs     const char                          *replyDomain,
14754b22b933Srs     void                                *context
14765ffb0c9bSToomas Soome );
14774b22b933Srs 
14784b22b933Srs 
14794b22b933Srs /* DNSServiceBrowse() Parameters:
14804b22b933Srs  *
14815ffb0c9bSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef. If the call succeeds
14824b22b933Srs  *                  then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
14834b22b933Srs  *                  and the browse operation will run indefinitely until the client
14844b22b933Srs  *                  terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
14854b22b933Srs  *
14864b22b933Srs  * flags:           Currently ignored, reserved for future use.
14874b22b933Srs  *
14884b22b933Srs  * interfaceIndex:  If non-zero, specifies the interface on which to browse for services
14894b22b933Srs  *                  (the index for a given interface is determined via the if_nametoindex()
14905ffb0c9bSToomas Soome  *                  family of calls.) Most applications will pass 0 to browse on all available
14914b22b933Srs  *                  interfaces. See "Constants for specifying an interface index" for more details.
14924b22b933Srs  *
14934b22b933Srs  * regtype:         The service type being browsed for followed by the protocol, separated by a
14945ffb0c9bSToomas Soome  *                  dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp".
14955ffb0c9bSToomas Soome  *                  A client may optionally specify a single subtype to perform filtered browsing:
14965ffb0c9bSToomas Soome  *                  e.g. browsing for "_primarytype._tcp,_subtype" will discover only those
14975ffb0c9bSToomas Soome  *                  instances of "_primarytype._tcp" that were registered specifying "_subtype"
14985ffb0c9bSToomas Soome  *                  in their list of registered subtypes. Additionally, a group identifier may
14995ffb0c9bSToomas Soome  *                  also be specified before the subtype e.g., _primarytype._tcp:GroupID, which
15005ffb0c9bSToomas Soome  *                  will discover only the members that register the service with GroupID. See
15015ffb0c9bSToomas Soome  *                  DNSServiceRegister for more details.
15024b22b933Srs  *
15034b22b933Srs  * domain:          If non-NULL, specifies the domain on which to browse for services.
15044b22b933Srs  *                  Most applications will not specify a domain, instead browsing on the
15054b22b933Srs  *                  default domain(s).
15064b22b933Srs  *
15074b22b933Srs  * callBack:        The function to be called when an instance of the service being browsed for
15084b22b933Srs  *                  is found, or if the call asynchronously fails.
15094b22b933Srs  *
15104b22b933Srs  * context:         An application context pointer which is passed to the callback function
15114b22b933Srs  *                  (may be NULL).
15124b22b933Srs  *
15135ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
15144b22b933Srs  *                  errors are delivered to the callback), otherwise returns an error code indicating
15154b22b933Srs  *                  the error that occurred (the callback is not invoked and the DNSServiceRef
15165ffb0c9bSToomas Soome  *                  is not initialized).
15174b22b933Srs  */
15184b22b933Srs 
1519*3b436d06SToomas Soome DNSSD_EXPORT
15204b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceBrowse
15215ffb0c9bSToomas Soome (
15224b22b933Srs     DNSServiceRef                       *sdRef,
15235ffb0c9bSToomas Soome     DNSServiceFlags flags,
15245ffb0c9bSToomas Soome     uint32_t interfaceIndex,
15254b22b933Srs     const char                          *regtype,
15264b22b933Srs     const char                          *domain,    /* may be NULL */
15275ffb0c9bSToomas Soome     DNSServiceBrowseReply callBack,
15284b22b933Srs     void                                *context    /* may be NULL */
15295ffb0c9bSToomas Soome );
15304b22b933Srs 
15314b22b933Srs 
15324b22b933Srs /* DNSServiceResolve()
15334b22b933Srs  *
15344b22b933Srs  * Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and
15354b22b933Srs  * txt record.
15364b22b933Srs  *
15374b22b933Srs  * Note: Applications should NOT use DNSServiceResolve() solely for txt record monitoring - use
15384b22b933Srs  * DNSServiceQueryRecord() instead, as it is more efficient for this task.
15394b22b933Srs  *
15404b22b933Srs  * Note: When the desired results have been returned, the client MUST terminate the resolve by calling
15414b22b933Srs  * DNSServiceRefDeallocate().
15424b22b933Srs  *
15434b22b933Srs  * Note: DNSServiceResolve() behaves correctly for typical services that have a single SRV record
15444b22b933Srs  * and a single TXT record. To resolve non-standard services with multiple SRV or TXT records,
15454b22b933Srs  * DNSServiceQueryRecord() should be used.
15464b22b933Srs  *
15474b22b933Srs  * DNSServiceResolveReply Callback Parameters:
15484b22b933Srs  *
15494b22b933Srs  * sdRef:           The DNSServiceRef initialized by DNSServiceResolve().
15504b22b933Srs  *
15515ffb0c9bSToomas Soome  * flags:           Possible values: kDNSServiceFlagsMoreComing
15524b22b933Srs  *
15534b22b933Srs  * interfaceIndex:  The interface on which the service was resolved.
15544b22b933Srs  *
15554b22b933Srs  * errorCode:       Will be kDNSServiceErr_NoError (0) on success, otherwise will
15565ffb0c9bSToomas Soome  *                  indicate the failure that occurred. Other parameters are undefined if
15574b22b933Srs  *                  the errorCode is nonzero.
15584b22b933Srs  *
15594b22b933Srs  * fullname:        The full service domain name, in the form <servicename>.<protocol>.<domain>.
15604b22b933Srs  *                  (This name is escaped following standard DNS rules, making it suitable for
15614b22b933Srs  *                  passing to standard system DNS APIs such as res_query(), or to the
15624b22b933Srs  *                  special-purpose functions included in this API that take fullname parameters.
15634b22b933Srs  *                  See "Notes on DNS Name Escaping" earlier in this file for more details.)
15644b22b933Srs  *
15655ffb0c9bSToomas Soome  * hosttarget:      The target hostname of the machine providing the service. This name can
15664b22b933Srs  *                  be passed to functions like gethostbyname() to identify the host's IP address.
15674b22b933Srs  *
15684b22b933Srs  * port:            The port, in network byte order, on which connections are accepted for this service.
15694b22b933Srs  *
15704b22b933Srs  * txtLen:          The length of the txt record, in bytes.
15714b22b933Srs  *
15724b22b933Srs  * txtRecord:       The service's primary txt record, in standard txt record format.
15734b22b933Srs  *
15744b22b933Srs  * context:         The context pointer that was passed to the callout.
15754b22b933Srs  *
15764b22b933Srs  * NOTE: In earlier versions of this header file, the txtRecord parameter was declared "const char *"
15774b22b933Srs  * This is incorrect, since it contains length bytes which are values in the range 0 to 255, not -128 to +127.
15784b22b933Srs  * Depending on your compiler settings, this change may cause signed/unsigned mismatch warnings.
15794b22b933Srs  * These should be fixed by updating your own callback function definition to match the corrected
15804b22b933Srs  * function signature using "const unsigned char *txtRecord". Making this change may also fix inadvertent
15814b22b933Srs  * bugs in your callback function, where it could have incorrectly interpreted a length byte with value 250
15824b22b933Srs  * as being -6 instead, with various bad consequences ranging from incorrect operation to software crashes.
15834b22b933Srs  * If you need to maintain portable code that will compile cleanly with both the old and new versions of
15844b22b933Srs  * this header file, you should update your callback function definition to use the correct unsigned value,
15854b22b933Srs  * and then in the place where you pass your callback function to DNSServiceResolve(), use a cast to eliminate
15864b22b933Srs  * the compiler warning, e.g.:
15874b22b933Srs  *   DNSServiceResolve(sd, flags, index, name, regtype, domain, (DNSServiceResolveReply)MyCallback, context);
15884b22b933Srs  * This will ensure that your code compiles cleanly without warnings (and more importantly, works correctly)
15894b22b933Srs  * with both the old header and with the new corrected version.
15904b22b933Srs  *
15914b22b933Srs  */
15924b22b933Srs 
15934b22b933Srs typedef void (DNSSD_API *DNSServiceResolveReply)
15945ffb0c9bSToomas Soome (
15955ffb0c9bSToomas Soome     DNSServiceRef sdRef,
15965ffb0c9bSToomas Soome     DNSServiceFlags flags,
15975ffb0c9bSToomas Soome     uint32_t interfaceIndex,
15985ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
15994b22b933Srs     const char                          *fullname,
16004b22b933Srs     const char                          *hosttarget,
16015ffb0c9bSToomas Soome     uint16_t port,                                   /* In network byte order */
16025ffb0c9bSToomas Soome     uint16_t txtLen,
16034b22b933Srs     const unsigned char                 *txtRecord,
16044b22b933Srs     void                                *context
16055ffb0c9bSToomas Soome );
16064b22b933Srs 
16074b22b933Srs 
16084b22b933Srs /* DNSServiceResolve() Parameters
16094b22b933Srs  *
16105ffb0c9bSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef. If the call succeeds
16114b22b933Srs  *                  then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
16124b22b933Srs  *                  and the resolve operation will run indefinitely until the client
16134b22b933Srs  *                  terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
16144b22b933Srs  *
16155ffb0c9bSToomas Soome  * flags:           Specifying kDNSServiceFlagsForceMulticast will cause query to be
16165ffb0c9bSToomas Soome  *                  performed with a link-local mDNS query, even if the name is an
16175ffb0c9bSToomas Soome  *                  apparently non-local name (i.e. a name not ending in ".local.")
16184b22b933Srs  *
16194b22b933Srs  * interfaceIndex:  The interface on which to resolve the service. If this resolve call is
16204b22b933Srs  *                  as a result of a currently active DNSServiceBrowse() operation, then the
16214b22b933Srs  *                  interfaceIndex should be the index reported in the DNSServiceBrowseReply
16224b22b933Srs  *                  callback. If this resolve call is using information previously saved
16234b22b933Srs  *                  (e.g. in a preference file) for later use, then use interfaceIndex 0, because
16244b22b933Srs  *                  the desired service may now be reachable via a different physical interface.
16254b22b933Srs  *                  See "Constants for specifying an interface index" for more details.
16264b22b933Srs  *
16274b22b933Srs  * name:            The name of the service instance to be resolved, as reported to the
16284b22b933Srs  *                  DNSServiceBrowseReply() callback.
16294b22b933Srs  *
16304b22b933Srs  * regtype:         The type of the service instance to be resolved, as reported to the
16314b22b933Srs  *                  DNSServiceBrowseReply() callback.
16324b22b933Srs  *
16334b22b933Srs  * domain:          The domain of the service instance to be resolved, as reported to the
16344b22b933Srs  *                  DNSServiceBrowseReply() callback.
16354b22b933Srs  *
16364b22b933Srs  * callBack:        The function to be called when a result is found, or if the call
16374b22b933Srs  *                  asynchronously fails.
16384b22b933Srs  *
16394b22b933Srs  * context:         An application context pointer which is passed to the callback function
16404b22b933Srs  *                  (may be NULL).
16414b22b933Srs  *
16425ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
16434b22b933Srs  *                  errors are delivered to the callback), otherwise returns an error code indicating
16444b22b933Srs  *                  the error that occurred (the callback is never invoked and the DNSServiceRef
16455ffb0c9bSToomas Soome  *                  is not initialized).
16464b22b933Srs  */
16474b22b933Srs 
1648*3b436d06SToomas Soome DNSSD_EXPORT
16494b22b933Srs DNSServiceErrorType DNSSD_API DNSServiceResolve
16505ffb0c9bSToomas Soome (
16514b22b933Srs     DNSServiceRef                       *sdRef,
16525ffb0c9bSToomas Soome     DNSServiceFlags flags,
16535ffb0c9bSToomas Soome     uint32_t interfaceIndex,
16544b22b933Srs     const char                          *name,
16554b22b933Srs     const char                          *regtype,
16564b22b933Srs     const char                          *domain,
16575ffb0c9bSToomas Soome     DNSServiceResolveReply callBack,
16584b22b933Srs     void                                *context  /* may be NULL */
16595ffb0c9bSToomas Soome );
16604b22b933Srs 
16614b22b933Srs 
16624b22b933Srs /*********************************************************************************************
16635ffb0c9bSToomas Soome *
16645ffb0c9bSToomas Soome *  Querying Individual Specific Records
16655ffb0c9bSToomas Soome *
16665ffb0c9bSToomas Soome *********************************************************************************************/
16675ffb0c9bSToomas Soome 
16685ffb0c9bSToomas Soome /* DNSServiceQueryRecord
16695ffb0c9bSToomas Soome  *
16705ffb0c9bSToomas Soome  * Query for an arbitrary DNS record.
16715ffb0c9bSToomas Soome  *
16725ffb0c9bSToomas Soome  * DNSServiceQueryRecordReply() Callback Parameters:
16735ffb0c9bSToomas Soome  *
16745ffb0c9bSToomas Soome  * sdRef:           The DNSServiceRef initialized by DNSServiceQueryRecord().
16755ffb0c9bSToomas Soome  *
16765ffb0c9bSToomas Soome  * flags:           Possible values are kDNSServiceFlagsMoreComing and
16775ffb0c9bSToomas Soome  *                  kDNSServiceFlagsAdd. The Add flag is NOT set for PTR records
16785ffb0c9bSToomas Soome  *                  with a ttl of 0, i.e. "Remove" events.
16795ffb0c9bSToomas Soome  *
16805ffb0c9bSToomas Soome  * interfaceIndex:  The interface on which the query was resolved (the index for a given
16815ffb0c9bSToomas Soome  *                  interface is determined via the if_nametoindex() family of calls).
16825ffb0c9bSToomas Soome  *                  See "Constants for specifying an interface index" for more details.
16835ffb0c9bSToomas Soome  *
16845ffb0c9bSToomas Soome  * errorCode:       Will be kDNSServiceErr_NoError on success, otherwise will
16855ffb0c9bSToomas Soome  *                  indicate the failure that occurred. Other parameters are undefined if
16865ffb0c9bSToomas Soome  *                  errorCode is nonzero.
16875ffb0c9bSToomas Soome  *
16885ffb0c9bSToomas Soome  * fullname:        The resource record's full domain name.
16895ffb0c9bSToomas Soome  *
16905ffb0c9bSToomas Soome  * rrtype:          The resource record's type (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc)
16915ffb0c9bSToomas Soome  *
16925ffb0c9bSToomas Soome  * rrclass:         The class of the resource record (usually kDNSServiceClass_IN).
16935ffb0c9bSToomas Soome  *
16945ffb0c9bSToomas Soome  * rdlen:           The length, in bytes, of the resource record rdata.
16955ffb0c9bSToomas Soome  *
16965ffb0c9bSToomas Soome  * rdata:           The raw rdata of the resource record.
16974b22b933Srs  *
16985ffb0c9bSToomas Soome  * ttl:             If the client wishes to cache the result for performance reasons,
16995ffb0c9bSToomas Soome  *                  the TTL indicates how long the client may legitimately hold onto
17005ffb0c9bSToomas Soome  *                  this result, in seconds. After the TTL expires, the client should
17015ffb0c9bSToomas Soome  *                  consider the result no longer valid, and if it requires this data
17025ffb0c9bSToomas Soome  *                  again, it should be re-fetched with a new query. Of course, this
17035ffb0c9bSToomas Soome  *                  only applies to clients that cancel the asynchronous operation when
17045ffb0c9bSToomas Soome  *                  they get a result. Clients that leave the asynchronous operation
17055ffb0c9bSToomas Soome  *                  running can safely assume that the data remains valid until they
1706c65ebfc7SToomas Soome  *                  get another callback telling them otherwise. The ttl value is not
1707c65ebfc7SToomas Soome  *                  updated when the daemon answers from the cache, hence relying on
1708c65ebfc7SToomas Soome  *                  the accuracy of the ttl value is not recommended.
17094b22b933Srs  *
17105ffb0c9bSToomas Soome  * context:         The context pointer that was passed to the callout.
17115ffb0c9bSToomas Soome  *
17125ffb0c9bSToomas Soome  */
17135ffb0c9bSToomas Soome 
17145ffb0c9bSToomas Soome typedef void (DNSSD_API *DNSServiceQueryRecordReply)
17155ffb0c9bSToomas Soome (
17165ffb0c9bSToomas Soome     DNSServiceRef sdRef,
17175ffb0c9bSToomas Soome     DNSServiceFlags flags,
17185ffb0c9bSToomas Soome     uint32_t interfaceIndex,
17195ffb0c9bSToomas Soome     DNSServiceErrorType errorCode,
17205ffb0c9bSToomas Soome     const char                          *fullname,
17215ffb0c9bSToomas Soome     uint16_t rrtype,
17225ffb0c9bSToomas Soome     uint16_t rrclass,
17235ffb0c9bSToomas Soome     uint16_t rdlen,
17245ffb0c9bSToomas Soome     const void                          *rdata,
17255ffb0c9bSToomas Soome     uint32_t ttl,
17265ffb0c9bSToomas Soome     void                                *context
17275ffb0c9bSToomas Soome );
17285ffb0c9bSToomas Soome 
17295ffb0c9bSToomas Soome 
17305ffb0c9bSToomas Soome /* DNSServiceQueryRecord() Parameters:
17315ffb0c9bSToomas Soome  *
17325ffb0c9bSToomas Soome  * sdRef:           A pointer to an uninitialized DNSServiceRef. If the call succeeds
17335ffb0c9bSToomas Soome  *                  then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError,
17345ffb0c9bSToomas Soome  *                  and the query operation will run indefinitely until the client
17355ffb0c9bSToomas Soome  *                  terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate().
17365ffb0c9bSToomas Soome  *
17375ffb0c9bSToomas Soome  * flags:           kDNSServiceFlagsForceMulticast or kDNSServiceFlagsLongLivedQuery.
17385ffb0c9bSToomas Soome  *                  Pass kDNSServiceFlagsLongLivedQuery to create a "long-lived" unicast
17395ffb0c9bSToomas Soome  *                  query to a unicast DNS server that implements the protocol. This flag
17405ffb0c9bSToomas Soome  *                  has no effect on link-local multicast queries.
17415ffb0c9bSToomas Soome  *
17425ffb0c9bSToomas Soome  * interfaceIndex:  If non-zero, specifies the interface on which to issue the query
17435ffb0c9bSToomas Soome  *                  (the index for a given interface is determined via the if_nametoindex()
17445ffb0c9bSToomas Soome  *                  family of calls.) Passing 0 causes the name to be queried for on all
17455ffb0c9bSToomas Soome  *                  interfaces. See "Constants for specifying an interface index" for more details.
17465ffb0c9bSToomas Soome  *
17475ffb0c9bSToomas Soome  * fullname:        The full domain name of the resource record to be queried for.
17485ffb0c9bSToomas Soome  *
17495ffb0c9bSToomas Soome  * rrtype:          The numerical type of the resource record to be queried for
17505ffb0c9bSToomas Soome  *                  (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc)
17515ffb0c9bSToomas Soome  *
17525ffb0c9bSToomas Soome  * rrclass:         The class of the resource record (usually kDNSServiceClass_IN).
17535ffb0c9bSToomas Soome  *
17545ffb0c9bSToomas Soome  * callBack:        The function to be called when a result is found, or if the call
17555ffb0c9bSToomas Soome  *                  asynchronously fails.
17565ffb0c9bSToomas Soome  *
17575ffb0c9bSToomas Soome  * context:         An application context pointer which is passed to the callback function
17585ffb0c9bSToomas Soome  *                  (may be NULL).
17595ffb0c9bSToomas Soome  *
17605ffb0c9bSToomas Soome  * return value:    Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous
17615ffb0c9bSToomas Soome  *                  errors are delivered to the callback), otherwise returns an error code indicating
17625ffb0c9bSToomas Soome  *                  the error that occurred (the callback is never invoked and the DNSServiceRef
17635ffb0c9bSToomas Soome  *                  is not initialized).
17645ffb0c9bSToomas Soome  */
17655ffb0c9bSToomas Soome 
1766*3b436d06SToomas Soome DNSSD_EXPORT
17675ffb0c9bSToomas Soome DNSServiceErrorType DNSSD_API DNSServiceQueryRecord
17685ffb0c9bSToomas Soome (
17695ffb0c9bSToomas Soome     DNSServiceRef                       *sdRef,
17705ffb0c9bSToomas Soome     DNSServiceFlags flags,
17715ffb0c9bSToomas Soome     uint32_t interfaceIndex,
17725ffb0c9bSToomas Soome     const char                          *fullname,
17735ffb0c9bSToomas Soome     uint16_t rrtype,
17745ffb0c9bSToomas Soome     uint16_t rrclass,
17755ffb0c9bSToomas Soome     DNSServiceQueryRecordReply callBack,
17765ffb0c9bSToomas Soome     void                                *context  /* may be NULL */
17775ffb0c9bSToomas Soome );
17785ffb0c9bSToomas Soome 
17795ffb0c9bSToomas Soome 
17805ffb0c9bSToomas Soome /*********************************************************************************************
17815ffb0c9bSToomas Soome *
17825ffb0c9bSToomas Soome *  Unified lookup of both IPv4 and IPv6 addresses for a fully qualified hostname
17835ffb0c9bSToomas Soome *
17845ffb0c9bSToomas Soome *********************************************************************************************/
17855ffb0c9bSToomas Soome 
17865ffb0c9bSToomas Soome /* DNSServiceGetAddrInfo
1787