1/* -*- Mode: C; tab-width: 4 -*- 2 * 3 * Copyright (c) 2002 Apple Computer, Inc. All rights reserved. 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18/*! @header DNS Service Discovery (Deprecated Mach-based API) 19 * 20 * @discussion This section describes the functions, callbacks, and data structures that 21 * make up the DNS Service Discovery API. 22 * 23 * The DNS Service Discovery API is part of Bonjour, Apple's implementation of 24 * zero-configuration networking (ZEROCONF). 25 * 26 * Bonjour allows you to register a network service, such as a 27 * printer or file server, so that it can be found by name or browsed 28 * for by service type and domain. Using Bonjour, applications can 29 * discover what services are available on the network, along with 30 * all necessary access information-such as name, IP address, and port 31 * number-for a given service. 32 * 33 * In effect, Bonjour combines the functions of a local DNS server 34 * and AppleTalk. Bonjour allows applications to provide user-friendly printer 35 * and server browsing, among other things, over standard IP networks. 36 * This behavior is a result of combining protocols such as multicast and DNS 37 * to add new functionality to the network (such as multicast DNS). 38 * 39 * Bonjour gives applications easy access to services over local IP 40 * networks without requiring the service or the application to support 41 * an AppleTalk or a Netbeui stack, and without requiring a DNS server 42 * for the local network. 43 * 44 * Note that this API was deprecated in Mac OS X 10.3, and replaced 45 * by the portable cross-platform /usr/include/dns_sd.h API. 46 */ 47 48#ifndef __DNS_SERVICE_DISCOVERY_H 49#define __DNS_SERVICE_DISCOVERY_H 50 51#include <mach/mach_types.h> 52 53#include <sys/types.h> 54#include <sys/socket.h> 55#include <sys/cdefs.h> 56 57#include <netinet/in.h> 58 59#include <AvailabilityMacros.h> 60 61__BEGIN_DECLS 62 63/* Opaque internal data type */ 64typedef struct _dns_service_discovery_t * dns_service_discovery_ref; 65 66/* possible reply flags values */ 67 68enum { 69 kDNSServiceDiscoveryNoFlags = 0, 70 kDNSServiceDiscoveryMoreRepliesImmediately = 1 << 0, 71}; 72 73 74/* possible error code values */ 75typedef enum 76{ 77 kDNSServiceDiscoveryWaiting = 1, 78 kDNSServiceDiscoveryNoError = 0, 79 // mDNS Error codes are in the range 80 // FFFE FF00 (-65792) to FFFE FFFF (-65537) 81 kDNSServiceDiscoveryUnknownErr = -65537, // 0xFFFE FFFF 82 kDNSServiceDiscoveryNoSuchNameErr = -65538, 83 kDNSServiceDiscoveryNoMemoryErr = -65539, 84 kDNSServiceDiscoveryBadParamErr = -65540, 85 kDNSServiceDiscoveryBadReferenceErr = -65541, 86 kDNSServiceDiscoveryBadStateErr = -65542, 87 kDNSServiceDiscoveryBadFlagsErr = -65543, 88 kDNSServiceDiscoveryUnsupportedErr = -65544, 89 kDNSServiceDiscoveryNotInitializedErr = -65545, 90 kDNSServiceDiscoveryNoCache = -65546, 91 kDNSServiceDiscoveryAlreadyRegistered = -65547, 92 kDNSServiceDiscoveryNameConflict = -65548, 93 kDNSServiceDiscoveryInvalid = -65549, 94 kDNSServiceDiscoveryMemFree = -65792 // 0xFFFE FF00 95} DNSServiceRegistrationReplyErrorType; 96 97typedef uint32_t DNSRecordReference; 98 99 100/*! 101 @function DNSServiceResolver_handleReply 102 @discussion This function should be called with the Mach message sent 103 to the port returned by the call to DNSServiceResolverResolve. 104 The reply message will be interpreted and will result in a 105 call to the specified callout function. 106 @param replyMsg The Mach message. 107 */ 108void DNSServiceDiscovery_handleReply(void *replyMsg); 109 110/* Service Registration */ 111 112typedef void (*DNSServiceRegistrationReply)( 113 DNSServiceRegistrationReplyErrorType errorCode, 114 void *context 115 ); 116 117/*! 118 @function DNSServiceRegistrationCreate 119 @discussion Register a named service with DNS Service Discovery 120 @param name The name of this service instance (e.g. "Steve's Printer") 121 @param regtype The service type (e.g. "_printer._tcp." -- see 122 RFC 2782 (DNS SRV) and <http://www.iana.org/assignments/port-numbers>) 123 @param domain The domain in which to register the service (e.g. "apple.com.") 124 @param port The local port on which this service is being offered (in network byte order) 125 @param txtRecord Optional protocol-specific additional information 126 @param callBack The DNSServiceRegistrationReply function to be called 127 @param context A user specified context which will be passed to the callout function. 128 @result A dns_registration_t 129 */ 130dns_service_discovery_ref DNSServiceRegistrationCreate 131( 132 const char *name, 133 const char *regtype, 134 const char *domain, 135 uint16_t port, 136 const char *txtRecord, 137 DNSServiceRegistrationReply callBack, 138 void *context 139) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 140 141/***************************************************************************/ 142/* DNS Domain Enumeration */ 143 144typedef enum 145{ 146 DNSServiceDomainEnumerationReplyAddDomain, // Domain found 147 DNSServiceDomainEnumerationReplyAddDomainDefault, // Domain found (and should be selected by default) 148 DNSServiceDomainEnumerationReplyRemoveDomain, // Domain has been removed from network 149} DNSServiceDomainEnumerationReplyResultType; 150 151typedef enum 152{ 153 DNSServiceDiscoverReplyFlagsFinished, 154 DNSServiceDiscoverReplyFlagsMoreComing, 155} DNSServiceDiscoveryReplyFlags; 156 157typedef void (*DNSServiceDomainEnumerationReply)( 158 DNSServiceDomainEnumerationReplyResultType resultType, // One of DNSServiceDomainEnumerationReplyResultType 159 const char *replyDomain, 160 DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information 161 void *context 162 ); 163 164/*! 165 @function DNSServiceDomainEnumerationCreate 166 @discussion Asynchronously create a DNS Domain Enumerator 167 @param registrationDomains A boolean indicating whether you are looking 168 for recommended registration domains 169 (e.g. equivalent to the AppleTalk zone list in the AppleTalk Control Panel) 170 or recommended browsing domains 171 (e.g. equivalent to the AppleTalk zone list in the Chooser). 172 @param callBack The function to be called when domains are found or removed 173 @param context A user specified context which will be passed to the callout function. 174 @result A dns_registration_t 175 */ 176dns_service_discovery_ref DNSServiceDomainEnumerationCreate 177( 178 int registrationDomains, 179 DNSServiceDomainEnumerationReply callBack, 180 void *context 181) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 182 183/***************************************************************************/ 184/* DNS Service Browser */ 185 186typedef enum 187{ 188 DNSServiceBrowserReplyAddInstance, // Instance of service found 189 DNSServiceBrowserReplyRemoveInstance // Instance has been removed from network 190} DNSServiceBrowserReplyResultType; 191 192typedef void (*DNSServiceBrowserReply)( 193 DNSServiceBrowserReplyResultType resultType, // One of DNSServiceBrowserReplyResultType 194 const char *replyName, 195 const char *replyType, 196 const char *replyDomain, 197 DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information 198 void *context 199 ); 200 201/*! 202 @function DNSServiceBrowserCreate 203 @discussion Asynchronously create a DNS Service browser 204 @param regtype The type of service 205 @param domain The domain in which to find the service 206 @param callBack The function to be called when service instances are found or removed 207 @param context A user specified context which will be passed to the callout function. 208 @result A dns_registration_t 209 */ 210dns_service_discovery_ref DNSServiceBrowserCreate 211( 212 const char *regtype, 213 const char *domain, 214 DNSServiceBrowserReply callBack, 215 void *context 216) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 217 218/***************************************************************************/ 219/* Resolver requests */ 220 221typedef void (*DNSServiceResolverReply)( 222 struct sockaddr *interface, // Needed for scoped addresses like link-local 223 struct sockaddr *address, 224 const char *txtRecord, 225 DNSServiceDiscoveryReplyFlags flags, // DNS Service Discovery reply flags information 226 void *context 227 ); 228 229/*! 230 @function DNSServiceResolverResolve 231 @discussion Resolved a named instance of a service to its address, port, and 232 (optionally) other demultiplexing information contained in the TXT record. 233 @param name The name of the service instance 234 @param regtype The type of service 235 @param domain The domain in which to find the service 236 @param callBack The DNSServiceResolverReply function to be called when the specified 237 address has been resolved. 238 @param context A user specified context which will be passed to the callout function. 239 @result A dns_registration_t 240 */ 241 242dns_service_discovery_ref DNSServiceResolverResolve 243( 244 const char *name, 245 const char *regtype, 246 const char *domain, 247 DNSServiceResolverReply callBack, 248 void *context 249) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 250 251/***************************************************************************/ 252/* Mach port accessor and deallocation */ 253 254/*! 255 @function DNSServiceDiscoveryMachPort 256 @discussion Returns the mach port for a dns_service_discovery_ref 257 @param registration A dns_service_discovery_ref as returned from DNSServiceRegistrationCreate 258 @result A mach reply port which will be sent messages as appropriate. 259 These messages should be passed to the DNSServiceDiscovery_handleReply 260 function. A NULL value indicates that no address was 261 specified or some other error occurred which prevented the 262 resolution from being started. 263 */ 264mach_port_t DNSServiceDiscoveryMachPort(dns_service_discovery_ref dnsServiceDiscovery) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 265 266/*! 267 @function DNSServiceDiscoveryDeallocate 268 @discussion Deallocates the DNS Service Discovery type / closes the connection to the server 269 @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a creation or enumeration call 270 @result void 271 */ 272void DNSServiceDiscoveryDeallocate(dns_service_discovery_ref dnsServiceDiscovery) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 273 274/***************************************************************************/ 275/* Registration updating */ 276 277 278/*! 279 @function DNSServiceRegistrationAddRecord 280 @discussion Request that the mDNS Responder add the DNS Record of a specific type 281 @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call 282 @param rrtype A standard DNS Resource Record Type, from http://www.iana.org/assignments/dns-parameters 283 @param rdlen Length of the data 284 @param rdata Opaque binary Resource Record data, up to 64 kB. 285 @param ttl time to live for the added record. 286 @result DNSRecordReference An opaque reference that can be passed to the update and remove record calls. If an error occurs, this value will be zero or negative 287 */ 288DNSRecordReference DNSServiceRegistrationAddRecord(dns_service_discovery_ref dnsServiceDiscovery, uint16_t rrtype, uint16_t rdlen, const char *rdata, uint32_t ttl) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 289 290/*! 291 @function DNSServiceRegistrationUpdateRecord 292 @discussion Request that the mDNS Responder add the DNS Record of a specific type 293 @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call 294 @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call 295 @param rdlen Length of the data 296 @param rdata Opaque binary Resource Record data, up to 64 kB. 297 @param ttl time to live for the updated record. 298 @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero 299 */ 300DNSServiceRegistrationReplyErrorType DNSServiceRegistrationUpdateRecord(dns_service_discovery_ref ref, DNSRecordReference reference, uint16_t rdlen, const char *rdata, uint32_t ttl) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 301 302/*! 303 @function DNSServiceRegistrationRemoveRecord 304 @discussion Request that the mDNS Responder remove the DNS Record(s) of a specific type 305 @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call 306 @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call 307 @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero 308 */ 309DNSServiceRegistrationReplyErrorType DNSServiceRegistrationRemoveRecord(dns_service_discovery_ref ref, DNSRecordReference reference) AVAILABLE_MAC_OS_X_VERSION_10_2_AND_LATER_BUT_DEPRECATED_IN_MAC_OS_X_VERSION_10_3; 310 311 312__END_DECLS 313 314#endif /* __DNS_SERVICE_DISCOVERY_H */ 315