mDNSWindows/DNSServices/DNSServiceDiscovery.h

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