mdns.subproj/DNSServiceDiscovery.h

   1 /*
   2  * Copyright (c) 2002 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * Copyright (c) 1999-2003 Apple Computer, Inc.  All Rights Reserved.
   7  *
   8  * This file contains Original Code and/or Modifications of Original Code
   9  * as defined in and that are subject to the Apple Public Source License
  10  * Version 2.0 (the 'License'). You may not use this file except in
  11  * compliance with the License. Please obtain a copy of the License at
  12  * http://www.opensource.apple.com/apsl/ and read it before using this
  13  * file.
  14  *
  15  * The Original Code and all software distributed under the License are
  16  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  17  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  18  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  19  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  20  * Please see the License for the specific language governing rights and
  21  * limitations under the License.
  22  *
  23  * @APPLE_LICENSE_HEADER_END@
  24  */
  25
  26 #ifndef __DNS_SERVICE_DISCOVERY_H
  27 #define __DNS_SERVICE_DISCOVERY_H
  28
  29 #include <mach/mach_types.h>
  30
  31 #include <sys/types.h>
  32 #include <sys/socket.h>
  33 #include <sys/cdefs.h>
  34
  35 #include <netinet/in.h>
  36
  37 __BEGIN_DECLS
  38
  39 /* Opaque internal data type */
  40 typedef struct _dns_service_discovery_t * dns_service_discovery_ref;
  41
  42 /* possible reply flags values */
  43
  44 enum {
  45     kDNSServiceDiscoveryNoFlags                 = 0,
  46     kDNSServiceDiscoveryMoreRepliesImmediately  = 1 << 0,
  47 };
  48
  49
  50 /* possible error code values */
  51 typedef enum
  52 {
  53     kDNSServiceDiscoveryWaiting     = 1,
  54     kDNSServiceDiscoveryNoError     = 0,
  55       // mDNS Error codes are in the range
  56       // FFFE FF00 (-65792) to FFFE FFFF (-65537)
  57     kDNSServiceDiscoveryUnknownErr        = -65537,       // 0xFFFE FFFF
  58     kDNSServiceDiscoveryNoSuchNameErr     = -65538,
  59     kDNSServiceDiscoveryNoMemoryErr       = -65539,
  60     kDNSServiceDiscoveryBadParamErr       = -65540,
  61     kDNSServiceDiscoveryBadReferenceErr   = -65541,
  62     kDNSServiceDiscoveryBadStateErr       = -65542,
  63     kDNSServiceDiscoveryBadFlagsErr       = -65543,
  64     kDNSServiceDiscoveryUnsupportedErr    = -65544,
  65     kDNSServiceDiscoveryNotInitializedErr = -65545,
  66     kDNSServiceDiscoveryNoCache           = -65546,
  67     kDNSServiceDiscoveryAlreadyRegistered = -65547,
  68     kDNSServiceDiscoveryNameConflict      = -65548,
  69     kDNSServiceDiscoveryInvalid           = -65549,
  70     kDNSServiceDiscoveryMemFree           = -65792        // 0xFFFE FF00
  71 } DNSServiceRegistrationReplyErrorType;
  72
  73 typedef uint32_t DNSRecordReference;
  74
  75
  76 /*!
  77 @function DNSServiceResolver_handleReply
  78  @description This function should be called with the Mach message sent
  79  to the port returned by the call to DNSServiceResolverResolve.
  80  The reply message will be interpreted and will result in a
  81  call to the specified callout function.
  82  @param replyMsg The Mach message.
  83  */
  84 void DNSServiceDiscovery_handleReply(void *replyMsg);
  85
  86 /* Service Registration */
  87
  88 typedef void (*DNSServiceRegistrationReply) (
  89     DNSServiceRegistrationReplyErrorType                errorCode,
  90     void                                                                                *context
  91 );
  92
  93 /*!
  94 @function DNSServiceRegistrationCreate
  95     @description Register a named service with DNS Service Discovery
  96     @param name The name of this service instance (e.g. "Steve's Printer")
  97     @param regtype The service type (e.g. "_printer._tcp." -- see
  98         RFC 2782 (DNS SRV) and <http://www.iana.org/assignments/port-numbers>)
  99     @param domain The domain in which to register the service (e.g. "apple.com.")
 100     @param port The local port on which this service is being offered (in network byte order)
 101     @param txtRecord Optional protocol-specific additional information
 102     @param callBack The DNSServiceRegistrationReply function to be called
 103     @param context A user specified context which will be passed to the callout function.
 104     @result A dns_registration_t
 105 */
 106 dns_service_discovery_ref DNSServiceRegistrationCreate
 107 (
 108     const char          *name,
 109     const char          *regtype,
 110     const char          *domain,
 111     uint16_t            port,
 112     const char          *txtRecord,
 113     DNSServiceRegistrationReply callBack,
 114     void                *context
 115 );
 116
 117 /***************************************************************************/
 118 /*   DNS Domain Enumeration   */
 119
 120 typedef enum
 121 {
 122     DNSServiceDomainEnumerationReplyAddDomain,                  // Domain found
 123     DNSServiceDomainEnumerationReplyAddDomainDefault,           // Domain found (and should be selected by default)
 124     DNSServiceDomainEnumerationReplyRemoveDomain,                       // Domain has been removed from network
 125 } DNSServiceDomainEnumerationReplyResultType;
 126
 127 typedef enum
 128 {
 129     DNSServiceDiscoverReplyFlagsFinished,
 130     DNSServiceDiscoverReplyFlagsMoreComing,
 131 } DNSServiceDiscoveryReplyFlags;
 132
 133 typedef void (*DNSServiceDomainEnumerationReply) (
 134     DNSServiceDomainEnumerationReplyResultType                  resultType,             // One of DNSServiceDomainEnumerationReplyResultType
 135     const char                                                  *replyDomain,
 136     DNSServiceDiscoveryReplyFlags               flags,                  // DNS Service Discovery reply flags information
 137     void                                                                *context
 138 );
 139
 140 /*!
 141     @function DNSServiceDomainEnumerationCreate
 142     @description Asynchronously create a DNS Domain Enumerator
 143     @param registrationDomains A boolean indicating whether you are looking
 144         for recommended registration domains
 145         (e.g. equivalent to the AppleTalk zone list in the AppleTalk Control Panel)
 146         or recommended browsing domains
 147         (e.g. equivalent to the AppleTalk zone list in the Chooser).
 148     @param callBack The function to be called when domains are found or removed
 149     @param context A user specified context which will be passed to the callout function.
 150     @result A dns_registration_t
 151 */
 152 dns_service_discovery_ref DNSServiceDomainEnumerationCreate
 153 (
 154     int                 registrationDomains,
 155     DNSServiceDomainEnumerationReply    callBack,
 156     void                *context
 157 );
 158
 159 /***************************************************************************/
 160 /*   DNS Service Browser   */
 161
 162 typedef enum
 163 {
 164     DNSServiceBrowserReplyAddInstance,  // Instance of service found
 165     DNSServiceBrowserReplyRemoveInstance        // Instance has been removed from network
 166 } DNSServiceBrowserReplyResultType;
 167
 168 typedef void (*DNSServiceBrowserReply) (
 169     DNSServiceBrowserReplyResultType                    resultType,             // One of DNSServiceBrowserReplyResultType
 170     const char          *replyName,
 171     const char          *replyType,
 172     const char          *replyDomain,
 173     DNSServiceDiscoveryReplyFlags                               flags,                  // DNS Service Discovery reply flags information
 174     void                        *context
 175 );
 176
 177 /*!
 178     @function DNSServiceBrowserCreate
 179     @description Asynchronously create a DNS Service browser
 180     @param regtype The type of service
 181     @param domain The domain in which to find the service
 182     @param callBack The function to be called when service instances are found or removed
 183     @param context A user specified context which will be passed to the callout function.
 184     @result A dns_registration_t
 185 */
 186 dns_service_discovery_ref DNSServiceBrowserCreate
 187 (
 188     const char          *regtype,
 189     const char          *domain,
 190     DNSServiceBrowserReply      callBack,
 191     void                *context
 192 );
 193
 194 /***************************************************************************/
 195 /* Resolver requests */
 196
 197 typedef void (*DNSServiceResolverReply) (
 198     struct sockaddr     *interface,             // Needed for scoped addresses like link-local
 199     struct sockaddr     *address,
 200     const char                  *txtRecord,
 201     DNSServiceDiscoveryReplyFlags                               flags,                  // DNS Service Discovery reply flags information
 202     void                                *context
 203 );
 204
 205 /*!
 206 @function DNSServiceResolverResolve
 207     @description Resolved a named instance of a service to its address, port, and
 208         (optionally) other demultiplexing information contained in the TXT record.
 209     @param name The name of the service instance
 210     @param regtype The type of service
 211     @param domain The domain in which to find the service
 212     @param callBack The DNSServiceResolverReply function to be called when the specified
 213         address has been resolved.
 214     @param context A user specified context which will be passed to the callout function.
 215     @result A dns_registration_t
 216 */
 217
 218 dns_service_discovery_ref DNSServiceResolverResolve
 219 (
 220     const char          *name,
 221     const char          *regtype,
 222     const char          *domain,
 223     DNSServiceResolverReply callBack,
 224     void                *context
 225 );
 226
 227 /***************************************************************************/
 228 /* Mach port accessor and deallocation */
 229
 230 /*!
 231     @function DNSServiceDiscoveryMachPort
 232     @description Returns the mach port for a dns_service_discovery_ref
 233     @param registration A dns_service_discovery_ref as returned from DNSServiceRegistrationCreate
 234     @result A mach reply port which will be sent messages as appropriate.
 235         These messages should be passed to the DNSServiceDiscovery_handleReply
 236         function.  A NULL value indicates that no address was
 237         specified or some other error occurred which prevented the
 238         resolution from being started.
 239 */
 240 mach_port_t DNSServiceDiscoveryMachPort(dns_service_discovery_ref dnsServiceDiscovery);
 241
 242 /*!
 243     @function DNSServiceDiscoveryDeallocate
 244     @description Deallocates the DNS Service Discovery type / closes the connection to the server
 245     @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a creation or enumeration call
 246     @result void
 247 */
 248 void DNSServiceDiscoveryDeallocate(dns_service_discovery_ref dnsServiceDiscovery);
 249
 250 /***************************************************************************/
 251 /* Registration updating */
 252
 253
 254 /*!
 255     @function DNSServiceRegistrationAddRecord
 256     @description Request that the mDNS Responder add the DNS Record of a specific type
 257     @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
 258     @param rrtype A standard DNS Resource Record Type, from http://www.iana.org/assignments/dns-parameters
 259     @param rdlen Length of the data
 260     @param rdata Opaque binary Resource Record data, up to 64 kB.
 261     @param ttl time to live for the added record.
 262     @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
 263 */
 264 DNSRecordReference DNSServiceRegistrationAddRecord(dns_service_discovery_ref dnsServiceDiscovery, uint16_t rrtype, uint16_t rdlen, const char *rdata, uint32_t ttl);
 265
 266 /*!
 267     @function DNSServiceRegistrationUpdateRecord
 268     @description Request that the mDNS Responder add the DNS Record of a specific type
 269     @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
 270     @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call
 271     @param rdlen Length of the data
 272     @param rdata Opaque binary Resource Record data, up to 64 kB.
 273     @param ttl time to live for the updated record.
 274     @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero
 275 */
 276 DNSServiceRegistrationReplyErrorType DNSServiceRegistrationUpdateRecord(dns_service_discovery_ref ref, DNSRecordReference reference, uint16_t rdlen, const char *rdata, uint32_t ttl);
 277
 278 /*!
 279     @function DNSServiceRegistrationRemoveRecord
 280     @description Request that the mDNS Responder remove the DNS Record(s) of a specific type
 281     @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
 282     @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call
 283     @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero
 284 */
 285 DNSServiceRegistrationReplyErrorType DNSServiceRegistrationRemoveRecord(dns_service_discovery_ref ref, DNSRecordReference reference);
 286
 287
 288 __END_DECLS
 289
 290 #endif  /* __DNS_SERVICE_DISCOVERY_H */