147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* -*- Mode: C; tab-width: 4 -*- 247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Copyright (c) 2003-2004, Apple Computer, Inc. All rights reserved. 447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Redistribution and use in source and binary forms, with or without 647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * modification, are permitted provided that the following conditions are met: 747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 1. Redistributions of source code must retain the above copyright notice, 947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * this list of conditions and the following disclaimer. 1047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 2. Redistributions in binary form must reproduce the above copyright notice, 1147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * this list of conditions and the following disclaimer in the documentation 1247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and/or other materials provided with the distribution. 1347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 3. Neither the name of Apple Computer, Inc. ("Apple") nor the names of its 1447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * contributors may be used to endorse or promote products derived from this 1547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * software without specific prior written permission. 1647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 1747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * THIS SOFTWARE IS PROVIDED BY APPLE AND ITS CONTRIBUTORS "AS IS" AND ANY 1847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED 1947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE 2047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DISCLAIMED. IN NO EVENT SHALL APPLE OR ITS CONTRIBUTORS BE LIABLE FOR ANY 2147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES 2247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 2347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND 2447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 2547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS 2647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 2747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 2847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 2947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 3047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/*! @header DNS Service Discovery 3147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 3247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * @discussion This section describes the functions, callbacks, and data structures 3347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * that make up the DNS Service Discovery API. 3447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 3547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The DNS Service Discovery API is part of Bonjour, Apple's implementation 3647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * of zero-configuration networking (ZEROCONF). 3747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 3847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Bonjour allows you to register a network service, such as a 3947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * printer or file server, so that it can be found by name or browsed 4047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * for by service type and domain. Using Bonjour, applications can 4147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * discover what services are available on the network, along with 4247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * all the information -- such as name, IP address, and port -- 4347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * necessary to access a particular service. 4447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 4547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * In effect, Bonjour combines the functions of a local DNS server and 4647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * AppleTalk. Bonjour allows applications to provide user-friendly printer 4747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and server browsing, among other things, over standard IP networks. 4847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This behavior is a result of combining protocols such as multicast and 4947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNS to add new functionality to the network (such as multicast DNS). 5047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 5147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Bonjour gives applications easy access to services over local IP 5247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * networks without requiring the service or the application to support 5347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * an AppleTalk or a Netbeui stack, and without requiring a DNS server 5447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * for the local network. 5547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 5647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 5747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 5847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* _DNS_SD_H contains the mDNSResponder version number for this header file, formatted as follows: 5947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Major part of the build number * 10000 + 6047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * minor part of the build number * 100 6147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For example, Mac OS X 10.4.9 has mDNSResponder-108.4, which would be represented as 6247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * version 1080400. This allows C code to do simple greater-than and less-than comparisons: 6347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * e.g. an application that requires the DNSServiceGetProperty() call (new in mDNSResponder-126) can check: 6447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 6547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * #if _DNS_SD_H+0 >= 1260000 6647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ... some C code that calls DNSServiceGetProperty() ... 6747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * #endif 6847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 6947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The version defined in this header file symbol allows for compile-time 7047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * checking, so that C code building with earlier versions of the header file 7147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * can avoid compile errors trying to use functions that aren't even defined 7247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in those earlier versions. Similar checks may also be performed at run-time: 7347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * => weak linking -- to avoid link failures if run with an earlier 7447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * version of the library that's missing some desired symbol, or 7547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * => DNSServiceGetProperty(DaemonVersion) -- to verify whether the running daemon 7647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ("system service" on Windows) meets some required minimum functionality level. 7747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 7847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 7947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#ifndef _DNS_SD_H 8047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define _DNS_SD_H 3201080 8147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 8247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#ifdef __cplusplus 8347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt extern "C" { 8447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif 8547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 8647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Set to 1 if libdispatch is supported 8747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: May also be set by project and/or Makefile 8847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 8947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#ifndef _DNS_SD_LIBDISPATCH 9047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define _DNS_SD_LIBDISPATCH 0 9147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif /* ndef _DNS_SD_LIBDISPATCH */ 9247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 9347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* standard calling convention under Win32 is __stdcall */ 9447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Note: When compiling Intel EFI (Extensible Firmware Interface) under MS Visual Studio, the */ 9547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* _WIN32 symbol is defined by the compiler even though it's NOT compiling code for Windows32 */ 9647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#if defined(_WIN32) && !defined(EFI32) && !defined(EFI64) 9747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define DNSSD_API __stdcall 9847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#else 9947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define DNSSD_API 10047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif 10147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 10247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* stdint.h does not exist on FreeBSD 4.x; its types are defined in sys/types.h instead */ 10347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#if defined(__FreeBSD__) && (__FreeBSD__ < 5) 10447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#include <sys/types.h> 10547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 10647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Likewise, on Sun, standard integer types are in sys/types.h */ 10747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#elif defined(__sun__) 10847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#include <sys/types.h> 10947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 11047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* EFI does not have stdint.h, or anything else equivalent */ 11147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#elif defined(EFI32) || defined(EFI64) || defined(EFIX64) 11247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#include "Tiano.h" 11347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#if !defined(_STDINT_H_) 11447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef UINT8 uint8_t; 11547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef INT8 int8_t; 11647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef UINT16 uint16_t; 11747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef INT16 int16_t; 11847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef UINT32 uint32_t; 11947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef INT32 int32_t; 12047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif 12147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Windows has its own differences */ 12247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#elif defined(_WIN32) 12347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#include <windows.h> 12447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define _UNUSED 12547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#ifndef _MSL_STDINT_H 12647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef UINT8 uint8_t; 12747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef INT8 int8_t; 12847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef UINT16 uint16_t; 12947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef INT16 int16_t; 13047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef UINT32 uint32_t; 13147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef INT32 int32_t; 13247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif 13347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 13447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* All other Posix platforms use stdint.h */ 13547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#else 13647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#include <stdint.h> 13747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif 13847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 13947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#if _DNS_SD_LIBDISPATCH 14047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#include <dispatch/dispatch.h> 14147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif 14247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 14347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceRef, DNSRecordRef 14447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 14547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Opaque internal data types. 14647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: client is responsible for serializing access to these structures if 14747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * they are shared between concurrent threads. 14847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 14947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 15047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef struct _DNSServiceRef_t *DNSServiceRef; 15147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef struct _DNSRecordRef_t *DNSRecordRef; 15247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 15347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltstruct sockaddr; 15447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 15547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/*! @enum General flags 15647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most DNS-SD API functions and callbacks include a DNSServiceFlags parameter. 15747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * As a general rule, any given bit in the 32-bit flags field has a specific fixed meaning, 15847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * regardless of the function or callback being used. For any given function or callback, 15947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * typically only a subset of the possible flags are meaningful, and all others should be zero. 16047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The discussion section for each API call describes which flags are valid for that call 16147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and callback. In some cases, for a particular call, it may be that no flags are currently 16247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * defined, in which case the DNSServiceFlags parameter exists purely to allow future expansion. 16347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * In all cases, developers should expect that in future releases, it is possible that new flag 16447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * values will be defined, and write code with this in mind. For example, code that tests 16547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if (flags == kDNSServiceFlagsAdd) ... 16647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will fail if, in a future release, another bit in the 32-bit flags field is also set. 16747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The reliable way to test whether a particular bit is set is not with an equality test, 16847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * but with a bitwise mask: 16947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if (flags & kDNSServiceFlagsAdd) ... 17047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 17147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltenum 17247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt { 17347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsMoreComing = 0x1, 17447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* MoreComing indicates to a callback that at least one more result is 17547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * queued and will be delivered following immediately after this one. 17647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * When the MoreComing flag is set, applications should not immediately 17747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * update their UI, because this can result in a great deal of ugly flickering 17847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * on the screen, and can waste a great deal of CPU time repeatedly updating 17947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the screen with content that is then immediately erased, over and over. 18047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Applications should wait until until MoreComing is not set, and then 18147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * update their UI when no more changes are imminent. 18247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * When MoreComing is not set, that doesn't mean there will be no more 18347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * answers EVER, just that there are no more answers immediately 18447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * available right now at this instant. If more answers become available 18547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in the future they will be delivered as usual. 18647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 18747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 18847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsAdd = 0x2, 18947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsDefault = 0x4, 19047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flags for domain enumeration and browse/query reply callbacks. 19147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * "Default" applies only to enumeration and is only valid in 19247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * conjunction with "Add". An enumeration callback with the "Add" 19347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flag NOT set indicates a "Remove", i.e. the domain is no longer 19447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * valid. 19547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 19647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 19747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsNoAutoRename = 0x8, 19847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flag for specifying renaming behavior on name conflict when registering 19947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * non-shared records. By default, name conflicts are automatically handled 20047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * by renaming the service. NoAutoRename overrides this behavior - with this 20147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flag set, name conflicts will result in a callback. The NoAutorename flag 20247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is only valid if a name is explicitly specified when registering a service 20347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (i.e. the default name is not used.) 20447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 20547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 20647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsShared = 0x10, 20747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsUnique = 0x20, 20847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flag for registering individual records on a connected 20947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRef. Shared indicates that there may be multiple records 21047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * with this name on the network (e.g. PTR records). Unique indicates that the 21147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * record's name is to be unique on the network (e.g. SRV records). 21247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 21347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 21447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsBrowseDomains = 0x40, 21547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsRegistrationDomains = 0x80, 21647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flags for specifying domain enumeration type in DNSServiceEnumerateDomains. 21747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * BrowseDomains enumerates domains recommended for browsing, RegistrationDomains 21847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * enumerates domains recommended for registration. 21947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 22047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 22147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsLongLivedQuery = 0x100, 22247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flag for creating a long-lived unicast query for the DNSServiceQueryRecord call. */ 22347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 22447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsAllowRemoteQuery = 0x200, 22547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flag for creating a record for which we will answer remote queries 22647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (queries from hosts more than one hop away; hosts not directly connected to the local link). 22747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 22847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 22947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsForceMulticast = 0x400, 23047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flag for signifying that a query or registration should be performed exclusively via multicast 23147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNS, even for a name in a domain (e.g. foo.apple.com.) that would normally imply unicast DNS. 23247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 23347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 23447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsForce = 0x800, 23547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flag for signifying a "stronger" variant of an operation. 23647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Currently defined only for DNSServiceReconfirmRecord(), where it forces a record to 23747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * be removed from the cache immediately, instead of querying for a few seconds before 23847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * concluding that the record is no longer valid and then removing it. This flag should 23947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * be used with caution because if a service browsing PTR record is indeed still valid 24047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * on the network, forcing its removal will result in a user-interface flap -- the 24147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * discovered service instance will disappear, and then re-appear moments later. 24247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 24347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 24447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsReturnIntermediates = 0x1000, 24547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* Flag for returning intermediate results. 24647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For example, if a query results in an authoritative NXDomain (name does not exist) 24747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then that result is returned to the client. However the query is not implicitly 24847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * cancelled -- it remains active and if the answer subsequently changes 24947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (e.g. because a VPN tunnel is subsequently established) then that positive 25047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * result will still be returned to the client. 25147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Similarly, if a query results in a CNAME record, then in addition to following 25247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the CNAME referral, the intermediate CNAME result is also returned to the client. 25347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * When this flag is not set, NXDomain errors are not returned, and CNAME records 25447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * are followed silently without informing the client of the intermediate steps. 25547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (In earlier builds this flag was briefly calledkDNSServiceFlagsReturnCNAME) 25647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 25747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 25847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsNonBrowsable = 0x2000, 25947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* A service registered with the NonBrowsable flag set can be resolved using 26047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceResolve(), but will not be discoverable using DNSServiceBrowse(). 26147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This is for cases where the name is actually a GUID; it is found by other means; 26247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * there is no end-user benefit to browsing to find a long list of opaque GUIDs. 26347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Using the NonBrowsable flag creates SRV+TXT without the cost of also advertising 26447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * an associated PTR record. 26547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 26647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 26747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsShareConnection = 0x4000, 26847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* For efficiency, clients that perform many concurrent operations may want to use a 26947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * single Unix Domain Socket connection with the background daemon, instead of having a 27047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * separate connection for each independent operation. To use this mode, clients first 27147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * call DNSServiceCreateConnection(&MainRef) to initialize the main DNSServiceRef. 27247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For each subsequent operation that is to share that same connection, the client copies 27347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the MainRef, and then passes the address of that copy, setting the ShareConnection flag 27447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to tell the library that this DNSServiceRef is not a typical uninitialized DNSServiceRef; 27547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * it's a copy of an existing DNSServiceRef whose connection information should be reused. 27647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 27747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For example: 27847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 27947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceErrorType error; 28047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRef MainRef; 28147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * error = DNSServiceCreateConnection(&MainRef); 28247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if (error) ... 28347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRef BrowseRef = MainRef; // Important: COPY the primary DNSServiceRef first... 28447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * error = DNSServiceBrowse(&BrowseRef, kDNSServiceFlagsShareConnection, ...); // then use the copy 28547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if (error) ... 28647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ... 28747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRefDeallocate(BrowseRef); // Terminate the browse operation 28847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRefDeallocate(MainRef); // Terminate the shared connection 28947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 29047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Notes: 29147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 29247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 1. Collective kDNSServiceFlagsMoreComing flag 29347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * When callbacks are invoked using a shared DNSServiceRef, the 29447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsMoreComing flag applies collectively to *all* active 29547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * operations sharing the same parent DNSServiceRef. If the MoreComing flag is 29647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * set it means that there are more results queued on this parent DNSServiceRef, 29747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * but not necessarily more results for this particular callback function. 29847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The implication of this for client programmers is that when a callback 29947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is invoked with the MoreComing flag set, the code should update its 30047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * internal data structures with the new result, and set a variable indicating 30147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * that its UI needs to be updated. Then, later when a callback is eventually 30247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * invoked with the MoreComing flag not set, the code should update *all* 30347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * stale UI elements related to that shared parent DNSServiceRef that need 30447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * updating, not just the UI elements related to the particular callback 30547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * that happened to be the last one to be invoked. 30647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 30747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 2. Canceling operations and kDNSServiceFlagsMoreComing 30847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Whenever you cancel any operation for which you had deferred UI updates 30947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * waiting because of a kDNSServiceFlagsMoreComing flag, you should perform 31047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * those deferred UI updates. This is because, after cancelling the operation, 31147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * you can no longer wait for a callback *without* MoreComing set, to tell 31247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * you do perform your deferred UI updates (the operation has been canceled, 31347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * so there will be no more callbacks). An implication of the collective 31447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsMoreComing flag for shared connections is that this 31547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * guideline applies more broadly -- any time you cancel an operation on 31647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a shared connection, you should perform all deferred UI updates for all 31747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * operations sharing that connection. This is because the MoreComing flag 31847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * might have been referring to events coming for the operation you canceled, 31947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * which will now not be coming because the operation has been canceled. 32047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 32147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 3. Only share DNSServiceRef's created with DNSServiceCreateConnection 32247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Calling DNSServiceCreateConnection(&ref) creates a special shareable DNSServiceRef. 32347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRef's created by other calls like DNSServiceBrowse() or DNSServiceResolve() 32447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * cannot be shared by copying them and using kDNSServiceFlagsShareConnection. 32547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 32647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 4. Don't Double-Deallocate 32747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Calling DNSServiceRefDeallocate(ref) for a particular operation's DNSServiceRef terminates 32847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * just that operation. Calling DNSServiceRefDeallocate(ref) for the main shared DNSServiceRef 32947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (the parent DNSServiceRef, originally created by DNSServiceCreateConnection(&ref)) 33047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * automatically terminates the shared connection and all operations that were still using it. 33147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * After doing this, DO NOT then attempt to deallocate any remaining subordinate DNSServiceRef's. 33247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The memory used by those subordinate DNSServiceRef's has already been freed, so any attempt 33347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to do a DNSServiceRefDeallocate (or any other operation) on them will result in accesses 33447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to freed memory, leading to crashes or other equally undesirable results. 33547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 33647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 5. Thread Safety 33747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The dns_sd.h API does not presuppose any particular threading model, and consequently 33847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * does no locking of its own (which would require linking some specific threading library). 33947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If client code calls API routines on the same DNSServiceRef concurrently 34047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * from multiple threads, it is the client's responsibility to use a mutext 34147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * lock or take similar appropriate precautions to serialize those calls. 34247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 34347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 34447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsSuppressUnusable = 0x8000, 34547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* 34647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This flag is meaningful only in DNSServiceQueryRecord which suppresses unusable queries on the 34747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * wire. If "hostname" is a wide-area unicast DNS hostname (i.e. not a ".local." name) 34847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * but this host has no routable IPv6 address, then the call will not try to look up IPv6 addresses 34947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * for "hostname", since any addresses it found would be unlikely to be of any use anyway. Similarly, 35047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if this host has no routable IPv4 address, the call will not try to look up IPv4 addresses for 35147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * "hostname". 35247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 35347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 35447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsTimeout = 0x10000, 35547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* 35647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * When kDNServiceFlagsTimeout is passed to DNSServiceQueryRecord or DNSServiceGetAddrInfo, the query is 35747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * stopped after a certain number of seconds have elapsed. The time at which the query will be stopped 35847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is determined by the system and cannot be configured by the user. The query will be stopped irrespective 35947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * of whether a response was given earlier or not. When the query is stopped, the callback will be called 36047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * with an error code of kDNSServiceErr_Timeout and a NULL sockaddr will be returned for DNSServiceGetAddrInfo 36147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and zero length rdata will be returned for DNSServiceQueryRecord. 36247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 36347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 36447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsIncludeP2P = 0x20000, 36547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* 36647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Include P2P interfaces when kDNSServiceInterfaceIndexAny is specified. 36747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * By default, specifying kDNSServiceInterfaceIndexAny does not include P2P interfaces. 36847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 36947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceFlagsWakeOnResolve = 0x40000 37047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* 37147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This flag is meaningful only in DNSServiceResolve. When set, it tries to send a magic packet 37247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to wake up the client. 37347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 37447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt }; 37547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 37647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Possible protocols for DNSServiceNATPortMappingCreate(). */ 37747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltenum 37847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt { 37947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceProtocol_IPv4 = 0x01, 38047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceProtocol_IPv6 = 0x02, 38147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* 0x04 and 0x08 reserved for future internetwork protocols */ 38247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 38347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceProtocol_UDP = 0x10, 38447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceProtocol_TCP = 0x20 38547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* 0x40 and 0x80 reserved for future transport protocols, e.g. SCTP [RFC 2960] 38647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or DCCP [RFC 4340]. If future NAT gateways are created that support port 38747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * mappings for these protocols, new constants will be defined here. 38847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 38947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt }; 39047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 39147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* 39247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The values for DNS Classes and Types are listed in RFC 1035, and are available 39347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * on every OS in its DNS header file. Unfortunately every OS does not have the 39447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * same header file containing DNS Class and Type constants, and the names of 39547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the constants are not consistent. For example, BIND 8 uses "T_A", 39647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * BIND 9 uses "ns_t_a", Windows uses "DNS_TYPE_A", etc. 39747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For this reason, these constants are also listed here, so that code using 39847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the DNS-SD programming APIs can use these constants, so that the same code 39947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * can compile on all our supported platforms. 40047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 40147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 40247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltenum 40347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt { 40447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceClass_IN = 1 /* Internet */ 40547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt }; 40647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 40747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltenum 40847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt { 40947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_A = 1, /* Host address. */ 41047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NS = 2, /* Authoritative server. */ 41147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MD = 3, /* Mail destination. */ 41247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MF = 4, /* Mail forwarder. */ 41347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_CNAME = 5, /* Canonical name. */ 41447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_SOA = 6, /* Start of authority zone. */ 41547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MB = 7, /* Mailbox domain name. */ 41647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MG = 8, /* Mail group member. */ 41747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MR = 9, /* Mail rename name. */ 41847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NULL = 10, /* Null resource record. */ 41947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_WKS = 11, /* Well known service. */ 42047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_PTR = 12, /* Domain name pointer. */ 42147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_HINFO = 13, /* Host information. */ 42247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MINFO = 14, /* Mailbox information. */ 42347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MX = 15, /* Mail routing information. */ 42447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_TXT = 16, /* One or more text strings (NOT "zero or more..."). */ 42547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_RP = 17, /* Responsible person. */ 42647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_AFSDB = 18, /* AFS cell database. */ 42747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_X25 = 19, /* X_25 calling address. */ 42847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_ISDN = 20, /* ISDN calling address. */ 42947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_RT = 21, /* Router. */ 43047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NSAP = 22, /* NSAP address. */ 43147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NSAP_PTR = 23, /* Reverse NSAP lookup (deprecated). */ 43247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_SIG = 24, /* Security signature. */ 43347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_KEY = 25, /* Security key. */ 43447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_PX = 26, /* X.400 mail mapping. */ 43547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_GPOS = 27, /* Geographical position (withdrawn). */ 43647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_AAAA = 28, /* IPv6 Address. */ 43747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_LOC = 29, /* Location Information. */ 43847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NXT = 30, /* Next domain (security). */ 43947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_EID = 31, /* Endpoint identifier. */ 44047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NIMLOC = 32, /* Nimrod Locator. */ 44147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_SRV = 33, /* Server Selection. */ 44247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_ATMA = 34, /* ATM Address */ 44347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NAPTR = 35, /* Naming Authority PoinTeR */ 44447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_KX = 36, /* Key Exchange */ 44547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_CERT = 37, /* Certification record */ 44647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_A6 = 38, /* IPv6 Address (deprecated) */ 44747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_DNAME = 39, /* Non-terminal DNAME (for IPv6) */ 44847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_SINK = 40, /* Kitchen sink (experimental) */ 44947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_OPT = 41, /* EDNS0 option (meta-RR) */ 45047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_APL = 42, /* Address Prefix List */ 45147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_DS = 43, /* Delegation Signer */ 45247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_SSHFP = 44, /* SSH Key Fingerprint */ 45347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_IPSECKEY = 45, /* IPSECKEY */ 45447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_RRSIG = 46, /* RRSIG */ 45547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NSEC = 47, /* Denial of Existence */ 45647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_DNSKEY = 48, /* DNSKEY */ 45747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_DHCID = 49, /* DHCP Client Identifier */ 45847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NSEC3 = 50, /* Hashed Authenticated Denial of Existence */ 45947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_NSEC3PARAM = 51, /* Hashed Authenticated Denial of Existence */ 46047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 46147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_HIP = 55, /* Host Identity Protocol */ 46247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 46347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_SPF = 99, /* Sender Policy Framework for E-Mail */ 46447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_UINFO = 100, /* IANA-Reserved */ 46547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_UID = 101, /* IANA-Reserved */ 46647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_GID = 102, /* IANA-Reserved */ 46747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_UNSPEC = 103, /* IANA-Reserved */ 46847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 46947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_TKEY = 249, /* Transaction key */ 47047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_TSIG = 250, /* Transaction signature. */ 47147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_IXFR = 251, /* Incremental zone transfer. */ 47247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_AXFR = 252, /* Transfer zone of authority. */ 47347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MAILB = 253, /* Transfer mailbox records. */ 47447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_MAILA = 254, /* Transfer mail agent records. */ 47547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceType_ANY = 255 /* Wildcard match. */ 47647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt }; 47747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 47847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* possible error code values */ 47947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltenum 48047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt { 48147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NoError = 0, 48247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_Unknown = -65537, /* 0xFFFE FFFF */ 48347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NoSuchName = -65538, 48447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NoMemory = -65539, 48547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_BadParam = -65540, 48647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_BadReference = -65541, 48747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_BadState = -65542, 48847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_BadFlags = -65543, 48947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_Unsupported = -65544, 49047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NotInitialized = -65545, 49147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_AlreadyRegistered = -65547, 49247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NameConflict = -65548, 49347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_Invalid = -65549, 49447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_Firewall = -65550, 49547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_Incompatible = -65551, /* client library incompatible with daemon */ 49647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_BadInterfaceIndex = -65552, 49747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_Refused = -65553, 49847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NoSuchRecord = -65554, 49947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NoAuth = -65555, 50047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NoSuchKey = -65556, 50147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NATTraversal = -65557, 50247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_DoubleNAT = -65558, 50347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_BadTime = -65559, /* Codes up to here existed in Tiger */ 50447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_BadSig = -65560, 50547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_BadKey = -65561, 50647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_Transient = -65562, 50747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_ServiceNotRunning = -65563, /* Background daemon not running */ 50847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NATPortMappingUnsupported = -65564, /* NAT doesn't support NAT-PMP or UPnP */ 50947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NATPortMappingDisabled = -65565, /* NAT supports NAT-PMP or UPnP but it's disabled by the administrator */ 51047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_NoRouter = -65566, /* No router currently configured (probably no network connectivity) */ 51147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_PollingMode = -65567, 51247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt kDNSServiceErr_Timeout = -65568 51347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 51447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt /* mDNS Error codes are in the range 51547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * FFFE FF00 (-65792) to FFFE FFFF (-65537) */ 51647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt }; 51747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 51847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Maximum length, in bytes, of a service name represented as a */ 51947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* literal C-String, including the terminating NULL at the end. */ 52047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 52147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceMaxServiceName 64 52247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 52347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Maximum length, in bytes, of a domain name represented as an *escaped* C-String */ 52447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* including the final trailing dot, and the C-String terminating NULL at the end. */ 52547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 52647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceMaxDomainName 1009 52747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 52847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* 52947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Notes on DNS Name Escaping 53047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * -- or -- 53147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * "Why is kDNSServiceMaxDomainName 1009, when the maximum legal domain name is 256 bytes?" 53247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 53347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * All strings used in the DNS-SD APIs are UTF-8 strings. Apart from the exceptions noted below, 53447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the APIs expect the strings to be properly escaped, using the conventional DNS escaping rules: 53547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 53647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * '\\' represents a single literal '\' in the name 53747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * '\.' represents a single literal '.' in the name 53847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * '\ddd', where ddd is a three-digit decimal value from 000 to 255, 53947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * represents a single literal byte with that value. 54047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * A bare unescaped '.' is a label separator, marking a boundary between domain and subdomain. 54147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 54247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The exceptions, that do not use escaping, are the routines where the full 54347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNS name of a resource is broken, for convenience, into servicename/regtype/domain. 54447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * In these routines, the "servicename" is NOT escaped. It does not need to be, since 54547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * it is, by definition, just a single literal string. Any characters in that string 54647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * represent exactly what they are. The "regtype" portion is, technically speaking, 54747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * escaped, but since legal regtypes are only allowed to contain letters, digits, 54847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and hyphens, there is nothing to escape, so the issue is moot. The "domain" 54947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * portion is also escaped, though most domains in use on the public Internet 55047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * today, like regtypes, don't contain any characters that need to be escaped. 55147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * As DNS-SD becomes more popular, rich-text domains for service discovery will 55247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * become common, so software should be written to cope with domains with escaping. 55347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 55447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The servicename may be up to 63 bytes of UTF-8 text (not counting the C-String 55547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * terminating NULL at the end). The regtype is of the form _service._tcp or 55647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * _service._udp, where the "service" part is 1-15 characters, which may be 55747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * letters, digits, or hyphens. The domain part of the three-part name may be 55847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * any legal domain, providing that the resulting servicename+regtype+domain 55947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * name does not exceed 256 bytes. 56047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 56147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For most software, these issues are transparent. When browsing, the discovered 56247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * servicenames should simply be displayed as-is. When resolving, the discovered 56347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * servicename/regtype/domain are simply passed unchanged to DNSServiceResolve(). 56447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * When a DNSServiceResolve() succeeds, the returned fullname is already in 56547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the correct format to pass to standard system DNS APIs such as res_query(). 56647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For converting from servicename/regtype/domain to a single properly-escaped 56747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * full DNS name, the helper function DNSServiceConstructFullName() is provided. 56847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 56947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The following (highly contrived) example illustrates the escaping process. 57047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Suppose you have an service called "Dr. Smith\Dr. Johnson", of type "_ftp._tcp" 57147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in subdomain "4th. Floor" of subdomain "Building 2" of domain "apple.com." 57247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The full (escaped) DNS name of this service's SRV record would be: 57347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Dr\.\032Smith\\Dr\.\032Johnson._ftp._tcp.4th\.\032Floor.Building\0322.apple.com. 57447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 57547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 57647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 57747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* 57847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Constants for specifying an interface index 57947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 58047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Specific interface indexes are identified via a 32-bit unsigned integer returned 58147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * by the if_nametoindex() family of calls. 58247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 58347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the client passes 0 for interface index, that means "do the right thing", 58447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * which (at present) means, "if the name is in an mDNS local multicast domain 58547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (e.g. 'local.', '254.169.in-addr.arpa.', '{8,9,A,B}.E.F.ip6.arpa.') then multicast 58647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * on all applicable interfaces, otherwise send via unicast to the appropriate 58747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNS server." Normally, most clients will use 0 for interface index to 58847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * automatically get the default sensible behaviour. 58947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 59047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the client passes a positive interface index, then for multicast names that 59147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * indicates to do the operation only on that one interface. For unicast names the 59247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interface index is ignored unless kDNSServiceFlagsForceMulticast is also set. 59347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 59447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the client passes kDNSServiceInterfaceIndexLocalOnly when registering 59547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a service, then that service will be found *only* by other local clients 59647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * on the same machine that are browsing using kDNSServiceInterfaceIndexLocalOnly 59747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or kDNSServiceInterfaceIndexAny. 59847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If a client has a 'private' service, accessible only to other processes 59947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * running on the same machine, this allows the client to advertise that service 60047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in a way such that it does not inadvertently appear in service lists on 60147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * all the other machines on the network. 60247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 60347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the client passes kDNSServiceInterfaceIndexLocalOnly when browsing 60447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then it will find *all* records registered on that same local machine. 60547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Clients explicitly wishing to discover *only* LocalOnly services can 60647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * accomplish this by inspecting the interfaceIndex of each service reported 60747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to their DNSServiceBrowseReply() callback function, and discarding those 60847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * where the interface index is not kDNSServiceInterfaceIndexLocalOnly. 60947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 61047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceInterfaceIndexP2P is meaningful only in Browse, QueryRecord, 61147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and Resolve operations. It should not be used in other DNSService APIs. 61247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 61347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceBrowse or 61447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceQueryRecord, it restricts the operation to P2P. 61547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 61647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - If kDNSServiceInterfaceIndexP2P is passed to DNSServiceResolve, it is 61747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * mapped internally to kDNSServiceInterfaceIndexAny, because resolving 61847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a P2P service may create and/or enable an interface whose index is not 61947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * known a priori. The resolve callback will indicate the index of the 62047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interface via which the service can be accessed. 62147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 62247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If applications pass kDNSServiceInterfaceIndexAny to DNSServiceBrowse 62347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or DNSServiceQueryRecord, they must set the kDNSServiceFlagsIncludeP2P flag 62447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to include P2P. In this case, if a service instance or the record being queried 62547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is found over P2P, the resulting ADD event will indicate kDNSServiceInterfaceIndexP2P 62647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * as the interface index. 62747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 62847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 62947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceInterfaceIndexAny 0 63047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceInterfaceIndexLocalOnly ((uint32_t)-1) 63147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceInterfaceIndexUnicast ((uint32_t)-2) 63247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceInterfaceIndexP2P ((uint32_t)-3) 63347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 63447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef uint32_t DNSServiceFlags; 63547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef uint32_t DNSServiceProtocol; 63647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef int32_t DNSServiceErrorType; 63747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 63847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 63947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 64047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 64147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Version checking 64247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 64347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 64447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 64547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceGetProperty() Parameters: 64647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 64747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * property: The requested property. 64847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Currently the only property defined is kDNSServiceProperty_DaemonVersion. 64947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 65047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * result: Place to store result. 65147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For retrieving DaemonVersion, this should be the address of a uint32_t. 65247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 65347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * size: Pointer to uint32_t containing size of the result location. 65447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For retrieving DaemonVersion, this should be sizeof(uint32_t). 65547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * On return the uint32_t is updated to the size of the data returned. 65647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For DaemonVersion, the returned size is always sizeof(uint32_t), but 65747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * future properties could be defined which return variable-sized results. 65847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 65947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success, or kDNSServiceErr_ServiceNotRunning 66047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if the daemon (or "system service" on Windows) is not running. 66147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 66247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 66347e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceGetProperty 66447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 66547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *property, /* Requested property (i.e. kDNSServiceProperty_DaemonVersion) */ 66647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *result, /* Pointer to place to store result */ 66747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t *size /* size of result location */ 66847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 66947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 67047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* 67147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * When requesting kDNSServiceProperty_DaemonVersion, the result pointer must point 67247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to a 32-bit unsigned integer, and the size parameter must be set to sizeof(uint32_t). 67347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 67447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * On return, the 32-bit unsigned integer contains the version number, formatted as follows: 67547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Major part of the build number * 10000 + 67647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * minor part of the build number * 100 67747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 67847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For example, Mac OS X 10.4.9 has mDNSResponder-108.4, which would be represented as 67947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * version 1080400. This allows applications to do simple greater-than and less-than comparisons: 68047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * e.g. an application that requires at least mDNSResponder-108.4 can check: 68147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 68247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if (version >= 1080400) ... 68347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 68447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Example usage: 68547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 68647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * uint32_t version; 68747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * uint32_t size = sizeof(version); 68847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceErrorType err = DNSServiceGetProperty(kDNSServiceProperty_DaemonVersion, &version, &size); 68947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if (!err) printf("Bonjour version is %d.%d\n", version / 10000, version / 100 % 100); 69047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 69147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 69247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceProperty_DaemonVersion "DaemonVersion" 69347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 69447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 69547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 69647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 69747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Unix Domain Socket access, DNSServiceRef deallocation, and data processing functions 69847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 69947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 70047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 70147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceRefSockFD() 70247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 70347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Access underlying Unix domain socket for an initialized DNSServiceRef. 70447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The DNS Service Discovery implementation uses this socket to communicate between the client and 70547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the mDNSResponder daemon. The application MUST NOT directly read from or write to this socket. 70647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Access to the socket is provided so that it can be used as a kqueue event source, a CFRunLoop 70747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * event source, in a select() loop, etc. When the underlying event management subsystem (kqueue/ 70847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * select/CFRunLoop etc.) indicates to the client that data is available for reading on the 70947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * socket, the client should call DNSServiceProcessResult(), which will extract the daemon's 71047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * reply from the socket, and pass it to the appropriate application callback. By using a run 71147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * loop or select(), results from the daemon can be processed asynchronously. Alternatively, 71247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a client can choose to fork a thread and have it loop calling "DNSServiceProcessResult(ref);" 71347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If DNSServiceProcessResult() is called when no data is available for reading on the socket, it 71447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will block until data does become available, and then process the data and return to the caller. 71547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * When data arrives on the socket, the client is responsible for calling DNSServiceProcessResult(ref) 71647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in a timely fashion -- if the client allows a large backlog of data to build up the daemon 71747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * may terminate the connection. 71847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 71947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A DNSServiceRef initialized by any of the DNSService calls. 72047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 72147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: The DNSServiceRef's underlying socket descriptor, or -1 on 72247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * error. 72347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 72447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 72547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltint DNSSD_API DNSServiceRefSockFD(DNSServiceRef sdRef); 72647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 72747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 72847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceProcessResult() 72947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 73047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Read a reply from the daemon, calling the appropriate application callback. This call will 73147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * block until the daemon's response is received. Use DNSServiceRefSockFD() in 73247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * conjunction with a run loop or select() to determine the presence of a response from the 73347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * server before calling this function to process the reply without blocking. Call this function 73447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * at any point if it is acceptable to block until the daemon's response arrives. Note that the 73547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * client is responsible for ensuring that DNSServiceProcessResult() is called whenever there is 73647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a reply from the daemon - the daemon may terminate its connection with a client that does not 73747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * process the daemon's responses. 73847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 73947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A DNSServiceRef initialized by any of the DNSService calls 74047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * that take a callback parameter. 74147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 74247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success, otherwise returns 74347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * an error code indicating the specific failure that occurred. 74447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 74547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 74647e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceProcessResult(DNSServiceRef sdRef); 74747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 74847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 74947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceRefDeallocate() 75047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 75147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Terminate a connection with the daemon and free memory associated with the DNSServiceRef. 75247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Any services or records registered with this DNSServiceRef will be deregistered. Any 75347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Browse, Resolve, or Query operations called with this reference will be terminated. 75447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 75547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: If the reference's underlying socket is used in a run loop or select() call, it should 75647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * be removed BEFORE DNSServiceRefDeallocate() is called, as this function closes the reference's 75747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * socket. 75847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 75947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: If the reference was initialized with DNSServiceCreateConnection(), any DNSRecordRefs 76047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * created via this reference will be invalidated by this call - the resource records are 76147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * deregistered, and their DNSRecordRefs may not be used in subsequent functions. Similarly, 76247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if the reference was initialized with DNSServiceRegister, and an extra resource record was 76347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * added to the service via DNSServiceAddRecord(), the DNSRecordRef created by the Add() call 76447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is invalidated when this function is called - the DNSRecordRef may not be used in subsequent 76547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * functions. 76647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 76747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: This call is to be used only with the DNSServiceRef defined by this API. It is 76847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * not compatible with dns_service_discovery_ref objects defined in the legacy Mach-based 76947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceDiscovery.h API. 77047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 77147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A DNSServiceRef initialized by any of the DNSService calls. 77247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 77347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 77447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 77547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltvoid DNSSD_API DNSServiceRefDeallocate(DNSServiceRef sdRef); 77647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 77747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 77847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 77947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 78047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Domain Enumeration 78147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 78247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 78347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 78447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceEnumerateDomains() 78547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 78647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Asynchronously enumerate domains available for browsing and registration. 78747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 78847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The enumeration MUST be cancelled via DNSServiceRefDeallocate() when no more domains 78947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * are to be found. 79047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 79147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note that the names returned are (like all of DNS-SD) UTF-8 strings, 79247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and are escaped using standard DNS escaping rules. 79347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (See "Notes on DNS Name Escaping" earlier in this file for more details.) 79447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * A graphical browser displaying a hierarchical tree-structured view should cut 79547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the names at the bare dots to yield individual labels, then de-escape each 79647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * label according to the escaping rules, and then display the resulting UTF-8 text. 79747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 79847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceDomainEnumReply Callback Parameters: 79947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 80047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: The DNSServiceRef initialized by DNSServiceEnumerateDomains(). 80147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 80247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Possible values are: 80347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsMoreComing 80447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsAdd 80547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsDefault 80647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 80747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: Specifies the interface on which the domain exists. (The index for a given 80847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interface is determined via the if_nametoindex() family of calls.) 80947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 81047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise indicates 81147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the failure that occurred (other parameters are undefined if errorCode is nonzero). 81247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 81347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * replyDomain: The name of the domain. 81447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 81547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: The context pointer passed to DNSServiceEnumerateDomains. 81647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 81747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 81847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 81947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef void (DNSSD_API *DNSServiceDomainEnumReply) 82047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 82147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 82247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 82347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 82447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceErrorType errorCode, 82547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *replyDomain, 82647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context 82747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 82847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 82947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 83047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceEnumerateDomains() Parameters: 83147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 83247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds 83347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError, 83447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and the enumeration operation will run indefinitely until the client 83547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate(). 83647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 83747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Possible values are: 83847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsBrowseDomains to enumerate domains recommended for browsing. 83947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsRegistrationDomains to enumerate domains recommended 84047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * for registration. 84147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 84247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: If non-zero, specifies the interface on which to look for domains. 84347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (the index for a given interface is determined via the if_nametoindex() 84447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * family of calls.) Most applications will pass 0 to enumerate domains on 84547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * all interfaces. See "Constants for specifying an interface index" for more details. 84647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 84747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callBack: The function to be called when a domain is found or the call asynchronously 84847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * fails. 84947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 85047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: An application context pointer which is passed to the callback function 85147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (may be NULL). 85247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 85347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 85447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errors are delivered to the callback), otherwise returns an error code indicating 85547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the error that occurred (the callback is not invoked and the DNSServiceRef 85647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is not initialized). 85747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 85847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 85947e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceEnumerateDomains 86047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 86147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef *sdRef, 86247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 86347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 86447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceDomainEnumReply callBack, 86547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context /* may be NULL */ 86647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 86747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 86847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 86947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 87047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 87147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Service Registration 87247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 87347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 87447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 87547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Register a service that is discovered via Browse() and Resolve() calls. 87647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 87747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRegisterReply() Callback Parameters: 87847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 87947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: The DNSServiceRef initialized by DNSServiceRegister(). 88047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 88147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: When a name is successfully registered, the callback will be 88247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * invoked with the kDNSServiceFlagsAdd flag set. When Wide-Area 88347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNS-SD is in use, it is possible for a single service to get 88447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * more than one success callback (e.g. one in the "local" multicast 88547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNS domain, and another in a wide-area unicast DNS domain). 88647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If a successfully-registered name later suffers a name conflict 88747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or similar problem and has to be deregistered, the callback will 88847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * be invoked with the kDNSServiceFlagsAdd flag not set. The callback 88947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is *not* invoked in the case where the caller explicitly terminates 89047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the service registration by calling DNSServiceRefDeallocate(ref); 89147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 89247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will 89347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * indicate the failure that occurred (including name conflicts, 89447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if the kDNSServiceFlagsNoAutoRename flag was used when registering.) 89547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Other parameters are undefined if errorCode is nonzero. 89647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 89747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * name: The service name registered (if the application did not specify a name in 89847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRegister(), this indicates what name was automatically chosen). 89947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 90047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * regtype: The type of service registered, as it was passed to the callout. 90147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 90247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * domain: The domain on which the service was registered (if the application did not 90347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * specify a domain in DNSServiceRegister(), this indicates the default domain 90447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * on which the service was registered). 90547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 90647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: The context pointer that was passed to the callout. 90747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 90847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 90947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 91047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef void (DNSSD_API *DNSServiceRegisterReply) 91147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 91247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 91347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 91447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceErrorType errorCode, 91547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *name, 91647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *regtype, 91747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *domain, 91847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context 91947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 92047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 92147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 92247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceRegister() Parameters: 92347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 92447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds 92547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError, 92647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and the registration will remain active indefinitely until the client 92747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate(). 92847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 92947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: If non-zero, specifies the interface on which to register the service 93047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (the index for a given interface is determined via the if_nametoindex() 93147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * family of calls.) Most applications will pass 0 to register on all 93247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * available interfaces. See "Constants for specifying an interface index" for more details. 93347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 93447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Indicates the renaming behavior on name conflict (most applications 93547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will pass 0). See flag definitions above for details. 93647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 93747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * name: If non-NULL, specifies the service name to be registered. 93847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most applications will not specify a name, in which case the computer 93947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * name is used (this name is communicated to the client via the callback). 94047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If a name is specified, it must be 1-63 bytes of UTF-8 text. 94147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the name is longer than 63 bytes it will be automatically truncated 94247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to a legal length, unless the NoAutoRename flag is set, 94347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in which case kDNSServiceErr_BadParam will be returned. 94447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 94547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * regtype: The service type followed by the protocol, separated by a dot 94647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (e.g. "_ftp._tcp"). The service type must be an underscore, followed 94747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * by 1-15 characters, which may be letters, digits, or hyphens. 94847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The transport protocol must be "_tcp" or "_udp". New service types 94947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * should be registered at <http://www.dns-sd.org/ServiceTypes.html>. 95047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 95147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Additional subtypes of the primary service type (where a service 95247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * type has defined subtypes) follow the primary service type in a 95347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * comma-separated list, with no additional spaces, e.g. 95447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * "_primarytype._tcp,_subtype1,_subtype2,_subtype3" 95547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Subtypes provide a mechanism for filtered browsing: A client browsing 95647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * for "_primarytype._tcp" will discover all instances of this type; 95747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a client browsing for "_primarytype._tcp,_subtype2" will discover only 95847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * those instances that were registered with "_subtype2" in their list of 95947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * registered subtypes. 96047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 96147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The subtype mechanism can be illustrated with some examples using the 96247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * dns-sd command-line tool: 96347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 96447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * % dns-sd -R Simple _test._tcp "" 1001 & 96547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * % dns-sd -R Better _test._tcp,HasFeatureA "" 1002 & 96647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * % dns-sd -R Best _test._tcp,HasFeatureA,HasFeatureB "" 1003 & 96747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 96847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Now: 96947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * % dns-sd -B _test._tcp # will find all three services 97047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * % dns-sd -B _test._tcp,HasFeatureA # finds "Better" and "Best" 97147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * % dns-sd -B _test._tcp,HasFeatureB # finds only "Best" 97247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 97347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Subtype labels may be up to 63 bytes long, and may contain any eight- 97447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * bit byte values, including zero bytes. However, due to the nature of 97547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * using a C-string-based API, conventional DNS escaping must be used for 97647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * dots ('.'), commas (','), backslashes ('\') and zero bytes, as shown below: 97747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 97847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * % dns-sd -R Test '_test._tcp,s\.one,s\,two,s\\three,s\000four' local 123 97947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 98047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * domain: If non-NULL, specifies the domain on which to advertise the service. 98147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most applications will not specify a domain, instead automatically 98247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * registering in the default domain(s). 98347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 98447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * host: If non-NULL, specifies the SRV target host name. Most applications 98547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will not specify a host, instead automatically using the machine's 98647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * default host name(s). Note that specifying a non-NULL host does NOT 98747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * create an address record for that host - the application is responsible 98847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * for ensuring that the appropriate address record exists, or creating it 98947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * via DNSServiceRegisterRecord(). 99047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 99147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * port: The port, in network byte order, on which the service accepts connections. 99247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Pass 0 for a "placeholder" service (i.e. a service that will not be discovered 99347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * by browsing, but will cause a name conflict if another client tries to 99447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * register that same name). Most clients will not use placeholder services. 99547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 99647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtLen: The length of the txtRecord, in bytes. Must be zero if the txtRecord is NULL. 99747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 99847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: The TXT record rdata. A non-NULL txtRecord MUST be a properly formatted DNS 99947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXT record, i.e. <length byte> <data> <length byte> <data> ... 100047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Passing NULL for the txtRecord is allowed as a synonym for txtLen=1, txtRecord="", 100147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * i.e. it creates a TXT record of length one containing a single empty string. 100247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * RFC 1035 doesn't allow a TXT record to contain *zero* strings, so a single empty 100347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * string is the smallest legal DNS TXT record. 100447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * As with the other parameters, the DNSServiceRegister call copies the txtRecord 100547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * data; e.g. if you allocated the storage for the txtRecord parameter with malloc() 100647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then you can safely free that memory right after the DNSServiceRegister call returns. 100747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 100847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callBack: The function to be called when the registration completes or asynchronously 100947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * fails. The client MAY pass NULL for the callback - The client will NOT be notified 101047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * of the default values picked on its behalf, and the client will NOT be notified of any 101147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * asynchronous errors (e.g. out of memory errors, etc.) that may prevent the registration 101247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * of the service. The client may NOT pass the NoAutoRename flag if the callback is NULL. 101347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The client may still deregister the service at any time via DNSServiceRefDeallocate(). 101447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 101547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: An application context pointer which is passed to the callback function 101647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (may be NULL). 101747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 101847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 101947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errors are delivered to the callback), otherwise returns an error code indicating 102047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the error that occurred (the callback is never invoked and the DNSServiceRef 102147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is not initialized). 102247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 102347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 102447e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceRegister 102547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 102647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef *sdRef, 102747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 102847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 102947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *name, /* may be NULL */ 103047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *regtype, 103147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *domain, /* may be NULL */ 103247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *host, /* may be NULL */ 103347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t port, /* In network byte order */ 103447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t txtLen, 103547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *txtRecord, /* may be NULL */ 103647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRegisterReply callBack, /* may be NULL */ 103747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context /* may be NULL */ 103847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 103947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 104047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 104147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceAddRecord() 104247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 104347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Add a record to a registered service. The name of the record will be the same as the 104447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * registered service's name. 104547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The record can later be updated or deregistered by passing the RecordRef initialized 104647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * by this function to DNSServiceUpdateRecord() or DNSServiceRemoveRecord(). 104747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 104847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note that the DNSServiceAddRecord/UpdateRecord/RemoveRecord are *NOT* thread-safe 104947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * with respect to a single DNSServiceRef. If you plan to have multiple threads 105047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in your program simultaneously add, update, or remove records from the same 105147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRef, then it's the caller's responsibility to use a mutext lock 105247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or take similar appropriate precautions to serialize those calls. 105347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 105447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Parameters; 105547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 105647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A DNSServiceRef initialized by DNSServiceRegister(). 105747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 105847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * RecordRef: A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this 105947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord(). 106047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the above DNSServiceRef is passed to DNSServiceRefDeallocate(), RecordRef is also 106147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * invalidated and may not be used further. 106247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 106347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Currently ignored, reserved for future use. 106447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 106547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrtype: The type of the record (e.g. kDNSServiceType_TXT, kDNSServiceType_SRV, etc) 106647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 106747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdlen: The length, in bytes, of the rdata. 106847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 106947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdata: The raw rdata to be contained in the added resource record. 107047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 107147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ttl: The time to live of the resource record, in seconds. 107247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most clients should pass 0 to indicate that the system should 107347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * select a sensible default value. 107447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 107547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an 107647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * error code indicating the error that occurred (the RecordRef is not initialized). 107747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 107847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 107947e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceAddRecord 108047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 108147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 108247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSRecordRef *RecordRef, 108347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 108447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrtype, 108547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rdlen, 108647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *rdata, 108747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t ttl 108847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 108947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 109047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 109147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceUpdateRecord 109247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 109347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Update a registered resource record. The record must either be: 109447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - The primary txt record of a service registered via DNSServiceRegister() 109547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - A record added to a registered service via DNSServiceAddRecord() 109647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - An individual record registered by DNSServiceRegisterRecord() 109747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 109847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Parameters: 109947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 110047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A DNSServiceRef that was initialized by DNSServiceRegister() 110147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or DNSServiceCreateConnection(). 110247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 110347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * RecordRef: A DNSRecordRef initialized by DNSServiceAddRecord, or NULL to update the 110447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * service's primary txt record. 110547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 110647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Currently ignored, reserved for future use. 110747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 110847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdlen: The length, in bytes, of the new rdata. 110947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 111047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdata: The new rdata to be contained in the updated resource record. 111147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 111247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ttl: The time to live of the updated resource record, in seconds. 111347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most clients should pass 0 to indicate that the system should 111447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * select a sensible default value. 111547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 111647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an 111747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * error code indicating the error that occurred. 111847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 111947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 112047e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceUpdateRecord 112147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 112247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 112347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSRecordRef RecordRef, /* may be NULL */ 112447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 112547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rdlen, 112647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *rdata, 112747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t ttl 112847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 112947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 113047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 113147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceRemoveRecord 113247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 113347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Remove a record previously added to a service record set via DNSServiceAddRecord(), or deregister 113447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * an record registered individually via DNSServiceRegisterRecord(). 113547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 113647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Parameters: 113747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 113847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A DNSServiceRef initialized by DNSServiceRegister() (if the 113947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * record being removed was registered via DNSServiceAddRecord()) or by 114047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceCreateConnection() (if the record being removed was registered via 114147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRegisterRecord()). 114247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 114347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * recordRef: A DNSRecordRef initialized by a successful call to DNSServiceAddRecord() 114447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or DNSServiceRegisterRecord(). 114547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 114647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Currently ignored, reserved for future use. 114747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 114847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success, otherwise returns an 114947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * error code indicating the error that occurred. 115047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 115147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 115247e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceRemoveRecord 115347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 115447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 115547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSRecordRef RecordRef, 115647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags 115747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 115847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 115947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 116047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 116147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 116247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Service Discovery 116347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 116447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 116547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 116647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Browse for instances of a service. 116747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 116847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceBrowseReply() Parameters: 116947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 117047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: The DNSServiceRef initialized by DNSServiceBrowse(). 117147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 117247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Possible values are kDNSServiceFlagsMoreComing and kDNSServiceFlagsAdd. 117347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * See flag definitions for details. 117447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 117547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: The interface on which the service is advertised. This index should 117647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * be passed to DNSServiceResolve() when resolving the service. 117747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 117847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise will 117947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * indicate the failure that occurred. Other parameters are undefined if 118047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the errorCode is nonzero. 118147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 118247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * serviceName: The discovered service name. This name should be displayed to the user, 118347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and stored for subsequent use in the DNSServiceResolve() call. 118447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 118547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * regtype: The service type, which is usually (but not always) the same as was passed 118647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to DNSServiceBrowse(). One case where the discovered service type may 118747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * not be the same as the requested service type is when using subtypes: 118847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The client may want to browse for only those ftp servers that allow 118947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * anonymous connections. The client will pass the string "_ftp._tcp,_anon" 119047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to DNSServiceBrowse(), but the type of the service that's discovered 119147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is simply "_ftp._tcp". The regtype for each discovered service instance 119247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * should be stored along with the name, so that it can be passed to 119347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceResolve() when the service is later resolved. 119447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 119547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * domain: The domain of the discovered service instance. This may or may not be the 119647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * same as the domain that was passed to DNSServiceBrowse(). The domain for each 119747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * discovered service instance should be stored along with the name, so that 119847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * it can be passed to DNSServiceResolve() when the service is later resolved. 119947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 120047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: The context pointer that was passed to the callout. 120147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 120247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 120347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 120447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef void (DNSSD_API *DNSServiceBrowseReply) 120547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 120647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 120747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 120847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 120947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceErrorType errorCode, 121047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *serviceName, 121147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *regtype, 121247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *replyDomain, 121347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context 121447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 121547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 121647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 121747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceBrowse() Parameters: 121847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 121947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds 122047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError, 122147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and the browse operation will run indefinitely until the client 122247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate(). 122347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 122447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Currently ignored, reserved for future use. 122547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 122647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: If non-zero, specifies the interface on which to browse for services 122747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (the index for a given interface is determined via the if_nametoindex() 122847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * family of calls.) Most applications will pass 0 to browse on all available 122947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaces. See "Constants for specifying an interface index" for more details. 123047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 123147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * regtype: The service type being browsed for followed by the protocol, separated by a 123247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * dot (e.g. "_ftp._tcp"). The transport protocol must be "_tcp" or "_udp". 123347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * A client may optionally specify a single subtype to perform filtered browsing: 123447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * e.g. browsing for "_primarytype._tcp,_subtype" will discover only those 123547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * instances of "_primarytype._tcp" that were registered specifying "_subtype" 123647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in their list of registered subtypes. 123747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 123847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * domain: If non-NULL, specifies the domain on which to browse for services. 123947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most applications will not specify a domain, instead browsing on the 124047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * default domain(s). 124147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 124247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callBack: The function to be called when an instance of the service being browsed for 124347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is found, or if the call asynchronously fails. 124447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 124547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: An application context pointer which is passed to the callback function 124647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (may be NULL). 124747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 124847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 124947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errors are delivered to the callback), otherwise returns an error code indicating 125047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the error that occurred (the callback is not invoked and the DNSServiceRef 125147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is not initialized). 125247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 125347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 125447e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceBrowse 125547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 125647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef *sdRef, 125747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 125847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 125947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *regtype, 126047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *domain, /* may be NULL */ 126147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceBrowseReply callBack, 126247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context /* may be NULL */ 126347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 126447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 126547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 126647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceResolve() 126747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 126847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Resolve a service name discovered via DNSServiceBrowse() to a target host name, port number, and 126947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txt record. 127047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 127147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: Applications should NOT use DNSServiceResolve() solely for txt record monitoring - use 127247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceQueryRecord() instead, as it is more efficient for this task. 127347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 127447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: When the desired results have been returned, the client MUST terminate the resolve by calling 127547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRefDeallocate(). 127647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 127747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: DNSServiceResolve() behaves correctly for typical services that have a single SRV record 127847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and a single TXT record. To resolve non-standard services with multiple SRV or TXT records, 127947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceQueryRecord() should be used. 128047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 128147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceResolveReply Callback Parameters: 128247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 128347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: The DNSServiceRef initialized by DNSServiceResolve(). 128447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 128547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Possible values: kDNSServiceFlagsMoreComing 128647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 128747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: The interface on which the service was resolved. 128847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 128947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode: Will be kDNSServiceErr_NoError (0) on success, otherwise will 129047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * indicate the failure that occurred. Other parameters are undefined if 129147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the errorCode is nonzero. 129247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 129347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * fullname: The full service domain name, in the form <servicename>.<protocol>.<domain>. 129447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (This name is escaped following standard DNS rules, making it suitable for 129547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * passing to standard system DNS APIs such as res_query(), or to the 129647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * special-purpose functions included in this API that take fullname parameters. 129747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * See "Notes on DNS Name Escaping" earlier in this file for more details.) 129847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 129947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * hosttarget: The target hostname of the machine providing the service. This name can 130047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * be passed to functions like gethostbyname() to identify the host's IP address. 130147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 130247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * port: The port, in network byte order, on which connections are accepted for this service. 130347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 130447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtLen: The length of the txt record, in bytes. 130547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 130647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: The service's primary txt record, in standard txt record format. 130747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 130847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: The context pointer that was passed to the callout. 130947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 131047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * NOTE: In earlier versions of this header file, the txtRecord parameter was declared "const char *" 131147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This is incorrect, since it contains length bytes which are values in the range 0 to 255, not -128 to +127. 131247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Depending on your compiler settings, this change may cause signed/unsigned mismatch warnings. 131347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * These should be fixed by updating your own callback function definition to match the corrected 131447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * function signature using "const unsigned char *txtRecord". Making this change may also fix inadvertent 131547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * bugs in your callback function, where it could have incorrectly interpreted a length byte with value 250 131647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * as being -6 instead, with various bad consequences ranging from incorrect operation to software crashes. 131747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If you need to maintain portable code that will compile cleanly with both the old and new versions of 131847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * this header file, you should update your callback function definition to use the correct unsigned value, 131947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and then in the place where you pass your callback function to DNSServiceResolve(), use a cast to eliminate 132047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the compiler warning, e.g.: 132147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceResolve(sd, flags, index, name, regtype, domain, (DNSServiceResolveReply)MyCallback, context); 132247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This will ensure that your code compiles cleanly without warnings (and more importantly, works correctly) 132347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * with both the old header and with the new corrected version. 132447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 132547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 132647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 132747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef void (DNSSD_API *DNSServiceResolveReply) 132847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 132947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 133047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 133147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 133247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceErrorType errorCode, 133347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *fullname, 133447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *hosttarget, 133547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t port, /* In network byte order */ 133647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t txtLen, 133747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const unsigned char *txtRecord, 133847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context 133947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 134047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 134147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 134247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceResolve() Parameters 134347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 134447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds 134547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError, 134647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and the resolve operation will run indefinitely until the client 134747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate(). 134847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 134947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Specifying kDNSServiceFlagsForceMulticast will cause query to be 135047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * performed with a link-local mDNS query, even if the name is an 135147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * apparently non-local name (i.e. a name not ending in ".local.") 135247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 135347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: The interface on which to resolve the service. If this resolve call is 135447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * as a result of a currently active DNSServiceBrowse() operation, then the 135547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex should be the index reported in the DNSServiceBrowseReply 135647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callback. If this resolve call is using information previously saved 135747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (e.g. in a preference file) for later use, then use interfaceIndex 0, because 135847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the desired service may now be reachable via a different physical interface. 135947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * See "Constants for specifying an interface index" for more details. 136047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 136147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * name: The name of the service instance to be resolved, as reported to the 136247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceBrowseReply() callback. 136347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 136447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * regtype: The type of the service instance to be resolved, as reported to the 136547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceBrowseReply() callback. 136647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 136747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * domain: The domain of the service instance to be resolved, as reported to the 136847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceBrowseReply() callback. 136947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 137047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callBack: The function to be called when a result is found, or if the call 137147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * asynchronously fails. 137247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 137347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: An application context pointer which is passed to the callback function 137447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (may be NULL). 137547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 137647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 137747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errors are delivered to the callback), otherwise returns an error code indicating 137847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the error that occurred (the callback is never invoked and the DNSServiceRef 137947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is not initialized). 138047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 138147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 138247e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceResolve 138347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 138447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef *sdRef, 138547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 138647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 138747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *name, 138847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *regtype, 138947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *domain, 139047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceResolveReply callBack, 139147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context /* may be NULL */ 139247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 139347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 139447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 139547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 139647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 139747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Querying Individual Specific Records 139847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 139947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 140047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 140147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceQueryRecord 140247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 140347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Query for an arbitrary DNS record. 140447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 140547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceQueryRecordReply() Callback Parameters: 140647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 140747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: The DNSServiceRef initialized by DNSServiceQueryRecord(). 140847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 140947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Possible values are kDNSServiceFlagsMoreComing and 141047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsAdd. The Add flag is NOT set for PTR records 141147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * with a ttl of 0, i.e. "Remove" events. 141247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 141347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: The interface on which the query was resolved (the index for a given 141447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interface is determined via the if_nametoindex() family of calls). 141547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * See "Constants for specifying an interface index" for more details. 141647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 141747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will 141847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * indicate the failure that occurred. Other parameters are undefined if 141947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode is nonzero. 142047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 142147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * fullname: The resource record's full domain name. 142247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 142347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrtype: The resource record's type (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc) 142447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 142547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrclass: The class of the resource record (usually kDNSServiceClass_IN). 142647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 142747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdlen: The length, in bytes, of the resource record rdata. 142847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 142947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdata: The raw rdata of the resource record. 143047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 143147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ttl: If the client wishes to cache the result for performance reasons, 143247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the TTL indicates how long the client may legitimately hold onto 143347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * this result, in seconds. After the TTL expires, the client should 143447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * consider the result no longer valid, and if it requires this data 143547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * again, it should be re-fetched with a new query. Of course, this 143647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * only applies to clients that cancel the asynchronous operation when 143747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * they get a result. Clients that leave the asynchronous operation 143847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * running can safely assume that the data remains valid until they 143947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * get another callback telling them otherwise. 144047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 144147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: The context pointer that was passed to the callout. 144247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 144347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 144447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 144547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef void (DNSSD_API *DNSServiceQueryRecordReply) 144647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 144747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 144847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 144947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 145047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceErrorType errorCode, 145147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *fullname, 145247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrtype, 145347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrclass, 145447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rdlen, 145547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *rdata, 145647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t ttl, 145747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context 145847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 145947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 146047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 146147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceQueryRecord() Parameters: 146247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 146347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds 146447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then it initializes the DNSServiceRef, returns kDNSServiceErr_NoError, 146547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and the query operation will run indefinitely until the client 146647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * terminates it by passing this DNSServiceRef to DNSServiceRefDeallocate(). 146747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 146847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: kDNSServiceFlagsForceMulticast or kDNSServiceFlagsLongLivedQuery. 146947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Pass kDNSServiceFlagsLongLivedQuery to create a "long-lived" unicast 147047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * query in a non-local domain. Without setting this flag, unicast queries 147147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will be one-shot - that is, only answers available at the time of the call 147247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will be returned. By setting this flag, answers (including Add and Remove 147347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * events) that become available after the initial call is made will generate 147447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callbacks. This flag has no effect on link-local multicast queries. 147547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 147647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: If non-zero, specifies the interface on which to issue the query 147747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (the index for a given interface is determined via the if_nametoindex() 147847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * family of calls.) Passing 0 causes the name to be queried for on all 147947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaces. See "Constants for specifying an interface index" for more details. 148047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 148147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * fullname: The full domain name of the resource record to be queried for. 148247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 148347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrtype: The numerical type of the resource record to be queried for 148447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc) 148547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 148647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrclass: The class of the resource record (usually kDNSServiceClass_IN). 148747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 148847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callBack: The function to be called when a result is found, or if the call 148947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * asynchronously fails. 149047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 149147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: An application context pointer which is passed to the callback function 149247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (may be NULL). 149347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 149447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 149547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errors are delivered to the callback), otherwise returns an error code indicating 149647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the error that occurred (the callback is never invoked and the DNSServiceRef 149747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is not initialized). 149847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 149947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 150047e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceQueryRecord 150147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 150247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef *sdRef, 150347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 150447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 150547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *fullname, 150647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrtype, 150747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrclass, 150847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceQueryRecordReply callBack, 150947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context /* may be NULL */ 151047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 151147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 151247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 151347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 151447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 151547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Unified lookup of both IPv4 and IPv6 addresses for a fully qualified hostname 151647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 151747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 151847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 151947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceGetAddrInfo 152047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 152147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Queries for the IP address of a hostname by using either Multicast or Unicast DNS. 152247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 152347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceGetAddrInfoReply() parameters: 152447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 152547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: The DNSServiceRef initialized by DNSServiceGetAddrInfo(). 152647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 152747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Possible values are kDNSServiceFlagsMoreComing and 152847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * kDNSServiceFlagsAdd. 152947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 153047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: The interface to which the answers pertain. 153147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 153247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will 153347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * indicate the failure that occurred. Other parameters are 153447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * undefined if errorCode is nonzero. 153547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 153647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * hostname: The fully qualified domain name of the host to be queried for. 153747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 153847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * address: IPv4 or IPv6 address. 153947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 154047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ttl: If the client wishes to cache the result for performance reasons, 154147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the TTL indicates how long the client may legitimately hold onto 154247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * this result, in seconds. After the TTL expires, the client should 154347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * consider the result no longer valid, and if it requires this data 154447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * again, it should be re-fetched with a new query. Of course, this 154547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * only applies to clients that cancel the asynchronous operation when 154647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * they get a result. Clients that leave the asynchronous operation 154747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * running can safely assume that the data remains valid until they 154847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * get another callback telling them otherwise. 154947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 155047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: The context pointer that was passed to the callout. 155147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 155247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 155347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 155447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef void (DNSSD_API *DNSServiceGetAddrInfoReply) 155547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 155647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 155747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 155847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 155947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceErrorType errorCode, 156047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *hostname, 156147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const struct sockaddr *address, 156247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t ttl, 156347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context 156447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 156547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 156647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 156747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceGetAddrInfo() Parameters: 156847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 156947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds then it 157047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * initializes the DNSServiceRef, returns kDNSServiceErr_NoError, and the query 157147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * begins and will last indefinitely until the client terminates the query 157247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * by passing this DNSServiceRef to DNSServiceRefDeallocate(). 157347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 157447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: kDNSServiceFlagsForceMulticast or kDNSServiceFlagsLongLivedQuery. 157547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Pass kDNSServiceFlagsLongLivedQuery to create a "long-lived" unicast 157647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * query in a non-local domain. Without setting this flag, unicast queries 157747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will be one-shot - that is, only answers available at the time of the call 157847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will be returned. By setting this flag, answers (including Add and Remove 157947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * events) that become available after the initial call is made will generate 158047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callbacks. This flag has no effect on link-local multicast queries. 158147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 158247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: The interface on which to issue the query. Passing 0 causes the query to be 158347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sent on all active interfaces via Multicast or the primary interface via Unicast. 158447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 158547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * protocol: Pass in kDNSServiceProtocol_IPv4 to look up IPv4 addresses, or kDNSServiceProtocol_IPv6 158647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to look up IPv6 addresses, or both to look up both kinds. If neither flag is 158747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * set, the system will apply an intelligent heuristic, which is (currently) 158847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * that it will attempt to look up both, except: 158947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 159047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * * If "hostname" is a wide-area unicast DNS hostname (i.e. not a ".local." name) 159147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * but this host has no routable IPv6 address, then the call will not try to 159247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * look up IPv6 addresses for "hostname", since any addresses it found would be 159347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * unlikely to be of any use anyway. Similarly, if this host has no routable 159447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * IPv4 address, the call will not try to look up IPv4 addresses for "hostname". 159547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 159647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * hostname: The fully qualified domain name of the host to be queried for. 159747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 159847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callBack: The function to be called when the query succeeds or fails asynchronously. 159947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 160047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: An application context pointer which is passed to the callback function 160147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (may be NULL). 160247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 160347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 160447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errors are delivered to the callback), otherwise returns an error code indicating 160547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the error that occurred. 160647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 160747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 160847e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceGetAddrInfo 160947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 161047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef *sdRef, 161147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 161247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 161347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceProtocol protocol, 161447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *hostname, 161547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceGetAddrInfoReply callBack, 161647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context /* may be NULL */ 161747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 161847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 161947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 162047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 162147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 162247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Special Purpose Calls: 162347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceCreateConnection(), DNSServiceRegisterRecord(), DNSServiceReconfirmRecord() 162447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (most applications will not use these) 162547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 162647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 162747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 162847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceCreateConnection() 162947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 163047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Create a connection to the daemon allowing efficient registration of 163147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * multiple individual records. 163247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 163347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Parameters: 163447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 163547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A pointer to an uninitialized DNSServiceRef. Deallocating 163647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the reference (via DNSServiceRefDeallocate()) severs the 163747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * connection and deregisters all records registered on this connection. 163847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 163947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success, otherwise returns 164047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * an error code indicating the specific failure that occurred (in which 164147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * case the DNSServiceRef is not initialized). 164247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 164347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 164447e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceCreateConnection(DNSServiceRef *sdRef); 164547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 164647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 164747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceRegisterRecord 164847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 164947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Register an individual resource record on a connected DNSServiceRef. 165047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 165147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note that name conflicts occurring for records registered via this call must be handled 165247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * by the client in the callback. 165347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 165447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRegisterRecordReply() parameters: 165547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 165647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: The connected DNSServiceRef initialized by 165747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceCreateConnection(). 165847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 165947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * RecordRef: The DNSRecordRef initialized by DNSServiceRegisterRecord(). If the above 166047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRef is passed to DNSServiceRefDeallocate(), this DNSRecordRef is 166147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * invalidated, and may not be used further. 166247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 166347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Currently unused, reserved for future use. 166447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 166547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode: Will be kDNSServiceErr_NoError on success, otherwise will 166647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * indicate the failure that occurred (including name conflicts.) 166747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Other parameters are undefined if errorCode is nonzero. 166847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 166947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: The context pointer that was passed to the callout. 167047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 167147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 167247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 167347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt typedef void (DNSSD_API *DNSServiceRegisterRecordReply) 167447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 167547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 167647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSRecordRef RecordRef, 167747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 167847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceErrorType errorCode, 167947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context 168047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 168147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 168247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 168347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceRegisterRecord() Parameters: 168447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 168547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A DNSServiceRef initialized by DNSServiceCreateConnection(). 168647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 168747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * RecordRef: A pointer to an uninitialized DNSRecordRef. Upon succesfull completion of this 168847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * call, this ref may be passed to DNSServiceUpdateRecord() or DNSServiceRemoveRecord(). 168947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (To deregister ALL records registered on a single connected DNSServiceRef 169047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and deallocate each of their corresponding DNSServiceRecordRefs, call 169147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRefDeallocate()). 169247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 169347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Possible values are kDNSServiceFlagsShared or kDNSServiceFlagsUnique 169447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (see flag type definitions for details). 169547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 169647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: If non-zero, specifies the interface on which to register the record 169747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (the index for a given interface is determined via the if_nametoindex() 169847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * family of calls.) Passing 0 causes the record to be registered on all interfaces. 169947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * See "Constants for specifying an interface index" for more details. 170047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 170147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * fullname: The full domain name of the resource record. 170247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 170347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrtype: The numerical type of the resource record (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc) 170447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 170547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrclass: The class of the resource record (usually kDNSServiceClass_IN) 170647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 170747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdlen: Length, in bytes, of the rdata. 170847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 170947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdata: A pointer to the raw rdata, as it is to appear in the DNS record. 171047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 171147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ttl: The time to live of the resource record, in seconds. 171247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most clients should pass 0 to indicate that the system should 171347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * select a sensible default value. 171447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 171547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callBack: The function to be called when a result is found, or if the call 171647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * asynchronously fails (e.g. because of a name conflict.) 171747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 171847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: An application context pointer which is passed to the callback function 171947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (may be NULL). 172047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 172147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 172247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errors are delivered to the callback), otherwise returns an error code indicating 172347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the error that occurred (the callback is never invoked and the DNSRecordRef is 172447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * not initialized). 172547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 172647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 172747e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceRegisterRecord 172847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 172947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 173047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSRecordRef *RecordRef, 173147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 173247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 173347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *fullname, 173447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrtype, 173547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrclass, 173647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rdlen, 173747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *rdata, 173847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t ttl, 173947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRegisterRecordReply callBack, 174047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context /* may be NULL */ 174147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 174247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 174347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 174447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceReconfirmRecord 174547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 174647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Instruct the daemon to verify the validity of a resource record that appears 174747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to be out of date (e.g. because TCP connection to a service's target failed.) 174847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Causes the record to be flushed from the daemon's cache (as well as all other 174947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * daemons' caches on the network) if the record is determined to be invalid. 175047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Use this routine conservatively. Reconfirming a record necessarily consumes 175147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * network bandwidth, so this should not be done indiscriminately. 175247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 175347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Parameters: 175447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 175547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Pass kDNSServiceFlagsForce to force immediate deletion of record, 175647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * instead of after some number of reconfirmation queries have gone unanswered. 175747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 175847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: Specifies the interface of the record in question. 175947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The caller must specify the interface. 176047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This API (by design) causes increased network traffic, so it requires 176147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the caller to be precise about which record should be reconfirmed. 176247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * It is not possible to pass zero for the interface index to perform 176347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a "wildcard" reconfirmation, where *all* matching records are reconfirmed. 176447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 176547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * fullname: The resource record's full domain name. 176647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 176747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrtype: The resource record's type (e.g. kDNSServiceType_PTR, kDNSServiceType_SRV, etc) 176847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 176947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rrclass: The class of the resource record (usually kDNSServiceClass_IN). 177047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 177147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdlen: The length, in bytes, of the resource record rdata. 177247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 177347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * rdata: The raw rdata of the resource record. 177447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 177547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 177647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 177747e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceReconfirmRecord 177847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 177947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 178047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 178147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *fullname, 178247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrtype, 178347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rrclass, 178447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t rdlen, 178547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *rdata 178647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 178747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 178847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 178947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 179047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 179147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * NAT Port Mapping 179247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 179347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 179447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 179547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceNATPortMappingCreate 179647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 179747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Request a port mapping in the NAT gateway, which maps a port on the local machine 179847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to an external port on the NAT. The NAT should support either the NAT-PMP or the UPnP IGD 179947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * protocol for this API to create a successful mapping. 180047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 180147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The port mapping will be renewed indefinitely until the client process exits, or 180247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * explicitly terminates the port mapping request by calling DNSServiceRefDeallocate(). 180347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The client callback will be invoked, informing the client of the NAT gateway's 180447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * external IP address and the external port that has been allocated for this client. 180547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The client should then record this external IP address and port using whatever 180647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * directory service mechanism it is using to enable peers to connect to it. 180747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (Clients advertising services using Wide-Area DNS-SD DO NOT need to use this API 180847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * -- when a client calls DNSServiceRegister() NAT mappings are automatically created 180947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and the external IP address and port for the service are recorded in the global DNS. 181047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Only clients using some directory mechanism other than Wide-Area DNS-SD need to use 181147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * this API to explicitly map their own ports.) 181247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 181347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * It's possible that the client callback could be called multiple times, for example 181447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if the NAT gateway's IP address changes, or if a configuration change results in a 181547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * different external port being mapped for this client. Over the lifetime of any long-lived 181647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * port mapping, the client should be prepared to handle these notifications of changes 181747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * in the environment, and should update its recorded address and/or port as appropriate. 181847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 181947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * NOTE: There are two unusual aspects of how the DNSServiceNATPortMappingCreate API works, 182047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * which were intentionally designed to help simplify client code: 182147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 182247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 1. It's not an error to request a NAT mapping when the machine is not behind a NAT gateway. 182347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * In other NAT mapping APIs, if you request a NAT mapping and the machine is not behind a NAT 182447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * gateway, then the API returns an error code -- it can't get you a NAT mapping if there's no 182547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * NAT gateway. The DNSServiceNATPortMappingCreate API takes a different view. Working out 182647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * whether or not you need a NAT mapping can be tricky and non-obvious, particularly on 182747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a machine with multiple active network interfaces. Rather than make every client recreate 182847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * this logic for deciding whether a NAT mapping is required, the PortMapping API does that 182947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * work for you. If the client calls the PortMapping API when the machine already has a 183047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * routable public IP address, then instead of complaining about it and giving an error, 183147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the PortMapping API just invokes your callback, giving the machine's public address 183247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and your own port number. This means you don't need to write code to work out whether 183347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * your client needs to call the PortMapping API -- just call it anyway, and if it wasn't 183447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * necessary, no harm is done: 183547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 183647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - If the machine already has a routable public IP address, then your callback 183747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will just be invoked giving your own address and port. 183847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - If a NAT mapping is required and obtained, then your callback will be invoked 183947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * giving you the external address and port. 184047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - If a NAT mapping is required but not obtained from the local NAT gateway, 184147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or the machine has no network connectivity, then your callback will be 184247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * invoked giving zero address and port. 184347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 184447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 2. In other NAT mapping APIs, if a laptop computer is put to sleep and woken up on a new 184547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * network, it's the client's job to notice this, and work out whether a NAT mapping 184647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is required on the new network, and make a new NAT mapping request if necessary. 184747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The DNSServiceNATPortMappingCreate API does this for you, automatically. 184847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The client just needs to make one call to the PortMapping API, and its callback will 184947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * be invoked any time the mapping state changes. This property complements point (1) above. 185047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the client didn't make a NAT mapping request just because it determined that one was 185147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * not required at that particular moment in time, the client would then have to monitor 185247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * for network state changes to determine if a NAT port mapping later became necessary. 185347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * By unconditionally making a NAT mapping request, even when a NAT mapping not to be 185447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * necessary, the PortMapping API will then begin monitoring network state changes on behalf of 185547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the client, and if a NAT mapping later becomes necessary, it will automatically create a NAT 185647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * mapping and inform the client with a new callback giving the new address and port information. 185747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 185847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceNATPortMappingReply() parameters: 185947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 186047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: The DNSServiceRef initialized by DNSServiceNATPortMappingCreate(). 186147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 186247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Currently unused, reserved for future use. 186347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 186447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: The interface through which the NAT gateway is reached. 186547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 186647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errorCode: Will be kDNSServiceErr_NoError on success. 186747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Will be kDNSServiceErr_DoubleNAT when the NAT gateway is itself behind one or 186847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * more layers of NAT, in which case the other parameters have the defined values. 186947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For other failures, will indicate the failure that occurred, and the other 187047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * parameters are undefined. 187147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 187247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * externalAddress: Four byte IPv4 address in network byte order. 187347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 187447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * protocol: Will be kDNSServiceProtocol_UDP or kDNSServiceProtocol_TCP or both. 187547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 187647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * internalPort: The port on the local machine that was mapped. 187747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 187847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * externalPort: The actual external port in the NAT gateway that was mapped. 187947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This is likely to be different than the requested external port. 188047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 188147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ttl: The lifetime of the NAT port mapping created on the gateway. 188247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This controls how quickly stale mappings will be garbage-collected 188347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if the client machine crashes, suffers a power failure, is disconnected 188447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * from the network, or suffers some other unfortunate demise which 188547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * causes it to vanish without explicitly removing its NAT port mapping. 188647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * It's possible that the ttl value will differ from the requested ttl value. 188747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 188847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: The context pointer that was passed to the callout. 188947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 189047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 189147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 189247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef void (DNSSD_API *DNSServiceNATPortMappingReply) 189347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 189447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef sdRef, 189547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 189647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 189747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceErrorType errorCode, 189847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t externalAddress, /* four byte IPv4 address in network byte order */ 189947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceProtocol protocol, 190047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t internalPort, /* In network byte order */ 190147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t externalPort, /* In network byte order and may be different than the requested port */ 190247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t ttl, /* may be different than the requested ttl */ 190347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context 190447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 190547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 190647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 190747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceNATPortMappingCreate() Parameters: 190847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 190947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * sdRef: A pointer to an uninitialized DNSServiceRef. If the call succeeds then it 191047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * initializes the DNSServiceRef, returns kDNSServiceErr_NoError, and the nat 191147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * port mapping will last indefinitely until the client terminates the port 191247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * mapping request by passing this DNSServiceRef to DNSServiceRefDeallocate(). 191347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 191447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * flags: Currently ignored, reserved for future use. 191547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 191647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * interfaceIndex: The interface on which to create port mappings in a NAT gateway. Passing 0 causes 191747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the port mapping request to be sent on the primary interface. 191847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 191947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * protocol: To request a port mapping, pass in kDNSServiceProtocol_UDP, or kDNSServiceProtocol_TCP, 192047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or (kDNSServiceProtocol_UDP | kDNSServiceProtocol_TCP) to map both. 192147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The local listening port number must also be specified in the internalPort parameter. 192247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * To just discover the NAT gateway's external IP address, pass zero for protocol, 192347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * internalPort, externalPort and ttl. 192447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 192547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * internalPort: The port number in network byte order on the local machine which is listening for packets. 192647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 192747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * externalPort: The requested external port in network byte order in the NAT gateway that you would 192847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * like to map to the internal port. Pass 0 if you don't care which external port is chosen for you. 192947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 193047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ttl: The requested renewal period of the NAT port mapping, in seconds. 193147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the client machine crashes, suffers a power failure, is disconnected from 193247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the network, or suffers some other unfortunate demise which causes it to vanish 193347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * unexpectedly without explicitly removing its NAT port mappings, then the NAT gateway 193447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * will garbage-collect old stale NAT port mappings when their lifetime expires. 193547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Requesting a short TTL causes such orphaned mappings to be garbage-collected 193647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * more promptly, but consumes system resources and network bandwidth with 193747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * frequent renewal packets to keep the mapping from expiring. 193847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Requesting a long TTL is more efficient on the network, but in the event of the 193947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * client vanishing, stale NAT port mappings will not be garbage-collected as quickly. 194047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most clients should pass 0 to use a system-wide default value. 194147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 194247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callBack: The function to be called when the port mapping request succeeds or fails asynchronously. 194347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 194447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * context: An application context pointer which is passed to the callback function 194547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (may be NULL). 194647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 194747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success (any subsequent, asynchronous 194847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * errors are delivered to the callback), otherwise returns an error code indicating 194947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the error that occurred. 195047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 195147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If you don't actually want a port mapped, and are just calling the API 195247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * because you want to find out the NAT's external IP address (e.g. for UI 195347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * display) then pass zero for protocol, internalPort, externalPort and ttl. 195447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 195547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 195647e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceNATPortMappingCreate 195747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 195847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef *sdRef, 195947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceFlags flags, 196047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t interfaceIndex, 196147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceProtocol protocol, /* TCP and/or UDP */ 196247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t internalPort, /* network byte order */ 196347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t externalPort, /* network byte order */ 196447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint32_t ttl, /* time to live in seconds */ 196547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceNATPortMappingReply callBack, 196647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *context /* may be NULL */ 196747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 196847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 196947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 1970afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalttypedef void (DNSSD_API *DNSHostnameChangedReply) 1971afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt ( 1972afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt DNSServiceRef sdRef, 1973afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt DNSServiceFlags flags, 1974afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt DNSServiceErrorType errorCode, 1975afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt const char *hostname, 1976afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt void *context 1977afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt ); 1978afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt 1979afc86e3216439a9437ea54905853275111eac4e2Robert GreenwaltDNSServiceErrorType DNSSD_API DNSSetHostname 1980afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt ( 1981afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt DNSServiceRef *sdRef, 1982afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt DNSServiceFlags flags, 1983afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt const char *hostname, 1984afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt DNSHostnameChangedReply callBack, 1985afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt void *context 1986afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt ); 1987afc86e3216439a9437ea54905853275111eac4e2Robert Greenwalt 198847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 198947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 199047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * General Utility Functions 199147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 199247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 199347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 199447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* DNSServiceConstructFullName() 199547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 199647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Concatenate a three-part domain name (as returned by the above callbacks) into a 199747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * properly-escaped full domain name. Note that callbacks in the above functions ALREADY ESCAPE 199847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * strings where necessary. 199947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 200047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Parameters: 200147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 200247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * fullName: A pointer to a buffer that where the resulting full domain name is to be written. 200347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The buffer must be kDNSServiceMaxDomainName (1009) bytes in length to 200447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * accommodate the longest legal domain name without buffer overrun. 200547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 200647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * service: The service name - any dots or backslashes must NOT be escaped. 200747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * May be NULL (to construct a PTR record name, e.g. 200847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * "_ftp._tcp.apple.com."). 200947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 201047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * regtype: The service type followed by the protocol, separated by a dot 201147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * (e.g. "_ftp._tcp"). 201247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 201347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * domain: The domain name, e.g. "apple.com.". Literal dots or backslashes, 201447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if any, must be escaped, e.g. "1st\. Floor.apple.com." 201547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 201647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError (0) on success, kDNSServiceErr_BadParam on error. 201747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 201847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 201947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 202047e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceConstructFullName 202147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 202247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt char * const fullName, 202347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char * const service, /* may be NULL */ 202447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char * const regtype, 202547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char * const domain 202647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 202747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 202847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 202947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 203047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 203147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXT Record Construction Functions 203247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 203347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 203447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 203547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* 203647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * A typical calling sequence for TXT record construction is something like: 203747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 203847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Client allocates storage for TXTRecord data (e.g. declare buffer on the stack) 203947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXTRecordCreate(); 204047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXTRecordSetValue(); 204147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXTRecordSetValue(); 204247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXTRecordSetValue(); 204347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ... 204447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * DNSServiceRegister( ... TXTRecordGetLength(), TXTRecordGetBytesPtr() ... ); 204547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXTRecordDeallocate(); 204647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Explicitly deallocate storage for TXTRecord data (if not allocated on the stack) 204747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 204847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 204947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 205047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordRef 205147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 205247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Opaque internal data type. 205347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: Represents a DNS-SD TXT record. 205447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 205547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 205647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalttypedef union _TXTRecordRef_t { char PrivateData[16]; char *ForceNaturalAlignment; } TXTRecordRef; 205747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 205847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 205947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordCreate() 206047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 206147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Creates a new empty TXTRecordRef referencing the specified storage. 206247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 206347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If the buffer parameter is NULL, or the specified storage size is not 206447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * large enough to hold a key subsequently added using TXTRecordSetValue(), 206547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then additional memory will be added as needed using malloc(). 206647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 206747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * On some platforms, when memory is low, malloc() may fail. In this 206847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * case, TXTRecordSetValue() will return kDNSServiceErr_NoMemory, and this 206947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * error condition will need to be handled as appropriate by the caller. 207047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 207147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * You can avoid the need to handle this error condition if you ensure 207247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * that the storage you initially provide is large enough to hold all 207347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the key/value pairs that are to be added to the record. 207447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * The caller can precompute the exact length required for all of the 207547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * key/value pairs to be added, or simply provide a fixed-sized buffer 207647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * known in advance to be large enough. 207747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * A no-value (key-only) key requires (1 + key length) bytes. 207847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * A key with empty value requires (1 + key length + 1) bytes. 207947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * A key with non-empty value requires (1 + key length + 1 + value length). 208047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For most applications, DNS-SD TXT records are generally 208147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * less than 100 bytes, so in most cases a simple fixed-sized 208247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 256-byte buffer will be more than sufficient. 208347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Recommended size limits for DNS-SD TXT Records are discussed in 208447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * <http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt> 208547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 208647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Note: When passing parameters to and from these TXT record APIs, 208747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the key name does not include the '=' character. The '=' character 208847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * is the separator between the key and value in the on-the-wire 208947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * packet format; it is not part of either the key or the value. 209047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 209147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: A pointer to an uninitialized TXTRecordRef. 209247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 209347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * bufferLen: The size of the storage provided in the "buffer" parameter. 209447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 209547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * buffer: Optional caller-supplied storage used to hold the TXTRecord data. 209647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * This storage must remain valid for as long as 209747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the TXTRecordRef. 209847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 209947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 210047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltvoid DNSSD_API TXTRecordCreate 210147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 210247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt TXTRecordRef *txtRecord, 210347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t bufferLen, 210447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt void *buffer 210547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 210647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 210747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 210847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordDeallocate() 210947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 211047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Releases any resources allocated in the course of preparing a TXT Record 211147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * using TXTRecordCreate()/TXTRecordSetValue()/TXTRecordRemoveValue(). 211247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Ownership of the buffer provided in TXTRecordCreate() returns to the client. 211347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 211447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 211547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 211647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 211747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 211847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltvoid DNSSD_API TXTRecordDeallocate 211947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 212047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt TXTRecordRef *txtRecord 212147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 212247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 212347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 212447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordSetValue() 212547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 212647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Adds a key (optionally with value) to a TXTRecordRef. If the "key" already 212747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * exists in the TXTRecordRef, then the current value will be replaced with 212847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * the new value. 212947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Keys may exist in four states with respect to a given TXT record: 213047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - Absent (key does not appear at all) 213147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - Present with no value ("key" appears alone) 213247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - Present with empty value ("key=" appears in TXT record) 213347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * - Present with non-empty value ("key=value" appears in TXT record) 213447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For more details refer to "Data Syntax for DNS-SD TXT Records" in 213547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * <http://files.dns-sd.org/draft-cheshire-dnsext-dns-sd.txt> 213647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 213747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 213847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 213947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * key: A null-terminated string which only contains printable ASCII 214047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * values (0x20-0x7E), excluding '=' (0x3D). Keys should be 214147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 9 characters or fewer (not counting the terminating null). 214247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 214347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * valueSize: The size of the value. 214447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 214547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * value: Any binary value. For values that represent 214647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * textual data, UTF-8 is STRONGLY recommended. 214747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For values that represent textual data, valueSize 214847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * should NOT include the terminating null (if any) 214947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * at the end of the string. 215047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If NULL, then "key" will be added with no value. 215147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If non-NULL but valueSize is zero, then "key=" will be 215247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * added with empty value. 215347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 215447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success. 215547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Returns kDNSServiceErr_Invalid if the "key" string contains 215647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * illegal characters. 215747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Returns kDNSServiceErr_NoMemory if adding this key would 215847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * exceed the available storage. 215947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 216047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 216147e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API TXTRecordSetValue 216247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 216347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt TXTRecordRef *txtRecord, 216447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *key, 216547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint8_t valueSize, /* may be zero */ 216647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *value /* may be NULL */ 216747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 216847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 216947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 217047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordRemoveValue() 217147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 217247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Removes a key from a TXTRecordRef. The "key" must be an 217347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ASCII string which exists in the TXTRecordRef. 217447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 217547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 217647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 217747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * key: A key name which exists in the TXTRecordRef. 217847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 217947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success. 218047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Returns kDNSServiceErr_NoSuchKey if the "key" does not 218147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * exist in the TXTRecordRef. 218247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 218347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 218447e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API TXTRecordRemoveValue 218547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 218647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt TXTRecordRef *txtRecord, 218747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *key 218847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 218947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 219047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 219147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordGetLength() 219247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 219347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Allows you to determine the length of the raw bytes within a TXTRecordRef. 219447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 219547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 219647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 219747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns the size of the raw bytes inside a TXTRecordRef 219847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * which you can pass directly to DNSServiceRegister() or 219947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to DNSServiceUpdateRecord(). 220047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Returns 0 if the TXTRecordRef is empty. 220147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 220247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 220347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltuint16_t DNSSD_API TXTRecordGetLength 220447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 220547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const TXTRecordRef *txtRecord 220647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 220747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 220847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 220947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordGetBytesPtr() 221047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 221147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Allows you to retrieve a pointer to the raw bytes within a TXTRecordRef. 221247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 221347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: A TXTRecordRef initialized by calling TXTRecordCreate(). 221447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 221547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns a pointer to the raw bytes inside the TXTRecordRef 221647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * which you can pass directly to DNSServiceRegister() or 221747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * to DNSServiceUpdateRecord(). 221847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 221947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 222047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltconst void * DNSSD_API TXTRecordGetBytesPtr 222147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 222247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const TXTRecordRef *txtRecord 222347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 222447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 222547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 222647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/********************************************************************************************* 222747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 222847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXT Record Parsing Functions 222947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 223047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt *********************************************************************************************/ 223147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 223247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* 223347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * A typical calling sequence for TXT record parsing is something like: 223447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 223547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Receive TXT record data in DNSServiceResolve() callback 223647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if (TXTRecordContainsKey(txtLen, txtRecord, "key")) then do something 223747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * val1ptr = TXTRecordGetValuePtr(txtLen, txtRecord, "key1", &len1); 223847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * val2ptr = TXTRecordGetValuePtr(txtLen, txtRecord, "key2", &len2); 223947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ... 224047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * memcpy(myval1, val1ptr, len1); 224147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * memcpy(myval2, val2ptr, len2); 224247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ... 224347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return; 224447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 224547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If you wish to retain the values after return from the DNSServiceResolve() 224647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * callback, then you need to copy the data to your own storage using memcpy() 224747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or similar, as shown in the example above. 224847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 224947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * If for some reason you need to parse a TXT record you built yourself 225047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * using the TXT record construction functions above, then you can do 225147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * that using TXTRecordGetLength and TXTRecordGetBytesPtr calls: 225247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXTRecordGetValue(TXTRecordGetLength(x), TXTRecordGetBytesPtr(x), key, &len); 225347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 225447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Most applications only fetch keys they know about from a TXT record and 225547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * ignore the rest. 225647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * However, some debugging tools wish to fetch and display all keys. 225747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * To do that, use the TXTRecordGetCount() and TXTRecordGetItemAtIndex() calls. 225847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 225947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 226047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordContainsKey() 226147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 226247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Allows you to determine if a given TXT Record contains a specified key. 226347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 226447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtLen: The size of the received TXT Record. 226547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 226647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: Pointer to the received TXT Record bytes. 226747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 226847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * key: A null-terminated ASCII string containing the key name. 226947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 227047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns 1 if the TXT Record contains the specified key. 227147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Otherwise, it returns 0. 227247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 227347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 227447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltint DNSSD_API TXTRecordContainsKey 227547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 227647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t txtLen, 227747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *txtRecord, 227847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *key 227947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 228047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 228147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 228247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordGetValuePtr() 228347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 228447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Allows you to retrieve the value for a given key from a TXT Record. 228547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 228647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtLen: The size of the received TXT Record 228747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 228847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: Pointer to the received TXT Record bytes. 228947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 229047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * key: A null-terminated ASCII string containing the key name. 229147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 229247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * valueLen: On output, will be set to the size of the "value" data. 229347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 229447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns NULL if the key does not exist in this TXT record, 229547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * or exists with no value (to differentiate between 229647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * these two cases use TXTRecordContainsKey()). 229747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Returns pointer to location within TXT Record bytes 229847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * if the key exists with empty or non-empty value. 229947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For empty value, valueLen will be zero. 230047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For non-empty value, valueLen will be length of value data. 230147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 230247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 230347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltconst void * DNSSD_API TXTRecordGetValuePtr 230447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 230547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t txtLen, 230647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *txtRecord, 230747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const char *key, 230847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint8_t *valueLen 230947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 231047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 231147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 231247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordGetCount() 231347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 231447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Returns the number of keys stored in the TXT Record. The count 231547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * can be used with TXTRecordGetItemAtIndex() to iterate through the keys. 231647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 231747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtLen: The size of the received TXT Record. 231847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 231947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: Pointer to the received TXT Record bytes. 232047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 232147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns the total number of keys in the TXT Record. 232247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 232347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 232447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 232547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltuint16_t DNSSD_API TXTRecordGetCount 232647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 232747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t txtLen, 232847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *txtRecord 232947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 233047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 233147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 233247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* TXTRecordGetItemAtIndex() 233347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 233447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Allows you to retrieve a key name and value pointer, given an index into 233547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * a TXT Record. Legal index values range from zero to TXTRecordGetCount()-1. 233647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * It's also possible to iterate through keys in a TXT record by simply 233747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * calling TXTRecordGetItemAtIndex() repeatedly, beginning with index zero 233847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and increasing until TXTRecordGetItemAtIndex() returns kDNSServiceErr_Invalid. 233947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 234047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * On return: 234147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For keys with no value, *value is set to NULL and *valueLen is zero. 234247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For keys with empty value, *value is non-NULL and *valueLen is zero. 234347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * For keys with non-empty value, *value is non-NULL and *valueLen is non-zero. 234447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 234547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtLen: The size of the received TXT Record. 234647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 234747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * txtRecord: Pointer to the received TXT Record bytes. 234847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 234947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * itemIndex: An index into the TXT Record. 235047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 235147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * keyBufLen: The size of the string buffer being supplied. 235247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 235347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * key: A string buffer used to store the key name. 235447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * On return, the buffer contains a null-terminated C string 235547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * giving the key name. DNS-SD TXT keys are usually 235647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 9 characters or fewer. To hold the maximum possible 235747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * key name, the buffer should be 256 bytes long. 235847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 235947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * valueLen: On output, will be set to the size of the "value" data. 236047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 236147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * value: On output, *value is set to point to location within TXT 236247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Record bytes that holds the value data. 236347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * 236447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * return value: Returns kDNSServiceErr_NoError on success. 236547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Returns kDNSServiceErr_NoMemory if keyBufLen is too short. 236647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * Returns kDNSServiceErr_Invalid if index is greater than 236747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * TXTRecordGetCount()-1. 236847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 236947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 237047e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API TXTRecordGetItemAtIndex 237147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 237247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t txtLen, 237347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void *txtRecord, 237447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t itemIndex, 237547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint16_t keyBufLen, 237647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt char *key, 237747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt uint8_t *valueLen, 237847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt const void **value 237947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 238047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 238147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#if _DNS_SD_LIBDISPATCH 238247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* 238347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* DNSServiceSetDispatchQueue 238447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* 238547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* Allows you to schedule a DNSServiceRef on a serial dispatch queue for receiving asynchronous 238647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* callbacks. It's the clients responsibility to ensure that the provided dispatch queue is running. 238747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* 238847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* A typical application that uses CFRunLoopRun or dispatch_main on its main thread will 238947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* usually schedule DNSServiceRefs on its main queue (which is always a serial queue) 239047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* using "DNSServiceSetDispatchQueue(sdref, dispatch_get_main_queue());" 239147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* 239247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* If there is any error during the processing of events, the application callback will 239347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* be called with an error code. For shared connections, each subordinate DNSServiceRef 239447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* will get its own error callback. Currently these error callbacks only happen 239547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* if the mDNSResponder daemon is manually terminated or crashes, and the error 239647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* code in this case is kDNSServiceErr_ServiceNotRunning. The application must call 239747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* DNSServiceRefDeallocate to free the DNSServiceRef when it gets such an error code. 239847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* These error callbacks are rare and should not normally happen on customer machines, 239947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* but application code should be written defensively to handle such error callbacks 240047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* gracefully if they occur. 240147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* 240247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* After using DNSServiceSetDispatchQueue on a DNSServiceRef, calling DNSServiceProcessResult 240347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* on the same DNSServiceRef will result in undefined behavior and should be avoided. 240447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* 240547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* Once the application successfully schedules a DNSServiceRef on a serial dispatch queue using 240647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* DNSServiceSetDispatchQueue, it cannot remove the DNSServiceRef from the dispatch queue, or use 240747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* DNSServiceSetDispatchQueue a second time to schedule the DNSServiceRef onto a different serial dispatch 240847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* queue. Once scheduled onto a dispatch queue a DNSServiceRef will deliver events to that queue until 240947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* the application no longer requires that operation and terminates it using DNSServiceRefDeallocate. 241047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* 241147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* service: DNSServiceRef that was allocated and returned to the application, when the 241247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* application calls one of the DNSService API. 241347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* 241447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* queue: dispatch queue where the application callback will be scheduled 241547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* 241647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* return value: Returns kDNSServiceErr_NoError on success. 241747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* Returns kDNSServiceErr_NoMemory if it cannot create a dispatch source 241847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* Returns kDNSServiceErr_BadParam if the service param is invalid or the 241947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt* queue param is invalid 242047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt*/ 242147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 242247e4cebad7397422144bb03a21f3f7682c062c4aRobert GreenwaltDNSServiceErrorType DNSSD_API DNSServiceSetDispatchQueue 242347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ( 242447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt DNSServiceRef service, 242547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt dispatch_queue_t queue 242647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt ); 242747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif //_DNS_SD_LIBDISPATCH 242847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 242947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#ifdef __APPLE_API_PRIVATE 243047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 243147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceCompPrivateDNS "PrivateDNS" 243247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#define kDNSServiceCompMulticastDNS "MulticastDNS" 243347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 243447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif //__APPLE_API_PRIVATE 243547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 243647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt/* Some C compiler cleverness. We can make the compiler check certain things for us, 243747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * and report errors at compile-time if anything is wrong. The usual way to do this would 243847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * be to use a run-time "if" statement or the conventional run-time "assert" mechanism, but 243947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * then you don't find out what's wrong until you run the software. This way, if the assertion 244047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt * condition is false, the array size is negative, and the complier complains immediately. 244147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt */ 244247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 244347e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwaltstruct CompileTimeAssertionChecks_DNS_SD 244447e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt { 244547e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt char assert0[(sizeof(union _TXTRecordRef_t) == 16) ? 1 : -1]; 244647e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt }; 244747e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 244847e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#ifdef __cplusplus 244947e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt } 245047e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif 245147e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt 245247e4cebad7397422144bb03a21f3f7682c062c4aRobert Greenwalt#endif /* _DNS_SD_H */ 2453