mdns.subproj/DNSServiceDiscovery.h

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