mDNSWindows/DNSServices/DNSServiceDiscovery.h

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