mDNSMacOSX/DNSServiceDiscovery.h

   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 */
  64 typedef struct _dns_service_discovery_t * dns_service_discovery_ref;
  65
  66 /* possible reply flags values */
  67
  68 enum {
  69     kDNSServiceDiscoveryNoFlags                 = 0,
  70     kDNSServiceDiscoveryMoreRepliesImmediately  = 1 << 0,
  71 };
  72
  73
  74 /* possible error code values */
  75 typedef 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
  97 typedef 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  */
 108 void DNSServiceDiscovery_handleReply(void *replyMsg);
 109
 110 /* Service Registration */
 111
 112 typedef 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 */
 130 dns_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
 144 typedef 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
 151 typedef enum
 152 {
 153     DNSServiceDiscoverReplyFlagsFinished,
 154     DNSServiceDiscoverReplyFlagsMoreComing,
 155 } DNSServiceDiscoveryReplyFlags;
 156
 157 typedef 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 */
 176 dns_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
 186 typedef enum
 187 {
 188     DNSServiceBrowserReplyAddInstance,  // Instance of service found
 189     DNSServiceBrowserReplyRemoveInstance        // Instance has been removed from network
 190 } DNSServiceBrowserReplyResultType;
 191
 192 typedef 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 */
 210 dns_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
 221 typedef 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
 242 dns_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 */
 264 mach_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 */
 272 void 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 */
 288 DNSRecordReference 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 */
 300 DNSServiceRegistrationReplyErrorType 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 */
 309 DNSServiceRegistrationReplyErrorType 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 */