mDNSWindows/DNSServices/DNSServiceDiscovery.h

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