mDNSWindows/DNSServices/DNSServiceDiscovery.h

   1 /*
   2  * Copyright (c) 2002-2004 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     Change History (most recent first):
  26
  27 $Log: DNSServiceDiscovery.h,v $
  28 Revision 1.4  2004/05/06 18:42:58  ksekar
  29 General dns_sd.h API cleanup, including the following radars:
  30 <rdar://problem/3592068>: Remove flags with zero value
  31 <rdar://problem/3479569>: Passing in NULL causes a crash.
  32
  33 Revision 1.3  2004/01/30 02:56:34  bradley
  34 Updated to support full Unicode display. Added support for all services on www.dns-sd.org.
  35
  36 Revision 1.2  2003/08/20 07:06:34  bradley
  37 Update to APSL 2.0. Updated change history to match other mDNSResponder files.
  38
  39 Revision 1.1  2003/08/20 06:04:45  bradley
  40 Platform-neutral DNSServices-based emulation layer for the Mac OS X DNSServiceDiscovery API.
  41
  42 */
  43
  44 //---------------------------------------------------------------------------------------------------------------------------
  45 /*!     @header         DNSServiceDiscovery
  46
  47         @abstract       DNSServiceDiscovery emulation using DNSServices.
  48 */
  49
  50 #ifndef __DNS_SERVICE_DISCOVERY__
  51 #define __DNS_SERVICE_DISCOVERY__
  52
  53 #include        <stddef.h>
  54
  55 #if( __MACH__ )
  56
  57         #include        <mach/mach_types.h>
  58
  59         #include        <sys/types.h>
  60         #include        <sys/socket.h>
  61         #include        <sys/cdefs.h>
  62
  63         #include        <netinet/in.h>
  64
  65 #elif( defined( __MWERKS__ ) )
  66
  67         #include        <stdint.h>
  68
  69 #elif( defined( _MSC_VER ) )
  70
  71         typedef signed char                     int8_t;         // C99 stdint.h not supported in VC++/VS.NET yet.
  72         typedef unsigned char           uint8_t;        // C99 stdint.h not supported in VC++/VS.NET yet.
  73         typedef signed short            int16_t;        // C99 stdint.h not supported in VC++/VS.NET yet.
  74         typedef unsigned short          uint16_t;       // C99 stdint.h not supported in VC++/VS.NET yet.
  75         typedef signed long                     int32_t;        // C99 stdint.h not supported in VC++/VS.NET yet.
  76         typedef unsigned long           uint32_t;       // C99 stdint.h not supported in VC++/VS.NET yet.
  77
  78 #endif
  79
  80 #ifdef  __cplusplus
  81         extern "C" {
  82 #endif
  83
  84 // Note: The following is mostly copied from DNSServiceDiscovery.h.
  85
  86 // Compatibility types.
  87
  88 #if( !__MACH__ )
  89         typedef int             mach_port_t;
  90 #endif
  91
  92 //---------------------------------------------------------------------------------------------------------------------------
  93 /*!     @typedef        dns_service_discovery_ref
  94
  95         @abstract       Reference to a DNS Service Discovery object.
  96 */
  97
  98 typedef struct _dns_service_discovery_t *               dns_service_discovery_ref;
  99
 100 //---------------------------------------------------------------------------------------------------------------------------
 101 /*!     @enum           DNSServiceRegistrationReplyErrorType
 102
 103         @abstract       Error codes.
 104 */
 105
 106 typedef enum
 107 {
 108     kDNSServiceDiscoveryWaiting                         = 1,
 109     kDNSServiceDiscoveryNoError                         = 0,
 110
 111         // mDNS Error codes are in the range
 112         // FFFE FF00 (-65792) to FFFE FFFF (-65537)
 113
 114     kDNSServiceDiscoveryUnknownErr                      = -65537,               // 0xFFFE FFFF
 115     kDNSServiceDiscoveryNoSuchNameErr           = -65538,
 116     kDNSServiceDiscoveryNoMemoryErr                     = -65539,
 117     kDNSServiceDiscoveryBadParamErr                     = -65540,
 118     kDNSServiceDiscoveryBadReferenceErr         = -65541,
 119     kDNSServiceDiscoveryBadStateErr                     = -65542,
 120     kDNSServiceDiscoveryBadFlagsErr                     = -65543,
 121     kDNSServiceDiscoveryUnsupportedErr          = -65544,
 122     kDNSServiceDiscoveryNotInitializedErr       = -65545,
 123     kDNSServiceDiscoveryNoCache                         = -65546,
 124     kDNSServiceDiscoveryAlreadyRegistered       = -65547,
 125     kDNSServiceDiscoveryNameConflict            = -65548,
 126     kDNSServiceDiscoveryInvalid                         = -65549,
 127     kDNSServiceDiscoveryMemFree                         = -65792                // 0xFFFE FF00
 128
 129 }       DNSServiceRegistrationReplyErrorType;
 130
 131 typedef uint32_t DNSRecordReference;
 132
 133 //---------------------------------------------------------------------------------------------------------------------------
 134 /*!
 135         @function       DNSServiceResolver_handleReply
 136
 137         @param          replyMsg        The Mach message.
 138
 139         @description
 140
 141         This function should be called with the Mach message sent to the port returned by the call to DNSServiceResolverResolve.
 142         The reply message will be interpreted and will result in a call to the specified callout function.
 143 */
 144
 145 void    DNSServiceDiscovery_handleReply( void *replyMsg );
 146
 147 /* Service Registration */
 148
 149 typedef void (*DNSServiceRegistrationReply) (
 150     DNSServiceRegistrationReplyErrorType                errorCode,
 151     void                                                                                *context
 152 );
 153
 154 /*!
 155 @function DNSServiceRegistrationCreate
 156     @description Register a named service with DNS Service Discovery
 157     @param name The name of this service instance (e.g. "Steve's Printer")
 158     @param regtype The service type (e.g. "_printer._tcp." -- see
 159         RFC 2782 (DNS SRV) and <http://www.iana.org/assignments/port-numbers>)
 160     @param domain The domain in which to register the service (e.g. "apple.com.")
 161     @param port The local port on which this service is being offered (in network byte order)
 162     @param txtRecord Optional protocol-specific additional information
 163     @param callBack The DNSServiceRegistrationReply function to be called
 164     @param context A user specified context which will be passed to the callout function.
 165     @result A dns_registration_t
 166 */
 167 dns_service_discovery_ref DNSServiceRegistrationCreate
 168 (
 169     const char          *name,
 170     const char          *regtype,
 171     const char          *domain,
 172     uint16_t            port,
 173     const char          *txtRecord,
 174     DNSServiceRegistrationReply callBack,
 175     void                *context
 176 );
 177
 178 /***************************************************************************/
 179 /*   DNS Domain Enumeration   */
 180
 181 typedef enum
 182 {
 183     DNSServiceDomainEnumerationReplyAddDomain,                  // Domain found
 184     DNSServiceDomainEnumerationReplyAddDomainDefault,           // Domain found (and should be selected by default)
 185     DNSServiceDomainEnumerationReplyRemoveDomain,                       // Domain has been removed from network
 186 } DNSServiceDomainEnumerationReplyResultType;
 187
 188 typedef enum
 189 {
 190     DNSServiceDiscoverReplyFlagsMoreComing,
 191 } DNSServiceDiscoveryReplyFlags;
 192
 193 typedef void (*DNSServiceDomainEnumerationReply) (
 194     DNSServiceDomainEnumerationReplyResultType                  resultType,             // One of DNSServiceDomainEnumerationReplyResultType
 195     const char                                                  *replyDomain,
 196     DNSServiceDiscoveryReplyFlags               flags,                  // DNS Service Discovery reply flags information
 197     void                                                                *context
 198 );
 199
 200 /*!
 201     @function DNSServiceDomainEnumerationCreate
 202     @description Asynchronously create a DNS Domain Enumerator
 203     @param registrationDomains A boolean indicating whether you are looking
 204         for recommended registration domains
 205         (e.g. equivalent to the AppleTalk zone list in the AppleTalk Control Panel)
 206         or recommended browsing domains
 207         (e.g. equivalent to the AppleTalk zone list in the Chooser).
 208     @param callBack The function to be called when domains are found or removed
 209     @param context A user specified context which will be passed to the callout function.
 210     @result A dns_registration_t
 211 */
 212 dns_service_discovery_ref DNSServiceDomainEnumerationCreate
 213 (
 214     int                 registrationDomains,
 215     DNSServiceDomainEnumerationReply    callBack,
 216     void                *context
 217 );
 218
 219 /***************************************************************************/
 220 /*   DNS Service Browser   */
 221
 222 typedef enum
 223 {
 224     DNSServiceBrowserReplyAddInstance,  // Instance of service found
 225     DNSServiceBrowserReplyRemoveInstance        // Instance has been removed from network
 226 } DNSServiceBrowserReplyResultType;
 227
 228 typedef void (*DNSServiceBrowserReply) (
 229     DNSServiceBrowserReplyResultType                    resultType,             // One of DNSServiceBrowserReplyResultType
 230     const char          *replyName,
 231     const char          *replyType,
 232     const char          *replyDomain,
 233     DNSServiceDiscoveryReplyFlags                               flags,                  // DNS Service Discovery reply flags information
 234     void                        *context
 235 );
 236
 237 /*!
 238     @function DNSServiceBrowserCreate
 239     @description Asynchronously create a DNS Service browser
 240     @param regtype The type of service
 241     @param domain The domain in which to find the service
 242     @param callBack The function to be called when service instances are found or removed
 243     @param context A user specified context which will be passed to the callout function.
 244     @result A dns_registration_t
 245 */
 246 dns_service_discovery_ref DNSServiceBrowserCreate
 247 (
 248     const char          *regtype,
 249     const char          *domain,
 250     DNSServiceBrowserReply      callBack,
 251     void                *context
 252 );
 253
 254 /***************************************************************************/
 255 /* Resolver requests */
 256
 257 typedef void (*DNSServiceResolverReply) (
 258     struct sockaddr     *interfaceAddr,         // Needed for scoped addresses like link-local
 259     struct sockaddr     *address,
 260     const char                  *txtRecord,
 261     DNSServiceDiscoveryReplyFlags                               flags,                  // DNS Service Discovery reply flags information
 262     void                                *context
 263 );
 264
 265 /*!
 266 @function DNSServiceResolverResolve
 267     @description Resolved a named instance of a service to its address, port, and
 268         (optionally) other demultiplexing information contained in the TXT record.
 269     @param name The name of the service instance
 270     @param regtype The type of service
 271     @param domain The domain in which to find the service
 272     @param callBack The DNSServiceResolverReply function to be called when the specified
 273         address has been resolved.
 274     @param context A user specified context which will be passed to the callout function.
 275     @result A dns_registration_t
 276 */
 277
 278 dns_service_discovery_ref DNSServiceResolverResolve
 279 (
 280     const char          *name,
 281     const char          *regtype,
 282     const char          *domain,
 283     DNSServiceResolverReply callBack,
 284     void                *context
 285 );
 286
 287 /***************************************************************************/
 288 /* Mach port accessor and deallocation */
 289
 290 /*!
 291     @function DNSServiceDiscoveryMachPort
 292     @description Returns the mach port for a dns_service_discovery_ref
 293     @param registration A dns_service_discovery_ref as returned from DNSServiceRegistrationCreate
 294     @result A mach reply port which will be sent messages as appropriate.
 295         These messages should be passed to the DNSServiceDiscovery_handleReply
 296         function.  A NULL value indicates that no address was
 297         specified or some other error occurred which prevented the
 298         resolution from being started.
 299 */
 300 mach_port_t DNSServiceDiscoveryMachPort(dns_service_discovery_ref dnsServiceDiscovery);
 301
 302 /*!
 303     @function DNSServiceDiscoveryDeallocate
 304     @description Deallocates the DNS Service Discovery type / closes the connection to the server
 305     @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a creation or enumeration call
 306     @result void
 307 */
 308 void DNSServiceDiscoveryDeallocate(dns_service_discovery_ref dnsServiceDiscovery);
 309
 310 /***************************************************************************/
 311 /* Registration updating */
 312
 313
 314 /*!
 315     @function DNSServiceRegistrationAddRecord
 316     @description Request that the mDNS Responder add the DNS Record of a specific type
 317     @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
 318     @param rrtype A standard DNS Resource Record Type, from http://www.iana.org/assignments/dns-parameters
 319     @param rdlen Length of the data
 320     @param rdata Opaque binary Resource Record data, up to 64 kB.
 321     @param ttl time to live for the added record.
 322     @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
 323 */
 324 DNSRecordReference DNSServiceRegistrationAddRecord(dns_service_discovery_ref dnsServiceDiscovery, uint16_t rrtype, uint16_t rdlen, const char *rdata, uint32_t ttl);
 325
 326 /*!
 327     @function DNSServiceRegistrationUpdateRecord
 328     @description Request that the mDNS Responder add the DNS Record of a specific type
 329     @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
 330     @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call
 331     @param rdlen Length of the data
 332     @param rdata Opaque binary Resource Record data, up to 64 kB.
 333     @param ttl time to live for the updated record.
 334     @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero
 335 */
 336 DNSServiceRegistrationReplyErrorType DNSServiceRegistrationUpdateRecord(dns_service_discovery_ref ref, DNSRecordReference reference, uint16_t rdlen, const char *rdata, uint32_t ttl);
 337
 338 /*!
 339     @function DNSServiceRegistrationRemoveRecord
 340     @description Request that the mDNS Responder remove the DNS Record(s) of a specific type
 341     @param dnsServiceDiscovery A dns_service_discovery_ref as returned from a DNSServiceRegistrationCreate call
 342     @param dnsRecordReference A dnsRecordReference as returned from a DNSServiceRegistrationAddRecord call
 343     @result DNSServiceRegistrationReplyErrorType If an error occurs, this value will be non zero
 344 */
 345
 346 DNSServiceRegistrationReplyErrorType DNSServiceRegistrationRemoveRecord(dns_service_discovery_ref ref, DNSRecordReference reference);
 347
 348 #ifdef  __cplusplus
 349         }
 350 #endif
 351
 352 #endif  // __DNS_SERVICE_DISCOVERY__