1c65ebfc7SToomas Soome /* -*- Mode: C; tab-width: 4 -*- 2c65ebfc7SToomas Soome * 33b436d06SToomas Soome * Copyright (c) 2003-2018 Apple Inc. All rights reserved. 4c65ebfc7SToomas Soome * 5c65ebfc7SToomas Soome * Redistribution and use in source and binary forms, with or without 6c65ebfc7SToomas Soome * modification, are permitted provided that the following conditions are met: 7c65ebfc7SToomas Soome * 8c65ebfc7SToomas Soome * 1. Redistributions of source code must retain the above copyright notice, 9c65ebfc7SToomas Soome * this list of conditions and the following disclaimer. 10c65ebfc7SToomas Soome * 2. Redistributions in binary form must reproduce the above copyright notice, 11c65ebfc7SToomas Soome * this list of conditions and the following disclaimer in the documentation 12c65ebfc7SToomas Soome * and/or other materials provided with the distribution. 13c65ebfc7SToomas Soome * 3. Neither the name of Apple Inc. ("Apple") nor the names of its 14c65ebfc7SToomas Soome * contributors may be used to endorse or promote products derived from this 15c65ebfc7SToomas Soome * software without specific prior written permission. 16c65ebfc7SToomas Soome * 17c65ebfc7SToomas Soome * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY 18c65ebfc7SToomas Soome * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 19c65ebfc7SToomas Soome * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 20c65ebfc7SToomas Soome * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY 21c65ebfc7SToomas Soome * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 22c65ebfc7SToomas Soome * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 23c65ebfc7SToomas Soome * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 24c65ebfc7SToomas Soome * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 25c65ebfc7SToomas Soome * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 26c65ebfc7SToomas Soome * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27c65ebfc7SToomas Soome */ 28c65ebfc7SToomas Soome 29c65ebfc7SToomas Soome 30c65ebfc7SToomas Soome /*! @header DNS Service Discovery 31c65ebfc7SToomas Soome * 32c65ebfc7SToomas Soome * @discussion This section describes the functions, callbacks, and data structures 33c65ebfc7SToomas Soome * that make up the DNS Service Discovery API. 34c65ebfc7SToomas Soome * 35c65ebfc7SToomas Soome * The DNS Service Discovery API is part of Bonjour, Apple's implementation 36c65ebfc7SToomas Soome * of zero-configuration networking (ZEROCONF). 37c65ebfc7SToomas Soome * 38c65ebfc7SToomas Soome * Bonjour allows you to register a network service, such as a 39c65ebfc7SToomas Soome * printer or file server, so that it can be found by name or browsed 40c65ebfc7SToomas Soome * for by service type and domain. Using Bonjour, applications can 41c65ebfc7SToomas Soome * discover what services are available on the network, along with 42c65ebfc7SToomas Soome * all the information -- such as name, IP address, and port -- 43c65ebfc7SToomas Soome * necessary to access a particular service. 44c65ebfc7SToomas Soome * 45c65ebfc7SToomas Soome * In effect, Bonjour combines the functions of a local DNS server and 46c65ebfc7SToomas Soome * AppleTalk. Bonjour allows applications to provide user-friendly printer 47c65ebfc7SToomas Soome * and server browsing, among other things, over standard IP networks. 48c65ebfc7SToomas Soome * This behavior is a result of combining protocols such as multicast and 49c65ebfc7SToomas Soome * DNS to add new functionality to the network (such as multicast DNS). 50c65ebfc7SToomas Soome * 51c65ebfc7SToomas Soome * Bonjour gives applications easy access to services over local IP 52c65ebfc7SToomas Soome * networks without requiring the service or the application to support 53c65ebfc7SToomas Soome * an AppleTalk or a Netbeui stack, and without requiring a DNS server 54c65ebfc7SToomas Soome * for the local network. 55c65ebfc7SToomas Soome */ 56c65ebfc7SToomas Soome 57c65ebfc7SToomas Soome /* _DNS_SD_H contains the API version number for this header file 58c65ebfc7SToomas Soome * The API version defined in this header file symbol allows for compile-time 59c65ebfc7SToomas Soome * checking, so that C code building with earlier versions of the header file 60c65ebfc7SToomas Soome * can avoid compile errors trying to use functions that aren't even defined 61c65ebfc7SToomas Soome * in those earlier versions. Similar checks may also be performed at run-time: 62c65ebfc7SToomas Soome * => weak linking -- to avoid link failures if run with an earlier 63c65ebfc7SToomas Soome * version of the library that's missing some desired symbol, or 64c65ebfc7SToomas Soome * => DNSServiceGetProperty(DaemonVersion) -- to verify whether the running daemon 65c65ebfc7SToomas Soome * ("system service" on Windows) meets some required minimum functionality level. 66c65ebfc7SToomas Soome */ 67c65ebfc7SToomas Soome 68c65ebfc7SToomas Soome #ifndef _DNS_SD_H 69*472cd20dSToomas Soome #define _DNS_SD_H 13108001 70c65ebfc7SToomas Soome 71c65ebfc7SToomas Soome #ifdef __cplusplus 72c65ebfc7SToomas Soome extern "C" { 73c65ebfc7SToomas Soome #endif 74c65ebfc7SToomas Soome 75c65ebfc7SToomas Soome /* Set to 1 if libdispatch is supported 76c65ebfc7SToomas Soome * Note: May also be set by project and/or Makefile 77c65ebfc7SToomas Soome */ 783b436d06SToomas Soome #if defined(__APPLE__) 793b436d06SToomas Soome #define _DNS_SD_LIBDISPATCH 1 803b436d06SToomas Soome #else 81c65ebfc7SToomas Soome #define _DNS_SD_LIBDISPATCH 0 823b436d06SToomas Soome #endif 83c65ebfc7SToomas Soome 84c65ebfc7SToomas Soome /* standard calling convention under Win32 is __stdcall */ 85c65ebfc7SToomas Soome /* Note: When compiling Intel EFI (Extensible Firmware Interface) under MS Visual Studio, the */ 86c65ebfc7SToomas Soome /* _WIN32 symbol is defined by the compiler even though it's NOT compiling code for Windows32 */ 87c65ebfc7SToomas Soome #if defined(_WIN32) && !defined(EFI32) && !defined(EFI64) 88c65ebfc7SToomas Soome #define DNSSD_API __stdcall 89c65ebfc7SToomas Soome #else 90c65ebfc7SToomas Soome #define DNSSD_API 91c65ebfc7SToomas Soome #endif 92c65ebfc7SToomas Soome 933b436d06SToomas Soome #if (defined(__GNUC__) && (__GNUC__ >= 4)) 943b436d06SToomas Soome #define DNSSD_EXPORT __attribute__((visibility("default"))) 953b436d06SToomas Soome #else 963b436d06SToomas Soome #define DNSSD_EXPORT 973b436d06SToomas Soome #endif 983b436d06SToomas Soome 99c65ebfc7SToomas Soome #if defined(_WIN32) 100c65ebfc7SToomas Soome #include <winsock2.h> 101c65ebfc7SToomas Soome typedef SOCKET dnssd_sock_t; 102c65ebfc7SToomas Soome #else 103c65ebfc7SToomas Soome typedef int dnssd_sock_t; 104c65ebfc7SToomas Soome #endif 105c65ebfc7SToomas Soome 106c65ebfc7SToomas Soome /* stdint.h does not exist on FreeBSD 4.x; its types are defined in sys/types.h instead */ 107c65ebfc7SToomas Soome #if defined(__FreeBSD__) && (__FreeBSD__ < 5) 108c65ebfc7SToomas Soome #include <sys/types.h> 109c65ebfc7SToomas Soome 110c65ebfc7SToomas Soome /* Likewise, on Sun, standard integer types are in sys/types.h */ 111c65ebfc7SToomas Soome #elif defined(__sun__) 112c65ebfc7SToomas Soome #include <sys/types.h> 113c65ebfc7SToomas Soome 114c65ebfc7SToomas Soome /* EFI does not have stdint.h, or anything else equivalent */ 115c65ebfc7SToomas Soome #elif defined(EFI32) || defined(EFI64) || defined(EFIX64) 116c65ebfc7SToomas Soome #include "Tiano.h" 117c65ebfc7SToomas Soome #if !defined(_STDINT_H_) 118c65ebfc7SToomas Soome typedef UINT8 uint8_t; 119c65ebfc7SToomas Soome typedef INT8 int8_t; 120c65ebfc7SToomas Soome typedef UINT16 uint16_t; 121c65ebfc7SToomas Soome typedef INT16 int16_t; 122c65ebfc7SToomas Soome typedef UINT32 uint32_t; 123c65ebfc7SToomas Soome typedef INT32 int32_t; 124c65ebfc7SToomas Soome #endif 125c65ebfc7SToomas Soome /* Windows has its own differences */ 126c65ebfc7SToomas Soome #elif defined(_WIN32) 127c65ebfc7SToomas Soome #include <windows.h> 128c65ebfc7SToomas Soome #define _UNUSED 129c65ebfc7SToomas Soome #ifndef _MSL_STDINT_H 130c65ebfc7SToomas Soome typedef UINT8 uint8_t; 131c65ebfc7SToomas Soome typedef INT8 int8_t; 132c65ebfc7SToomas Soome typedef UINT16 uint16_t; 133c65ebfc7SToomas Soome typedef INT16 int16_t; 134c65ebfc7SToomas Soome typedef UINT32 uint32_t; 135c65ebfc7SToomas Soome typedef INT32 int32_t; 136c65ebfc7SToomas Soome #endif 137c65ebfc7SToomas Soome 138c65ebfc7SToomas Soome /* All other Posix platforms use stdint.h */ 139c65ebfc7SToomas Soome #else 140c65ebfc7SToomas Soome #include <stdint.h> 141c65ebfc7SToomas Soome #endif 142c65ebfc7SToomas Soome 143c65ebfc7SToomas Soome #if _DNS_SD_LIBDISPATCH 144c65ebfc7SToomas Soome #include <dispatch/dispatch.h> 145c65ebfc7SToomas Soome #endif 146c65ebfc7SToomas Soome 147c65ebfc7SToomas Soome /* DNSServiceRef, DNSRecordRef 148c65ebfc7SToomas Soome * 149c65ebfc7SToomas Soome * Opaque internal data types. 150c65ebfc7SToomas Soome * Note: client is responsible for serializing access to these structures if 151c65ebfc7SToomas Soome * they are shared between concurrent threads. 152c65ebfc7SToomas Soome */ 153c65ebfc7SToomas Soome 154c65ebfc7SToomas Soome typedef struct _DNSServiceRef_t *DNSServiceRef; 155c65ebfc7SToomas Soome typedef struct _DNSRecordRef_t *DNSRecordRef; 156c65ebfc7SToomas Soome 157c65ebfc7SToomas Soome struct sockaddr; 158c65ebfc7SToomas Soome 159c65ebfc7SToomas Soome /*! @enum General flags 160c65ebfc7SToomas Soome * Most DNS-SD API functions and callbacks include a DNSServiceFlags parameter. 161c65ebfc7SToomas Soome * As a general rule, any given bit in the 32-bit flags field has a specific fixed meaning, 162c65ebfc7SToomas Soome * regardless of the function or callback being used. For any given function or callback, 163c65ebfc7SToomas Soome * typically only a subset of the possible flags are meaningful, and all others should be zero. 164c65ebfc7SToomas Soome * The discussion section for each API call describes which flags are valid for that call 165c65ebfc7SToomas Soome * and callback. In some cases, for a particular call, it may be that no flags are currently 166c65ebfc7SToomas Soome * defined, in which case the DNSServiceFlags parameter exists purely to allow future expansion. 167c65ebfc7SToomas Soome * In all cases, developers should expect that in future releases, it is possible that new flag 168c65ebfc7SToomas Soome * values will be defined, and write code with this in mind. For example, code that tests 169c65ebfc7SToomas Soome * if (flags == kDNSServiceFlagsAdd) ... 170c65ebfc7SToomas Soome * will fail if, in a future release, another bit in the 32-bit flags field is also set. 171c65ebfc7SToomas Soome * The reliable way to test whether a particular bit is set is not with an equality test, 172c65ebfc7SToomas Soome * but with a bitwise mask: 173c65ebfc7SToomas Soome * if (flags & kDNSServiceFlagsAdd) ... 174c65ebfc7SToomas Soome * With the exception of kDNSServiceFlagsValidate, each flag can be valid(be set) 175c65ebfc7SToomas Soome * EITHER only as an input to one of the DNSService*() APIs OR only as an output 176c65ebfc7SToomas Soome * (provide status) through any of the callbacks used. For example, kDNSServiceFlagsAdd 177c65ebfc7SToomas 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 179c65ebfc7SToomas Soome * defined in enum below. 180c65ebfc7SToomas Soome */ 181c65ebfc7SToomas Soome enum 182c65ebfc7SToomas Soome { 183c65ebfc7SToomas Soome kDNSServiceFlagsMoreComing = 0x1, 184c65ebfc7SToomas Soome /* MoreComing indicates to a callback that at least one more result is 185c65ebfc7SToomas Soome * queued and will be delivered following immediately after this one. 186c65ebfc7SToomas Soome * When the MoreComing flag is set, applications should not immediately 187c65ebfc7SToomas Soome * update their UI, because this can result in a great deal of ugly flickering 188c65ebfc7SToomas Soome * on the screen, and can waste a great deal of CPU time repeatedly updating 189c65ebfc7SToomas Soome * the screen with content that is then immediately erased, over and over. 190c65ebfc7SToomas Soome * Applications should wait until MoreComing is not set, and then 191c65ebfc7SToomas Soome * update their UI when no more changes are imminent. 192c65ebfc7SToomas Soome * When MoreComing is not set, that doesn't mean there will be no more 193c65ebfc7SToomas Soome * answers EVER, just that there are no more answers immediately 194c65ebfc7SToomas Soome * available right now at this instant. If more answers become available 195c65ebfc7SToomas Soome * in the future they will be delivered as usual. 196c65ebfc7SToomas Soome */ 197c65ebfc7SToomas Soome 198c65ebfc7SToomas Soome kDNSServiceFlagsAutoTrigger = 0x1, 199c65ebfc7SToomas Soome /* Valid for browses using kDNSServiceInterfaceIndexAny. 200*472cd20dSToomas Soome * Will auto trigger the browse over AWDL as well once the service is discovered 201c65ebfc7SToomas Soome * over BLE. 202c65ebfc7SToomas Soome * This flag is an input value to DNSServiceBrowse(), which is why we can 203c65ebfc7SToomas Soome * use the same value as kDNSServiceFlagsMoreComing, which is an output flag 204c65ebfc7SToomas Soome * for various client callbacks. 205c65ebfc7SToomas Soome */ 206c65ebfc7SToomas Soome 207c65ebfc7SToomas Soome kDNSServiceFlagsAdd = 0x2, 208c65ebfc7SToomas Soome kDNSServiceFlagsDefault = 0x4, 209c65ebfc7SToomas Soome /* Flags for domain enumeration and browse/query reply callbacks. 210c65ebfc7SToomas Soome * "Default" applies only to enumeration and is only valid in 211c65ebfc7SToomas Soome * conjunction with "Add". An enumeration callback with the "Add" 212c65ebfc7SToomas Soome * flag NOT set indicates a "Remove", i.e. the domain is no longer 213c65ebfc7SToomas Soome * valid. 214c65ebfc7SToomas Soome */ 215c65ebfc7SToomas Soome 216c65ebfc7SToomas Soome kDNSServiceFlagsNoAutoRename = 0x8, 217c65ebfc7SToomas Soome /* Flag for specifying renaming behavior on name conflict when registering 218c65ebfc7SToomas Soome * non-shared records. By default, name conflicts are automatically handled 219c65ebfc7SToomas Soome * by renaming the service. NoAutoRename overrides this behavior - with this 220c65ebfc7SToomas Soome * flag set, name conflicts will result in a callback. The NoAutorename flag 221c65ebfc7SToomas Soome * is only valid if a name is explicitly specified when registering a service 222c65ebfc7SToomas Soome * (i.e. the default name is not used.) 223c65ebfc7SToomas Soome */ 224c65ebfc7SToomas Soome 225c65ebfc7SToomas Soome kDNSServiceFlagsShared = 0x10, 226c65ebfc7SToomas Soome kDNSServiceFlagsUnique = 0x20, 227c65ebfc7SToomas Soome /* Flag for registering individual records on a connected 228c65ebfc7SToomas Soome * DNSServiceRef. Shared indicates that there may be multiple records 229c65ebfc7SToomas Soome * with this name on the network (e.g. PTR records). Unique indicates that the 230c65ebfc7SToomas Soome * record's name is to be unique on the network (e.g. SRV records). 231c65ebfc7SToomas Soome */ 232c65ebfc7SToomas Soome 233c65ebfc7SToomas Soome kDNSServiceFlagsBrowseDomains = 0x40, 234c65ebfc7SToomas Soome kDNSServiceFlagsRegistrationDomains = 0x80, 235c65ebfc7SToomas Soome /* Flags for specifying domain enumeration type in DNSServiceEnumerateDomains. 236c65ebfc7SToomas Soome * BrowseDomains enumerates domains recommended for browsing, RegistrationDomains 237c65ebfc7SToomas Soome * enumerates domains recommended for registration. 238c65ebfc7SToomas Soome */ 239c65ebfc7SToomas Soome 240c65ebfc7SToomas Soome kDNSServiceFlagsLongLivedQuery = 0x100, 241c65ebfc7SToomas Soome /* Flag for creating a long-lived unicast query for the DNSServiceQueryRecord call. */ 242c65ebfc7SToomas Soome 243c65ebfc7SToomas Soome kDNSServiceFlagsAllowRemoteQuery = 0x200, 244c65ebfc7SToomas Soome /* Flag for creating a record for which we will answer remote queries 245c65ebfc7SToomas Soome * (queries from hosts more than one hop away; hosts not directly connected to the local link). 246c65ebfc7SToomas Soome */ 247c65ebfc7SToomas Soome 248c65ebfc7SToomas Soome kDNSServiceFlagsForceMulticast = 0x400, 249c65ebfc7SToomas Soome /* Flag for signifying that a query or registration should be performed exclusively via multicast 250c65ebfc7SToomas Soome * DNS, even for a name in a domain (e.g. foo.apple.com.) that would normally imply unicast DNS. 251c65ebfc7SToomas Soome */ 252c65ebfc7SToomas Soome 253c65ebfc7SToomas Soome kDNSServiceFlagsForce = 0x800, // This flag is deprecated. 254c65ebfc7SToomas Soome 255c65ebfc7SToomas Soome kDNSServiceFlagsKnownUnique = 0x800, 256c65ebfc7SToomas Soome /* 257c65ebfc7SToomas Soome * Client guarantees that record names are unique, so we can skip sending out initial 258c65ebfc7SToomas Soome * probe messages. Standard name conflict resolution is still done if a conflict is discovered. 259c65ebfc7SToomas Soome */ 260c65ebfc7SToomas Soome 261c65ebfc7SToomas Soome kDNSServiceFlagsReturnIntermediates = 0x1000, 262c65ebfc7SToomas Soome /* Flag for returning intermediate results. 263c65ebfc7SToomas Soome * For example, if a query results in an authoritative NXDomain (name does not exist) 264c65ebfc7SToomas Soome * then that result is returned to the client. However the query is not implicitly 265c65ebfc7SToomas Soome * cancelled -- it remains active and if the answer subsequently changes 266c65ebfc7SToomas Soome * (e.g. because a VPN tunnel is subsequently established) then that positive 267c65ebfc7SToomas Soome * result will still be returned to the client. 268c65ebfc7SToomas Soome * Similarly, if a query results in a CNAME record, then in addition to following 269c65ebfc7SToomas Soome * the CNAME referral, the intermediate CNAME result is also returned to the client. 270c65ebfc7SToomas Soome * When this flag is not set, NXDomain errors are not returned, and CNAME records 271c65ebfc7SToomas Soome * are followed silently without informing the client of the intermediate steps. 272c65ebfc7SToomas Soome * (In earlier builds this flag was briefly calledkDNSServiceFlagsReturnCNAME) 273c65ebfc7SToomas Soome */ 274c65ebfc7SToomas Soome 275c65ebfc7SToomas Soome kDNSServiceFlagsShareConnection = 0x4000, 276c65ebfc7SToomas Soome /* For efficiency, clients that perform many concurrent operations may want to use a 277c65ebfc7SToomas Soome * single Unix Domain Socket connection with the background daemon, instead of having a 278c65ebfc7SToomas Soome * separate connection for each independent operation. To use this mode, clients first 279*472cd20dSToomas Soome * call DNSServiceCreateConnection(&SharedRef) to initialize the main DNSServiceRef. 280c65ebfc7SToomas Soome * For each subsequent operation that is to share that same connection, the client copies 281*472cd20dSToomas Soome * the SharedRef, and then passes the address of that copy, setting the ShareConnection flag 282c65ebfc7SToomas Soome * to tell the library that this DNSServiceRef is not a typical uninitialized DNSServiceRef; 283c65ebfc7SToomas Soome * it's a copy of an existing DNSServiceRef whose connection information should be reused. 284c65ebfc7SToomas Soome * 285c65ebfc7SToomas Soome * For example: 286c65ebfc7SToomas Soome * 287c65ebfc7SToomas Soome * DNSServiceErrorType error; 288*472cd20dSToomas Soome * DNSServiceRef SharedRef; 289*472cd20dSToomas Soome * error = DNSServiceCreateConnection(&SharedRef); 290c65ebfc7SToomas Soome * if (error) ... 291*472cd20dSToomas Soome * DNSServiceRef BrowseRef = SharedRef; // Important: COPY the primary DNSServiceRef first... 292c65ebfc7SToomas Soome * error = DNSServiceBrowse(&BrowseRef, kDNSServiceFlagsShareConnection, ...); // then use the copy 293c65ebfc7SToomas Soome * if (error) ... 294c65ebfc7SToomas Soome * ... 295c65ebfc7SToomas Soome * DNSServiceRefDeallocate(BrowseRef); // Terminate the browse operation 296*472cd20dSToomas Soome * DNSServiceRefDeallocate(SharedRef); // Terminate the shared connection 297c65ebfc7SToomas Soome * 298c65ebfc7SToomas Soome * Notes: 299c65ebfc7SToomas Soome * 300c65ebfc7SToomas Soome * 1. Collective kDNSServiceFlagsMoreComing flag 301c65ebfc7SToomas Soome * When callbacks are invoked using a shared DNSServiceRef, the 302c65ebfc7SToomas Soome * kDNSServiceFlagsMoreComing flag applies collectively to *all* active 303c65ebfc7SToomas Soome * operations sharing the same parent DNSServiceRef. If the MoreComing flag is 304c65ebfc7SToomas Soome * set it means that there are more results queued on this parent DNSServiceRef, 305c65ebfc7SToomas Soome * but not necessarily more results for this particular callback function. 306c65ebfc7SToomas Soome * The implication of this for client programmers is that when a callback 307c65ebfc7SToomas Soome * is invoked with the MoreComing flag set, the code should update its 308c65ebfc7SToomas Soome * internal data structures with the new result, and set a variable indicating 309c65ebfc7SToomas Soome * that its UI needs to be updated. Then, later when a callback is eventually 310c65ebfc7SToomas Soome * invoked with the MoreComing flag not set, the code should update *all* 311c65ebfc7SToomas Soome * stale UI elements related to that shared parent DNSServiceRef that need 312c65ebfc7SToomas Soome * updating, not just the UI elements related to the particular callback 313c65ebfc7SToomas Soome * that happened to be the last one to be invoked. 314c65ebfc7SToomas Soome * 315c65ebfc7SToomas Soome * 2. Canceling operations and kDNSServiceFlagsMoreComing 316c65ebfc7SToomas Soome * Whenever you cancel any operation for which you had deferred UI updates 317c65ebfc7SToomas Soome * waiting because of a kDNSServiceFlagsMoreComing flag, you should perform 318c65ebfc7SToomas Soome * those deferred UI updates. This is because, after cancelling the operation, 319c65ebfc7SToomas Soome * you can no longer wait for a callback *without* MoreComing set, to tell 320c65ebfc7SToomas Soome * you do perform your deferred UI updates (the operation has been canceled, 321c65ebfc7SToomas Soome * so there will be no more callbacks). An implication of the collective 322c65ebfc7SToomas Soome * kDNSServiceFlagsMoreComing flag for shared connections is that this 323c65ebfc7SToomas Soome * guideline applies more broadly -- any time you cancel an operation on 324c65ebfc7SToomas Soome * a shared connection, you should perform all deferred UI updates for all 325c65ebfc7SToomas Soome * operations sharing that connection. This is because the MoreComing flag 326c65ebfc7SToomas Soome * might have been referring to events coming for the operation you canceled, 327c65ebfc7SToomas Soome * which will now not be coming because the operation has been canceled. 328c65ebfc7SToomas Soome * 329c65ebfc7SToomas Soome * 3. Only share DNSServiceRef's created with DNSServiceCreateConnection 330c65ebfc7SToomas Soome * Calling DNSServiceCreateConnection(&ref) creates a special shareable DNSServiceRef. 331c65ebfc7SToomas Soome * DNSServiceRef's created by other calls like DNSServiceBrowse() or DNSServiceResolve() 332c65ebfc7SToomas Soome * cannot be shared by copying them and using kDNSServiceFlagsShareConnection. 333c65ebfc7SToomas Soome * 334*472cd20dSToomas Soome * 4. Don't Double-Deallocate 335*472cd20dSToomas Soome * Calling DNSServiceRefDeallocate(OpRef) for a particular operation's DNSServiceRef terminates 336*472cd20dSToomas Soome * just that operation. Calling DNSServiceRefDeallocate(SharedRef) for the main shared DNSServiceRef 337*472cd20dSToomas Soome * (the parent DNSServiceRef, originally created by DNSServiceCreateConnection(&SharedRef)) 338*472cd20dSToomas Soome * automatically terminates the shared connection *and* all operations that were still using it. 339c65ebfc7SToomas Soome * After doing this, DO NOT then attempt to deallocate any remaining subordinate DNSServiceRef's. 340c65ebfc7SToomas Soome * The memory used by those subordinate DNSServiceRef's has already been freed, so any attempt 341c65ebfc7SToomas Soome * to do a DNSServiceRefDeallocate (or any other operation) on them will result in accesses 342c65ebfc7SToomas Soome * to freed memory, leading to crashes or other equally undesirable results. 343*472cd20dSToomas Soome * You can deallocate individual operations first and then deallocate the parent DNSServiceRef last, 344*472cd20dSToomas Soome * but if you deallocate the parent DNSServiceRef first, then all of the subordinate DNSServiceRef's 345*472cd20dSToomas Soome * are implicitly deallocated, and explicitly deallocating them a second time will lead to crashes. 346c65ebfc7SToomas Soome * 347c65ebfc7SToomas Soome * 5. Thread Safety 348c65ebfc7SToomas Soome * The dns_sd.h API does not presuppose any particular threading model, and consequently 349c65ebfc7SToomas Soome * does no locking internally (which would require linking with a specific threading library). 350c65ebfc7SToomas Soome * If the client concurrently, from multiple threads (or contexts), calls API routines using 351c65ebfc7SToomas Soome * the same DNSServiceRef, it is the client's responsibility to provide mutual exclusion for 352c65ebfc7SToomas Soome * that DNSServiceRef. 353*472cd20dSToomas Soome * 354c65ebfc7SToomas Soome * For example, use of DNSServiceRefDeallocate requires caution. A common mistake is as follows: 355c65ebfc7SToomas Soome * Thread B calls DNSServiceRefDeallocate to deallocate sdRef while Thread A is processing events 356c65ebfc7SToomas Soome * using sdRef. Doing this will lead to intermittent crashes on thread A if the sdRef is used after 357c65ebfc7SToomas Soome * it was deallocated. 358*472cd20dSToomas Soome * 359c65ebfc7SToomas Soome * A telltale sign of this crash type is to see DNSServiceProcessResult on the stack preceding the 360c65ebfc7SToomas Soome * actual crash location. 361*472cd20dSToomas Soome * 362c65ebfc7SToomas Soome * To state this more explicitly, mDNSResponder does not queue DNSServiceRefDeallocate so 363c65ebfc7SToomas Soome * that it occurs discretely before or after an event is handled. 364c65ebfc7SToomas Soome */ 365c65ebfc7SToomas Soome 366c65ebfc7SToomas Soome kDNSServiceFlagsSuppressUnusable = 0x8000, 367c65ebfc7SToomas Soome /* 368c65ebfc7SToomas Soome * This flag is meaningful only in DNSServiceQueryRecord which suppresses unusable queries on the 369c65ebfc7SToomas Soome * wire. If "hostname" is a wide-area unicast DNS hostname (i.e. not a ".local." name) 370c65ebfc7SToomas Soome * but this host has no routable IPv6 address, then the call will not try to look up IPv6 addresses 371c65ebfc7SToomas Soome * for "hostname", since any addresses it found would be unlikely to be of any use anyway. Similarly, 372c65ebfc7SToomas Soome * if this host has no routable IPv4 address, the call will not try to look up IPv4 addresses for 373c65ebfc7SToomas Soome * "hostname". 374c65ebfc7SToomas Soome */ 375c65ebfc7SToomas Soome 376c65ebfc7SToomas Soome kDNSServiceFlagsTimeout = 0x10000, 377c65ebfc7SToomas Soome /* 378c65ebfc7SToomas Soome * When kDNServiceFlagsTimeout is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo, the query is 379c65ebfc7SToomas Soome * stopped after a certain number of seconds have elapsed. The time at which the query will be stopped 380c65ebfc7SToomas Soome * is determined by the system and cannot be configured by the user. The query will be stopped irrespective 381c65ebfc7SToomas Soome * of whether a response was given earlier or not. When the query is stopped, the callback will be called 382c65ebfc7SToomas Soome * with an error code of kDNSServiceErr_Timeout and a NULL sockaddr will be returned for DNSServiceGetAddrInfo 383c65ebfc7SToomas Soome * and zero length rdata will be returned for DNSServiceQueryRecord. 384c65ebfc7SToomas Soome */ 385c65ebfc7SToomas Soome 386c65ebfc7SToomas Soome kDNSServiceFlagsIncludeP2P = 0x20000, 387c65ebfc7SToomas Soome /* 388c65ebfc7SToomas Soome * Include P2P interfaces when kDNSServiceInterfaceIndexAny is specified. 389c65ebfc7SToomas Soome * By default, specifying kDNSServiceInterfaceIndexAny does not include P2P interfaces. 390c65ebfc7SToomas Soome */ 391c65ebfc7SToomas Soome 392c65ebfc7SToomas Soome kDNSServiceFlagsWakeOnResolve = 0x40000, 393c65ebfc7SToomas Soome /* 394c65ebfc7SToomas Soome * This flag is meaningful only in DNSServiceResolve. When set, it tries to send a magic packet 395c65ebfc7SToomas Soome * to wake up the client. 396c65ebfc7SToomas Soome */ 397c65ebfc7SToomas Soome 398c65ebfc7SToomas Soome kDNSServiceFlagsBackgroundTrafficClass = 0x80000, 399c65ebfc7SToomas Soome /* 400c65ebfc7SToomas Soome * This flag is meaningful for Unicast DNS queries. When set, it uses the background traffic 401c65ebfc7SToomas Soome * class for packets that service the request. 402c65ebfc7SToomas Soome */ 403c65ebfc7SToomas Soome 404c65ebfc7SToomas Soome kDNSServiceFlagsIncludeAWDL = 0x100000, 405c65ebfc7SToomas Soome /* 406c65ebfc7SToomas Soome * Include AWDL interface when kDNSServiceInterfaceIndexAny is specified. 407c65ebfc7SToomas Soome */ 408c65ebfc7SToomas Soome 409*472cd20dSToomas Soome kDNSServiceFlagsEnableDNSSEC = 0x200000, 410*472cd20dSToomas Soome /* 411*472cd20dSToomas Soome * Perform DNSSEC validation on the client request when kDNSServiceFlagsEnableDNSSEC is specified 412*472cd20dSToomas Soome * Since the client API has not been finalized, we will use it as a temporary flag to turn on the DNSSEC validation. 413*472cd20dSToomas Soome */ 414*472cd20dSToomas Soome 415c65ebfc7SToomas Soome kDNSServiceFlagsValidate = 0x200000, 416c65ebfc7SToomas Soome /* 417c65ebfc7SToomas Soome * This flag is meaningful in DNSServiceGetAddrInfo and DNSServiceQueryRecord. This is the ONLY flag to be valid 418c65ebfc7SToomas Soome * as an input to the APIs and also an output through the callbacks in the APIs. 419c65ebfc7SToomas Soome * 420c65ebfc7SToomas Soome * When this flag is passed to DNSServiceQueryRecord and DNSServiceGetAddrInfo to resolve unicast names, 421c65ebfc7SToomas Soome * the response will be validated using DNSSEC. The validation results are delivered using the flags field in 422c65ebfc7SToomas Soome * the callback and kDNSServiceFlagsValidate is marked in the flags to indicate that DNSSEC status is also available. 423c65ebfc7SToomas Soome * When the callback is called to deliver the query results, the validation results may or may not be available. 424c65ebfc7SToomas Soome * If it is not delivered along with the results, the validation status is delivered when the validation completes. 425c65ebfc7SToomas Soome * 426c65ebfc7SToomas Soome * When the validation results are delivered in the callback, it is indicated by marking the flags with 427c65ebfc7SToomas Soome * kDNSServiceFlagsValidate and kDNSServiceFlagsAdd along with the DNSSEC status flags (described below) and a NULL 428c65ebfc7SToomas Soome * sockaddr will be returned for DNSServiceGetAddrInfo and zero length rdata will be returned for DNSServiceQueryRecord. 429c65ebfc7SToomas Soome * DNSSEC validation results are for the whole RRSet and not just individual records delivered in the callback. When 430c65ebfc7SToomas Soome * kDNSServiceFlagsAdd is not set in the flags, applications should implicitly assume that the DNSSEC status of the 431c65ebfc7SToomas Soome * RRSet that has been delivered up until that point is not valid anymore, till another callback is called with 432c65ebfc7SToomas Soome * kDNSServiceFlagsAdd and kDNSServiceFlagsValidate. 433c65ebfc7SToomas Soome * 434c65ebfc7SToomas Soome * The following four flags indicate the status of the DNSSEC validation and marked in the flags field of the callback. 435c65ebfc7SToomas Soome * When any of the four flags is set, kDNSServiceFlagsValidate will also be set. To check the validation status, the 436*472cd20dSToomas Soome * other applicable output flags should be masked. 437c65ebfc7SToomas Soome */ 438c65ebfc7SToomas Soome 439c65ebfc7SToomas Soome kDNSServiceFlagsSecure = 0x200010, 440c65ebfc7SToomas Soome /* 441c65ebfc7SToomas Soome * The response has been validated by verifying all the signatures in the response and was able to 442c65ebfc7SToomas Soome * build a successful authentication chain starting from a known trust anchor. 443c65ebfc7SToomas Soome */ 444c65ebfc7SToomas Soome 445c65ebfc7SToomas Soome kDNSServiceFlagsInsecure = 0x200020, 446c65ebfc7SToomas Soome /* 447c65ebfc7SToomas Soome * A chain of trust cannot be built starting from a known trust anchor to the response. 448c65ebfc7SToomas Soome */ 449c65ebfc7SToomas Soome 450c65ebfc7SToomas Soome kDNSServiceFlagsBogus = 0x200040, 451c65ebfc7SToomas Soome /* 452c65ebfc7SToomas Soome * If the response cannot be verified to be secure due to expired signatures, missing signatures etc., 453c65ebfc7SToomas Soome * then the results are considered to be bogus. 454c65ebfc7SToomas Soome */ 455c65ebfc7SToomas Soome 456c65ebfc7SToomas Soome kDNSServiceFlagsIndeterminate = 0x200080, 457c65ebfc7SToomas Soome /* 458c65ebfc7SToomas Soome * There is no valid trust anchor that can be used to determine whether a response is secure or not. 459c65ebfc7SToomas Soome */ 460c65ebfc7SToomas Soome 461c65ebfc7SToomas Soome kDNSServiceFlagsUnicastResponse = 0x400000, 462c65ebfc7SToomas Soome /* 463c65ebfc7SToomas Soome * Request unicast response to query. 464c65ebfc7SToomas Soome */ 465c65ebfc7SToomas Soome kDNSServiceFlagsValidateOptional = 0x800000, 466c65ebfc7SToomas Soome 467c65ebfc7SToomas Soome /* 468c65ebfc7SToomas Soome * This flag is identical to kDNSServiceFlagsValidate except for the case where the response 469c65ebfc7SToomas Soome * cannot be validated. If this flag is set in DNSServiceQueryRecord or DNSServiceGetAddrInfo, 470c65ebfc7SToomas Soome * the DNSSEC records will be requested for validation. If they cannot be received for some reason 471c65ebfc7SToomas Soome * during the validation (e.g., zone is not signed, zone is signed but cannot be traced back to 472c65ebfc7SToomas Soome * root, recursive server does not understand DNSSEC etc.), then this will fallback to the default 473c65ebfc7SToomas Soome * behavior where the validation will not be performed and no DNSSEC results will be provided. 474c65ebfc7SToomas Soome * 475c65ebfc7SToomas Soome * If the zone is signed and there is a valid path to a known trust anchor configured in the system 476c65ebfc7SToomas Soome * and the application requires DNSSEC validation irrespective of the DNSSEC awareness in the current 477c65ebfc7SToomas Soome * network, then this option MUST not be used. This is only intended to be used during the transition 478c65ebfc7SToomas Soome * period where the different nodes participating in the DNS resolution may not understand DNSSEC or 479c65ebfc7SToomas Soome * managed properly (e.g. missing DS record) but still want to be able to resolve DNS successfully. 480c65ebfc7SToomas Soome */ 481c65ebfc7SToomas Soome 482c65ebfc7SToomas Soome kDNSServiceFlagsWakeOnlyService = 0x1000000, 483c65ebfc7SToomas Soome /* 484c65ebfc7SToomas Soome * This flag is meaningful only in DNSServiceRegister. When set, the service will not be registered 485c65ebfc7SToomas Soome * with sleep proxy server during sleep. 486c65ebfc7SToomas Soome */ 487c65ebfc7SToomas Soome 488c65ebfc7SToomas Soome kDNSServiceFlagsThresholdOne = 0x2000000, 489c65ebfc7SToomas Soome kDNSServiceFlagsThresholdFinder = 0x4000000, 490c65ebfc7SToomas Soome kDNSServiceFlagsThresholdReached = kDNSServiceFlagsThresholdOne, 491c65ebfc7SToomas Soome /* 492c65ebfc7SToomas Soome * kDNSServiceFlagsThresholdOne is meaningful only in DNSServiceBrowse. When set, 493c65ebfc7SToomas Soome * the system will stop issuing browse queries on the network once the number 494c65ebfc7SToomas Soome * of answers returned is one or more. It will issue queries on the network 495c65ebfc7SToomas Soome * again if the number of answers drops to zero. 496c65ebfc7SToomas Soome * This flag is for Apple internal use only. Third party developers 497c65ebfc7SToomas Soome * should not rely on this behavior being supported in any given software release. 498c65ebfc7SToomas Soome * 499c65ebfc7SToomas Soome * kDNSServiceFlagsThresholdFinder is meaningful only in DNSServiceBrowse. When set, 500c65ebfc7SToomas Soome * the system will stop issuing browse queries on the network once the number 501c65ebfc7SToomas Soome * of answers has reached the threshold set for Finder. 502c65ebfc7SToomas Soome * It will issue queries on the network again if the number of answers drops below 503c65ebfc7SToomas Soome * this threshold. 504c65ebfc7SToomas Soome * This flag is for Apple internal use only. Third party developers 505c65ebfc7SToomas Soome * should not rely on this behavior being supported in any given software release. 506c65ebfc7SToomas Soome * 507c65ebfc7SToomas Soome * When kDNSServiceFlagsThresholdReached is set in the client callback add or remove event, 508c65ebfc7SToomas Soome * it indicates that the browse answer threshold has been reached and no 509c65ebfc7SToomas Soome * browse requests will be generated on the network until the number of answers falls 510c65ebfc7SToomas Soome * below the threshold value. Add and remove events can still occur based 511c65ebfc7SToomas Soome * on incoming Bonjour traffic observed by the system. 512c65ebfc7SToomas Soome * The set of services return to the client is not guaranteed to represent the 513c65ebfc7SToomas Soome * entire set of services present on the network once the threshold has been reached. 514c65ebfc7SToomas Soome * 515c65ebfc7SToomas Soome * Note, while kDNSServiceFlagsThresholdReached and kDNSServiceFlagsThresholdOne 516c65ebfc7SToomas Soome * have the same value, there isn't a conflict because kDNSServiceFlagsThresholdReached 517c65ebfc7SToomas Soome * is only set in the callbacks and kDNSServiceFlagsThresholdOne is only set on 518c65ebfc7SToomas Soome * input to a DNSServiceBrowse call. 519c65ebfc7SToomas Soome */ 520*472cd20dSToomas Soome kDNSServiceFlagsPrivateOne = 0x2000, 521c65ebfc7SToomas Soome /* 522c65ebfc7SToomas Soome * This flag is private and should not be used. 523c65ebfc7SToomas Soome */ 524c65ebfc7SToomas Soome 525*472cd20dSToomas Soome kDNSServiceFlagsPrivateTwo = 0x8000000, 526c65ebfc7SToomas Soome /* 527c65ebfc7SToomas Soome * This flag is private and should not be used. 528c65ebfc7SToomas Soome */ 529c65ebfc7SToomas Soome 530*472cd20dSToomas Soome kDNSServiceFlagsPrivateThree = 0x10000000, 531c65ebfc7SToomas Soome /* 532c65ebfc7SToomas Soome * This flag is private and should not be used. 533c65ebfc7SToomas Soome */ 534c65ebfc7SToomas Soome 535*472cd20dSToomas Soome kDNSServiceFlagsPrivateFour = 0x20000000, 536c65ebfc7SToomas Soome /* 537c65ebfc7SToomas Soome * This flag is private and should not be used. 538c65ebfc7SToomas Soome */ 539c65ebfc7SToomas Soome 540*472cd20dSToomas Soome kDNSServiceFlagsPrivateFive = 0x40000000, 541*472cd20dSToomas Soome /* 542*472cd20dSToomas Soome * This flag is private and should not be used. 543*472cd20dSToomas Soome */ 544*472cd20dSToomas Soome 545*472cd20dSToomas Soome 546*472cd20dSToomas Soome kDNSServiceFlagAnsweredFromCache = 0x40000000, 547*472cd20dSToomas Soome /* 548*472cd20dSToomas Soome * When kDNSServiceFlagAnsweredFromCache is passed back in the flags parameter of DNSServiceQueryRecordReply or DNSServiceGetAddrInfoReply, 549*472cd20dSToomas Soome * an answer will have this flag set if it was answered from the cache. 550*472cd20dSToomas Soome */ 551*472cd20dSToomas Soome 5523b436d06SToomas Soome kDNSServiceFlagsAllowExpiredAnswers = 0x80000000, 5533b436d06SToomas Soome /* 5543b436d06SToomas Soome * When kDNSServiceFlagsAllowExpiredAnswers is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo, 5553b436d06SToomas Soome * if there are matching expired records still in the cache, then they are immediately returned to the 5563b436d06SToomas Soome * client, and in parallel a network query for that name is issued. All returned records from the query will 5573b436d06SToomas Soome * remain in the cache after expiration. 5583b436d06SToomas Soome */ 5593b436d06SToomas Soome 5603b436d06SToomas Soome kDNSServiceFlagsExpiredAnswer = 0x80000000 5613b436d06SToomas Soome /* 5623b436d06SToomas Soome * When kDNSServiceFlagsAllowExpiredAnswers is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo, 5633b436d06SToomas Soome * an expired answer will have this flag set. 5643b436d06SToomas Soome */ 5653b436d06SToomas Soome 566c65ebfc7SToomas Soome }; 567c65ebfc7SToomas Soome 568c65ebfc7SToomas Soome /* Possible protocol values */ 569c65ebfc7SToomas Soome enum 570c65ebfc7SToomas Soome { 571c65ebfc7SToomas Soome /* for DNSServiceGetAddrInfo() */ 572c65ebfc7SToomas Soome kDNSServiceProtocol_IPv4 = 0x01, 573c65ebfc7SToomas Soome kDNSServiceProtocol_IPv6 = 0x02, 574c65ebfc7SToomas Soome /* 0x04 and 0x08 reserved for future internetwork protocols */ 575c65ebfc7SToomas Soome 576c65ebfc7SToomas Soome /* for DNSServiceNATPortMappingCreate() */ 577c65ebfc7SToomas Soome kDNSServiceProtocol_UDP = 0x10, 578c65ebfc7SToomas Soome kDNSServiceProtocol_TCP = 0x20 579c65ebfc7SToomas Soome /* 0x40 and 0x80 reserved for future transport protocols, e.g. SCTP [RFC 2960] 580c65ebfc7SToomas Soome * or DCCP [RFC 4340]. If future NAT gateways are created that support port 581c65ebfc7SToomas Soome * mappings for these protocols, new constants will be defined here. 582c65ebfc7SToomas Soome */ 583c65ebfc7SToomas Soome }; 584c65ebfc7SToomas Soome 585c65ebfc7SToomas Soome /* 586c65ebfc7SToomas Soome * The values for DNS Classes and Types are listed in RFC 1035, and are available 587c65ebfc7SToomas Soome * on every OS in its DNS header file. Unfortunately every OS does not have the 588c65ebfc7SToomas Soome * same header file containing DNS Class and Type constants, and the names of 589c65ebfc7SToomas Soome * the constants are not consistent. For example, BIND 8 uses "T_A", 590c65ebfc7SToomas Soome * BIND 9 uses "ns_t_a", Windows uses "DNS_TYPE_A", etc. 591c65ebfc7SToomas Soome * For this reason, these constants are also listed here, so that code using 592c65ebfc7SToomas Soome * the DNS-SD programming APIs can use these constants, so that the same code 593c65ebfc7SToomas Soome * can compile on all our supported platforms. 594c65ebfc7SToomas Soome */ 595c65ebfc7SToomas Soome 596c65ebfc7SToomas Soome enum 597c65ebfc7SToomas Soome { 598c65ebfc7SToomas Soome kDNSServiceClass_IN = 1 /* Internet */ 599c65ebfc7SToomas Soome }; 600c65ebfc7SToomas Soome 601c65ebfc7SToomas Soome enum 602c65ebfc7SToomas Soome { 603c65ebfc7SToomas Soome kDNSServiceType_A = 1, /* Host address. */ 604c65ebfc7SToomas Soome kDNSServiceType_NS = 2, /* Authoritative server. */ 605c65ebfc7SToomas Soome kDNSServiceType_MD = 3, /* Mail destination. */ 606c65ebfc7SToomas Soome kDNSServiceType_MF = 4, /* Mail forwarder. */ 607c65ebfc7SToomas Soome kDNSServiceType_CNAME = 5, /* Canonical name. */ 608c65ebfc7SToomas Soome kDNSServiceType_SOA = 6, /* Start of authority zone. */ 609c65ebfc7SToomas Soome kDNSServiceType_MB = 7, /* Mailbox domain name. */ 610c65ebfc7SToomas Soome kDNSServiceType_MG = 8, /* Mail group member. */ 611c65ebfc7SToomas Soome kDNSServiceType_MR = 9, /* Mail rename name. */ 612c65ebfc7SToomas Soome kDNSServiceType_NULL = 10, /* Null resource record. */ 613c65ebfc7SToomas Soome kDNSServiceType_WKS = 11, /* Well known service. */ 614c65ebfc7SToomas Soome kDNSServiceType_PTR = 12, /* Domain name pointer. */ 615c65ebfc7SToomas Soome kDNSServiceType_HINFO = 13, /* Host information. */ 616c65ebfc7SToomas Soome kDNSServiceType_MINFO = 14, /* Mailbox information. */ 617c65ebfc7SToomas Soome kDNSServiceType_MX = 15, /* Mail routing information. */ 618c65ebfc7SToomas Soome kDNSServiceType_TXT = 16, /* One or more text strings (NOT "zero or more..."). */ 619c65ebfc7SToomas Soome kDNSServiceType_RP = 17, /* Responsible person. */ 620c65ebfc7SToomas Soome kDNSServiceType_AFSDB = 18, /* AFS cell database. */ 621c65ebfc7SToomas Soome kDNSServiceType_X25 = 19, /* X_25 calling address. */ 622c65ebfc7SToomas Soome kDNSServiceType_ISDN = 20, /* ISDN calling address. */ 623c65ebfc7SToomas Soome kDNSServiceType_RT = 21, /* Router. */ 624c65ebfc7SToomas Soome kDNSServiceType_NSAP = 22, /* NSAP address. */ 625c65ebfc7SToomas Soome kDNSServiceType_NSAP_PTR = 23, /* Reverse NSAP lookup (deprecated). */ 626c65ebfc7SToomas Soome kDNSServiceType_SIG = 24, /* Security signature. */ 627c65ebfc7SToomas Soome kDNSServiceType_KEY = 25, /* Security key. */ 628c65ebfc7SToomas Soome kDNSServiceType_PX = 26, /* X.400 mail mapping. */ 629c65ebfc7SToomas Soome kDNSServiceType_GPOS = 27, /* Geographical position (withdrawn). */ 630c65ebfc7SToomas Soome kDNSServiceType_AAAA = 28, /* IPv6 Address. */ 631c65ebfc7SToomas Soome kDNSServiceType_LOC = 29, /* Location Information. */ 632c65ebfc7SToomas Soome kDNSServiceType_NXT = 30, /* Next domain (security). */ 633c65ebfc7SToomas Soome kDNSServiceType_EID = 31, /* Endpoint identifier. */ 634c65ebfc7SToomas Soome kDNSServiceType_NIMLOC = 32, /* Nimrod Locator. */ 635c65ebfc7SToomas Soome kDNSServiceType_SRV = 33, /* Server Selection. */ 636c65ebfc7SToomas Soome kDNSServiceType_ATMA = 34, /* ATM Address */ 637c65ebfc7SToomas Soome kDNSServiceType_NAPTR = 35, /* Naming Authority PoinTeR */ 638c65ebfc7SToomas Soome kDNSServiceType_KX = 36, /* Key Exchange */ 639c65ebfc7SToomas Soome kDNSServiceType_CERT = 37, /* Certification record */ 640c65ebfc7SToomas Soome kDNSServiceType_A6 = 38, /* IPv6 Address (deprecated) */ 641c65ebfc7SToomas Soome kDNSServiceType_DNAME = 39, /* Non-terminal DNAME (for IPv6) */ 642c65ebfc7SToomas Soome kDNSServiceType_SINK = 40, /* Kitchen sink (experimental) */ 643c65ebfc7SToomas Soome kDNSServiceType_OPT = 41, /* EDNS0 option (meta-RR) */ 644c65ebfc7SToomas Soome kDNSServiceType_APL = 42, /* Address Prefix List */ 645c65ebfc7SToomas Soome kDNSServiceType_DS = 43, /* Delegation Signer */ 646c65ebfc7SToomas Soome kDNSServiceType_SSHFP = 44, /* SSH Key Fingerprint */ 647c65ebfc7SToomas Soome kDNSServiceType_IPSECKEY = 45, /* IPSECKEY */ 648c65ebfc7SToomas Soome kDNSServiceType_RRSIG = 46, /* RRSIG */ 649c65ebfc7SToomas Soome kDNSServiceType_NSEC = 47, /* Denial of Existence */ 650c65ebfc7SToomas Soome kDNSServiceType_DNSKEY = 48, /* DNSKEY */ 651c65ebfc7SToomas Soome kDNSServiceType_DHCID = 49, /* DHCP Client Identifier */ 652c65ebfc7SToomas Soome kDNSServiceType_NSEC3 = 50, /* Hashed Authenticated Denial of Existence */ 653c65ebfc7SToomas Soome kDNSServiceType_NSEC3PARAM = 51, /* Hashed Authenticated Denial of Existence */ 654c65ebfc7SToomas Soome 655c65ebfc7SToomas Soome kDNSServiceType_HIP = 55, /* Host Identity Protocol */ 656c65ebfc7SToomas Soome 657*472cd20dSToomas Soome kDNSServiceType_SVCB = 64, /* Service Binding. */ 658*472cd20dSToomas Soome kDNSServiceType_HTTPS = 65, /* HTTPS Service Binding. */ 659*472cd20dSToomas Soome 660c65ebfc7SToomas Soome kDNSServiceType_SPF = 99, /* Sender Policy Framework for E-Mail */ 661c65ebfc7SToomas Soome kDNSServiceType_UINFO = 100, /* IANA-Reserved */ 662c65ebfc7SToomas Soome kDNSServiceType_UID = 101, /* IANA-Reserved */ 663c65ebfc7SToomas Soome kDNSServiceType_GID = 102, /* IANA-Reserved */ 664c65ebfc7SToomas Soome kDNSServiceType_UNSPEC = 103, /* IANA-Reserved */ 665c65ebfc7SToomas Soome 666c65ebfc7SToomas Soome kDNSServiceType_TKEY = 249, /* Transaction key */ 667c65ebfc7SToomas Soome kDNSServiceType_TSIG = 250, /* Transaction signature. */ 668c65ebfc7SToomas Soome kDNSServiceType_IXFR = 251, /* Incremental zone transfer. */ 669c65ebfc7SToomas Soome kDNSServiceType_AXFR = 252, /* Transfer zone of authority. */ 670c65ebfc7SToomas Soome kDNSServiceType_MAILB = 253, /* Transfer mailbox records. */ 671c65ebfc7SToomas Soome kDNSServiceType_MAILA = 254, /* Transfer mail agent records. */ 672c65ebfc7SToomas Soome kDNSServiceType_ANY = 255 /* Wildcard match. */ 673c65ebfc7SToomas Soome }; 674c65ebfc7SToomas Soome 675c65ebfc7SToomas Soome /* possible error code values */ 676c65ebfc7SToomas Soome enum 677c65ebfc7SToomas Soome { 678c65ebfc7SToomas Soome kDNSServiceErr_NoError = 0, 679c65ebfc7SToomas Soome kDNSServiceErr_Unknown = -65537, /* 0xFFFE FFFF */ 680c65ebfc7SToomas Soome kDNSServiceErr_NoSuchName = -65538, 681c65ebfc7SToomas Soome kDNSServiceErr_NoMemory = -65539, 682c65ebfc7SToomas Soome kDNSServiceErr_BadParam = -65540, 683c65ebfc7SToomas Soome kDNSServiceErr_BadReference = -65541, 684c65ebfc7SToomas Soome kDNSServiceErr_BadState = -65542, 685c65ebfc7SToomas Soome kDNSServiceErr_BadFlags = -65543, 686c65ebfc7SToomas Soome kDNSServiceErr_Unsupported = -65544, 687c65ebfc7SToomas Soome kDNSServiceErr_NotInitialized = -65545, 688c65ebfc7SToomas Soome kDNSServiceErr_AlreadyRegistered = -65547, 689c65ebfc7SToomas Soome kDNSServiceErr_NameConflict = -65548, 690c65ebfc7SToomas Soome kDNSServiceErr_Invalid = -65549, 691c65ebfc7SToomas Soome kDNSServiceErr_Firewall = -65550, 692c65ebfc7SToomas Soome kDNSServiceErr_Incompatible = -65551, /* client library incompatible with daemon */ 693c65ebfc7SToomas Soome kDNSServiceErr_BadInterfaceIndex = -65552, 694c65ebfc7SToomas Soome kDNSServiceErr_Refused = -65553, 695c65ebfc7SToomas Soome kDNSServiceErr_NoSuchRecord = -65554, 696c65ebfc7SToomas Soome kDNSServiceErr_NoAuth = -65555, 697c65ebfc7SToomas Soome kDNSServiceErr_NoSuchKey = -65556, 698c65ebfc7SToomas Soome kDNSServiceErr_NATTraversal = -65557, 699c65ebfc7SToomas Soome kDNSServiceErr_DoubleNAT = -65558, 700c65ebfc7SToomas Soome kDNSServiceErr_BadTime = -65559, /* Codes up to here existed in Tiger */ 701c65ebfc7SToomas Soome kDNSServiceErr_BadSig = -65560, 702c65ebfc7SToomas Soome kDNSServiceErr_BadKey = -65561, 703c65ebfc7SToomas Soome kDNSServiceErr_Transient = -65562, 704c65ebfc7SToomas Soome kDNSServiceErr_ServiceNotRunning = -65563, /* Background daemon not running */ 705c65ebfc7SToomas Soome kDNSServiceErr_NATPortMappingUnsupported = -65564, /* NAT doesn't support PCP, NAT-PMP or UPnP */ 706c65ebfc7SToomas Soome kDNSServiceErr_NATPortMappingDisabled = -65565, /* NAT supports PCP, NAT-PMP or UPnP, but it's disabled by the administrator */ 707c65ebfc7SToomas Soome kDNSServiceErr_NoRouter = -65566, /* No router currently configured (probably no network connectivity) */ 708c65ebfc7SToomas Soome kDNSServiceErr_PollingMode = -65567, 709*472cd20dSToomas Soome kDNSServiceErr_Timeout = -65568, 710*472cd20dSToomas Soome kDNSServiceErr_DefunctConnection = -65569, /* Connection to daemon returned a SO_ISDEFUNCT error result */ 711*472cd20dSToomas Soome kDNSServiceErr_PolicyDenied = -65570 712c65ebfc7SToomas Soome 713c65ebfc7SToomas Soome /* mDNS Error codes are in the range 714c65ebfc7SToomas Soome * FFFE FF00 (-65792) to FFFE FFFF (-65537) */ 715c65ebfc7SToomas Soome }; 716c65ebfc7SToomas Soome 717c65ebfc7SToomas Soome /* Maximum length, in bytes, of a service name represented as a */ 718c65ebfc7SToomas Soome /* literal C-String, including the terminating NULL at the end. */ 719c65ebfc7SToomas Soome 720c65ebfc7SToomas Soome #define kDNSServiceMaxServiceName 64 721c65ebfc7SToomas Soome 722c65ebfc7SToomas Soome /* Maximum length, in bytes, of a domain name represented as an *escaped* C-String */ 723c65ebfc7SToomas Soome /* including the final trailing dot, and the C-String terminating NULL at the end. */ 724c65ebfc7SToomas Soome 725c65ebfc7SToomas Soome #define kDNSServiceMaxDomainName 1009 726c65ebfc7SToomas Soome 727c65ebfc7SToomas Soome /* 728c65ebfc7SToomas Soome * Notes on DNS Name Escaping 729c65ebfc7SToomas Soome * -- or -- 730c65ebfc7SToomas Soome * "Why is kDNSServiceMaxDomainName 1009, when the maximum legal domain name is 256 bytes?" 731c65ebfc7SToomas Soome * 732c65ebfc7SToomas Soome * All strings used in the DNS-SD APIs are UTF-8 strings. 733c65ebfc7SToomas Soome * Apart from the exceptions noted below, the APIs expect the strings to be properly escaped, using the 734c65ebfc7SToomas Soome * conventional DNS escaping rules, as used by the traditional DNS res_query() API, as described below: 735c65ebfc7SToomas Soome * 736c65ebfc7SToomas Soome * Generally all UTF-8 characters (which includes all US ASCII characters) represent themselves, 737*472cd20dSToomas Soome * with three exceptions: 738*472cd20dSToomas Soome * the dot ('.') character, which is the DNS label separator, 739*472cd20dSToomas Soome * the backslash ('\') character, which is the DNS escape character, and 740*472cd20dSToomas Soome * the ASCII NUL (0) byte value, which is the C-string terminator character. 741c65ebfc7SToomas Soome * The escape character ('\') is interpreted as described below: 742c65ebfc7SToomas Soome * 743c65ebfc7SToomas Soome * '\ddd', where ddd is a three-digit decimal value from 000 to 255, 744c65ebfc7SToomas Soome * represents a single literal byte with that value. Any byte value may be 745c65ebfc7SToomas Soome * represented in '\ddd' format, even characters that don't strictly need to be escaped. 746c65ebfc7SToomas Soome * For example, the ASCII code for 'w' is 119, and therefore '\119' is equivalent to 'w'. 747c65ebfc7SToomas Soome * Thus the command "ping '\119\119\119.apple.com'" is the equivalent to the command "ping 'www.apple.com'". 748c65ebfc7SToomas Soome * Nonprinting ASCII characters in the range 0-31 are often represented this way. 749*472cd20dSToomas Soome * In particular, the ASCII NUL character (0) cannot appear in a C-string because C uses it as the 750*472cd20dSToomas Soome * string terminator character, so ASCII NUL in a domain name has to be represented in a C-string as '\000'. 751c65ebfc7SToomas Soome * Other characters like space (ASCII code 32) are sometimes represented as '\032' 752*472cd20dSToomas Soome * in contexts where having an actual space character in a C-string would be inconvenient. 753c65ebfc7SToomas Soome * 754c65ebfc7SToomas Soome * Otherwise, for all cases where a '\' is followed by anything other than a three-digit decimal value 755c65ebfc7SToomas Soome * from 000 to 255, the character sequence '\x' represents a single literal occurrence of character 'x'. 756c65ebfc7SToomas Soome * This is legal for any character, so, for example, '\w' is equivalent to 'w'. 757c65ebfc7SToomas Soome * Thus the command "ping '\w\w\w.apple.com'" is the equivalent to the command "ping 'www.apple.com'". 758c65ebfc7SToomas Soome * However, this encoding is most useful when representing the characters '.' and '\', 759c65ebfc7SToomas Soome * which otherwise would have special meaning in DNS name strings. 760c65ebfc7SToomas Soome * This means that the following encodings are particularly common: 761c65ebfc7SToomas Soome * '\\' represents a single literal '\' in the name 762c65ebfc7SToomas Soome * '\.' represents a single literal '.' in the name 763c65ebfc7SToomas Soome * 764c65ebfc7SToomas Soome * A lone escape character ('\') appearing at the end of a string is not allowed, since it is 765c65ebfc7SToomas Soome * followed by neither a three-digit decimal value from 000 to 255 nor a single character. 766c65ebfc7SToomas Soome * If a lone escape character ('\') does appear as the last character of a string, it is silently ignored. 767c65ebfc7SToomas Soome * 768*472cd20dSToomas Soome * The worse-case length for an escaped domain name is calculated as follows: 769*472cd20dSToomas Soome * The longest legal domain name is 256 bytes in wire format (see RFC 6762, Appendix C, DNS Name Length). 770*472cd20dSToomas Soome * For our calculation of the longest *escaped* domain name, we use 771*472cd20dSToomas Soome * the longest legal domain name, with the most characters escaped. 772*472cd20dSToomas Soome * 773*472cd20dSToomas Soome * We consider a domain name of the form: "label63.label63.label63.label62." 774*472cd20dSToomas Soome * where "label63" is a 63-byte label and "label62" is a 62-byte label. 775*472cd20dSToomas Soome * Counting four label-length bytes, 251 bytes of label data, and the terminating zero, 776*472cd20dSToomas Soome * this makes a total of 256 bytes in wire format, the longest legal domain name. 777*472cd20dSToomas Soome * 778*472cd20dSToomas Soome * If each one of the 251 bytes of label data is represented using '\ddd', 779*472cd20dSToomas Soome * then it takes 251 * 4 = 1004 bytes to represent these in a C-string. 780*472cd20dSToomas Soome * Adding four '.' characters as shown above, plus the C-string terminating 781*472cd20dSToomas Soome * zero at the end, results in a maximum storage requirement of 1009 bytes. 782*472cd20dSToomas Soome * 783c65ebfc7SToomas Soome * The exceptions, that do not use escaping, are the routines where the full 784c65ebfc7SToomas Soome * DNS name of a resource is broken, for convenience, into servicename/regtype/domain. 785c65ebfc7SToomas Soome * In these routines, the "servicename" is NOT escaped. It does not need to be, since 786c65ebfc7SToomas Soome * it is, by definition, just a single literal string. Any characters in that string 787c65ebfc7SToomas Soome * represent exactly what they are. The "regtype" portion is, technically speaking, 788c65ebfc7SToomas Soome * escaped, but since legal regtypes are only allowed to contain US ASCII letters, 789c65ebfc7SToomas Soome * digits, and hyphens, there is nothing to escape, so the issue is moot. 790c65ebfc7SToomas Soome * The "domain" portion is also escaped, though most domains in use on the public 791c65ebfc7SToomas Soome * Internet today, like regtypes, don't contain any characters that need to be escaped. 792c65ebfc7SToomas Soome * As DNS-SD becomes more popular, rich-text domains for service discovery will 793c65ebfc7SToomas Soome * become common, so software should be written to cope with domains with escaping. 794c65ebfc7SToomas Soome * 795c65ebfc7SToomas Soome * The servicename may be up to 63 bytes of UTF-8 text (not counting the C-String 796c65ebfc7SToomas Soome * terminating NULL at the end). The regtype is of the form _service._tcp or 797c65ebfc7SToomas Soome * _service._udp, where the "service" part is 1-15 characters, which may be 798c65ebfc7SToomas Soome * letters, digits, or hyphens. The domain part of the three-part name may be 799c65ebfc7SToomas Soome * any legal domain, providing that the resulting servicename+regtype+domain 800c65ebfc7SToomas Soome * name does not exceed 256 bytes. 801c65ebfc7SToomas Soome * 802c65ebfc7SToomas Soome * For most software, these issues are transparent. When browsing, the discovered 803c65ebfc7SToomas Soome * servicenames should simply be displayed as-is. When resolving, the discovered 804c65ebfc7SToomas Soome * servicename/regtype/domain are simply passed unchanged to DNSServiceResolve(). 805c65ebfc7SToomas Soome * When a DNSServiceResolve() succeeds, the returned fullname is already in 806c65ebfc7SToomas Soome * the correct format to pass to standard system DNS APIs such as res_query(). 807c65ebfc7SToomas Soome * For converting from servicename/regtype/domain to a single properly-escaped 808c65ebfc7SToomas Soome * full DNS name, the helper function DNSServiceConstructFullName() is provided. 809c65ebfc7SToomas Soome * 810c65ebfc7SToomas Soome * The following (highly contrived) example illustrates the escaping process. 811c65ebfc7SToomas Soome * Suppose you have a service called "Dr. Smith\Dr. Johnson", of type "_ftp._tcp" 812c65ebfc7SToomas Soome * in subdomain "4th. Floor" of subdomain "Building 2" of domain "apple.com." 813c65ebfc7SToomas Soome * The full (escaped) DNS name of this service's SRV record would be: 814c65ebfc7SToomas Soome * Dr\.\032Smith\\Dr\.\032Johnson._ftp._tcp.4th\.\032Floor.Building\0322.apple.com. 815c65ebfc7SToomas Soome */ 816c65ebfc7SToomas Soome 817c65ebfc7SToomas Soome 818c65ebfc7SToomas Soome /* 819c65ebfc7SToomas Soome * Constants for specifying an interface index 820c65ebfc7SToomas Soome * 821c65ebfc7SToomas Soome * Specific interface indexes are identified via a 32-bit unsigned integer returned 822c65ebfc7SToomas Soome * by the if_nametoindex() family of calls. 823c65ebfc7SToomas Soome * 824c65ebfc7SToomas Soome * If the client passes 0 for interface index, that means "do the right thing", 825c65ebfc7SToomas Soome * which (at present) means, "if the name is in an mDNS local multicast domain 826c65ebfc7SToomas Soome * (e.g. 'local.', '254.169.in-addr.arpa.', '{8,9,A,B}.E.F.ip6.arpa.') then multicast 827c65ebfc7SToomas Soome * on all applicable interfaces, otherwise send via unicast to the appropriate 828c65ebfc7SToomas Soome * DNS server." Normally, most clients will use 0 for interface index to 829c65ebfc7SToomas Soome * automatically get the default sensible behaviour. 830c65ebfc7SToomas Soome * 831c65ebfc7SToomas Soome * If the client passes a positive interface index, then that indicates to do the 832c65ebfc7SToomas Soome * operation only on that one specified interface. 833c65ebfc7SToomas Soome * 834c65ebfc7SToomas Soome * If the client passes kDNSServiceInterfaceIndexLocalOnly when registering 835c65ebfc7SToomas Soome * a service, then that service will be found *only* by other local clients 836c65ebfc7SToomas Soome * on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly 837c65ebfc7SToomas Soome * or kDNSServiceInterfaceIndexAny. 838c65ebfc7SToomas Soome * If a client has a 'private' service, accessible only to other processes 839c65ebfc7SToomas Soome * running on the same machine, this allows the client to advertise that service 840c65ebfc7SToomas Soome * in a way such that it does not inadvertently appear in service lists on 841c65ebfc7SToomas Soome * all the other machines on the network. 842c65ebfc7SToomas Soome * 843c65ebfc7SToomas Soome * If the client passes kDNSServiceInterfaceIndexLocalOnly when querying or 844c65ebfc7SToomas Soome * browsing, then the LocalOnly authoritative records and /etc/hosts caches 845c65ebfc7SToomas Soome * are searched and will find *all* records registered or configured on that 846c65ebfc7SToomas Soome * same local machine. 847c65ebfc7SToomas Soome * 848c65ebfc7SToomas Soome * If interested in getting negative answers to local questions while querying 849c65ebfc7SToomas Soome * or browsing, then set both the kDNSServiceInterfaceIndexLocalOnly and the 850c65ebfc7SToomas Soome * kDNSServiceFlagsReturnIntermediates flags. If no local answers exist at this 851c65ebfc7SToomas Soome * moment in time, then the reply will return an immediate negative answer. If 852c65ebfc7SToomas Soome * local records are subsequently created that answer the question, then those 853c65ebfc7SToomas Soome * answers will be delivered, for as long as the question is still active. 854c65ebfc7SToomas Soome * 855c65ebfc7SToomas Soome * If the kDNSServiceFlagsTimeout and kDNSServiceInterfaceIndexLocalOnly flags 856c65ebfc7SToomas Soome * are set simultaneously when either DNSServiceQueryRecord or DNSServiceGetAddrInfo 857c65ebfc7SToomas Soome * is called then both flags take effect. However, if DNSServiceQueryRecord is called 858c65ebfc7SToomas Soome * with both the kDNSServiceFlagsSuppressUnusable and kDNSServiceInterfaceIndexLocalOnly 859c65ebfc7SToomas Soome * flags set, then the kDNSServiceFlagsSuppressUnusable flag is ignored. 860c65ebfc7SToomas Soome * 861c65ebfc7SToomas Soome * Clients explicitly wishing to discover *only* LocalOnly services during a 862c65ebfc7SToomas Soome * browse may do this, without flags, by inspecting the interfaceIndex of each 863c65ebfc7SToomas Soome * service reported to a DNSServiceBrowseReply() callback function, and 864c65ebfc7SToomas Soome * discarding those answers where the interface index is not set to 865c65ebfc7SToomas Soome * kDNSServiceInterfaceIndexLocalOnly. 866c65ebfc7SToomas Soome * 867c65ebfc7SToomas Soome * kDNSServiceInterfaceIndexP2P is meaningful only in Browse, QueryRecord, Register, 868c65ebfc7SToomas Soome * and Resolve operations. It should not be used in other DNSService APIs. 869c65ebfc7SToomas Soome * 870c65ebfc7SToomas Soome * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceBrowse or 871c65ebfc7SToomas Soome * DNSServiceQueryRecord, it restricts the operation to P2P. 872c65ebfc7SToomas Soome * 873c65ebfc7SToomas Soome * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceRegister, it is 874c65ebfc7SToomas Soome * mapped internally to kDNSServiceInterfaceIndexAny with the kDNSServiceFlagsIncludeP2P 875c65ebfc7SToomas Soome * set. 876c65ebfc7SToomas Soome * 877c65ebfc7SToomas Soome * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceResolve, it is 878c65ebfc7SToomas Soome * mapped internally to kDNSServiceInterfaceIndexAny with the kDNSServiceFlagsIncludeP2P 879c65ebfc7SToomas Soome * set, because resolving a P2P service may create and/or enable an interface whose 880c65ebfc7SToomas Soome * index is not known a priori. The resolve callback will indicate the index of the 881c65ebfc7SToomas Soome * interface via which the service can be accessed. 882c65ebfc7SToomas Soome * 883c65ebfc7SToomas Soome * If applications pass kDNSServiceInterfaceIndexAny to DNSServiceBrowse 884c65ebfc7SToomas Soome * or DNSServiceQueryRecord, they must set the kDNSServiceFlagsIncludeP2P flag 885c65ebfc7SToomas Soome * to include P2P. In this case, if a service instance or the record being queried 886c65ebfc7SToomas Soome * is found over P2P, the resulting ADD event will indicate kDNSServiceInterfaceIndexP2P 887c65ebfc7SToomas Soome * as the interface index. 888c65ebfc7SToomas Soome */ 889c65ebfc7SToomas Soome 890c65ebfc7SToomas Soome #define kDNSServiceInterfaceIndexAny 0 891c65ebfc7SToomas Soome #define kDNSServiceInterfaceIndexLocalOnly ((uint32_t)-1) 892c65ebfc7SToomas Soome #define kDNSServiceInterfaceIndexUnicast ((uint32_t)-2) 893c65ebfc7SToomas Soome #define kDNSServiceInterfaceIndexP2P ((uint32_t)-3) 894c65ebfc7SToomas Soome #define kDNSServiceInterfaceIndexBLE ((uint32_t)-4) 895c65ebfc7SToomas Soome 896c65ebfc7SToomas Soome typedef uint32_t DNSServiceFlags; 897c65ebfc7SToomas Soome typedef uint32_t DNSServiceProtocol; 898c65ebfc7SToomas Soome typedef int32_t DNSServiceErrorType; 899c65ebfc7SToomas Soome 900c65ebfc7SToomas Soome 901c65ebfc7SToomas Soome /********************************************************************************************* 902c65ebfc7SToomas Soome * 903c65ebfc7SToomas Soome * Version checking 904c65ebfc7SToomas Soome * 905c65ebfc7SToomas Soome *********************************************************************************************/ 906c65ebfc7SToomas Soome 907c65ebfc7SToomas Soome /* DNSServiceGetProperty() Parameters: 908c65ebfc7SToomas Soome * 909c65ebfc7SToomas Soome * property: The requested property. 910c65ebfc7SToomas Soome * Currently the only property defined is kDNSServiceProperty_DaemonVersion. 911c65ebfc7SToomas Soome * 912c65ebfc7SToomas Soome * result: Place to store result. 913c65ebfc7SToomas Soome * For retrieving DaemonVersion, this should be the address of a uint32_t. 914c65ebfc7SToomas Soome * 915c65ebfc7SToomas Soome * size: Pointer to uint32_t containing size of the result location. 916c65ebfc7SToomas Soome * For retrieving DaemonVersion, this should be sizeof(uint32_t). 917c65ebfc7SToomas Soome * On return the uint32_t is updated to the size of the data returned. 918c65ebfc7SToomas Soome * For DaemonVersion, the returned size is always sizeof(uint32_t), but 919c65ebfc7SToomas Soome * future properties could be defined which return variable-sized results. 920c65ebfc7SToomas Soome * 921c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success, or kDNSServiceErr_ServiceNotRunning 922c65ebfc7SToomas Soome * if the daemon (or "system service" on Windows) is not running. 923c65ebfc7SToomas Soome */ 924c65ebfc7SToomas Soome 9253b436d06SToomas Soome DNSSD_EXPORT 926c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceGetProperty 927c65ebfc7SToomas Soome ( 928c65ebfc7SToomas Soome const char *property, /* Requested property (i.e. kDNSServiceProperty_DaemonVersion) */ 929c65ebfc7SToomas Soome void *result, /* Pointer to place to store result */ 930c65ebfc7SToomas Soome uint32_t *size /* size of result location */ 931c65ebfc7SToomas Soome ); 932c65ebfc7SToomas Soome 933c65ebfc7SToomas Soome /* 934c65ebfc7SToomas Soome * When requesting kDNSServiceProperty_DaemonVersion, the result pointer must point 935c65ebfc7SToomas Soome * to a 32-bit unsigned integer, and the size parameter must be set to sizeof(uint32_t). 936c65ebfc7SToomas Soome * 937c65ebfc7SToomas Soome * On return, the 32-bit unsigned integer contains the API version number 938c65ebfc7SToomas Soome * 939c65ebfc7SToomas Soome * For example, Mac OS X 10.4.9 has API version 1080400. 940c65ebfc7SToomas Soome * This allows applications to do simple greater-than and less-than comparisons: 941c65ebfc7SToomas Soome * e.g. an application that requires at least API version 1080400 can check: 942c65ebfc7SToomas Soome * if (version >= 1080400) ... 943c65ebfc7SToomas Soome * 944c65ebfc7SToomas Soome * Example usage: 945c65ebfc7SToomas Soome * uint32_t version; 946c65ebfc7SToomas Soome * uint32_t size = sizeof(version); 947c65ebfc7SToomas Soome * DNSServiceErrorType err = DNSServiceGetProperty(kDNSServiceProperty_DaemonVersion, &version, &size); 948c65ebfc7SToomas Soome * if (!err) printf("DNS_SD API version is %d.%d\n", version / 10000, version / 100 % 100); 949c65ebfc7SToomas Soome */ 950c65ebfc7SToomas Soome 951c65ebfc7SToomas Soome #define kDNSServiceProperty_DaemonVersion "DaemonVersion" 952c65ebfc7SToomas Soome 953c65ebfc7SToomas Soome /********************************************************************************************* 954c65ebfc7SToomas Soome * 955c65ebfc7SToomas Soome * Unix Domain Socket access, DNSServiceRef deallocation, and data processing functions 956c65ebfc7SToomas Soome * 957c65ebfc7SToomas Soome *********************************************************************************************/ 958c65ebfc7SToomas Soome 959c65ebfc7SToomas Soome /* DNSServiceRefSockFD() 960c65ebfc7SToomas Soome * 961c65ebfc7SToomas Soome * Access underlying Unix domain socket for an initialized DNSServiceRef. 962c65ebfc7SToomas Soome * The DNS Service Discovery implementation uses this socket to communicate between the client and 963c65ebfc7SToomas Soome * the daemon. The application MUST NOT directly read from or write to this socket. 964c65ebfc7SToomas Soome * Access to the socket is provided so that it can be used as a kqueue event source, a CFRunLoop 965c65ebfc7SToomas Soome * event source, in a select() loop, etc. When the underlying event management subsystem (kqueue/ 966c65ebfc7SToomas Soome * select/CFRunLoop etc.) indicates to the client that data is available for reading on the 967c65ebfc7SToomas Soome * socket, the client should call DNSServiceProcessResult(), which will extract the daemon's 968c65ebfc7SToomas Soome * reply from the socket, and pass it to the appropriate application callback. By using a run 969c65ebfc7SToomas Soome * loop or select(), results from the daemon can be processed asynchronously. Alternatively, 970c65ebfc7SToomas Soome * a client can choose to fork a thread and have it loop calling "DNSServiceProcessResult(ref);" 971c65ebfc7SToomas Soome * If DNSServiceProcessResult() is called when no data is available for reading on the socket, it 972c65ebfc7SToomas Soome * will block until data does become available, and then process the data and return to the caller. 973c65ebfc7SToomas Soome * The application is responsible for checking the return value of DNSServiceProcessResult() 974c65ebfc7SToomas Soome * to determine if the socket is valid and if it should continue to process data on the socket. 975c65ebfc7SToomas Soome * When data arrives on the socket, the client is responsible for calling DNSServiceProcessResult(ref) 976c65ebfc7SToomas Soome * in a timely fashion -- if the client allows a large backlog of data to build up the daemon 977c65ebfc7SToomas Soome * may terminate the connection. 978c65ebfc7SToomas Soome * 979c65ebfc7SToomas Soome * sdRef: A DNSServiceRef initialized by any of the DNSService calls. 980c65ebfc7SToomas Soome * 981c65ebfc7SToomas Soome * return value: The DNSServiceRef's underlying socket descriptor, or -1 on 982c65ebfc7SToomas Soome * error. 983c65ebfc7SToomas Soome */ 984c65ebfc7SToomas Soome 9853b436d06SToomas Soome DNSSD_EXPORT 986c65ebfc7SToomas Soome dnssd_sock_t DNSSD_API DNSServiceRefSockFD(DNSServiceRef sdRef); 987c65ebfc7SToomas Soome 988c65ebfc7SToomas Soome 989c65ebfc7SToomas Soome /* DNSServiceProcessResult() 990c65ebfc7SToomas Soome * 991c65ebfc7SToomas Soome * Read a reply from the daemon, calling the appropriate application callback. This call will 992c65ebfc7SToomas Soome * block until the daemon's response is received. Use DNSServiceRefSockFD() in 993c65ebfc7SToomas Soome * conjunction with a run loop or select() to determine the presence of a response from the 994c65ebfc7SToomas Soome * server before calling this function to process the reply without blocking. Call this function 995c65ebfc7SToomas Soome * at any point if it is acceptable to block until the daemon's response arrives. Note that the 996c65ebfc7SToomas Soome * client is responsible for ensuring that DNSServiceProcessResult() is called whenever there is 997c65ebfc7SToomas Soome * a reply from the daemon - the daemon may terminate its connection with a client that does not 998c65ebfc7SToomas Soome * process the daemon's responses. 999c65ebfc7SToomas Soome * 1000c65ebfc7SToomas Soome * sdRef: A DNSServiceRef initialized by any of the DNSService calls 1001c65ebfc7SToomas Soome * that take a callback parameter. 1002c65ebfc7SToomas Soome * 1003c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success, otherwise returns 1004c65ebfc7SToomas Soome * an error code indicating the specific failure that occurred. 1005c65ebfc7SToomas Soome */ 1006c65ebfc7SToomas Soome 10073b436d06SToomas Soome DNSSD_EXPORT 1008c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceProcessResult(DNSServiceRef sdRef); 1009c65ebfc7SToomas Soome 1010c65ebfc7SToomas Soome 1011c65ebfc7SToomas Soome /* DNSServiceRefDeallocate() 1012c65ebfc7SToomas Soome * 1013c65ebfc7SToomas Soome * Terminate a connection with the daemon and free memory associated with the DNSServiceRef. 1014c65ebfc7SToomas Soome * Any services or records registered with this DNSServiceRef will be deregistered. Any 1015c65ebfc7SToomas Soome * Browse, Resolve, or Query operations called with this reference will be terminated. 1016c65ebfc7SToomas Soome * 1017c65ebfc7SToomas Soome * Note: If the reference's underlying socket is used in a run loop or select() call, it should 1018c65ebfc7SToomas Soome * be removed BEFORE DNSServiceRefDeallocate() is called, as this function closes the reference's 1019c65ebfc7SToomas Soome * socket. 1020c65ebfc7SToomas Soome * 1021c65ebfc7SToomas Soome * Note: If the reference was initialized with DNSServiceCreateConnection(), any DNSRecordRefs 1022c65ebfc7SToomas Soome * created via this reference will be invalidated by this call - the resource records are 1023c65ebfc7SToomas Soome * deregistered, and their DNSRecordRefs may not be used in subsequent functions. Similarly, 1024c65ebfc7SToomas Soome * if the reference was initialized with DNSServiceRegister, and an extra resource record was 1025c65ebfc7SToomas Soome * added to the service via DNSServiceAddRecord(), the DNSRecordRef created by the Add() call 1026c65ebfc7SToomas Soome * is invalidated when this function is called - the DNSRecordRef may not be used in subsequent 1027c65ebfc7SToomas Soome * functions. 1028c65ebfc7SToomas Soome * 1029*472cd20dSToomas Soome * If the reference was passed to DNSServiceSetDispatchQueue(), DNSServiceRefDeallocate() must 1030*472cd20dSToomas Soome * be called on the same queue originally passed as an argument to DNSServiceSetDispatchQueue(). 1031*472cd20dSToomas Soome * 1032c65ebfc7SToomas Soome * Note: This call is to be used only with the DNSServiceRef defined by this API. 1033c65ebfc7SToomas Soome * 1034c65ebfc7SToomas Soome * sdRef: A DNSServiceRef initialized by any of the DNSService calls. 1035c65ebfc7SToomas Soome * 1036c65ebfc7SToomas Soome */ 1037c65ebfc7SToomas Soome 10383b436d06SToomas Soome DNSSD_EXPORT 1039c65ebfc7SToomas Soome void DNSSD_API DNSServiceRefDeallocate(DNSServiceRef sdRef); 1040c65ebfc7SToomas Soome 1041c65ebfc7SToomas Soome 1042c65ebfc7SToomas Soome /********************************************************************************************* 1043c65ebfc7SToomas Soome * 1044c65ebfc7SToomas Soome * Domain Enumeration 1045c65ebfc7SToomas Soome * 1046c65ebfc7SToomas Soome *********************************************************************************************/ 1047c65ebfc7SToomas Soome 1048c65ebfc7SToomas Soome /* DNSServiceEnumerateDomains() 1049c65ebfc7SToomas Soome * 1050c65ebfc7SToomas Soome * Asynchronously enumerate domains available for browsing and registration. 1051c65ebfc7SToomas Soome * 1052c65ebfc7SToomas Soome * The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains 1053c65ebfc7SToomas Soome * are to be found. 1054c65ebfc7SToomas Soome * 1055c65ebfc7SToomas Soome * Note that the names returned are (like all of DNS-SD) UTF-8 strings, 1056c65ebfc7SToomas Soome * and are escaped using standard DNS escaping rules. 1057c65ebfc7SToomas Soome * (See "Notes on DNS Name Escaping" earlier in this file for more details.) 1058c65ebfc7SToomas Soome * A graphical browser displaying a hierarchical tree-structured view should cut 1059c65ebfc7SToomas Soome * the names at the bare dots to yield individual labels, then de-escape each 1060c65ebfc7SToomas Soome * label according to the escaping rules, and then display the resulting UTF-8 text. 1061c65ebfc7SToomas Soome * 1062c65ebfc7SToomas Soome * DNSServiceDomainEnumReply Callback Parameters: 1063c65ebfc7SToomas Soome * 1064c65ebfc7SToomas Soome * sdRef: The DNSServiceRef initialized by DNSServiceEnumerateDomains(). 1065c65ebfc7SToomas Soome * 1066c65ebfc7SToomas Soome * flags: Possible values are: 1067c65ebfc7SToomas Soome * kDNSServiceFlagsMoreComing 1068c65ebfc7SToomas Soome * kDNSServiceFlagsAdd 1069c65ebfc7SToomas Soome * kDNSServiceFlagsDefault 1070c65ebfc7SToomas Soome * 1071c65ebfc7SToomas Soome * interfaceIndex: Specifies the interface on which the domain exists. (The index for a given 1072c65ebfc7SToomas Soome * interface is determined via the if_nametoindex() family of calls.) 1073c65ebfc7SToomas Soome * 1074c65ebfc7SToomas Soome * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise indicates 1075c65ebfc7SToomas Soome * the failure that occurred (other parameters are undefined if errorCode is nonzero). 1076c65ebfc7SToomas Soome * 1077c65ebfc7SToomas Soome * replyDomain: The name of the domain. 1078c65ebfc7SToomas Soome * 1079c65ebfc7SToomas Soome * context: The context pointer passed to DNSServiceEnumerateDomains. 1080c65ebfc7SToomas Soome * 1081c65ebfc7SToomas Soome */ 1082c65ebfc7SToomas Soome 1083c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceDomainEnumReply) 1084c65ebfc7SToomas Soome ( 1085c65ebfc7SToomas Soome DNSServiceRef sdRef, 1086c65ebfc7SToomas Soome DNSServiceFlags flags, 1087c65ebfc7SToomas Soome uint32_t interfaceIndex, 1088c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 1089c65ebfc7SToomas Soome const char *replyDomain, 1090c65ebfc7SToomas Soome void *context 1091c65ebfc7SToomas Soome ); 1092c65ebfc7SToomas Soome 1093c65ebfc7SToomas Soome 1094c65ebfc7SToomas Soome /* DNSServiceEnumerateDomains() Parameters: 1095c65ebfc7SToomas Soome * 1096*472cd20dSToomas Soome * sdRef: A pointer to an uninitialized DNSServiceRef 1097*472cd20dSToomas Soome * (or, if the kDNSServiceFlagsShareConnection flag is used, 1098*472cd20dSToomas Soome * a copy of the shared connection reference that is to be used). 1099*472cd20dSToomas Soome * If the call succeeds then it initializes (or updates) the DNSServiceRef, 1100*472cd20dSToomas Soome * returns kDNSServiceErr_NoError, and the enumeration operation 1101*472cd20dSToomas Soome * will remain active indefinitely until the client terminates it 1102*472cd20dSToomas Soome * by passing this DNSServiceRef to DNSServiceRefDeallocate() 1103*472cd20dSToomas Soome * (or by closing the underlying shared connection, if used). 1104c65ebfc7SToomas Soome * 1105c65ebfc7SToomas Soome * flags: Possible values are: 1106*472cd20dSToomas Soome * kDNSServiceFlagsShareConnection to use a shared connection. 1107c65ebfc7SToomas Soome * kDNSServiceFlagsBrowseDomains to enumerate domains recommended for browsing. 1108c65ebfc7SToomas Soome * kDNSServiceFlagsRegistrationDomains to enumerate domains recommended 1109c65ebfc7SToomas Soome * for registration. 1110c65ebfc7SToomas Soome * 1111c65ebfc7SToomas Soome * interfaceIndex: If non-zero, specifies the interface on which to look for domains. 1112c65ebfc7SToomas Soome * (the index for a given interface is determined via the if_nametoindex() 1113c65ebfc7SToomas Soome * family of calls.) Most applications will pass 0 to enumerate domains on 1114c65ebfc7SToomas Soome * all interfaces. See "Constants for specifying an interface index" for more details. 1115c65ebfc7SToomas Soome * 1116c65ebfc7SToomas Soome * callBack: The function to be called when a domain is found or the call asynchronously 1117c65ebfc7SToomas Soome * fails. 1118c65ebfc7SToomas Soome * 1119c65ebfc7SToomas Soome * context: An application context pointer which is passed to the callback function 1120c65ebfc7SToomas Soome * (may be NULL). 1121c65ebfc7SToomas Soome * 1122c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 1123c65ebfc7SToomas Soome * errors are delivered to the callback), otherwise returns an error code indicating 1124c65ebfc7SToomas Soome * the error that occurred (the callback is not invoked and the DNSServiceRef 1125c65ebfc7SToomas Soome * is not initialized). 1126c65ebfc7SToomas Soome */ 1127c65ebfc7SToomas Soome 11283b436d06SToomas Soome DNSSD_EXPORT 1129c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceEnumerateDomains 1130c65ebfc7SToomas Soome ( 1131c65ebfc7SToomas Soome DNSServiceRef *sdRef, 1132c65ebfc7SToomas Soome DNSServiceFlags flags, 1133c65ebfc7SToomas Soome uint32_t interfaceIndex, 1134c65ebfc7SToomas Soome DNSServiceDomainEnumReply callBack, 1135c65ebfc7SToomas Soome void *context /* may be NULL */ 1136c65ebfc7SToomas Soome ); 1137c65ebfc7SToomas Soome 1138c65ebfc7SToomas Soome 1139c65ebfc7SToomas Soome /********************************************************************************************* 1140c65ebfc7SToomas Soome * 1141c65ebfc7SToomas Soome * Service Registration 1142c65ebfc7SToomas Soome * 1143c65ebfc7SToomas Soome *********************************************************************************************/ 1144c65ebfc7SToomas Soome 1145c65ebfc7SToomas Soome /* Register a service that is discovered via Browse() and Resolve() calls. 1146c65ebfc7SToomas Soome * 1147c65ebfc7SToomas Soome * DNSServiceRegisterReply() Callback Parameters: 1148c65ebfc7SToomas Soome * 1149c65ebfc7SToomas Soome * sdRef: The DNSServiceRef initialized by DNSServiceRegister(). 1150c65ebfc7SToomas Soome * 1151c65ebfc7SToomas Soome * flags: When a name is successfully registered, the callback will be 1152c65ebfc7SToomas Soome * invoked with the kDNSServiceFlagsAdd flag set. When Wide-Area 1153c65ebfc7SToomas Soome * DNS-SD is in use, it is possible for a single service to get 1154c65ebfc7SToomas Soome * more than one success callback (e.g. one in the "local" multicast 1155c65ebfc7SToomas Soome * DNS domain, and another in a wide-area unicast DNS domain). 1156c65ebfc7SToomas Soome * If a successfully-registered name later suffers a name conflict 1157c65ebfc7SToomas Soome * or similar problem and has to be deregistered, the callback will 1158c65ebfc7SToomas Soome * be invoked with the kDNSServiceFlagsAdd flag not set. The callback 1159c65ebfc7SToomas Soome * is *not* invoked in the case where the caller explicitly terminates 1160c65ebfc7SToomas Soome * the service registration by calling DNSServiceRefDeallocate(ref); 1161c65ebfc7SToomas Soome * 1162c65ebfc7SToomas Soome * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will 1163c65ebfc7SToomas Soome * indicate the failure that occurred (including name conflicts, 1164c65ebfc7SToomas Soome * if the kDNSServiceFlagsNoAutoRename flag was used when registering.) 1165c65ebfc7SToomas Soome * Other parameters are undefined if errorCode is nonzero. 1166c65ebfc7SToomas Soome * 1167c65ebfc7SToomas Soome * name: The service name registered (if the application did not specify a name in 1168c65ebfc7SToomas Soome * DNSServiceRegister(), this indicates what name was automatically chosen). 1169c65ebfc7SToomas Soome * 1170c65ebfc7SToomas Soome * regtype: The type of service registered, as it was passed to the callout. 1171c65ebfc7SToomas Soome * 1172c65ebfc7SToomas Soome * domain: The domain on which the service was registered (if the application did not 1173c65ebfc7SToomas Soome * specify a domain in DNSServiceRegister(), this indicates the default domain 1174c65ebfc7SToomas Soome * on which the service was registered). 1175c65ebfc7SToomas Soome * 1176c65ebfc7SToomas Soome * context: The context pointer that was passed to the callout. 1177c65ebfc7SToomas Soome * 1178c65ebfc7SToomas Soome */ 1179c65ebfc7SToomas Soome 1180c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceRegisterReply) 1181c65ebfc7SToomas Soome ( 1182c65ebfc7SToomas Soome DNSServiceRef sdRef, 1183c65ebfc7SToomas Soome DNSServiceFlags flags, 1184c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 1185c65ebfc7SToomas Soome const char *name, 1186c65ebfc7SToomas Soome const char *regtype, 1187c65ebfc7SToomas Soome const char *domain, 1188c65ebfc7SToomas Soome void *context 1189c65ebfc7SToomas Soome ); 1190c65ebfc7SToomas Soome 1191c65ebfc7SToomas Soome 1192c65ebfc7SToomas Soome /* DNSServiceRegister() Parameters: 1193c65ebfc7SToomas Soome * 1194*472cd20dSToomas Soome * sdRef: A pointer to an uninitialized DNSServiceRef 1195*472cd20dSToomas Soome * (or, if the kDNSServiceFlagsShareConnection flag is used, 1196*472cd20dSToomas Soome * a copy of the shared connection reference that is to be used). 1197*472cd20dSToomas Soome * If the call succeeds then it initializes (or updates) the DNSServiceRef, 1198*472cd20dSToomas Soome * returns kDNSServiceErr_NoError, and the service registration 1199*472cd20dSToomas Soome * will remain active indefinitely until the client terminates it 1200*472cd20dSToomas Soome * by passing this DNSServiceRef to DNSServiceRefDeallocate() 1201*472cd20dSToomas Soome * (or by closing the underlying shared connection, if used). 1202c65ebfc7SToomas Soome * 1203*472cd20dSToomas Soome * flags: Possible values are: 1204*472cd20dSToomas Soome * kDNSServiceFlagsShareConnection to use a shared connection. 1205*472cd20dSToomas Soome * Other flags indicate the renaming behavior on name conflict 1206*472cd20dSToomas Soome * (not required for most applications). 1207*472cd20dSToomas Soome * See flag definitions above for details. 1208c65ebfc7SToomas Soome * 1209c65ebfc7SToomas Soome * interfaceIndex: If non-zero, specifies the interface on which to register the service 1210c65ebfc7SToomas Soome * (the index for a given interface is determined via the if_nametoindex() 1211c65ebfc7SToomas Soome * family of calls.) Most applications will pass 0 to register on all 1212c65ebfc7SToomas Soome * available interfaces. See "Constants for specifying an interface index" for more details. 1213c65ebfc7SToomas Soome * 1214c65ebfc7SToomas Soome * name: If non-NULL, specifies the service name to be registered. 1215c65ebfc7SToomas Soome * Most applications will not specify a name, in which case the computer 1216c65ebfc7SToomas Soome * name is used (this name is communicated to the client via the callback). 1217c65ebfc7SToomas Soome * If a name is specified, it must be 1-63 bytes of UTF-8 text. 1218c65ebfc7SToomas Soome * If the name is longer than 63 bytes it will be automatically truncated 1219c65ebfc7SToomas Soome * to a legal length, unless the NoAutoRename flag is set, 1220c65ebfc7SToomas Soome * in which case kDNSServiceErr_BadParam will be returned. 1221c65ebfc7SToomas Soome * 1222c65ebfc7SToomas Soome * regtype: The service type followed by the protocol, separated by a dot 1223c65ebfc7SToomas Soome * (e.g. "_ftp._tcp"). The service type must be an underscore, followed 1224c65ebfc7SToomas Soome * by 1-15 characters, which may be letters, digits, or hyphens. 1225c65ebfc7SToomas Soome * The transport protocol must be "_tcp" or "_udp". New service types 1226c65ebfc7SToomas Soome * should be registered at <http://www.dns-sd.org/ServiceTypes.html>. 1227c65ebfc7SToomas Soome * 1228c65ebfc7SToomas Soome * Additional subtypes of the primary service type (where a service 1229c65ebfc7SToomas Soome * type has defined subtypes) follow the primary service type in a 1230c65ebfc7SToomas Soome * comma-separated list, with no additional spaces, e.g. 1231c65ebfc7SToomas Soome * "_primarytype._tcp,_subtype1,_subtype2,_subtype3" 1232c65ebfc7SToomas Soome * Subtypes provide a mechanism for filtered browsing: A client browsing 1233c65ebfc7SToomas Soome * for "_primarytype._tcp" will discover all instances of this type; 1234c65ebfc7SToomas Soome * a client browsing for "_primarytype._tcp,_subtype2" will discover only 1235c65ebfc7SToomas Soome * those instances that were registered with "_subtype2" in their list of 1236c65ebfc7SToomas Soome * registered subtypes. 1237c65ebfc7SToomas Soome * 1238c65ebfc7SToomas Soome * The subtype mechanism can be illustrated with some examples using the 1239c65ebfc7SToomas Soome * dns-sd command-line tool: 1240c65ebfc7SToomas Soome * 1241c65ebfc7SToomas Soome * % dns-sd -R Simple _test._tcp "" 1001 & 1242c65ebfc7SToomas Soome * % dns-sd -R Better _test._tcp,HasFeatureA "" 1002 & 1243c65ebfc7SToomas Soome * % dns-sd -R Best _test._tcp,HasFeatureA,HasFeatureB "" 1003 & 1244c65ebfc7SToomas Soome * 1245c65ebfc7SToomas Soome * Now: 1246c65ebfc7SToomas Soome * % dns-sd -B _test._tcp # will find all three services 1247c65ebfc7SToomas Soome * % dns-sd -B _test._tcp,HasFeatureA # finds "Better" and "Best" 1248c65ebfc7SToomas Soome * % dns-sd -B _test._tcp,HasFeatureB # finds only "Best" 1249c65ebfc7SToomas Soome * 1250c65ebfc7SToomas Soome * Subtype labels may be up to 63 bytes long, and may contain any eight- 1251c65ebfc7SToomas Soome * bit byte values, including zero bytes. However, due to the nature of 1252c65ebfc7SToomas Soome * using a C-string-based API, conventional DNS escaping must be used for 1253c65ebfc7SToomas Soome * dots ('.'), commas (','), backslashes ('\') and zero bytes, as shown below: 1254c65ebfc7SToomas Soome * 1255c65ebfc7SToomas Soome * % dns-sd -R Test '_test._tcp,s\.one,s\,two,s\\three,s\000four' local 123 1256c65ebfc7SToomas Soome * 1257c65ebfc7SToomas Soome * domain: If non-NULL, specifies the domain on which to advertise the service. 1258c65ebfc7SToomas Soome * Most applications will not specify a domain, instead automatically 1259c65ebfc7SToomas Soome * registering in the default domain(s). 1260c65ebfc7SToomas Soome * 1261c65ebfc7SToomas Soome * host: If non-NULL, specifies the SRV target host name. Most applications 1262c65ebfc7SToomas Soome * will not specify a host, instead automatically using the machine's 1263c65ebfc7SToomas Soome * default host name(s). Note that specifying a non-NULL host does NOT 1264c65ebfc7SToomas Soome * create an address record for that host - the application is responsible 1265c65ebfc7SToomas Soome * for ensuring that the appropriate address record exists, or creating it 1266c65ebfc7SToomas Soome * via DNSServiceRegisterRecord(). 1267c65ebfc7SToomas Soome * 1268c65ebfc7SToomas Soome * port: The port, in network byte order, on which the service accepts connections. 1269c65ebfc7SToomas Soome * Pass 0 for a "placeholder" service (i.e. a service that will not be discovered 1270c65ebfc7SToomas Soome * by browsing, but will cause a name conflict if another client tries to 1271c65ebfc7SToomas Soome * register that same name). Most clients will not use placeholder services. 1272c65ebfc7SToomas Soome * 1273c65ebfc7SToomas Soome * txtLen: The length of the txtRecord, in bytes. Must be zero if the txtRecord is NULL. 1274c65ebfc7SToomas Soome * 1275c65ebfc7SToomas Soome * txtRecord: The TXT record rdata. A non-NULL txtRecord MUST be a properly formatted DNS 1276c65ebfc7SToomas Soome * TXT record, i.e. <length byte> <data> <length byte> <data> ... 1277c65ebfc7SToomas Soome * Passing NULL for the txtRecord is allowed as a synonym for txtLen=1, txtRecord="", 1278c65ebfc7SToomas Soome * i.e. it creates a TXT record of length one containing a single empty string. 1279c65ebfc7SToomas Soome * RFC 1035 doesn't allow a TXT record to contain *zero* strings, so a single empty 1280c65ebfc7SToomas Soome * string is the smallest legal DNS TXT record. 1281c65ebfc7SToomas Soome * As with the other parameters, the DNSServiceRegister call copies the txtRecord 1282c65ebfc7SToomas Soome * data; e.g. if you allocated the storage for the txtRecord parameter with malloc() 1283c65ebfc7SToomas Soome * then you can safely free that memory right after the DNSServiceRegister call returns. 1284c65ebfc7SToomas Soome * 1285c65ebfc7SToomas Soome * callBack: The function to be called when the registration completes or asynchronously 1286c65ebfc7SToomas Soome * fails. The client MAY pass NULL for the callback - The client will NOT be notified 1287c65ebfc7SToomas Soome * of the default values picked on its behalf, and the client will NOT be notified of any 1288c65ebfc7SToomas Soome * asynchronous errors (e.g. out of memory errors, etc.) that may prevent the registration 1289c65ebfc7SToomas Soome * of the service. The client may NOT pass the NoAutoRename flag if the callback is NULL. 1290c65ebfc7SToomas Soome * The client may still deregister the service at any time via DNSServiceRefDeallocate(). 1291c65ebfc7SToomas Soome * 1292c65ebfc7SToomas Soome * context: An application context pointer which is passed to the callback function 1293c65ebfc7SToomas Soome * (may be NULL). 1294c65ebfc7SToomas Soome * 1295c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 1296c65ebfc7SToomas Soome * errors are delivered to the callback), otherwise returns an error code indicating 1297c65ebfc7SToomas Soome * the error that occurred (the callback is never invoked and the DNSServiceRef 1298c65ebfc7SToomas Soome * is not initialized). 1299c65ebfc7SToomas Soome */ 1300c65ebfc7SToomas Soome 13013b436d06SToomas Soome DNSSD_EXPORT 1302c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceRegister 1303c65ebfc7SToomas Soome ( 1304c65ebfc7SToomas Soome DNSServiceRef *sdRef, 1305c65ebfc7SToomas Soome DNSServiceFlags flags, 1306c65ebfc7SToomas Soome uint32_t interfaceIndex, 1307c65ebfc7SToomas Soome const char *name, /* may be NULL */ 1308c65ebfc7SToomas Soome const char *regtype, 1309c65ebfc7SToomas Soome const char *domain, /* may be NULL */ 1310c65ebfc7SToomas Soome const char *host, /* may be NULL */ 1311c65ebfc7SToomas Soome uint16_t port, /* In network byte order */ 1312c65ebfc7SToomas Soome uint16_t txtLen, 1313c65ebfc7SToomas Soome const void *txtRecord, /* may be NULL */ 1314c65ebfc7SToomas Soome DNSServiceRegisterReply callBack, /* may be NULL */ 1315c65ebfc7SToomas Soome void *context /* may be NULL */ 1316c65ebfc7SToomas Soome ); 1317c65ebfc7SToomas Soome 1318c65ebfc7SToomas Soome 1319c65ebfc7SToomas Soome /* DNSServiceAddRecord() 1320c65ebfc7SToomas Soome * 1321c65ebfc7SToomas Soome * Add a record to a registered service. The name of the record will be the same as the 1322c65ebfc7SToomas Soome * registered service's name. 1323c65ebfc7SToomas Soome * The record can later be updated or deregistered by passing the RecordRef initialized 1324c65ebfc7SToomas Soome * by this function to DNSServiceUpdateRecord() or DNSServiceRemoveRecord(). 1325c65ebfc7SToomas Soome * 1326c65ebfc7SToomas Soome * Note that the DNSServiceAddRecord/UpdateRecord/RemoveRecord are *NOT* thread-safe 1327c65ebfc7SToomas Soome * with respect to a single DNSServiceRef. If you plan to have multiple threads 1328c65ebfc7SToomas Soome * in your program simultaneously add, update, or remove records from the same 1329c65ebfc7SToomas Soome * DNSServiceRef, then it's the caller's responsibility to use a mutex lock 1330c65ebfc7SToomas Soome * or take similar appropriate precautions to serialize those calls. 1331c65ebfc7SToomas Soome * 1332c65ebfc7SToomas Soome * Parameters; 1333c65ebfc7SToomas Soome * 1334c65ebfc7SToomas Soome * sdRef: A DNSServiceRef initialized by DNSServiceRegister(). 1335c65ebfc7SToomas Soome * 1336c65ebfc7SToomas Soome * RecordRef: A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this 1337c65ebfc7SToomas Soome * call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord(). 1338c65ebfc7SToomas Soome * If the above DNSServiceRef is passed to DNSServiceRefDeallocate(), RecordRef is also 1339c65ebfc7SToomas Soome * invalidated and may not be used further. 1340c65ebfc7SToomas Soome * 1341c65ebfc7SToomas Soome * flags: Currently ignored, reserved for future use. 1342c65ebfc7SToomas Soome * 1343c65ebfc7SToomas Soome * rrtype: The type of the record (e.g. kDNSServiceType_TXT, kDNSServiceType_SRV, etc) 1344c65ebfc7SToomas Soome * 1345c65ebfc7SToomas Soome * rdlen: The length, in bytes, of the rdata. 1346c65ebfc7SToomas Soome * 1347c65ebfc7SToomas Soome * rdata: The raw rdata to be contained in the added resource record. 1348c65ebfc7SToomas Soome * 1349c65ebfc7SToomas Soome * ttl: The time to live of the resource record, in seconds. 1350c65ebfc7SToomas Soome * Most clients should pass 0 to indicate that the system should 1351c65ebfc7SToomas Soome * select a sensible default value. 1352c65ebfc7SToomas Soome * 1353c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an 1354c65ebfc7SToomas Soome * error code indicating the error that occurred (the RecordRef is not initialized). 1355c65ebfc7SToomas Soome */ 1356c65ebfc7SToomas Soome 13573b436d06SToomas Soome DNSSD_EXPORT 1358c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceAddRecord 1359c65ebfc7SToomas Soome ( 1360c65ebfc7SToomas Soome DNSServiceRef sdRef, 1361c65ebfc7SToomas Soome DNSRecordRef *RecordRef, 1362c65ebfc7SToomas Soome DNSServiceFlags flags, 1363c65ebfc7SToomas Soome uint16_t rrtype, 1364c65ebfc7SToomas Soome uint16_t rdlen, 1365c65ebfc7SToomas Soome const void *rdata, 1366c65ebfc7SToomas Soome uint32_t ttl 1367c65ebfc7SToomas Soome ); 1368c65ebfc7SToomas Soome 1369c65ebfc7SToomas Soome 1370c65ebfc7SToomas Soome /* DNSServiceUpdateRecord 1371c65ebfc7SToomas Soome * 1372c65ebfc7SToomas Soome * Update a registered resource record. The record must either be: 1373c65ebfc7SToomas Soome * - The primary txt record of a service registered via DNSServiceRegister() 1374c65ebfc7SToomas Soome * - A record added to a registered service via DNSServiceAddRecord() 1375c65ebfc7SToomas Soome * - An individual record registered by DNSServiceRegisterRecord() 1376c65ebfc7SToomas Soome * 1377c65ebfc7SToomas Soome * Parameters: 1378c65ebfc7SToomas Soome * 1379c65ebfc7SToomas Soome * sdRef: A DNSServiceRef that was initialized by DNSServiceRegister() 1380c65ebfc7SToomas Soome * or DNSServiceCreateConnection(). 1381c65ebfc7SToomas Soome * 1382c65ebfc7SToomas Soome * RecordRef: A DNSRecordRef initialized by DNSServiceAddRecord, or NULL to update the 1383c65ebfc7SToomas Soome * service's primary txt record. 1384c65ebfc7SToomas Soome * 1385c65ebfc7SToomas Soome * flags: Currently ignored, reserved for future use. 1386c65ebfc7SToomas Soome * 1387c65ebfc7SToomas Soome * rdlen: The length, in bytes, of the new rdata. 1388c65ebfc7SToomas Soome * 1389c65ebfc7SToomas Soome * rdata: The new rdata to be contained in the updated resource record. 1390c65ebfc7SToomas Soome * 1391c65ebfc7SToomas Soome * ttl: The time to live of the updated resource record, in seconds. 1392c65ebfc7SToomas Soome * Most clients should pass 0 to indicate that the system should 1393c65ebfc7SToomas Soome * select a sensible default value. 1394c65ebfc7SToomas Soome * 1395c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an 1396c65ebfc7SToomas Soome * error code indicating the error that occurred. 1397c65ebfc7SToomas Soome */ 1398c65ebfc7SToomas Soome 13993b436d06SToomas Soome DNSSD_EXPORT 1400c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceUpdateRecord 1401c65ebfc7SToomas Soome ( 1402c65ebfc7SToomas Soome DNSServiceRef sdRef, 1403c65ebfc7SToomas Soome DNSRecordRef RecordRef, /* may be NULL */ 1404c65ebfc7SToomas Soome DNSServiceFlags flags, 1405c65ebfc7SToomas Soome uint16_t rdlen, 1406c65ebfc7SToomas Soome const void *rdata, 1407c65ebfc7SToomas Soome uint32_t ttl 1408c65ebfc7SToomas Soome ); 1409c65ebfc7SToomas Soome 1410c65ebfc7SToomas Soome 1411c65ebfc7SToomas Soome /* DNSServiceRemoveRecord 1412c65ebfc7SToomas Soome * 1413c65ebfc7SToomas Soome * Remove a record previously added to a service record set via DNSServiceAddRecord(), or deregister 1414c65ebfc7SToomas Soome * a record registered individually via DNSServiceRegisterRecord(). 1415c65ebfc7SToomas Soome * 1416c65ebfc7SToomas Soome * Parameters: 1417c65ebfc7SToomas Soome * 1418c65ebfc7SToomas Soome * sdRef: A DNSServiceRef initialized by DNSServiceRegister() (if the 1419c65ebfc7SToomas Soome * record being removed was registered via DNSServiceAddRecord()) or by 1420c65ebfc7SToomas Soome * DNSServiceCreateConnection() (if the record being removed was registered via 1421c65ebfc7SToomas Soome * DNSServiceRegisterRecord()). 1422c65ebfc7SToomas Soome * 1423c65ebfc7SToomas Soome * recordRef: A DNSRecordRef initialized by a successful call to DNSServiceAddRecord() 1424c65ebfc7SToomas Soome * or DNSServiceRegisterRecord(). 1425c65ebfc7SToomas Soome * 1426c65ebfc7SToomas Soome * flags: Currently ignored, reserved for future use. 1427c65ebfc7SToomas Soome * 1428c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an 1429c65ebfc7SToomas Soome * error code indicating the error that occurred. 1430c65ebfc7SToomas Soome */ 1431c65ebfc7SToomas Soome 14323b436d06SToomas Soome DNSSD_EXPORT 1433c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceRemoveRecord 1434c65ebfc7SToomas Soome ( 1435c65ebfc7SToomas Soome DNSServiceRef sdRef, 1436c65ebfc7SToomas Soome DNSRecordRef RecordRef, 1437c65ebfc7SToomas Soome DNSServiceFlags flags 1438c65ebfc7SToomas Soome ); 1439c65ebfc7SToomas Soome 1440c65ebfc7SToomas Soome 1441c65ebfc7SToomas Soome /********************************************************************************************* 1442c65ebfc7SToomas Soome * 1443c65ebfc7SToomas Soome * Service Discovery 1444c65ebfc7SToomas Soome * 1445c65ebfc7SToomas Soome *********************************************************************************************/ 1446c65ebfc7SToomas Soome 1447c65ebfc7SToomas Soome /* Browse for instances of a service. 1448c65ebfc7SToomas Soome * 1449c65ebfc7SToomas Soome * DNSServiceBrowseReply() Parameters: 1450c65ebfc7SToomas Soome * 1451c65ebfc7SToomas Soome * sdRef: The DNSServiceRef initialized by DNSServiceBrowse(). 1452c65ebfc7SToomas Soome * 1453c65ebfc7SToomas Soome * flags: Possible values are kDNSServiceFlagsMoreComing and kDNSServiceFlagsAdd. 1454c65ebfc7SToomas Soome * See flag definitions for details. 1455c65ebfc7SToomas Soome * 1456c65ebfc7SToomas Soome * interfaceIndex: The interface on which the service is advertised. This index should 1457c65ebfc7SToomas Soome * be passed to DNSServiceResolve() when resolving the service. 1458c65ebfc7SToomas Soome * 1459c65ebfc7SToomas Soome * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise will 1460c65ebfc7SToomas Soome * indicate the failure that occurred. Other parameters are undefined if 1461c65ebfc7SToomas Soome * the errorCode is nonzero. 1462c65ebfc7SToomas Soome * 1463c65ebfc7SToomas Soome * serviceName: The discovered service name. This name should be displayed to the user, 1464c65ebfc7SToomas Soome * and stored for subsequent use in the DNSServiceResolve() call. 1465c65ebfc7SToomas Soome * 1466c65ebfc7SToomas Soome * regtype: The service type, which is usually (but not always) the same as was passed 1467c65ebfc7SToomas Soome * to DNSServiceBrowse(). One case where the discovered service type may 1468c65ebfc7SToomas Soome * not be the same as the requested service type is when using subtypes: 1469c65ebfc7SToomas Soome * The client may want to browse for only those ftp servers that allow 1470c65ebfc7SToomas Soome * anonymous connections. The client will pass the string "_ftp._tcp,_anon" 1471c65ebfc7SToomas Soome * to DNSServiceBrowse(), but the type of the service that's discovered 1472c65ebfc7SToomas Soome * is simply "_ftp._tcp". The regtype for each discovered service instance 1473c65ebfc7SToomas Soome * should be stored along with the name, so that it can be passed to 1474c65ebfc7SToomas Soome * DNSServiceResolve() when the service is later resolved. 1475c65ebfc7SToomas Soome * 1476c65ebfc7SToomas Soome * domain: The domain of the discovered service instance. This may or may not be the 1477c65ebfc7SToomas Soome * same as the domain that was passed to DNSServiceBrowse(). The domain for each 1478c65ebfc7SToomas Soome * discovered service instance should be stored along with the name, so that 1479c65ebfc7SToomas Soome * it can be passed to DNSServiceResolve() when the service is later resolved. 1480c65ebfc7SToomas Soome * 1481c65ebfc7SToomas Soome * context: The context pointer that was passed to the callout. 1482c65ebfc7SToomas Soome * 1483c65ebfc7SToomas Soome */ 1484c65ebfc7SToomas Soome 1485c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceBrowseReply) 1486c65ebfc7SToomas Soome ( 1487c65ebfc7SToomas Soome DNSServiceRef sdRef, 1488c65ebfc7SToomas Soome DNSServiceFlags flags, 1489c65ebfc7SToomas Soome uint32_t interfaceIndex, 1490c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 1491c65ebfc7SToomas Soome const char *serviceName, 1492c65ebfc7SToomas Soome const char *regtype, 1493c65ebfc7SToomas Soome const char *replyDomain, 1494c65ebfc7SToomas Soome void *context 1495c65ebfc7SToomas Soome ); 1496c65ebfc7SToomas Soome 1497c65ebfc7SToomas Soome 1498c65ebfc7SToomas Soome /* DNSServiceBrowse() Parameters: 1499c65ebfc7SToomas Soome * 1500*472cd20dSToomas Soome * sdRef: A pointer to an uninitialized DNSServiceRef 1501*472cd20dSToomas Soome * (or, if the kDNSServiceFlagsShareConnection flag is used, 1502*472cd20dSToomas Soome * a copy of the shared connection reference that is to be used). 1503*472cd20dSToomas Soome * If the call succeeds then it initializes (or updates) the DNSServiceRef, 1504*472cd20dSToomas Soome * returns kDNSServiceErr_NoError, and the browse operation 1505*472cd20dSToomas Soome * will remain active indefinitely until the client terminates it 1506*472cd20dSToomas Soome * by passing this DNSServiceRef to DNSServiceRefDeallocate() 1507*472cd20dSToomas Soome * (or by closing the underlying shared connection, if used). 1508c65ebfc7SToomas Soome * 1509*472cd20dSToomas Soome * flags: Possible values are: 1510*472cd20dSToomas Soome * kDNSServiceFlagsShareConnection to use a shared connection. 1511c65ebfc7SToomas Soome * 1512c65ebfc7SToomas Soome * interfaceIndex: If non-zero, specifies the interface on which to browse for services 1513c65ebfc7SToomas Soome * (the index for a given interface is determined via the if_nametoindex() 1514c65ebfc7SToomas Soome * family of calls.) Most applications will pass 0 to browse on all available 1515c65ebfc7SToomas Soome * interfaces. See "Constants for specifying an interface index" for more details. 1516c65ebfc7SToomas Soome * 1517c65ebfc7SToomas Soome * regtype: The service type being browsed for followed by the protocol, separated by a 1518c65ebfc7SToomas Soome * dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp". 1519c65ebfc7SToomas Soome * A client may optionally specify a single subtype to perform filtered browsing: 1520c65ebfc7SToomas Soome * e.g. browsing for "_primarytype._tcp,_subtype" will discover only those 1521c65ebfc7SToomas Soome * instances of "_primarytype._tcp" that were registered specifying "_subtype" 1522*472cd20dSToomas Soome * in their list of registered subtypes. 1523c65ebfc7SToomas Soome * 1524c65ebfc7SToomas Soome * domain: If non-NULL, specifies the domain on which to browse for services. 1525c65ebfc7SToomas Soome * Most applications will not specify a domain, instead browsing on the 1526c65ebfc7SToomas Soome * default domain(s). 1527c65ebfc7SToomas Soome * 1528c65ebfc7SToomas Soome * callBack: The function to be called when an instance of the service being browsed for 1529c65ebfc7SToomas Soome * is found, or if the call asynchronously fails. 1530c65ebfc7SToomas Soome * 1531c65ebfc7SToomas Soome * context: An application context pointer which is passed to the callback function 1532c65ebfc7SToomas Soome * (may be NULL). 1533c65ebfc7SToomas Soome * 1534c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 1535c65ebfc7SToomas Soome * errors are delivered to the callback), otherwise returns an error code indicating 1536c65ebfc7SToomas Soome * the error that occurred (the callback is not invoked and the DNSServiceRef 1537c65ebfc7SToomas Soome * is not initialized). 1538c65ebfc7SToomas Soome */ 1539c65ebfc7SToomas Soome 15403b436d06SToomas Soome DNSSD_EXPORT 1541c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceBrowse 1542c65ebfc7SToomas Soome ( 1543c65ebfc7SToomas Soome DNSServiceRef *sdRef, 1544c65ebfc7SToomas Soome DNSServiceFlags flags, 1545c65ebfc7SToomas Soome uint32_t interfaceIndex, 1546c65ebfc7SToomas Soome const char *regtype, 1547c65ebfc7SToomas Soome const char *domain, /* may be NULL */ 1548c65ebfc7SToomas Soome DNSServiceBrowseReply callBack, 1549c65ebfc7SToomas Soome void *context /* may be NULL */ 1550c65ebfc7SToomas Soome ); 1551c65ebfc7SToomas Soome 1552c65ebfc7SToomas Soome 1553c65ebfc7SToomas Soome /* DNSServiceResolve() 1554c65ebfc7SToomas Soome * 1555c65ebfc7SToomas Soome * Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and 1556c65ebfc7SToomas Soome * txt record. 1557c65ebfc7SToomas Soome * 1558c65ebfc7SToomas Soome * Note: Applications should NOT use DNSServiceResolve() solely for txt record monitoring - use 1559c65ebfc7SToomas Soome * DNSServiceQueryRecord() instead, as it is more efficient for this task. 1560c65ebfc7SToomas Soome * 1561c65ebfc7SToomas Soome * Note: When the desired results have been returned, the client MUST terminate the resolve by calling 1562c65ebfc7SToomas Soome * DNSServiceRefDeallocate(). 1563c65ebfc7SToomas Soome * 1564c65ebfc7SToomas Soome * Note: DNSServiceResolve() behaves correctly for typical services that have a single SRV record 1565c65ebfc7SToomas Soome * and a single TXT record. To resolve non-standard services with multiple SRV or TXT records, 1566c65ebfc7SToomas Soome * DNSServiceQueryRecord() should be used. 1567c65ebfc7SToomas Soome * 1568c65ebfc7SToomas Soome * DNSServiceResolveReply Callback Parameters: 1569c65ebfc7SToomas Soome * 1570c65ebfc7SToomas Soome * sdRef: The DNSServiceRef initialized by DNSServiceResolve(). 1571c65ebfc7SToomas Soome * 1572c65ebfc7SToomas Soome * flags: Possible values: kDNSServiceFlagsMoreComing 1573c65ebfc7SToomas Soome * 1574c65ebfc7SToomas Soome * interfaceIndex: The interface on which the service was resolved. 1575c65ebfc7SToomas Soome * 1576c65ebfc7SToomas Soome * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise will 1577c65ebfc7SToomas Soome * indicate the failure that occurred. Other parameters are undefined if 1578c65ebfc7SToomas Soome * the errorCode is nonzero. 1579c65ebfc7SToomas Soome * 1580c65ebfc7SToomas Soome * fullname: The full service domain name, in the form <servicename>.<protocol>.<domain>. 1581c65ebfc7SToomas Soome * (This name is escaped following standard DNS rules, making it suitable for 1582c65ebfc7SToomas Soome * passing to standard system DNS APIs such as res_query(), or to the 1583c65ebfc7SToomas Soome * special-purpose functions included in this API that take fullname parameters. 1584c65ebfc7SToomas Soome * See "Notes on DNS Name Escaping" earlier in this file for more details.) 1585c65ebfc7SToomas Soome * 1586c65ebfc7SToomas Soome * hosttarget: The target hostname of the machine providing the service. This name can 1587c65ebfc7SToomas Soome * be passed to functions like gethostbyname() to identify the host's IP address. 1588c65ebfc7SToomas Soome * 1589c65ebfc7SToomas Soome * port: The port, in network byte order, on which connections are accepted for this service. 1590c65ebfc7SToomas Soome * 1591c65ebfc7SToomas Soome * txtLen: The length of the txt record, in bytes. 1592c65ebfc7SToomas Soome * 1593c65ebfc7SToomas Soome * txtRecord: The service's primary txt record, in standard txt record format. 1594c65ebfc7SToomas Soome * 1595c65ebfc7SToomas Soome * context: The context pointer that was passed to the callout. 1596c65ebfc7SToomas Soome * 1597c65ebfc7SToomas Soome * NOTE: In earlier versions of this header file, the txtRecord parameter was declared "const char *" 1598c65ebfc7SToomas Soome * This is incorrect, since it contains length bytes which are values in the range 0 to 255, not -128 to +127. 1599c65ebfc7SToomas Soome * Depending on your compiler settings, this change may cause signed/unsigned mismatch warnings. 1600c65ebfc7SToomas Soome * These should be fixed by updating your own callback function definition to match the corrected 1601c65ebfc7SToomas Soome * function signature using "const unsigned char *txtRecord". Making this change may also fix inadvertent 1602c65ebfc7SToomas Soome * bugs in your callback function, where it could have incorrectly interpreted a length byte with value 250 1603c65ebfc7SToomas Soome * as being -6 instead, with various bad consequences ranging from incorrect operation to software crashes. 1604c65ebfc7SToomas Soome * If you need to maintain portable code that will compile cleanly with both the old and new versions of 1605c65ebfc7SToomas Soome * this header file, you should update your callback function definition to use the correct unsigned value, 1606c65ebfc7SToomas Soome * and then in the place where you pass your callback function to DNSServiceResolve(), use a cast to eliminate 1607c65ebfc7SToomas Soome * the compiler warning, e.g.: 1608c65ebfc7SToomas Soome * DNSServiceResolve(sd, flags, index, name, regtype, domain, (DNSServiceResolveReply)MyCallback, context); 1609c65ebfc7SToomas Soome * This will ensure that your code compiles cleanly without warnings (and more importantly, works correctly) 1610c65ebfc7SToomas Soome * with both the old header and with the new corrected version. 1611c65ebfc7SToomas Soome * 1612c65ebfc7SToomas Soome */ 1613c65ebfc7SToomas Soome 1614c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceResolveReply) 1615c65ebfc7SToomas Soome ( 1616c65ebfc7SToomas Soome DNSServiceRef sdRef, 1617c65ebfc7SToomas Soome DNSServiceFlags flags, 1618c65ebfc7SToomas Soome uint32_t interfaceIndex, 1619c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 1620c65ebfc7SToomas Soome const char *fullname, 1621c65ebfc7SToomas Soome const char *hosttarget, 1622c65ebfc7SToomas Soome uint16_t port, /* In network byte order */ 1623c65ebfc7SToomas Soome uint16_t txtLen, 1624c65ebfc7SToomas Soome const unsigned char *txtRecord, 1625c65ebfc7SToomas Soome void *context 1626c65ebfc7SToomas Soome ); 1627c65ebfc7SToomas Soome 1628c65ebfc7SToomas Soome 1629c65ebfc7SToomas Soome /* DNSServiceResolve() Parameters 1630c65ebfc7SToomas Soome * 1631*472cd20dSToomas Soome * sdRef: A pointer to an uninitialized DNSServiceRef 1632*472cd20dSToomas Soome * (or, if the kDNSServiceFlagsShareConnection flag is used, 1633*472cd20dSToomas Soome * a copy of the shared connection reference that is to be used). 1634*472cd20dSToomas Soome * If the call succeeds then it initializes (or updates) the DNSServiceRef, 1635*472cd20dSToomas Soome * returns kDNSServiceErr_NoError, and the resolve operation 1636*472cd20dSToomas Soome * will remain active indefinitely until the client terminates it 1637*472cd20dSToomas Soome * by passing this DNSServiceRef to DNSServiceRefDeallocate() 1638*472cd20dSToomas Soome * (or by closing the underlying shared connection, if used). 1639c65ebfc7SToomas Soome * 1640*472cd20dSToomas Soome * flags: Possible values are: 1641*472cd20dSToomas Soome * kDNSServiceFlagsShareConnection to use a shared connection. 1642*472cd20dSToomas Soome * Specifying kDNSServiceFlagsForceMulticast will cause query to be 1643c65ebfc7SToomas Soome * performed with a link-local mDNS query, even if the name is an 1644c65ebfc7SToomas Soome * apparently non-local name (i.e. a name not ending in ".local.") 1645c65ebfc7SToomas Soome * 1646c65ebfc7SToomas Soome * interfaceIndex: The interface on which to resolve the service. If this resolve call is 1647c65ebfc7SToomas Soome * as a result of a currently active DNSServiceBrowse() operation, then the 1648c65ebfc7SToomas Soome * interfaceIndex should be the index reported in the DNSServiceBrowseReply 1649c65ebfc7SToomas Soome * callback. If this resolve call is using information previously saved 1650c65ebfc7SToomas Soome * (e.g. in a preference file) for later use, then use interfaceIndex 0, because 1651c65ebfc7SToomas Soome * the desired service may now be reachable via a different physical interface. 1652c65ebfc7SToomas Soome * See "Constants for specifying an interface index" for more details. 1653c65ebfc7SToomas Soome * 1654c65ebfc7SToomas Soome * name: The name of the service instance to be resolved, as reported to the 1655c65ebfc7SToomas Soome * DNSServiceBrowseReply() callback. 1656c65ebfc7SToomas Soome * 1657c65ebfc7SToomas Soome * regtype: The type of the service instance to be resolved, as reported to the 1658c65ebfc7SToomas Soome * DNSServiceBrowseReply() callback. 1659c65ebfc7SToomas Soome * 1660c65ebfc7SToomas Soome * domain: The domain of the service instance to be resolved, as reported to the 1661c65ebfc7SToomas Soome * DNSServiceBrowseReply() callback. 1662c65ebfc7SToomas Soome * 1663c65ebfc7SToomas Soome * callBack: The function to be called when a result is found, or if the call 1664c65ebfc7SToomas Soome * asynchronously fails. 1665c65ebfc7SToomas Soome * 1666c65ebfc7SToomas Soome * context: An application context pointer which is passed to the callback function 1667c65ebfc7SToomas Soome * (may be NULL). 1668c65ebfc7SToomas Soome * 1669c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 1670c65ebfc7SToomas Soome * errors are delivered to the callback), otherwise returns an error code indicating 1671c65ebfc7SToomas Soome * the error that occurred (the callback is never invoked and the DNSServiceRef 1672c65ebfc7SToomas Soome * is not initialized). 1673c65ebfc7SToomas Soome */ 1674c65ebfc7SToomas Soome 16753b436d06SToomas Soome DNSSD_EXPORT 1676c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceResolve 1677c65ebfc7SToomas Soome ( 1678c65ebfc7SToomas Soome DNSServiceRef *sdRef, 1679c65ebfc7SToomas Soome DNSServiceFlags flags, 1680c65ebfc7SToomas Soome uint32_t interfaceIndex, 1681c65ebfc7SToomas Soome const char *name, 1682c65ebfc7SToomas Soome const char *regtype, 1683c65ebfc7SToomas Soome const char *domain, 1684c65ebfc7SToomas Soome DNSServiceResolveReply callBack, 1685c65ebfc7SToomas Soome void *context /* may be NULL */ 1686c65ebfc7SToomas Soome ); 1687c65ebfc7SToomas Soome 1688c65ebfc7SToomas Soome 1689c65ebfc7SToomas Soome /********************************************************************************************* 1690c65ebfc7SToomas Soome * 1691c65ebfc7SToomas Soome * Querying Individual Specific Records 1692c65ebfc7SToomas Soome * 1693c65ebfc7SToomas Soome *********************************************************************************************/ 1694c65ebfc7SToomas Soome 1695c65ebfc7SToomas Soome /* DNSServiceQueryRecord 1696c65ebfc7SToomas Soome * 1697c65ebfc7SToomas Soome * Query for an arbitrary DNS record. 1698c65ebfc7SToomas Soome * 1699c65ebfc7SToomas Soome * DNSServiceQueryRecordReply() Callback Parameters: 1700c65ebfc7SToomas Soome * 1701c65ebfc7SToomas Soome * sdRef: The DNSServiceRef initialized by DNSServiceQueryRecord(). 1702c65ebfc7SToomas Soome * 1703c65ebfc7SToomas Soome * flags: Possible values are kDNSServiceFlagsMoreComing and 1704c65ebfc7SToomas Soome * kDNSServiceFlagsAdd. The Add flag is NOT set for PTR records 1705c65ebfc7SToomas Soome * with a ttl of 0, i.e. "Remove" events. 1706c65ebfc7SToomas Soome * 1707c65ebfc7SToomas Soome * interfaceIndex: The interface on which the query was resolved (the index for a given 1708c65ebfc7SToomas Soome * interface is determined via the if_nametoindex() family of calls). 1709c65ebfc7SToomas Soome * See "Constants for specifying an interface index" for more details. 1710c65ebfc7SToomas Soome * 1711c65ebfc7SToomas Soome * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will 1712c65ebfc7SToomas Soome * indicate the failure that occurred. Other parameters are undefined if 1713c65ebfc7SToomas Soome * errorCode is nonzero. 1714c65ebfc7SToomas Soome * 1715c65ebfc7SToomas Soome * fullname: The resource record's full domain name. 1716c65ebfc7SToomas Soome * 1717c65ebfc7SToomas Soome * rrtype: The resource record's type (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc) 1718c65ebfc7SToomas Soome * 1719c65ebfc7SToomas Soome * rrclass: The class of the resource record (usually kDNSServiceClass_IN). 1720c65ebfc7SToomas Soome * 1721c65ebfc7SToomas Soome * rdlen: The length, in bytes, of the resource record rdata. 1722c65ebfc7SToomas Soome * 1723c65ebfc7SToomas Soome * rdata: The raw rdata of the resource record. 1724c65ebfc7SToomas Soome * 1725c65ebfc7SToomas Soome * ttl: If the client wishes to cache the result for performance reasons, 1726c65ebfc7SToomas Soome * the TTL indicates how long the client may legitimately hold onto 1727c65ebfc7SToomas Soome * this result, in seconds. After the TTL expires, the client should 1728c65ebfc7SToomas Soome * consider the result no longer valid, and if it requires this data 1729c65ebfc7SToomas Soome * again, it should be re-fetched with a new query. Of course, this 1730c65ebfc7SToomas Soome * only applies to clients that cancel the asynchronous operation when 1731c65ebfc7SToomas Soome * they get a result. Clients that leave the asynchronous operation 1732c65ebfc7SToomas Soome * running can safely assume that the data remains valid until they 1733c65ebfc7SToomas Soome * get another callback telling them otherwise. The ttl value is not 1734c65ebfc7SToomas Soome * updated when the daemon answers from the cache, hence relying on 1735c65ebfc7SToomas Soome * the accuracy of the ttl value is not recommended. 1736c65ebfc7SToomas Soome * 1737c65ebfc7SToomas Soome * context: The context pointer that was passed to the callout. 1738c65ebfc7SToomas Soome * 1739c65ebfc7SToomas Soome */ 1740c65ebfc7SToomas Soome 1741c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceQueryRecordReply) 1742c65ebfc7SToomas Soome ( 1743c65ebfc7SToomas Soome DNSServiceRef sdRef, 1744c65ebfc7SToomas Soome DNSServiceFlags flags, 1745c65ebfc7SToomas Soome uint32_t interfaceIndex, 1746c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 1747c65ebfc7SToomas Soome const char *fullname, 1748c65ebfc7SToomas Soome uint16_t rrtype, 1749c65ebfc7SToomas Soome uint16_t rrclass, 1750c65ebfc7SToomas Soome uint16_t rdlen, 1751c65ebfc7SToomas Soome const void *rdata, 1752c65ebfc7SToomas Soome uint32_t ttl, 1753c65ebfc7SToomas Soome void *context 1754c65ebfc7SToomas Soome ); 1755c65ebfc7SToomas Soome 1756c65ebfc7SToomas Soome 1757c65ebfc7SToomas Soome /* DNSServiceQueryRecord() Parameters: 1758c65ebfc7SToomas Soome * 1759*472cd20dSToomas Soome * sdRef: A pointer to an uninitialized DNSServiceRef 1760*472cd20dSToomas Soome * (or, if the kDNSServiceFlagsShareConnection flag is used, 1761*472cd20dSToomas Soome * a copy of the shared connection reference that is to be used). 1762*472cd20dSToomas Soome * If the call succeeds then it initializes (or updates) the DNSServiceRef, 1763*472cd20dSToomas Soome * returns kDNSServiceErr_NoError, and the query operation 1764*472cd20dSToomas Soome * will remain active indefinitely until the client terminates it 1765*472cd20dSToomas Soome * by passing this DNSServiceRef to DNSServiceRefDeallocate() 1766*472cd20dSToomas Soome * (or by closing the underlying shared connection, if used). 1767c65ebfc7SToomas Soome * 1768*472cd20dSToomas Soome * flags: Possible values are: 1769*472cd20dSToomas Soome * kDNSServiceFlagsShareConnection to use a shared connection. 1770*472cd20dSToomas Soome * kDNSServiceFlagsForceMulticast or kDNSServiceFlagsLongLivedQuery. 1771c65ebfc7SToomas Soome * Pass kDNSServiceFlagsLongLivedQuery to create a "long-lived" unicast 1772c65ebfc7SToomas Soome * query to a unicast DNS server that implements the protocol. This flag 1773c65ebfc7SToomas Soome * has no effect on link-local multicast queries. 1774c65ebfc7SToomas Soome * 1775c65ebfc7SToomas Soome * interfaceIndex: If non-zero, specifies the interface on which to issue the query 1776c65ebfc7SToomas Soome * (the index for a given interface is determined via the if_nametoindex() 1777c65ebfc7SToomas Soome * family of calls.) Passing 0 causes the name to be queried for on all 1778c65ebfc7SToomas Soome * interfaces. See "Constants for specifying an interface index" for more details. 1779c65ebfc7SToomas Soome * 1780c65ebfc7SToomas Soome * fullname: The full domain name of the resource record to be queried for. 1781c65ebfc7SToomas Soome * 1782c65ebfc7SToomas Soome * rrtype: The numerical type of the resource record to be queried for 1783c65ebfc7SToomas Soome * (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc) 1784c65ebfc7SToomas Soome * 1785c65ebfc7SToomas Soome * rrclass: The class of the resource record (usually kDNSServiceClass_IN). 1786c65ebfc7SToomas Soome * 1787c65ebfc7SToomas Soome * callBack: The function to be called when a result is found, or if the call 1788c65ebfc7SToomas Soome * asynchronously fails. 1789c65ebfc7SToomas Soome * 1790c65ebfc7SToomas Soome * context: An application context pointer which is passed to the callback function 1791c65ebfc7SToomas Soome * (may be NULL). 1792c65ebfc7SToomas Soome * 1793c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 1794c65ebfc7SToomas Soome * errors are delivered to the callback), otherwise returns an error code indicating 1795c65ebfc7SToomas Soome * the error that occurred (the callback is never invoked and the DNSServiceRef 1796c65ebfc7SToomas Soome * is not initialized). 1797c65ebfc7SToomas Soome */ 1798c65ebfc7SToomas Soome 17993b436d06SToomas Soome DNSSD_EXPORT 1800c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceQueryRecord 1801c65ebfc7SToomas Soome ( 1802c65ebfc7SToomas Soome DNSServiceRef *sdRef, 1803c65ebfc7SToomas Soome DNSServiceFlags flags, 1804c65ebfc7SToomas Soome uint32_t interfaceIndex, 1805c65ebfc7SToomas Soome const char *fullname, 1806c65ebfc7SToomas Soome uint16_t rrtype, 1807c65ebfc7SToomas Soome uint16_t rrclass, 1808c65ebfc7SToomas Soome DNSServiceQueryRecordReply callBack, 1809c65ebfc7SToomas Soome void *context /* may be NULL */ 1810c65ebfc7SToomas Soome ); 1811c65ebfc7SToomas Soome 1812c65ebfc7SToomas Soome 1813c65ebfc7SToomas Soome /********************************************************************************************* 1814c65ebfc7SToomas Soome * 1815c65ebfc7SToomas Soome * Unified lookup of both IPv4 and IPv6 addresses for a fully qualified hostname 1816c65ebfc7SToomas Soome * 1817c65ebfc7SToomas Soome *********************************************************************************************/ 1818c65ebfc7SToomas Soome 1819c65ebfc7SToomas Soome /* DNSServiceGetAddrInfo 1820c65ebfc7SToomas Soome * 1821c65ebfc7SToomas Soome * Queries for the IP address of a hostname by using either Multicast or Unicast DNS. 1822c65ebfc7SToomas Soome * 1823c65ebfc7SToomas Soome * DNSServiceGetAddrInfoReply() parameters: 1824c65ebfc7SToomas Soome * 1825c65ebfc7SToomas Soome * sdRef: The DNSServiceRef initialized by DNSServiceGetAddrInfo(). 1826c65ebfc7SToomas Soome * 1827c65ebfc7SToomas Soome * flags: Possible values are kDNSServiceFlagsMoreComing and 1828c65ebfc7SToomas Soome * kDNSServiceFlagsAdd. 1829c65ebfc7SToomas Soome * 1830c65ebfc7SToomas Soome * interfaceIndex: The interface to which the answers pertain. 1831c65ebfc7SToomas Soome * 1832c65ebfc7SToomas Soome * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will 1833c65ebfc7SToomas Soome * indicate the failure that occurred. Other parameters are 1834c65ebfc7SToomas Soome * undefined if errorCode is nonzero. 1835c65ebfc7SToomas Soome * 1836c65ebfc7SToomas Soome * hostname: The fully qualified domain name of the host to be queried for. 1837c65ebfc7SToomas Soome * 1838c65ebfc7SToomas Soome * address: IPv4 or IPv6 address. 1839c65ebfc7SToomas Soome * 1840c65ebfc7SToomas Soome * ttl: If the client wishes to cache the result for performance reasons, 1841c65ebfc7SToomas Soome * the TTL indicates how long the client may legitimately hold onto 1842c65ebfc7SToomas Soome * this result, in seconds. After the TTL expires, the client should 1843c65ebfc7SToomas Soome * consider the result no longer valid, and if it requires this data 1844c65ebfc7SToomas Soome * again, it should be re-fetched with a new query. Of course, this 1845c65ebfc7SToomas Soome * only applies to clients that cancel the asynchronous operation when 1846c65ebfc7SToomas Soome * they get a result. Clients that leave the asynchronous operation 1847c65ebfc7SToomas Soome * running can safely assume that the data remains valid until they 1848c65ebfc7SToomas Soome * get another callback telling them otherwise. The ttl value is not 1849c65ebfc7SToomas Soome * updated when the daemon answers from the cache, hence relying on 1850c65ebfc7SToomas Soome * the accuracy of the ttl value is not recommended. 1851c65ebfc7SToomas Soome * 1852c65ebfc7SToomas Soome * context: The context pointer that was passed to the callout. 1853c65ebfc7SToomas Soome * 1854c65ebfc7SToomas Soome */ 1855c65ebfc7SToomas Soome 1856c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceGetAddrInfoReply) 1857c65ebfc7SToomas Soome ( 1858c65ebfc7SToomas Soome DNSServiceRef sdRef, 1859c65ebfc7SToomas Soome DNSServiceFlags flags, 1860c65ebfc7SToomas Soome uint32_t interfaceIndex, 1861c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 1862c65ebfc7SToomas Soome const char *hostname, 1863c65ebfc7SToomas Soome const struct sockaddr *address, 1864c65ebfc7SToomas Soome uint32_t ttl, 1865c65ebfc7SToomas Soome void *context 1866c65ebfc7SToomas Soome ); 1867c65ebfc7SToomas Soome 1868c65ebfc7SToomas Soome 1869c65ebfc7SToomas Soome /* DNSServiceGetAddrInfo() Parameters: 1870c65ebfc7SToomas Soome * 1871*472cd20dSToomas Soome * sdRef: A pointer to an uninitialized DNSServiceRef 1872*472cd20dSToomas Soome * (or, if the kDNSServiceFlagsShareConnection flag is used, 1873*472cd20dSToomas Soome * a copy of the shared connection reference that is to be used). 1874*472cd20dSToomas Soome * If the call succeeds then it initializes (or updates) the DNSServiceRef, 1875*472cd20dSToomas Soome * returns kDNSServiceErr_NoError, and the address query operation 1876*472cd20dSToomas Soome * will remain active indefinitely until the client terminates it 1877*472cd20dSToomas Soome * by passing this DNSServiceRef to DNSServiceRefDeallocate() 1878*472cd20dSToomas Soome * (or by closing the underlying shared connection, if used). 1879c65ebfc7SToomas Soome * 1880*472cd20dSToomas Soome * flags: Possible values are: 1881*472cd20dSToomas Soome * kDNSServiceFlagsShareConnection to use a shared connection. 1882*472cd20dSToomas Soome * kDNSServiceFlagsForceMulticast 1883c65ebfc7SToomas Soome * 1884c65ebfc7SToomas Soome * interfaceIndex: The interface on which to issue the query. Passing 0 causes the query to be 1885c65ebfc7SToomas Soome * sent on all active interfaces via Multicast or the primary interface via Unicast. 1886c65ebfc7SToomas Soome * 1887c65ebfc7SToomas Soome * protocol: Pass in kDNSServiceProtocol_IPv4 to look up IPv4 addresses, or kDNSServiceProtocol_IPv6 1888c65ebfc7SToomas Soome * to look up IPv6 addresses, or both to look up both kinds. If neither flag is 1889c65ebfc7SToomas Soome * set, the system will apply an intelligent heuristic, which is (currently) 1890c65ebfc7SToomas Soome * that it will attempt to look up both, except: 1891c65ebfc7SToomas Soome * 1892c65ebfc7SToomas Soome * * If "hostname" is a wide-area unicast DNS hostname (i.e. not a ".local." name) 1893c65ebfc7SToomas Soome * but this host has no routable IPv6 address, then the call will not try to 1894c65ebfc7SToomas Soome * look up IPv6 addresses for "hostname", since any addresses it found would be 1895c65ebfc7SToomas Soome * unlikely to be of any use anyway. Similarly, if this host has no routable 1896c65ebfc7SToomas Soome * IPv4 address, the call will not try to look up IPv4 addresses for "hostname". 1897c65ebfc7SToomas Soome * 1898c65ebfc7SToomas Soome * hostname: The fully qualified domain name of the host to be queried for. 1899c65ebfc7SToomas Soome * 1900c65ebfc7SToomas Soome * callBack: The function to be called when the query succeeds or fails asynchronously. 1901c65ebfc7SToomas Soome * 1902c65ebfc7SToomas Soome * context: An application context pointer which is passed to the callback function 1903c65ebfc7SToomas Soome * (may be NULL). 1904c65ebfc7SToomas Soome * 1905c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 1906c65ebfc7SToomas Soome * errors are delivered to the callback), otherwise returns an error code indicating 1907c65ebfc7SToomas Soome * the error that occurred. 1908c65ebfc7SToomas Soome */ 1909c65ebfc7SToomas Soome 19103b436d06SToomas Soome DNSSD_EXPORT 1911c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceGetAddrInfo 1912c65ebfc7SToomas Soome ( 1913c65ebfc7SToomas Soome DNSServiceRef *sdRef, 1914c65ebfc7SToomas Soome DNSServiceFlags flags, 1915c65ebfc7SToomas Soome uint32_t interfaceIndex, 1916c65ebfc7SToomas Soome DNSServiceProtocol protocol, 1917c65ebfc7SToomas Soome const char *hostname, 1918c65ebfc7SToomas Soome DNSServiceGetAddrInfoReply callBack, 1919c65ebfc7SToomas Soome void *context /* may be NULL */ 1920c65ebfc7SToomas Soome ); 1921c65ebfc7SToomas Soome 1922c65ebfc7SToomas Soome 1923c65ebfc7SToomas Soome /********************************************************************************************* 1924c65ebfc7SToomas Soome * 1925c65ebfc7SToomas Soome * Special Purpose Calls: 1926c65ebfc7SToomas Soome * DNSServiceCreateConnection(), DNSServiceRegisterRecord(), DNSServiceReconfirmRecord() 1927c65ebfc7SToomas Soome * (most applications will not use these) 1928c65ebfc7SToomas Soome * 1929c65ebfc7SToomas Soome *********************************************************************************************/ 1930c65ebfc7SToomas Soome 1931c65ebfc7SToomas Soome /* DNSServiceCreateConnection() 1932c65ebfc7SToomas Soome * 1933c65ebfc7SToomas Soome * Create a connection to the daemon allowing efficient registration of 1934c65ebfc7SToomas Soome * multiple individual records. 1935c65ebfc7SToomas Soome * 1936c65ebfc7SToomas Soome * Parameters: 1937c65ebfc7SToomas Soome * 1938*472cd20dSToomas Soome * sdRef: A pointer to an uninitialized DNSServiceRef. 1939*472cd20dSToomas Soome * Deallocating the reference (via DNSServiceRefDeallocate()) 1940*472cd20dSToomas Soome * severs the connection and cancels all operations and 1941*472cd20dSToomas Soome * deregisters all records registered on this connection. 1942c65ebfc7SToomas Soome * 1943c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success, otherwise returns 1944*472cd20dSToomas Soome * an error code indicating the specific failure that occurred 1945*472cd20dSToomas Soome * (in which case the DNSServiceRef is not initialized). 1946c65ebfc7SToomas Soome */ 1947c65ebfc7SToomas Soome 19483b436d06SToomas Soome DNSSD_EXPORT 1949c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceCreateConnection(DNSServiceRef *sdRef); 1950c65ebfc7SToomas Soome 1951c65ebfc7SToomas Soome /* DNSServiceRegisterRecord 1952c65ebfc7SToomas Soome * 1953c65ebfc7SToomas Soome * Register an individual resource record on a connected DNSServiceRef. 1954c65ebfc7SToomas Soome * 1955c65ebfc7SToomas Soome * Note that name conflicts occurring for records registered via this call must be handled 1956c65ebfc7SToomas Soome * by the client in the callback. 1957c65ebfc7SToomas Soome * 1958c65ebfc7SToomas Soome * DNSServiceRegisterRecordReply() parameters: 1959c65ebfc7SToomas Soome * 1960c65ebfc7SToomas Soome * sdRef: The connected DNSServiceRef initialized by 1961c65ebfc7SToomas Soome * DNSServiceCreateConnection(). 1962c65ebfc7SToomas Soome * 1963c65ebfc7SToomas Soome * RecordRef: The DNSRecordRef initialized by DNSServiceRegisterRecord(). If the above 1964c65ebfc7SToomas Soome * DNSServiceRef is passed to DNSServiceRefDeallocate(), this DNSRecordRef is 1965c65ebfc7SToomas Soome * invalidated, and may not be used further. 1966c65ebfc7SToomas Soome * 1967c65ebfc7SToomas Soome * flags: Currently unused, reserved for future use. 1968c65ebfc7SToomas Soome * 1969c65ebfc7SToomas Soome * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will 1970c65ebfc7SToomas Soome * indicate the failure that occurred (including name conflicts.) 1971c65ebfc7SToomas Soome * Other parameters are undefined if errorCode is nonzero. 1972c65ebfc7SToomas Soome * 1973c65ebfc7SToomas Soome * context: The context pointer that was passed to the callout. 1974c65ebfc7SToomas Soome * 1975c65ebfc7SToomas Soome */ 1976c65ebfc7SToomas Soome 1977c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceRegisterRecordReply) 1978c65ebfc7SToomas Soome ( 1979c65ebfc7SToomas Soome DNSServiceRef sdRef, 1980c65ebfc7SToomas Soome DNSRecordRef RecordRef, 1981c65ebfc7SToomas Soome DNSServiceFlags flags, 1982c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 1983c65ebfc7SToomas Soome void *context 1984c65ebfc7SToomas Soome ); 1985c65ebfc7SToomas Soome 1986c65ebfc7SToomas Soome 1987c65ebfc7SToomas Soome /* DNSServiceRegisterRecord() Parameters: 1988c65ebfc7SToomas Soome * 1989c65ebfc7SToomas Soome * sdRef: A DNSServiceRef initialized by DNSServiceCreateConnection(). 1990c65ebfc7SToomas Soome * 1991c65ebfc7SToomas Soome * RecordRef: A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this 1992c65ebfc7SToomas Soome * call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord(). 1993c65ebfc7SToomas Soome * (To deregister ALL records registered on a single connected DNSServiceRef 1994c65ebfc7SToomas Soome * and deallocate each of their corresponding DNSServiceRecordRefs, call 1995c65ebfc7SToomas Soome * DNSServiceRefDeallocate()). 1996c65ebfc7SToomas Soome * 1997*472cd20dSToomas Soome * flags: One of either kDNSServiceFlagsShared, kDNSServiceFlagsUnique or kDNSServiceFlagsKnownUnique must be set. 1998c65ebfc7SToomas Soome * 1999c65ebfc7SToomas Soome * interfaceIndex: If non-zero, specifies the interface on which to register the record 2000c65ebfc7SToomas Soome * (the index for a given interface is determined via the if_nametoindex() 2001c65ebfc7SToomas Soome * family of calls.) Passing 0 causes the record to be registered on all interfaces. 2002c65ebfc7SToomas Soome * See "Constants for specifying an interface index" for more details. 2003c65ebfc7SToomas Soome * 2004c65ebfc7SToomas Soome * fullname: The full domain name of the resource record. 2005c65ebfc7SToomas Soome * 2006c65ebfc7SToomas Soome * rrtype: The numerical type of the resource record (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc) 2007c65ebfc7SToomas Soome * 2008c65ebfc7SToomas Soome * rrclass: The class of the resource record (usually kDNSServiceClass_IN) 2009c65ebfc7SToomas Soome * 2010c65ebfc7SToomas Soome * rdlen: Length, in bytes, of the rdata. 2011c65ebfc7SToomas Soome * 2012c65ebfc7SToomas Soome * rdata: A pointer to the raw rdata, as it is to appear in the DNS record. 2013c65ebfc7SToomas Soome * 2014c65ebfc7SToomas Soome * ttl: The time to live of the resource record, in seconds. 2015c65ebfc7SToomas Soome * Most clients should pass 0 to indicate that the system should 2016c65ebfc7SToomas Soome * select a sensible default value. 2017c65ebfc7SToomas Soome * 2018c65ebfc7SToomas Soome * callBack: The function to be called when a result is found, or if the call 2019c65ebfc7SToomas Soome * asynchronously fails (e.g. because of a name conflict.) 2020c65ebfc7SToomas Soome * 2021c65ebfc7SToomas Soome * context: An application context pointer which is passed to the callback function 2022c65ebfc7SToomas Soome * (may be NULL). 2023c65ebfc7SToomas Soome * 2024c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 2025c65ebfc7SToomas Soome * errors are delivered to the callback), otherwise returns an error code indicating 2026c65ebfc7SToomas Soome * the error that occurred (the callback is never invoked and the DNSRecordRef is 2027c65ebfc7SToomas Soome * not initialized). 2028c65ebfc7SToomas Soome */ 2029c65ebfc7SToomas Soome 20303b436d06SToomas Soome DNSSD_EXPORT 2031c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceRegisterRecord 2032c65ebfc7SToomas Soome ( 2033c65ebfc7SToomas Soome DNSServiceRef sdRef, 2034c65ebfc7SToomas Soome DNSRecordRef *RecordRef, 2035c65ebfc7SToomas Soome DNSServiceFlags flags, 2036c65ebfc7SToomas Soome uint32_t interfaceIndex, 2037c65ebfc7SToomas Soome const char *fullname, 2038c65ebfc7SToomas Soome uint16_t rrtype, 2039c65ebfc7SToomas Soome uint16_t rrclass, 2040c65ebfc7SToomas Soome uint16_t rdlen, 2041c65ebfc7SToomas Soome const void *rdata, 2042c65ebfc7SToomas Soome uint32_t ttl, 2043c65ebfc7SToomas Soome DNSServiceRegisterRecordReply callBack, 2044c65ebfc7SToomas Soome void *context /* may be NULL */ 2045c65ebfc7SToomas Soome ); 2046c65ebfc7SToomas Soome 2047c65ebfc7SToomas Soome 2048c65ebfc7SToomas Soome /* DNSServiceReconfirmRecord 2049c65ebfc7SToomas Soome * 2050c65ebfc7SToomas Soome * Instruct the daemon to verify the validity of a resource record that appears 2051c65ebfc7SToomas Soome * to be out of date (e.g. because TCP connection to a service's target failed.) 2052c65ebfc7SToomas Soome * Causes the record to be flushed from the daemon's cache (as well as all other 2053c65ebfc7SToomas Soome * daemons' caches on the network) if the record is determined to be invalid. 2054c65ebfc7SToomas Soome * Use this routine conservatively. Reconfirming a record necessarily consumes 2055c65ebfc7SToomas Soome * network bandwidth, so this should not be done indiscriminately. 2056c65ebfc7SToomas Soome * 2057c65ebfc7SToomas Soome * Parameters: 2058c65ebfc7SToomas Soome * 2059c65ebfc7SToomas Soome * flags: Not currently used. 2060c65ebfc7SToomas Soome * 2061c65ebfc7SToomas Soome * interfaceIndex: Specifies the interface of the record in question. 2062c65ebfc7SToomas Soome * The caller must specify the interface. 2063c65ebfc7SToomas Soome * This API (by design) causes increased network traffic, so it requires 2064c65ebfc7SToomas Soome * the caller to be precise about which record should be reconfirmed. 2065c65ebfc7SToomas Soome * It is not possible to pass zero for the interface index to perform 2066c65ebfc7SToomas Soome * a "wildcard" reconfirmation, where *all* matching records are reconfirmed. 2067c65ebfc7SToomas Soome * 2068c65ebfc7SToomas Soome * fullname: The resource record's full domain name. 2069c65ebfc7SToomas Soome * 2070c65ebfc7SToomas Soome * rrtype: The resource record's type (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc) 2071c65ebfc7SToomas Soome * 2072c65ebfc7SToomas Soome * rrclass: The class of the resource record (usually kDNSServiceClass_IN). 2073c65ebfc7SToomas Soome * 2074c65ebfc7SToomas Soome * rdlen: The length, in bytes, of the resource record rdata. 2075c65ebfc7SToomas Soome * 2076c65ebfc7SToomas Soome * rdata: The raw rdata of the resource record. 2077c65ebfc7SToomas Soome * 2078c65ebfc7SToomas Soome */ 2079c65ebfc7SToomas Soome 20803b436d06SToomas Soome DNSSD_EXPORT 2081c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceReconfirmRecord 2082c65ebfc7SToomas Soome ( 2083c65ebfc7SToomas Soome DNSServiceFlags flags, 2084c65ebfc7SToomas Soome uint32_t interfaceIndex, 2085c65ebfc7SToomas Soome const char *fullname, 2086c65ebfc7SToomas Soome uint16_t rrtype, 2087c65ebfc7SToomas Soome uint16_t rrclass, 2088c65ebfc7SToomas Soome uint16_t rdlen, 2089c65ebfc7SToomas Soome const void *rdata 2090c65ebfc7SToomas Soome ); 2091c65ebfc7SToomas Soome 2092c65ebfc7SToomas Soome 2093c65ebfc7SToomas Soome /********************************************************************************************* 2094c65ebfc7SToomas Soome * 2095c65ebfc7SToomas Soome * NAT Port Mapping 2096c65ebfc7SToomas Soome * 2097c65ebfc7SToomas Soome *********************************************************************************************/ 2098c65ebfc7SToomas Soome 2099c65ebfc7SToomas Soome /* DNSServiceNATPortMappingCreate 2100c65ebfc7SToomas Soome * 2101c65ebfc7SToomas Soome * Request a port mapping in the NAT gateway, which maps a port on the local machine 2102c65ebfc7SToomas Soome * to an external port on the NAT. The NAT should support either PCP, NAT-PMP or the 2103c65ebfc7SToomas Soome * UPnP/IGD protocol for this API to create a successful mapping. Note that this API 2104c65ebfc7SToomas Soome * currently supports IPv4 addresses/mappings only. If the NAT gateway supports PCP and 2105c65ebfc7SToomas Soome * returns an IPv6 address (incorrectly, since this API specifically requests IPv4 2106c65ebfc7SToomas Soome * addresses), the DNSServiceNATPortMappingReply callback will be invoked with errorCode 2107c65ebfc7SToomas Soome * kDNSServiceErr_NATPortMappingUnsupported. 2108c65ebfc7SToomas Soome * 2109c65ebfc7SToomas Soome * The port mapping will be renewed indefinitely until the client process exits, or 2110c65ebfc7SToomas Soome * explicitly terminates the port mapping request by calling DNSServiceRefDeallocate(). 2111c65ebfc7SToomas Soome * The client callback will be invoked, informing the client of the NAT gateway's 2112c65ebfc7SToomas Soome * external IP address and the external port that has been allocated for this client. 2113c65ebfc7SToomas Soome * The client should then record this external IP address and port using whatever 2114c65ebfc7SToomas Soome * directory service mechanism it is using to enable peers to connect to it. 2115c65ebfc7SToomas Soome * (Clients advertising services using Wide-Area DNS-SD DO NOT need to use this API 2116c65ebfc7SToomas Soome * -- when a client calls DNSServiceRegister() NAT mappings are automatically created 2117c65ebfc7SToomas Soome * and the external IP address and port for the service are recorded in the global DNS. 2118c65ebfc7SToomas Soome * Only clients using some directory mechanism other than Wide-Area DNS-SD need to use 2119c65ebfc7SToomas Soome * this API to explicitly map their own ports.) 2120c65ebfc7SToomas Soome * 2121c65ebfc7SToomas Soome * It's possible that the client callback could be called multiple times, for example 2122c65ebfc7SToomas Soome * if the NAT gateway's IP address changes, or if a configuration change results in a 2123c65ebfc7SToomas Soome * different external port being mapped for this client. Over the lifetime of any long-lived 2124c65ebfc7SToomas Soome * port mapping, the client should be prepared to handle these notifications of changes 2125c65ebfc7SToomas Soome * in the environment, and should update its recorded address and/or port as appropriate. 2126c65ebfc7SToomas Soome * 2127c65ebfc7SToomas Soome * NOTE: There are two unusual aspects of how the DNSServiceNATPortMappingCreate API works, 2128c65ebfc7SToomas Soome * which were intentionally designed to help simplify client code: 2129c65ebfc7SToomas Soome * 2130c65ebfc7SToomas Soome * 1. It's not an error to request a NAT mapping when the machine is not behind a NAT gateway. 2131c65ebfc7SToomas Soome * In other NAT mapping APIs, if you request a NAT mapping and the machine is not behind a NAT 2132c65ebfc7SToomas Soome * gateway, then the API returns an error code -- it can't get you a NAT mapping if there's no 2133c65ebfc7SToomas Soome * NAT gateway. The DNSServiceNATPortMappingCreate API takes a different view. Working out 2134c65ebfc7SToomas Soome * whether or not you need a NAT mapping can be tricky and non-obvious, particularly on 2135c65ebfc7SToomas Soome * a machine with multiple active network interfaces. Rather than make every client recreate 2136c65ebfc7SToomas Soome * this logic for deciding whether a NAT mapping is required, the PortMapping API does that 2137c65ebfc7SToomas Soome * work for you. If the client calls the PortMapping API when the machine already has a 2138c65ebfc7SToomas Soome * routable public IP address, then instead of complaining about it and giving an error, 2139c65ebfc7SToomas Soome * the PortMapping API just invokes your callback, giving the machine's public address 2140c65ebfc7SToomas Soome * and your own port number. This means you don't need to write code to work out whether 2141c65ebfc7SToomas Soome * your client needs to call the PortMapping API -- just call it anyway, and if it wasn't 2142c65ebfc7SToomas Soome * necessary, no harm is done: 2143c65ebfc7SToomas Soome * 2144c65ebfc7SToomas Soome * - If the machine already has a routable public IP address, then your callback 2145c65ebfc7SToomas Soome * will just be invoked giving your own address and port. 2146c65ebfc7SToomas Soome * - If a NAT mapping is required and obtained, then your callback will be invoked 2147c65ebfc7SToomas Soome * giving you the external address and port. 2148c65ebfc7SToomas Soome * - If a NAT mapping is required but not obtained from the local NAT gateway, 2149c65ebfc7SToomas Soome * or the machine has no network connectivity, then your callback will be 2150c65ebfc7SToomas Soome * invoked giving zero address and port. 2151c65ebfc7SToomas Soome * 2152c65ebfc7SToomas Soome * 2. In other NAT mapping APIs, if a laptop computer is put to sleep and woken up on a new 2153c65ebfc7SToomas Soome * network, it's the client's job to notice this, and work out whether a NAT mapping 2154c65ebfc7SToomas Soome * is required on the new network, and make a new NAT mapping request if necessary. 2155c65ebfc7SToomas Soome * The DNSServiceNATPortMappingCreate API does this for you, automatically. 2156c65ebfc7SToomas Soome * The client just needs to make one call to the PortMapping API, and its callback will 2157c65ebfc7SToomas Soome * be invoked any time the mapping state changes. This property complements point (1) above. 2158c65ebfc7SToomas Soome * If the client didn't make a NAT mapping request just because it determined that one was 2159c65ebfc7SToomas Soome * not required at that particular moment in time, the client would then have to monitor 2160c65ebfc7SToomas Soome * for network state changes to determine if a NAT port mapping later became necessary. 2161c65ebfc7SToomas Soome * By unconditionally making a NAT mapping request, even when a NAT mapping not to be 2162c65ebfc7SToomas Soome * necessary, the PortMapping API will then begin monitoring network state changes on behalf of 2163c65ebfc7SToomas Soome * the client, and if a NAT mapping later becomes necessary, it will automatically create a NAT 2164c65ebfc7SToomas Soome * mapping and inform the client with a new callback giving the new address and port information. 2165c65ebfc7SToomas Soome * 2166c65ebfc7SToomas Soome * DNSServiceNATPortMappingReply() parameters: 2167c65ebfc7SToomas Soome * 2168c65ebfc7SToomas Soome * sdRef: The DNSServiceRef initialized by DNSServiceNATPortMappingCreate(). 2169c65ebfc7SToomas Soome * 2170c65ebfc7SToomas Soome * flags: Currently unused, reserved for future use. 2171c65ebfc7SToomas Soome * 2172c65ebfc7SToomas Soome * interfaceIndex: The interface through which the NAT gateway is reached. 2173c65ebfc7SToomas Soome * 2174c65ebfc7SToomas Soome * errorCode: Will be kDNSServiceErr_NoError on success. 2175c65ebfc7SToomas Soome * Will be kDNSServiceErr_DoubleNAT when the NAT gateway is itself behind one or 2176c65ebfc7SToomas Soome * more layers of NAT, in which case the other parameters have the defined values. 2177c65ebfc7SToomas Soome * For other failures, will indicate the failure that occurred, and the other 2178c65ebfc7SToomas Soome * parameters are undefined. 2179c65ebfc7SToomas Soome * 2180c65ebfc7SToomas Soome * externalAddress: Four byte IPv4 address in network byte order. 2181c65ebfc7SToomas Soome * 2182c65ebfc7SToomas Soome * protocol: Will be kDNSServiceProtocol_UDP or kDNSServiceProtocol_TCP or both. 2183c65ebfc7SToomas Soome * 2184c65ebfc7SToomas Soome * internalPort: The port on the local machine that was mapped. 2185c65ebfc7SToomas Soome * 2186c65ebfc7SToomas Soome * externalPort: The actual external port in the NAT gateway that was mapped. 2187c65ebfc7SToomas Soome * This is likely to be different than the requested external port. 2188c65ebfc7SToomas Soome * 2189c65ebfc7SToomas Soome * ttl: The lifetime of the NAT port mapping created on the gateway. 2190c65ebfc7SToomas Soome * This controls how quickly stale mappings will be garbage-collected 2191c65ebfc7SToomas Soome * if the client machine crashes, suffers a power failure, is disconnected 2192c65ebfc7SToomas Soome * from the network, or suffers some other unfortunate demise which 2193c65ebfc7SToomas Soome * causes it to vanish without explicitly removing its NAT port mapping. 2194c65ebfc7SToomas Soome * It's possible that the ttl value will differ from the requested ttl value. 2195c65ebfc7SToomas Soome * 2196c65ebfc7SToomas Soome * context: The context pointer that was passed to the callout. 2197c65ebfc7SToomas Soome * 2198c65ebfc7SToomas Soome */ 2199c65ebfc7SToomas Soome 2200c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceNATPortMappingReply) 2201c65ebfc7SToomas Soome ( 2202c65ebfc7SToomas Soome DNSServiceRef sdRef, 2203c65ebfc7SToomas Soome DNSServiceFlags flags, 2204c65ebfc7SToomas Soome uint32_t interfaceIndex, 2205c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 2206c65ebfc7SToomas Soome uint32_t externalAddress, /* four byte IPv4 address in network byte order */ 2207c65ebfc7SToomas Soome DNSServiceProtocol protocol, 2208c65ebfc7SToomas Soome uint16_t internalPort, /* In network byte order */ 2209c65ebfc7SToomas Soome uint16_t externalPort, /* In network byte order and may be different than the requested port */ 2210c65ebfc7SToomas Soome uint32_t ttl, /* may be different than the requested ttl */ 2211c65ebfc7SToomas Soome void *context 2212c65ebfc7SToomas Soome ); 2213c65ebfc7SToomas Soome 2214c65ebfc7SToomas Soome 2215c65ebfc7SToomas Soome /* DNSServiceNATPortMappingCreate() Parameters: 2216c65ebfc7SToomas Soome * 2217*472cd20dSToomas Soome * sdRef: A pointer to an uninitialized DNSServiceRef 2218*472cd20dSToomas Soome * (or, if the kDNSServiceFlagsShareConnection flag is used, 2219*472cd20dSToomas Soome * a copy of the shared connection reference that is to be used). 2220*472cd20dSToomas Soome * If the call succeeds then it initializes (or updates) the DNSServiceRef, 2221*472cd20dSToomas Soome * returns kDNSServiceErr_NoError, and the NAT port mapping 2222*472cd20dSToomas Soome * will remain active indefinitely until the client terminates it 2223*472cd20dSToomas Soome * by passing this DNSServiceRef to DNSServiceRefDeallocate() 2224*472cd20dSToomas Soome * (or by closing the underlying shared connection, if used). 2225c65ebfc7SToomas Soome * 2226*472cd20dSToomas Soome * flags: Possible values are: 2227*472cd20dSToomas Soome * kDNSServiceFlagsShareConnection to use a shared connection. 2228c65ebfc7SToomas Soome * 2229*472cd20dSToomas Soome * interfaceIndex: The interface on which to create port mappings in a NAT gateway. 2230*472cd20dSToomas Soome * Passing 0 causes the port mapping request to be sent on the primary interface. 2231c65ebfc7SToomas Soome * 2232c65ebfc7SToomas Soome * protocol: To request a port mapping, pass in kDNSServiceProtocol_UDP, or kDNSServiceProtocol_TCP, 2233c65ebfc7SToomas Soome * or (kDNSServiceProtocol_UDP | kDNSServiceProtocol_TCP) to map both. 2234c65ebfc7SToomas Soome * The local listening port number must also be specified in the internalPort parameter. 2235c65ebfc7SToomas Soome * To just discover the NAT gateway's external IP address, pass zero for protocol, 2236c65ebfc7SToomas Soome * internalPort, externalPort and ttl. 2237c65ebfc7SToomas Soome * 2238c65ebfc7SToomas Soome * internalPort: The port number in network byte order on the local machine which is listening for packets. 2239c65ebfc7SToomas Soome * 2240c65ebfc7SToomas Soome * externalPort: The requested external port in network byte order in the NAT gateway that you would 2241c65ebfc7SToomas Soome * like to map to the internal port. Pass 0 if you don't care which external port is chosen for you. 2242c65ebfc7SToomas Soome * 2243c65ebfc7SToomas Soome * ttl: The requested renewal period of the NAT port mapping, in seconds. 2244c65ebfc7SToomas Soome * If the client machine crashes, suffers a power failure, is disconnected from 2245c65ebfc7SToomas Soome * the network, or suffers some other unfortunate demise which causes it to vanish 2246c65ebfc7SToomas Soome * unexpectedly without explicitly removing its NAT port mappings, then the NAT gateway 2247c65ebfc7SToomas Soome * will garbage-collect old stale NAT port mappings when their lifetime expires. 2248c65ebfc7SToomas Soome * Requesting a short TTL causes such orphaned mappings to be garbage-collected 2249c65ebfc7SToomas Soome * more promptly, but consumes system resources and network bandwidth with 2250c65ebfc7SToomas Soome * frequent renewal packets to keep the mapping from expiring. 2251c65ebfc7SToomas Soome * Requesting a long TTL is more efficient on the network, but in the event of the 2252c65ebfc7SToomas Soome * client vanishing, stale NAT port mappings will not be garbage-collected as quickly. 2253c65ebfc7SToomas Soome * Most clients should pass 0 to use a system-wide default value. 2254c65ebfc7SToomas Soome * 2255c65ebfc7SToomas Soome * callBack: The function to be called when the port mapping request succeeds or fails asynchronously. 2256c65ebfc7SToomas Soome * 2257c65ebfc7SToomas Soome * context: An application context pointer which is passed to the callback function 2258c65ebfc7SToomas Soome * (may be NULL). 2259c65ebfc7SToomas Soome * 2260c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 2261c65ebfc7SToomas Soome * errors are delivered to the callback), otherwise returns an error code indicating 2262c65ebfc7SToomas Soome * the error that occurred. 2263c65ebfc7SToomas Soome * 2264c65ebfc7SToomas Soome * If you don't actually want a port mapped, and are just calling the API 2265c65ebfc7SToomas Soome * because you want to find out the NAT's external IP address (e.g. for UI 2266c65ebfc7SToomas Soome * display) then pass zero for protocol, internalPort, externalPort and ttl. 2267c65ebfc7SToomas Soome */ 2268c65ebfc7SToomas Soome 22693b436d06SToomas Soome DNSSD_EXPORT 2270c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceNATPortMappingCreate 2271c65ebfc7SToomas Soome ( 2272c65ebfc7SToomas Soome DNSServiceRef *sdRef, 2273c65ebfc7SToomas Soome DNSServiceFlags flags, 2274c65ebfc7SToomas Soome uint32_t interfaceIndex, 2275c65ebfc7SToomas Soome DNSServiceProtocol protocol, /* TCP and/or UDP */ 2276c65ebfc7SToomas Soome uint16_t internalPort, /* network byte order */ 2277c65ebfc7SToomas Soome uint16_t externalPort, /* network byte order */ 2278c65ebfc7SToomas Soome uint32_t ttl, /* time to live in seconds */ 2279c65ebfc7SToomas Soome DNSServiceNATPortMappingReply callBack, 2280c65ebfc7SToomas Soome void *context /* may be NULL */ 2281c65ebfc7SToomas Soome ); 2282c65ebfc7SToomas Soome 2283c65ebfc7SToomas Soome 2284c65ebfc7SToomas Soome /********************************************************************************************* 2285c65ebfc7SToomas Soome * 2286c65ebfc7SToomas Soome * General Utility Functions 2287c65ebfc7SToomas Soome * 2288c65ebfc7SToomas Soome *********************************************************************************************/ 2289c65ebfc7SToomas Soome 2290c65ebfc7SToomas Soome /* DNSServiceConstructFullName() 2291c65ebfc7SToomas Soome * 2292c65ebfc7SToomas Soome * Concatenate a three-part domain name (as returned by the above callbacks) into a 2293c65ebfc7SToomas Soome * properly-escaped full domain name. Note that callbacks in the above functions ALREADY ESCAPE 2294c65ebfc7SToomas Soome * strings where necessary. 2295c65ebfc7SToomas Soome * 2296c65ebfc7SToomas Soome * Parameters: 2297c65ebfc7SToomas Soome * 2298c65ebfc7SToomas Soome * fullName: A pointer to a buffer that where the resulting full domain name is to be written. 2299c65ebfc7SToomas Soome * The buffer must be kDNSServiceMaxDomainName (1009) bytes in length to 2300c65ebfc7SToomas Soome * accommodate the longest legal domain name without buffer overrun. 2301c65ebfc7SToomas Soome * 2302c65ebfc7SToomas Soome * service: The service name - any dots or backslashes must NOT be escaped. 2303c65ebfc7SToomas Soome * May be NULL (to construct a PTR record name, e.g. 2304c65ebfc7SToomas Soome * "_ftp._tcp.apple.com."). 2305c65ebfc7SToomas Soome * 2306c65ebfc7SToomas Soome * regtype: The service type followed by the protocol, separated by a dot 2307c65ebfc7SToomas Soome * (e.g. "_ftp._tcp"). 2308c65ebfc7SToomas Soome * 2309c65ebfc7SToomas Soome * domain: The domain name, e.g. "apple.com.". Literal dots or backslashes, 2310c65ebfc7SToomas Soome * if any, must be escaped, e.g. "1st\. Floor.apple.com." 2311c65ebfc7SToomas Soome * 2312c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError (0) on success, kDNSServiceErr_BadParam on error. 2313c65ebfc7SToomas Soome * 2314c65ebfc7SToomas Soome */ 2315c65ebfc7SToomas Soome 23163b436d06SToomas Soome DNSSD_EXPORT 2317c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceConstructFullName 2318c65ebfc7SToomas Soome ( 2319c65ebfc7SToomas Soome char * const fullName, 2320c65ebfc7SToomas Soome const char * const service, /* may be NULL */ 2321c65ebfc7SToomas Soome const char * const regtype, 2322c65ebfc7SToomas Soome const char * const domain 2323c65ebfc7SToomas Soome ); 2324c65ebfc7SToomas Soome 2325c65ebfc7SToomas Soome 2326c65ebfc7SToomas Soome /********************************************************************************************* 2327c65ebfc7SToomas Soome * 2328c65ebfc7SToomas Soome * TXT Record Construction Functions 2329c65ebfc7SToomas Soome * 2330c65ebfc7SToomas Soome *********************************************************************************************/ 2331c65ebfc7SToomas Soome 2332c65ebfc7SToomas Soome /* 2333c65ebfc7SToomas Soome * A typical calling sequence for TXT record construction is something like: 2334c65ebfc7SToomas Soome * 2335c65ebfc7SToomas Soome * Client allocates storage for TXTRecord data (e.g. declare buffer on the stack) 2336c65ebfc7SToomas Soome * TXTRecordCreate(); 2337c65ebfc7SToomas Soome * TXTRecordSetValue(); 2338c65ebfc7SToomas Soome * TXTRecordSetValue(); 2339c65ebfc7SToomas Soome * TXTRecordSetValue(); 2340c65ebfc7SToomas Soome * ... 2341c65ebfc7SToomas Soome * DNSServiceRegister( ... TXTRecordGetLength(), TXTRecordGetBytesPtr() ... ); 2342c65ebfc7SToomas Soome * TXTRecordDeallocate(); 2343c65ebfc7SToomas Soome * Explicitly deallocate storage for TXTRecord data (if not allocated on the stack) 2344c65ebfc7SToomas Soome */ 2345c65ebfc7SToomas Soome 2346c65ebfc7SToomas Soome 2347c65ebfc7SToomas Soome /* TXTRecordRef 2348c65ebfc7SToomas Soome * 2349c65ebfc7SToomas Soome * Opaque internal data type. 2350c65ebfc7SToomas Soome * Note: Represents a DNS-SD TXT record. 2351c65ebfc7SToomas Soome */ 2352c65ebfc7SToomas Soome 2353c65ebfc7SToomas Soome typedef union _TXTRecordRef_t { char PrivateData[16]; char *ForceNaturalAlignment; } TXTRecordRef; 2354c65ebfc7SToomas Soome 2355c65ebfc7SToomas Soome 2356c65ebfc7SToomas Soome /* TXTRecordCreate() 2357c65ebfc7SToomas Soome * 2358c65ebfc7SToomas Soome * Creates a new empty TXTRecordRef referencing the specified storage. 2359c65ebfc7SToomas Soome * 2360c65ebfc7SToomas Soome * If the buffer parameter is NULL, or the specified storage size is not 2361c65ebfc7SToomas Soome * large enough to hold a key subsequently added using TXTRecordSetValue(), 2362*472cd20dSToomas Soome * then additional memory will be added as needed using malloc(). Note that 2363*472cd20dSToomas Soome * an existing TXT record buffer should not be passed to TXTRecordCreate 2364*472cd20dSToomas Soome * to create a copy of another TXT Record. The correct way to copy TXTRecordRef 2365*472cd20dSToomas Soome * is creating an empty TXTRecordRef with TXTRecordCreate() first, and using 2366*472cd20dSToomas Soome * TXTRecordSetValue to set the same value. 2367c65ebfc7SToomas Soome * 2368c65ebfc7SToomas Soome * On some platforms, when memory is low, malloc() may fail. In this 2369c65ebfc7SToomas Soome * case, TXTRecordSetValue() will return kDNSServiceErr_NoMemory, and this 2370c65ebfc7SToomas Soome * error condition will need to be handled as appropriate by the caller. 2371c65ebfc7SToomas Soome * 2372c65ebfc7SToomas Soome * You can avoid the need to handle this error condition if you ensure 2373c65ebfc7SToomas Soome * that the storage you initially provide is large enough to hold all 2374c65ebfc7SToomas Soome * the key/value pairs that are to be added to the record. 2375c65ebfc7SToomas Soome * The caller can precompute the exact length required for all of the 2376c65ebfc7SToomas Soome * key/value pairs to be added, or simply provide a fixed-sized buffer 2377c65ebfc7SToomas Soome * known in advance to be large enough. 2378c65ebfc7SToomas Soome * A no-value (key-only) key requires (1 + key length) bytes. 2379c65ebfc7SToomas Soome * A key with empty value requires (1 + key length + 1) bytes. 2380c65ebfc7SToomas Soome * A key with non-empty value requires (1 + key length + 1 + value length). 2381c65ebfc7SToomas Soome * For most applications, DNS-SD TXT records are generally 2382c65ebfc7SToomas Soome * less than 100 bytes, so in most cases a simple fixed-sized 2383c65ebfc7SToomas Soome * 256-byte buffer will be more than sufficient. 2384c65ebfc7SToomas Soome * Recommended size limits for DNS-SD TXT Records are discussed in RFC 6763 2385c65ebfc7SToomas Soome * <https://tools.ietf.org/html/rfc6763#section-6.2> 2386c65ebfc7SToomas Soome * 2387c65ebfc7SToomas Soome * Note: When passing parameters to and from these TXT record APIs, 2388c65ebfc7SToomas Soome * the key name does not include the '=' character. The '=' character 2389c65ebfc7SToomas Soome * is the separator between the key and value in the on-the-wire 2390c65ebfc7SToomas Soome * packet format; it is not part of either the key or the value. 2391c65ebfc7SToomas Soome * 2392c65ebfc7SToomas Soome * txtRecord: A pointer to an uninitialized TXTRecordRef. 2393c65ebfc7SToomas Soome * 2394c65ebfc7SToomas Soome * bufferLen: The size of the storage provided in the "buffer" parameter. 2395c65ebfc7SToomas Soome * 2396c65ebfc7SToomas Soome * buffer: Optional caller-supplied storage used to hold the TXTRecord data. 2397c65ebfc7SToomas Soome * This storage must remain valid for as long as 2398c65ebfc7SToomas Soome * the TXTRecordRef. 2399c65ebfc7SToomas Soome */ 2400c65ebfc7SToomas Soome 24013b436d06SToomas Soome DNSSD_EXPORT 2402c65ebfc7SToomas Soome void DNSSD_API TXTRecordCreate 2403c65ebfc7SToomas Soome ( 2404c65ebfc7SToomas Soome TXTRecordRef *txtRecord, 2405c65ebfc7SToomas Soome uint16_t bufferLen, 2406c65ebfc7SToomas Soome void *buffer 2407c65ebfc7SToomas Soome ); 2408c65ebfc7SToomas Soome 2409c65ebfc7SToomas Soome 2410c65ebfc7SToomas Soome /* TXTRecordDeallocate() 2411c65ebfc7SToomas Soome * 2412c65ebfc7SToomas Soome * Releases any resources allocated in the course of preparing a TXT Record 2413c65ebfc7SToomas Soome * using TXTRecordCreate()/TXTRecordSetValue()/TXTRecordRemoveValue(). 2414c65ebfc7SToomas Soome * Ownership of the buffer provided in TXTRecordCreate() returns to the client. 2415c65ebfc7SToomas Soome * 2416c65ebfc7SToomas Soome * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 2417c65ebfc7SToomas Soome * 2418c65ebfc7SToomas Soome */ 2419c65ebfc7SToomas Soome 24203b436d06SToomas Soome DNSSD_EXPORT 2421c65ebfc7SToomas Soome void DNSSD_API TXTRecordDeallocate 2422c65ebfc7SToomas Soome ( 2423c65ebfc7SToomas Soome TXTRecordRef *txtRecord 2424c65ebfc7SToomas Soome ); 2425c65ebfc7SToomas Soome 2426c65ebfc7SToomas Soome 2427c65ebfc7SToomas Soome /* TXTRecordSetValue() 2428c65ebfc7SToomas Soome * 2429c65ebfc7SToomas Soome * Adds a key (optionally with value) to a TXTRecordRef. If the "key" already 2430c65ebfc7SToomas Soome * exists in the TXTRecordRef, then the current value will be replaced with 2431c65ebfc7SToomas Soome * the new value. 2432c65ebfc7SToomas Soome * Keys may exist in four states with respect to a given TXT record: 2433c65ebfc7SToomas Soome * - Absent (key does not appear at all) 2434c65ebfc7SToomas Soome * - Present with no value ("key" appears alone) 2435c65ebfc7SToomas Soome * - Present with empty value ("key=" appears in TXT record) 2436c65ebfc7SToomas Soome * - Present with non-empty value ("key=value" appears in TXT record) 2437c65ebfc7SToomas Soome * For more details refer to "Data Syntax for DNS-SD TXT Records" in RFC 6763 2438c65ebfc7SToomas Soome * <https://tools.ietf.org/html/rfc6763#section-6> 2439c65ebfc7SToomas Soome * 2440c65ebfc7SToomas Soome * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 2441c65ebfc7SToomas Soome * 2442c65ebfc7SToomas Soome * key: A null-terminated string which only contains printable ASCII 2443c65ebfc7SToomas Soome * values (0x20-0x7E), excluding '=' (0x3D). Keys should be 2444c65ebfc7SToomas Soome * 9 characters or fewer (not counting the terminating null). 2445c65ebfc7SToomas Soome * 2446c65ebfc7SToomas Soome * valueSize: The size of the value. 2447c65ebfc7SToomas Soome * 2448c65ebfc7SToomas Soome * value: Any binary value. For values that represent 2449c65ebfc7SToomas Soome * textual data, UTF-8 is STRONGLY recommended. 2450c65ebfc7SToomas Soome * For values that represent textual data, valueSize 2451c65ebfc7SToomas Soome * should NOT include the terminating null (if any) 2452c65ebfc7SToomas Soome * at the end of the string. 2453c65ebfc7SToomas Soome * If NULL, then "key" will be added with no value. 2454c65ebfc7SToomas Soome * If non-NULL but valueSize is zero, then "key=" will be 2455c65ebfc7SToomas Soome * added with empty value. 2456c65ebfc7SToomas Soome * 2457c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success. 2458c65ebfc7SToomas Soome * Returns kDNSServiceErr_Invalid if the "key" string contains 2459c65ebfc7SToomas Soome * illegal characters. 2460c65ebfc7SToomas Soome * Returns kDNSServiceErr_NoMemory if adding this key would 2461c65ebfc7SToomas Soome * exceed the available storage. 2462c65ebfc7SToomas Soome */ 2463c65ebfc7SToomas Soome 24643b436d06SToomas Soome DNSSD_EXPORT 2465c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API TXTRecordSetValue 2466c65ebfc7SToomas Soome ( 2467c65ebfc7SToomas Soome TXTRecordRef *txtRecord, 2468c65ebfc7SToomas Soome const char *key, 2469c65ebfc7SToomas Soome uint8_t valueSize, /* may be zero */ 2470c65ebfc7SToomas Soome const void *value /* may be NULL */ 2471c65ebfc7SToomas Soome ); 2472c65ebfc7SToomas Soome 2473c65ebfc7SToomas Soome 2474c65ebfc7SToomas Soome /* TXTRecordRemoveValue() 2475c65ebfc7SToomas Soome * 2476c65ebfc7SToomas Soome * Removes a key from a TXTRecordRef. The "key" must be an 2477c65ebfc7SToomas Soome * ASCII string which exists in the TXTRecordRef. 2478c65ebfc7SToomas Soome * 2479c65ebfc7SToomas Soome * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 2480c65ebfc7SToomas Soome * 2481c65ebfc7SToomas Soome * key: A key name which exists in the TXTRecordRef. 2482c65ebfc7SToomas Soome * 2483c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success. 2484c65ebfc7SToomas Soome * Returns kDNSServiceErr_NoSuchKey if the "key" does not 2485c65ebfc7SToomas Soome * exist in the TXTRecordRef. 2486c65ebfc7SToomas Soome */ 2487c65ebfc7SToomas Soome 24883b436d06SToomas Soome DNSSD_EXPORT 2489c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API TXTRecordRemoveValue 2490c65ebfc7SToomas Soome ( 2491c65ebfc7SToomas Soome TXTRecordRef *txtRecord, 2492c65ebfc7SToomas Soome const char *key 2493c65ebfc7SToomas Soome ); 2494c65ebfc7SToomas Soome 2495c65ebfc7SToomas Soome 2496c65ebfc7SToomas Soome /* TXTRecordGetLength() 2497c65ebfc7SToomas Soome * 2498c65ebfc7SToomas Soome * Allows you to determine the length of the raw bytes within a TXTRecordRef. 2499c65ebfc7SToomas Soome * 2500c65ebfc7SToomas Soome * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 2501c65ebfc7SToomas Soome * 2502c65ebfc7SToomas Soome * return value: Returns the size of the raw bytes inside a TXTRecordRef 2503c65ebfc7SToomas Soome * which you can pass directly to DNSServiceRegister() or 2504c65ebfc7SToomas Soome * to DNSServiceUpdateRecord(). 2505c65ebfc7SToomas Soome * Returns 0 if the TXTRecordRef is empty. 2506c65ebfc7SToomas Soome */ 2507c65ebfc7SToomas Soome 25083b436d06SToomas Soome DNSSD_EXPORT 2509c65ebfc7SToomas Soome uint16_t DNSSD_API TXTRecordGetLength 2510c65ebfc7SToomas Soome ( 2511c65ebfc7SToomas Soome const TXTRecordRef *txtRecord 2512c65ebfc7SToomas Soome ); 2513c65ebfc7SToomas Soome 2514c65ebfc7SToomas Soome 2515c65ebfc7SToomas Soome /* TXTRecordGetBytesPtr() 2516c65ebfc7SToomas Soome * 2517c65ebfc7SToomas Soome * Allows you to retrieve a pointer to the raw bytes within a TXTRecordRef. 2518c65ebfc7SToomas Soome * 2519c65ebfc7SToomas Soome * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 2520c65ebfc7SToomas Soome * 2521c65ebfc7SToomas Soome * return value: Returns a pointer to the raw bytes inside the TXTRecordRef 2522c65ebfc7SToomas Soome * which you can pass directly to DNSServiceRegister() or 2523c65ebfc7SToomas Soome * to DNSServiceUpdateRecord(). 2524c65ebfc7SToomas Soome */ 2525c65ebfc7SToomas Soome 25263b436d06SToomas Soome DNSSD_EXPORT 2527c65ebfc7SToomas Soome const void * DNSSD_API TXTRecordGetBytesPtr 2528c65ebfc7SToomas Soome ( 2529c65ebfc7SToomas Soome const TXTRecordRef *txtRecord 2530c65ebfc7SToomas Soome ); 2531c65ebfc7SToomas Soome 2532c65ebfc7SToomas Soome 2533c65ebfc7SToomas Soome /********************************************************************************************* 2534c65ebfc7SToomas Soome * 2535c65ebfc7SToomas Soome * TXT Record Parsing Functions 2536c65ebfc7SToomas Soome * 2537c65ebfc7SToomas Soome *********************************************************************************************/ 2538c65ebfc7SToomas Soome 2539c65ebfc7SToomas Soome /* 2540c65ebfc7SToomas Soome * A typical calling sequence for TXT record parsing is something like: 2541c65ebfc7SToomas Soome * 2542c65ebfc7SToomas Soome * Receive TXT record data in DNSServiceResolve() callback 2543c65ebfc7SToomas Soome * if (TXTRecordContainsKey(txtLen, txtRecord, "key")) then do something 2544c65ebfc7SToomas Soome * val1ptr = TXTRecordGetValuePtr(txtLen, txtRecord, "key1", &len1); 2545c65ebfc7SToomas Soome * val2ptr = TXTRecordGetValuePtr(txtLen, txtRecord, "key2", &len2); 2546c65ebfc7SToomas Soome * ... 2547c65ebfc7SToomas Soome * memcpy(myval1, val1ptr, len1); 2548c65ebfc7SToomas Soome * memcpy(myval2, val2ptr, len2); 2549c65ebfc7SToomas Soome * ... 2550c65ebfc7SToomas Soome * return; 2551c65ebfc7SToomas Soome * 2552c65ebfc7SToomas Soome * If you wish to retain the values after return from the DNSServiceResolve() 2553c65ebfc7SToomas Soome * callback, then you need to copy the data to your own storage using memcpy() 2554c65ebfc7SToomas Soome * or similar, as shown in the example above. 2555c65ebfc7SToomas Soome * 2556c65ebfc7SToomas Soome * If for some reason you need to parse a TXT record you built yourself 2557c65ebfc7SToomas Soome * using the TXT record construction functions above, then you can do 2558c65ebfc7SToomas Soome * that using TXTRecordGetLength and TXTRecordGetBytesPtr calls: 2559c65ebfc7SToomas Soome * TXTRecordGetValue(TXTRecordGetLength(x), TXTRecordGetBytesPtr(x), key, &len); 2560c65ebfc7SToomas Soome * 2561c65ebfc7SToomas Soome * Most applications only fetch keys they know about from a TXT record and 2562c65ebfc7SToomas Soome * ignore the rest. 2563c65ebfc7SToomas Soome * However, some debugging tools wish to fetch and display all keys. 2564c65ebfc7SToomas Soome * To do that, use the TXTRecordGetCount() and TXTRecordGetItemAtIndex() calls. 2565c65ebfc7SToomas Soome */ 2566c65ebfc7SToomas Soome 2567c65ebfc7SToomas Soome /* TXTRecordContainsKey() 2568c65ebfc7SToomas Soome * 2569c65ebfc7SToomas Soome * Allows you to determine if a given TXT Record contains a specified key. 2570c65ebfc7SToomas Soome * 2571c65ebfc7SToomas Soome * txtLen: The size of the received TXT Record. 2572c65ebfc7SToomas Soome * 2573c65ebfc7SToomas Soome * txtRecord: Pointer to the received TXT Record bytes. 2574c65ebfc7SToomas Soome * 2575c65ebfc7SToomas Soome * key: A null-terminated ASCII string containing the key name. 2576c65ebfc7SToomas Soome * 2577c65ebfc7SToomas Soome * return value: Returns 1 if the TXT Record contains the specified key. 2578c65ebfc7SToomas Soome * Otherwise, it returns 0. 2579c65ebfc7SToomas Soome */ 2580c65ebfc7SToomas Soome 25813b436d06SToomas Soome DNSSD_EXPORT 2582c65ebfc7SToomas Soome int DNSSD_API TXTRecordContainsKey 2583c65ebfc7SToomas Soome ( 2584c65ebfc7SToomas Soome uint16_t txtLen, 2585c65ebfc7SToomas Soome const void *txtRecord, 2586c65ebfc7SToomas Soome const char *key 2587c65ebfc7SToomas Soome ); 2588c65ebfc7SToomas Soome 2589c65ebfc7SToomas Soome 2590c65ebfc7SToomas Soome /* TXTRecordGetValuePtr() 2591c65ebfc7SToomas Soome * 2592c65ebfc7SToomas Soome * Allows you to retrieve the value for a given key from a TXT Record. 2593c65ebfc7SToomas Soome * 2594c65ebfc7SToomas Soome * txtLen: The size of the received TXT Record 2595c65ebfc7SToomas Soome * 2596c65ebfc7SToomas Soome * txtRecord: Pointer to the received TXT Record bytes. 2597c65ebfc7SToomas Soome * 2598c65ebfc7SToomas Soome * key: A null-terminated ASCII string containing the key name. 2599c65ebfc7SToomas Soome * 2600c65ebfc7SToomas Soome * valueLen: On output, will be set to the size of the "value" data. 2601c65ebfc7SToomas Soome * 2602c65ebfc7SToomas Soome * return value: Returns NULL if the key does not exist in this TXT record, 2603c65ebfc7SToomas Soome * or exists with no value (to differentiate between 2604c65ebfc7SToomas Soome * these two cases use TXTRecordContainsKey()). 2605c65ebfc7SToomas Soome * Returns pointer to location within TXT Record bytes 2606c65ebfc7SToomas Soome * if the key exists with empty or non-empty value. 2607c65ebfc7SToomas Soome * For empty value, valueLen will be zero. 2608c65ebfc7SToomas Soome * For non-empty value, valueLen will be length of value data. 2609c65ebfc7SToomas Soome */ 2610c65ebfc7SToomas Soome 26113b436d06SToomas Soome DNSSD_EXPORT 2612c65ebfc7SToomas Soome const void * DNSSD_API TXTRecordGetValuePtr 2613c65ebfc7SToomas Soome ( 2614c65ebfc7SToomas Soome uint16_t txtLen, 2615c65ebfc7SToomas Soome const void *txtRecord, 2616c65ebfc7SToomas Soome const char *key, 2617c65ebfc7SToomas Soome uint8_t *valueLen 2618c65ebfc7SToomas Soome ); 2619c65ebfc7SToomas Soome 2620c65ebfc7SToomas Soome 2621c65ebfc7SToomas Soome /* TXTRecordGetCount() 2622c65ebfc7SToomas Soome * 2623c65ebfc7SToomas Soome * Returns the number of keys stored in the TXT Record. The count 2624c65ebfc7SToomas Soome * can be used with TXTRecordGetItemAtIndex() to iterate through the keys. 2625c65ebfc7SToomas Soome * 2626c65ebfc7SToomas Soome * txtLen: The size of the received TXT Record. 2627c65ebfc7SToomas Soome * 2628c65ebfc7SToomas Soome * txtRecord: Pointer to the received TXT Record bytes. 2629c65ebfc7SToomas Soome * 2630c65ebfc7SToomas Soome * return value: Returns the total number of keys in the TXT Record. 2631c65ebfc7SToomas Soome * 2632c65ebfc7SToomas Soome */ 2633c65ebfc7SToomas Soome 26343b436d06SToomas Soome DNSSD_EXPORT 2635c65ebfc7SToomas Soome uint16_t DNSSD_API TXTRecordGetCount 2636c65ebfc7SToomas Soome ( 2637c65ebfc7SToomas Soome uint16_t txtLen, 2638c65ebfc7SToomas Soome const void *txtRecord 2639c65ebfc7SToomas Soome ); 2640c65ebfc7SToomas Soome 2641c65ebfc7SToomas Soome 2642c65ebfc7SToomas Soome /* TXTRecordGetItemAtIndex() 2643c65ebfc7SToomas Soome * 2644c65ebfc7SToomas Soome * Allows you to retrieve a key name and value pointer, given an index into 2645c65ebfc7SToomas Soome * a TXT Record. Legal index values range from zero to TXTRecordGetCount()-1. 2646c65ebfc7SToomas Soome * It's also possible to iterate through keys in a TXT record by simply 2647c65ebfc7SToomas Soome * calling TXTRecordGetItemAtIndex() repeatedly, beginning with index zero 2648c65ebfc7SToomas Soome * and increasing until TXTRecordGetItemAtIndex() returns kDNSServiceErr_Invalid. 2649c65ebfc7SToomas Soome * 2650c65ebfc7SToomas Soome * On return: 2651c65ebfc7SToomas Soome * For keys with no value, *value is set to NULL and *valueLen is zero. 2652c65ebfc7SToomas Soome * For keys with empty value, *value is non-NULL and *valueLen is zero. 2653c65ebfc7SToomas Soome * For keys with non-empty value, *value is non-NULL and *valueLen is non-zero. 2654c65ebfc7SToomas Soome * 2655c65ebfc7SToomas Soome * txtLen: The size of the received TXT Record. 2656c65ebfc7SToomas Soome * 2657c65ebfc7SToomas Soome * txtRecord: Pointer to the received TXT Record bytes. 2658c65ebfc7SToomas Soome * 2659c65ebfc7SToomas Soome * itemIndex: An index into the TXT Record. 2660c65ebfc7SToomas Soome * 2661c65ebfc7SToomas Soome * keyBufLen: The size of the string buffer being supplied. 2662c65ebfc7SToomas Soome * 2663c65ebfc7SToomas Soome * key: A string buffer used to store the key name. 2664*472cd20dSToomas Soome * On return, the buffer contains a null-terminated C-string 2665c65ebfc7SToomas Soome * giving the key name. DNS-SD TXT keys are usually 2666c65ebfc7SToomas Soome * 9 characters or fewer. To hold the maximum possible 2667c65ebfc7SToomas Soome * key name, the buffer should be 256 bytes long. 2668c65ebfc7SToomas Soome * 2669c65ebfc7SToomas Soome * valueLen: On output, will be set to the size of the "value" data. 2670c65ebfc7SToomas Soome * 2671c65ebfc7SToomas Soome * value: On output, *value is set to point to location within TXT 2672c65ebfc7SToomas Soome * Record bytes that holds the value data. 2673c65ebfc7SToomas Soome * 2674c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success. 2675c65ebfc7SToomas Soome * Returns kDNSServiceErr_NoMemory if keyBufLen is too short. 2676c65ebfc7SToomas Soome * Returns kDNSServiceErr_Invalid if index is greater than 2677c65ebfc7SToomas Soome * TXTRecordGetCount()-1. 2678c65ebfc7SToomas Soome */ 2679c65ebfc7SToomas Soome 26803b436d06SToomas Soome DNSSD_EXPORT 2681c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API TXTRecordGetItemAtIndex 2682c65ebfc7SToomas Soome ( 2683c65ebfc7SToomas Soome uint16_t txtLen, 2684c65ebfc7SToomas Soome const void *txtRecord, 2685c65ebfc7SToomas Soome uint16_t itemIndex, 2686c65ebfc7SToomas Soome uint16_t keyBufLen, 2687c65ebfc7SToomas Soome char *key, 2688c65ebfc7SToomas Soome uint8_t *valueLen, 2689c65ebfc7SToomas Soome const void **value 2690c65ebfc7SToomas Soome ); 2691c65ebfc7SToomas Soome 2692c65ebfc7SToomas Soome #if _DNS_SD_LIBDISPATCH 2693c65ebfc7SToomas Soome /* 2694c65ebfc7SToomas Soome * DNSServiceSetDispatchQueue 2695c65ebfc7SToomas Soome * 2696c65ebfc7SToomas Soome * Allows you to schedule a DNSServiceRef on a serial dispatch queue for receiving asynchronous 2697c65ebfc7SToomas Soome * callbacks. It's the clients responsibility to ensure that the provided dispatch queue is running. 2698c65ebfc7SToomas Soome * 2699c65ebfc7SToomas Soome * A typical application that uses CFRunLoopRun or dispatch_main on its main thread will 2700c65ebfc7SToomas Soome * usually schedule DNSServiceRefs on its main queue (which is always a serial queue) 2701c65ebfc7SToomas Soome * using "DNSServiceSetDispatchQueue(sdref, dispatch_get_main_queue());" 2702c65ebfc7SToomas Soome * 2703c65ebfc7SToomas Soome * If there is any error during the processing of events, the application callback will 2704c65ebfc7SToomas Soome * be called with an error code. For shared connections, each subordinate DNSServiceRef 2705c65ebfc7SToomas Soome * will get its own error callback. Currently these error callbacks only happen 2706c65ebfc7SToomas Soome * if the daemon is manually terminated or crashes, and the error 2707c65ebfc7SToomas Soome * code in this case is kDNSServiceErr_ServiceNotRunning. The application must call 2708c65ebfc7SToomas Soome * DNSServiceRefDeallocate to free the DNSServiceRef when it gets such an error code. 2709c65ebfc7SToomas Soome * These error callbacks are rare and should not normally happen on customer machines, 2710c65ebfc7SToomas Soome * but application code should be written defensively to handle such error callbacks 2711c65ebfc7SToomas Soome * gracefully if they occur. 2712c65ebfc7SToomas Soome * 2713c65ebfc7SToomas Soome * After using DNSServiceSetDispatchQueue on a DNSServiceRef, calling DNSServiceProcessResult 2714c65ebfc7SToomas Soome * on the same DNSServiceRef will result in undefined behavior and should be avoided. 2715c65ebfc7SToomas Soome * 2716c65ebfc7SToomas Soome * Once the application successfully schedules a DNSServiceRef on a serial dispatch queue using 2717c65ebfc7SToomas Soome * DNSServiceSetDispatchQueue, it cannot remove the DNSServiceRef from the dispatch queue, or use 2718c65ebfc7SToomas Soome * DNSServiceSetDispatchQueue a second time to schedule the DNSServiceRef onto a different serial dispatch 2719c65ebfc7SToomas Soome * queue. Once scheduled onto a dispatch queue a DNSServiceRef will deliver events to that queue until 2720c65ebfc7SToomas Soome * the application no longer requires that operation and terminates it using DNSServiceRefDeallocate. 2721*472cd20dSToomas Soome * Note that the call to DNSServiceRefDeallocate() must be done on the same queue originally passed 2722*472cd20dSToomas Soome * as an argument to DNSServiceSetDispatchQueue(). 2723c65ebfc7SToomas Soome * 2724c65ebfc7SToomas Soome * service: DNSServiceRef that was allocated and returned to the application, when the 2725c65ebfc7SToomas Soome * application calls one of the DNSService API. 2726c65ebfc7SToomas Soome * 2727c65ebfc7SToomas Soome * queue: dispatch queue where the application callback will be scheduled 2728c65ebfc7SToomas Soome * 2729c65ebfc7SToomas Soome * return value: Returns kDNSServiceErr_NoError on success. 2730c65ebfc7SToomas Soome * Returns kDNSServiceErr_NoMemory if it cannot create a dispatch source 2731c65ebfc7SToomas Soome * Returns kDNSServiceErr_BadParam if the service param is invalid or the 2732c65ebfc7SToomas Soome * queue param is invalid 2733c65ebfc7SToomas Soome */ 2734c65ebfc7SToomas Soome 27353b436d06SToomas Soome DNSSD_EXPORT 2736c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceSetDispatchQueue 2737c65ebfc7SToomas Soome ( 2738c65ebfc7SToomas Soome DNSServiceRef service, 2739c65ebfc7SToomas Soome dispatch_queue_t queue 2740c65ebfc7SToomas Soome ); 2741c65ebfc7SToomas Soome #endif //_DNS_SD_LIBDISPATCH 2742c65ebfc7SToomas Soome 2743c65ebfc7SToomas Soome #if !defined(_WIN32) 2744c65ebfc7SToomas Soome typedef void (DNSSD_API *DNSServiceSleepKeepaliveReply) 2745c65ebfc7SToomas Soome ( 2746c65ebfc7SToomas Soome DNSServiceRef sdRef, 2747c65ebfc7SToomas Soome DNSServiceErrorType errorCode, 2748c65ebfc7SToomas Soome void *context 2749c65ebfc7SToomas Soome ); 27503b436d06SToomas Soome DNSSD_EXPORT 2751c65ebfc7SToomas Soome DNSServiceErrorType DNSSD_API DNSServiceSleepKeepalive 2752c65ebfc7SToomas Soome ( 2753c65ebfc7SToomas Soome DNSServiceRef *sdRef, 2754c65ebfc7SToomas Soome DNSServiceFlags flags, 2755c65ebfc7SToomas Soome int fd, 2756c65ebfc7SToomas Soome unsigned int timeout, 2757c65ebfc7SToomas Soome DNSServiceSleepKeepaliveReply callBack, 2758c65ebfc7SToomas Soome void *context 2759c65ebfc7SToomas Soome ); 2760c65ebfc7SToomas Soome #endif 2761c65ebfc7SToomas Soome 2762c65ebfc7SToomas Soome /* Some C compiler cleverness. We can make the compiler check certain things for us, 2763c65ebfc7SToomas Soome * and report errors at compile-time if anything is wrong. The usual way to do this would 2764c65ebfc7SToomas Soome * be to use a run-time "if" statement or the conventional run-time "assert" mechanism, but 2765c65ebfc7SToomas Soome * then you don't find out what's wrong until you run the software. This way, if the assertion 2766c65ebfc7SToomas Soome * condition is false, the array size is negative, and the complier complains immediately. 2767c65ebfc7SToomas Soome */ 2768c65ebfc7SToomas Soome 2769c65ebfc7SToomas Soome struct CompileTimeAssertionChecks_DNS_SD 2770c65ebfc7SToomas Soome { 2771c65ebfc7SToomas Soome char assert0[(sizeof(union _TXTRecordRef_t) == 16) ? 1 : -1]; 2772c65ebfc7SToomas Soome }; 2773c65ebfc7SToomas Soome 2774c65ebfc7SToomas Soome #ifdef __cplusplus 2775c65ebfc7SToomas Soome } 2776c65ebfc7SToomas Soome #endif 2777c65ebfc7SToomas Soome 2778c65ebfc7SToomas Soome #endif /* _DNS_SD_H */ 2779