mDNSCore/mDNSEmbeddedAPI.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
  24    NOTE:
  25    If you're building an application that uses DNS Service Discovery
  26    this is probably NOT the header file you're looking for.
  27    In most cases you will want to use /usr/include/dns_sd.h instead.
  28
  29    This header file defines the lowest level raw interface to mDNSCore,
  30    which is appropriate *only* on tiny embedded systems where everything
  31    runs in a single address space and memory is extremely constrained.
  32    All the APIs here are malloc-free, which means that the caller is
  33    responsible for passing in a pointer to the relevant storage that
  34    will be used in the execution of that call, and (when called with
  35    correct parameters) all the calls are guaranteed to succeed. There
  36    is never a case where a call can suffer intermittent failures because
  37    the implementation calls malloc() and sometimes malloc() returns NULL
  38    because memory is so limited that no more is available.
  39    This is primarily for devices that need to have precisely known fixed
  40    memory requirements, with absolutely no uncertainty or run-time variation,
  41    but that certainty comes at a cost of more difficult programming.
  42
  43    For applications running on general-purpose desktop operating systems
  44    (Mac OS, Linux, Solaris, Windows, etc.) the API you should use is
  45    /usr/include/dns_sd.h, which defines the API by which multiple
  46    independent client processes communicate their DNS Service Discovery
  47    requests to a single "mdnsd" daemon running in the background.
  48
  49    Even on platforms that don't run multiple independent processes in
  50    multiple independent address spaces, you can still use the preferred
  51    dns_sd.h APIs by linking in "dnssd_clientshim.c", which implements
  52    the standard "dns_sd.h" API calls, allocates any required storage
  53    using malloc(), and then calls through to the low-level malloc-free
  54    mDNSCore routines defined here. This has the benefit that even though
  55    you're running on a small embedded system with a single address space,
  56    you can still use the exact same client C code as you'd use on a
  57    general-purpose desktop system.
  58
  59
  60     Change History (most recent first):
  61
  62 $Log: mDNSEmbeddedAPI.h,v $
  63 Revision 1.281  2005/02/25 17:47:44  ksekar
  64 <rdar://problem/4021868> SendServiceRegistration fails on wake from sleep
  65
  66 Revision 1.280  2005/02/25 04:21:00  cheshire
  67 <rdar://problem/4015377> mDNS -F returns the same domain multiple times with different casing
  68
  69 Revision 1.279  2005/02/17 01:56:14  cheshire
  70 Increase ifname field to 64 bytes
  71
  72 Revision 1.278  2005/02/09 23:38:51  ksekar
  73 <rdar://problem/3993508> Reregister hostname when DNS server changes but IP address does not
  74
  75 Revision 1.277  2005/02/09 23:31:12  ksekar
  76 <rdar://problem/3984374> NAT-PMP response callback should return a boolean indicating if the packet matched the request
  77
  78 Revision 1.276  2005/02/01 19:33:29  ksekar
  79 <rdar://problem/3985239> Keychain format too restrictive
  80
  81 Revision 1.275  2005/01/27 22:57:55  cheshire
  82 Fix compile errors on gcc4
  83
  84 Revision 1.274  2005/01/19 21:01:54  ksekar
  85 <rdar://problem/3955355> uDNS needs to support subtype registration and browsing
  86
  87 Revision 1.273  2005/01/19 19:15:31  ksekar
  88 Refinement to <rdar://problem/3954575> - Simplify mDNS_PurgeResultsForDomain logic and move into daemon layer
  89
  90 Revision 1.272  2005/01/18 18:10:55  ksekar
  91 <rdar://problem/3954575> Use 10.4 resolver API to get search domains
  92
  93 Revision 1.271  2005/01/15 00:56:41  ksekar
  94 <rdar://problem/3954575> Unicast services don't disappear when logging
  95 out of VPN
  96
  97 Revision 1.270  2005/01/14 18:34:22  ksekar
  98 <rdar://problem/3954571> Services registered outside of firewall don't succeed after location change
  99
 100 Revision 1.269  2005/01/11 22:50:52  ksekar
 101 Fixed constant naming (was using kLLQ_DefLease for update leases)
 102
 103 Revision 1.268  2004/12/22 22:25:47  ksekar
 104 <rdar://problem/3734265> NATPMP: handle location changes
 105
 106 Revision 1.267  2004/12/22 00:13:49  ksekar
 107 <rdar://problem/3873993> Change version, port, and polling interval for LLQ
 108
 109 Revision 1.266  2004/12/18 03:13:45  cheshire
 110 <rdar://problem/3751638> kDNSServiceInterfaceIndexLocalOnly should return all local records
 111
 112 Revision 1.265  2004/12/17 23:37:45  cheshire
 113 <rdar://problem/3485365> Guard against repeating wireless dissociation/re-association
 114 (and other repetitive configuration changes)
 115
 116 Revision 1.264  2004/12/17 05:25:46  cheshire
 117 <rdar://problem/3925163> Shorten DNS-SD queries to avoid NAT bugs
 118
 119 Revision 1.263  2004/12/16 20:40:25  cheshire
 120 Fix compile warnings
 121
 122 Revision 1.262  2004/12/16 20:13:00  cheshire
 123 <rdar://problem/3324626> Cache memory management improvements
 124
 125 Revision 1.261  2004/12/14 21:21:20  ksekar
 126 <rdar://problem/3825979> NAT-PMP: Update response format to contain "Seconds Since Boot"
 127
 128 Revision 1.260  2004/12/12 23:51:42  ksekar
 129 <rdar://problem/3845683> Wide-area registrations should fallback to using DHCP hostname as target
 130
 131 Revision 1.259  2004/12/11 20:55:29  ksekar
 132 <rdar://problem/3916479> Clean up registration state machines
 133
 134 Revision 1.258  2004/12/10 20:48:32  cheshire
 135 <rdar://problem/3705229> Need to pick final EDNS numbers for LLQ and GC
 136
 137 Revision 1.257  2004/12/10 02:09:23  cheshire
 138 <rdar://problem/3898376> Modify default TTLs
 139
 140 Revision 1.256  2004/12/09 03:15:40  ksekar
 141 <rdar://problem/3806610> use _legacy instead of _default to find "empty string" browse domains
 142
 143 Revision 1.255  2004/12/07 22:48:37  cheshire
 144 Tidying
 145
 146 Revision 1.254  2004/12/07 21:26:04  ksekar
 147 <rdar://problem/3908336> DNSServiceRegisterRecord() can crash on deregistration
 148
 149 Revision 1.253  2004/12/07 20:42:33  cheshire
 150 Add explicit context parameter to mDNS_RemoveRecordFromService()
 151
 152 Revision 1.252  2004/12/07 03:02:12  ksekar
 153 Fixed comments, grouped unicast-specific routines together
 154
 155 Revision 1.251  2004/12/06 21:15:22  ksekar
 156 <rdar://problem/3884386> mDNSResponder crashed in CheckServiceRegistrations
 157
 158 Revision 1.250  2004/12/04 02:12:45  cheshire
 159 <rdar://problem/3517236> mDNSResponder puts LargeCacheRecord on the stack
 160
 161 Revision 1.249  2004/12/03 05:18:33  ksekar
 162 <rdar://problem/3810596> mDNSResponder needs to return more specific TSIG errors
 163
 164 Revision 1.248  2004/12/02 20:03:48  ksekar
 165 <rdar://problem/3889647> Still publishes wide-area domains even after switching to a local subnet
 166
 167 Revision 1.247  2004/12/01 20:57:19  ksekar
 168 <rdar://problem/3873921> Wide Area Service Discovery must be split-DNS aware
 169
 170 Revision 1.246  2004/11/29 23:26:32  cheshire
 171 Added NonZeroTime() function, which usually returns the value given, with the exception
 172 that if the value given is zero, it returns one instead. For timer values where zero is
 173 used to mean "not set", this can be used to ensure that setting them to the result of an
 174 interval computation (e.g. "now+interval") does not inadvertently result in a zero value.
 175
 176 Revision 1.245  2004/11/25 01:28:09  cheshire
 177 <rdar://problem/3557050> Need to implement random delay for 'QU' unicast replies (and set cache flush bit too)
 178
 179 Revision 1.244  2004/11/24 22:00:59  cheshire
 180 Move definition of mDNSAddressIsAllDNSLinkGroup() from mDNSMacOSX.c to mDNSEmbeddedAPI.h
 181
 182 Revision 1.243  2004/11/23 22:43:53  cheshire
 183 Tidy up code alignment
 184
 185 Revision 1.242  2004/11/23 03:39:46  cheshire
 186 Let interface name/index mapping capability live directly in JNISupport.c,
 187 instead of having to call through to the daemon via IPC to get this information.
 188
 189 Revision 1.241  2004/11/22 17:16:19  ksekar
 190 <rdar://problem/3854298> Unicast services don't disappear when you disable all networking
 191
 192 Revision 1.240  2004/11/19 02:32:43  ksekar
 193 Wide-Area Security: Add LLQ-ID to events
 194
 195 Revision 1.239  2004/11/15 20:09:23  ksekar
 196 <rdar://problem/3719050> Wide Area support for Add/Remove record
 197
 198 Revision 1.238  2004/11/12 03:16:48  rpantos
 199 rdar://problem/3809541 Add mDNSPlatformGetInterfaceByName, mDNSPlatformGetInterfaceName
 200
 201 Revision 1.237  2004/11/10 20:40:53  ksekar
 202 <rdar://problem/3868216> LLQ mobility fragile on non-primary interface
 203
 204 Revision 1.236  2004/11/01 20:36:11  ksekar
 205 <rdar://problem/3802395> mDNSResponder should not receive Keychain Notifications
 206
 207 Revision 1.235  2004/11/01 17:48:14  cheshire
 208 Changed SOA serial number back to signed. RFC 1035 may describe it as "unsigned", but
 209 it's wrong. The SOA serial is a modular counter, as explained in "DNS & BIND", page
 210 137. Since C doesn't have a modular type, we used signed, C's closest approximation.
 211
 212 Revision 1.234  2004/10/29 21:59:02  ksekar
 213 SOA serial should be a unsigned integer, as per RFC 1035
 214
 215 Revision 1.233  2004/10/28 03:24:41  cheshire
 216 Rename m->CanReceiveUnicastOn as m->CanReceiveUnicastOn5353
 217
 218 Revision 1.232  2004/10/26 06:20:23  cheshire
 219 Add mDNSAddressIsValidNonZero() macro
 220
 221 Revision 1.231  2004/10/26 06:11:41  cheshire
 222 Add improved logging to aid in diagnosis of <rdar://problem/3842714> mDNSResponder crashed
 223
 224 Revision 1.230  2004/10/26 03:52:02  cheshire
 225 Update checkin comments
 226
 227 Revision 1.229  2004/10/25 19:30:52  ksekar
 228 <rdar://problem/3827956> Simplify dynamic host name structures
 229
 230 Revision 1.228  2004/10/23 01:16:00  cheshire
 231 <rdar://problem/3851677> uDNS operations not always reliable on multi-homed hosts
 232
 233 Revision 1.227  2004/10/22 20:52:07  ksekar
 234 <rdar://problem/3799260> Create NAT port mappings for Long Lived Queries
 235
 236 Revision 1.226  2004/10/20 01:50:40  cheshire
 237 <rdar://problem/3844991> Cannot resolve non-local registrations using the mach API
 238 Implemented ForceMCast mode for AuthRecords as well as for Questions
 239
 240 Revision 1.225  2004/10/19 21:33:17  cheshire
 241 <rdar://problem/3844991> Cannot resolve non-local registrations using the mach API
 242 Added flag 'kDNSServiceFlagsForceMulticast'. Passing through an interface id for a unicast name
 243 doesn't force multicast unless you set this flag to indicate explicitly that this is what you want
 244
 245 Revision 1.224  2004/10/16 00:16:59  cheshire
 246 <rdar://problem/3770558> Replace IP TTL 255 check with local subnet source address check
 247
 248 Revision 1.223  2004/10/15 23:00:17  ksekar
 249 <rdar://problem/3799242> Need to update LLQs on location changes
 250
 251 Revision 1.222  2004/10/12 02:49:20  ksekar
 252 <rdar://problem/3831228> Clean up LLQ sleep/wake, error handling
 253
 254 Revision 1.221  2004/10/10 06:57:15  cheshire
 255 Change definition of "localdomain" to make code compile a little smaller
 256
 257 Revision 1.220  2004/10/06 01:44:19  cheshire
 258 <rdar://problem/3813936> Resolving too quickly sometimes returns stale TXT record
 259
 260 Revision 1.219  2004/10/03 23:18:58  cheshire
 261 Move address comparison macros from DNSCommon.h to mDNSEmbeddedAPI.h
 262
 263 Revision 1.218  2004/10/03 23:14:12  cheshire
 264 Add "mDNSEthAddr" type and "zeroEthAddr" constant
 265
 266 Revision 1.217  2004/09/30 00:24:56  ksekar
 267 <rdar://problem/3695802> Dynamically update default registration domains on config change
 268
 269 Revision 1.216  2004/09/27 23:24:32  cheshire
 270 Fix typo: SOA refresh interval is supposed to be unsigned
 271
 272 Revision 1.215  2004/09/26 23:20:35  ksekar
 273 <rdar://problem/3813108> Allow default registrations in multiple wide-area domains
 274
 275 Revision 1.214  2004/09/25 02:41:39  cheshire
 276 <rdar://problem/3637266> Deliver near-pending "remove" events before new "add" events
 277
 278 Revision 1.213  2004/09/25 02:24:27  cheshire
 279 Removed unused rr->UseCount
 280
 281 Revision 1.212  2004/09/24 20:57:39  cheshire
 282 <rdar://problem/3680902> Eliminate inappropriate casts that cause misaligned-address errors
 283
 284 Revision 1.211  2004/09/24 20:33:22  cheshire
 285 Remove unused DNSDigest_MD5 declaration
 286
 287 Revision 1.210  2004/09/23 20:21:07  cheshire
 288 <rdar://problem/3426876> Refine "immediate answer burst; restarting exponential backoff sequence" logic
 289 Associate a unique sequence number with each received packet, and only increment the count of recent answer
 290 packets if the packet sequence number for this answer record is not one we've already seen and counted.
 291
 292 Revision 1.209  2004/09/23 20:14:39  cheshire
 293 Rename "question->RecentAnswers" to "question->RecentAnswerPkts"
 294
 295 Revision 1.208  2004/09/23 00:50:53  cheshire
 296 <rdar://problem/3419452> Don't send a (DE) if a service is unregistered after wake from sleep
 297
 298 Revision 1.207  2004/09/22 02:34:46  cheshire
 299 Move definitions of default TTL times from mDNS.c to mDNSEmbeddedAPI.h
 300
 301 Revision 1.206  2004/09/22 00:41:59  cheshire
 302 Move tcp connection status codes into the legal range allocated for mDNS use
 303
 304 Revision 1.205  2004/09/21 23:40:11  ksekar
 305 <rdar://problem/3810349> mDNSResponder to return errors on NAT traversal failure
 306
 307 Revision 1.204  2004/09/21 23:29:50  cheshire
 308 <rdar://problem/3680045> DNSServiceResolve should delay sending packets
 309
 310 Revision 1.203  2004/09/21 20:58:22  cheshire
 311 Add ifname field to NetworkInterfaceInfo_struct
 312
 313 Revision 1.202  2004/09/17 00:46:34  cheshire
 314 mDNS_TimeNow should take const mDNS parameter
 315
 316 Revision 1.201  2004/09/17 00:31:51  cheshire
 317 For consistency with ipv6, renamed rdata field 'ip' to 'ipv4'
 318
 319 Revision 1.200  2004/09/17 00:19:10  cheshire
 320 For consistency with AllDNSLinkGroupv6, rename AllDNSLinkGroup to AllDNSLinkGroupv4
 321
 322 Revision 1.199  2004/09/16 21:59:16  cheshire
 323 For consistency with zerov6Addr, rename zeroIPAddr to zerov4Addr
 324
 325 Revision 1.198  2004/09/16 21:36:36  cheshire
 326 <rdar://problem/3803162> Fix unsafe use of mDNSPlatformTimeNow()
 327 Changes to add necessary locking calls around unicast DNS operations
 328
 329 Revision 1.197  2004/09/16 00:24:48  cheshire
 330 <rdar://problem/3803162> Fix unsafe use of mDNSPlatformTimeNow()
 331
 332 Revision 1.196  2004/09/14 23:42:35  cheshire
 333 <rdar://problem/3801296> Need to seed random number generator from platform-layer data
 334
 335 Revision 1.195  2004/09/14 23:27:46  cheshire
 336 Fix compile errors
 337
 338 Revision 1.194  2004/09/10 00:49:57  cheshire
 339 <rdar://problem/3787644> Add error code kDNSServiceErr_Firewall, for future use
 340
 341 Revision 1.193  2004/09/03 19:23:05  ksekar
 342 <rdar://problem/3788460>: Need retransmission mechanism for wide-area service registrations
 343
 344 Revision 1.192  2004/09/02 03:48:47  cheshire
 345 <rdar://problem/3709039> Disable targeted unicast query support by default
 346 1. New flag kDNSServiceFlagsAllowRemoteQuery to indicate we want to allow remote queries for this record
 347 2. New field AllowRemoteQuery in AuthRecord structure
 348 3. uds_daemon.c sets AllowRemoteQuery if kDNSServiceFlagsAllowRemoteQuery is set
 349 4. mDNS.c only answers remote queries if AllowRemoteQuery is set
 350
 351 Revision 1.191  2004/08/25 00:37:27  ksekar
 352 <rdar://problem/3774635>: Cleanup DynDNS hostname registration code
 353
 354 Revision 1.190  2004/08/18 17:35:41  ksekar
 355 <rdar://problem/3651443>: Feature #9586: Need support for Legacy NAT gateways
 356
 357 Revision 1.189  2004/08/14 03:22:41  cheshire
 358 <rdar://problem/3762579> Dynamic DNS UI <-> mDNSResponder glue
 359 Add GetUserSpecifiedDDNSName() routine
 360 Convert ServiceRegDomain to domainname instead of C string
 361 Replace mDNS_GenerateFQDN/mDNS_GenerateGlobalFQDN with mDNS_SetFQDNs
 362
 363 Revision 1.188  2004/08/13 23:46:58  cheshire
 364 "asyncronous" -> "asynchronous"
 365
 366 Revision 1.187  2004/08/13 23:37:02  cheshire
 367 Now that we do both uDNS and mDNS, global replace "uDNS_info.hostname" with
 368 "uDNS_info.UnicastHostname" for clarity
 369
 370 Revision 1.186  2004/08/13 23:25:00  cheshire
 371 Now that we do both uDNS and mDNS, global replace "m->hostname" with
 372 "m->MulticastHostname" for clarity
 373
 374 Revision 1.185  2004/08/12 00:32:36  ksekar
 375 <rdar://problem/3759567>: LLQ Refreshes never terminate if unanswered
 376
 377 Revision 1.184  2004/08/11 17:09:31  cheshire
 378 Add comment clarifying the applicability of these APIs
 379
 380 Revision 1.183  2004/08/10 23:19:14  ksekar
 381 <rdar://problem/3722542>: DNS Extension daemon for Wide Area Service Discovery
 382 Moved routines/constants to allow extern access for garbage collection daemon
 383
 384 Revision 1.182  2004/07/30 17:40:06  ksekar
 385 <rdar://problem/3739115>: TXT Record updates not available for wide-area services
 386
 387 Revision 1.181  2004/07/29 19:27:15  ksekar
 388 NATPMP Support - minor fixes and cleanup
 389
 390 Revision 1.180  2004/07/29 02:03:35  ksekar
 391 Delete unused #define and structure field
 392
 393 Revision 1.179  2004/07/26 22:49:30  ksekar
 394 <rdar://problem/3651409>: Feature #9516: Need support for NATPMP in client
 395
 396 Revision 1.178  2004/07/13 21:24:24  rpantos
 397 Fix for <rdar://problem/3701120>.
 398
 399 Revision 1.177  2004/06/05 00:04:26  cheshire
 400 <rdar://problem/3668639>: wide-area domains should be returned in reg. domain enumeration
 401
 402 Revision 1.176  2004/06/04 08:58:29  ksekar
 403 <rdar://problem/3668624>: Keychain integration for secure dynamic update
 404
 405 Revision 1.175  2004/06/04 00:15:06  cheshire
 406 Move misplaced brackets
 407
 408 Revision 1.174  2004/06/03 23:30:16  cheshire
 409 Remove extraneous blank lines and white space
 410
 411 Revision 1.173  2004/06/03 03:09:58  ksekar
 412 <rdar://problem/3668626>: Garbage Collection for Dynamic Updates
 413
 414 Revision 1.172  2004/06/01 23:46:50  ksekar
 415 <rdar://problem/3675149>: DynDNS: dynamically look up LLQ/Update ports
 416
 417 Revision 1.171  2004/05/28 23:42:37  ksekar
 418 <rdar://problem/3258021>: Feature: DNS server->client notification on record changes (#7805)
 419
 420 Revision 1.170  2004/05/18 23:51:25  cheshire
 421 Tidy up all checkin comments to use consistent "<rdar://problem/xxxxxxx>" format for bug numbers
 422
 423 Revision 1.169  2004/05/13 04:54:20  ksekar
 424 Unified list copy/free code.  Added symetric list for
 425
 426 Revision 1.168  2004/05/12 22:03:09  ksekar
 427 Made GetSearchDomainList a true platform-layer call (declaration moved
 428 from mDNSMacOSX.h to mDNSEmbeddedAPI.h), implemented to return "local"
 429 only on non-OSX platforms.  Changed call to return a copy of the list
 430 to avoid shared memory issues.  Added a routine to free the list.
 431
 432 Revision 1.167  2004/04/22 04:07:01  cheshire
 433 Fix from Bob Bradley: Don't try to do inline functions on compilers that don't support it
 434
 435 Revision 1.166  2004/04/22 03:15:56  cheshire
 436 Fix use of "struct __attribute__((__packed__))" so it only applies on GCC >= 2.9
 437
 438 Revision 1.165  2004/04/22 03:05:28  cheshire
 439 kDNSClass_ANY should be kDNSQClass_ANY
 440
 441 Revision 1.164  2004/04/21 02:55:03  cheshire
 442 Update comments describing 'InterfaceActive' field
 443
 444 Revision 1.163  2004/04/21 02:49:11  cheshire
 445 To reduce future confusion, renamed 'TxAndRx' to 'McastTxRx'
 446
 447 Revision 1.162  2004/04/15 00:51:28  bradley
 448 Minor tweaks for Windows and C++ builds. Added casts for signed/unsigned integers and 64-bit pointers.
 449 Prefix some functions with mDNS to avoid conflicts. Disable benign warnings on Microsoft compilers.
 450
 451 Revision 1.161  2004/04/14 23:09:28  ksekar
 452 Support for TSIG signed dynamic updates.
 453
 454 Revision 1.160  2004/04/09 17:40:26  cheshire
 455 Remove unnecessary "Multicast" field -- it duplicates the semantics of the existing McastTxRx field
 456
 457 Revision 1.159  2004/04/09 16:37:15  cheshire
 458 Suggestion from Bob Bradley:
 459 Move NumCacheRecordsForInterfaceID() to DNSCommon.c so it's available to all platform layers
 460
 461 Revision 1.158  2004/04/02 19:38:33  cheshire
 462 Update comment about typical RR TTLs
 463
 464 Revision 1.157  2004/04/02 19:35:53  cheshire
 465 Add clarifying comments about legal mDNSInterfaceID values
 466
 467 Revision 1.156  2004/04/02 19:19:48  cheshire
 468 Add code to do optional logging of multi-packet KA list time intervals
 469
 470 Revision 1.155  2004/03/24 00:29:45  ksekar
 471 Make it safe to call StopQuery in a unicast question callback
 472
 473 Revision 1.154  2004/03/20 01:05:49  cheshire
 474 Test __LP64__ and __ILP64__ to compile properly on a wider range of 64-bit architectures
 475
 476 Revision 1.153  2004/03/13 01:57:33  ksekar
 477 <rdar://problem/3192546>: DynDNS: Dynamic update of service records
 478
 479 Revision 1.152  2004/03/09 02:27:16  cheshire
 480 Remove erroneous underscore in 'packed_struct' (makes no difference now, but might in future)
 481
 482 Revision 1.151  2004/03/02 03:21:56  cheshire
 483 <rdar://problem/3549576> Properly support "_services._dns-sd._udp" meta-queries
 484
 485 Revision 1.150  2004/02/21 02:06:24  cheshire
 486 Can't use anonymous unions -- they're non-standard and don't work on all compilers
 487
 488 Revision 1.149  2004/02/06 23:04:19  ksekar
 489 Basic Dynamic Update support via mDNS_Register (dissabled via
 490 UNICAST_REGISTRATION #define)
 491
 492 Revision 1.148  2004/02/03 19:47:36  ksekar
 493 Added an asynchronous state machine mechanism to uDNS.c, including
 494 calls to find the parent zone for a domain name.  Changes include code
 495 in repository previously dissabled via "#if 0 incomplete".  Codepath
 496 is currently unused, and will be called to create update records, etc.
 497
 498 Revision 1.147  2004/02/03 18:57:35  cheshire
 499 Update comment for "IsLocalDomain()"
 500
 501 Revision 1.146  2004/01/30 02:20:24  bradley
 502 Map inline to __inline when building with Microsoft C compilers since they do not support C99 inline.
 503
 504 Revision 1.145  2004/01/29 02:59:17  ksekar
 505 Unicast DNS: Changed from a resource record oriented question/response
 506 matching to packet based matching.  New callback architecture allows
 507 collections of records in a response to be processed differently
 508 depending on the nature of the request, and allows the same structure
 509 to be used for internal and client-driven queries with different processing needs.
 510
 511 Revision 1.144  2004/01/28 20:20:45  ksekar
 512 Unified ActiveQueries and ActiveInternalQueries lists, using a flag to
 513 demux them.  Check-in includes work-in-progress code, #ifdef'd out.
 514
 515 Revision 1.143  2004/01/28 03:41:00  cheshire
 516 <rdar://problem/3541946>: Need ability to do targeted queries as well as multicast queries
 517
 518 Revision 1.142  2004/01/28 02:30:07  ksekar
 519 Added default Search Domains to unicast browsing, controlled via
 520 Networking sharing prefs pane.  Stopped sending unicast messages on
 521 every interface.  Fixed unicast resolving via mach-port API.
 522
 523 Revision 1.141  2004/01/27 20:15:22  cheshire
 524 <rdar://problem/3541288>: Time to prune obsolete code for listening on port 53
 525
 526 Revision 1.140  2004/01/24 23:37:08  cheshire
 527 At Kiren's suggestion, made functions to convert mDNSOpaque16s to/from integer values
 528
 529 Revision 1.139  2004/01/24 08:46:26  bradley
 530 Added InterfaceID<->Index platform interfaces since they are now used by all platforms for the DNS-SD APIs.
 531
 532 Revision 1.138  2004/01/24 04:59:15  cheshire
 533 Fixes so that Posix/Linux, OS9, Windows, and VxWorks targets build again
 534
 535 Revision 1.137  2004/01/24 03:40:56  cheshire
 536 Move mDNSAddrIsDNSMulticast() from DNSCommon.h to mDNSEmbeddedAPI.h so clients can use it
 537
 538 Revision 1.136  2004/01/24 03:38:27  cheshire
 539 Fix minor syntactic error: Headers should use "extern" declarations, not "mDNSexport"
 540
 541 Revision 1.135  2004/01/23 23:23:15  ksekar
 542 Added TCP support for truncated unicast messages.
 543
 544 Revision 1.134  2004/01/22 03:54:11  cheshire
 545 Create special meta-interface 'mDNSInterface_ForceMCast' (-2),
 546 which means "do this query via multicast, even if it's apparently a unicast domain"
 547
 548 Revision 1.133  2004/01/22 03:48:41  cheshire
 549 Make sure uDNS client doesn't accidentally use query ID zero
 550
 551 Revision 1.132  2004/01/22 03:43:08  cheshire
 552 Export constants like mDNSInterface_LocalOnly so that the client layers can use them
 553
 554 Revision 1.131  2004/01/21 21:53:18  cheshire
 555 <rdar://problem/3448144>: Don't try to receive unicast responses if we're not the first to bind to the UDP port
 556
 557 Revision 1.130  2003/12/14 05:05:29  cheshire
 558 Add comments explaining mDNS_Init_NoCache and mDNS_Init_ZeroCacheSize
 559
 560 Revision 1.129  2003/12/13 03:05:27  ksekar
 561 <rdar://problem/3192548>: DynDNS: Unicast query of service records
 562
 563 Revision 1.128  2003/12/01 21:44:23  cheshire
 564 Add mStatus_BadInterfaceErr = -65552 for consistency with dns_sd.h
 565
 566 Revision 1.127  2003/12/01 18:26:37  cheshire
 567 Also pack the OpaqueXX union types. Otherwise, on some systems, mDNSOpaque16 is four bytes!
 568
 569 Revision 1.126  2003/12/01 18:23:48  cheshire
 570 <rdar://problem/3464646>: Scalar size problem in mDNS code on some 64-bit architectures
 571
 572 Revision 1.125  2003/11/22 00:18:27  cheshire
 573 Add compile-time asserts to verify correct sizes of mDNSu32, mDNSOpaque16, etc.
 574
 575 Revision 1.124  2003/11/20 22:59:54  cheshire
 576 Changed runtime checks in mDNS.c to be compile-time checks in mDNSEmbeddedAPI.h
 577 Thanks to Bob Bradley for suggesting the ingenious compiler trick to make this work.
 578
 579 Revision 1.123  2003/11/20 22:53:01  cheshire
 580 Add comment about MAX_ESCAPED_DOMAIN_LABEL
 581
 582 Revision 1.122  2003/11/20 20:49:53  cheshire
 583 Another fix from HP: Use packedstruct macro to ensure proper packing for on-the-wire packet structures
 584
 585 Revision 1.121  2003/11/20 05:01:38  cheshire
 586 Update comments; add explanation of Advertise/DontAdvertiseLocalAddresses
 587
 588 Revision 1.120  2003/11/14 20:59:08  cheshire
 589 Clients can't use AssignDomainName macro because mDNSPlatformMemCopy is defined in mDNSPlatformFunctions.h.
 590 Best solution is just to combine mDNSEmbeddedAPI.h and mDNSPlatformFunctions.h into a single file.
 591
 592 Revision 1.119  2003/11/14 19:47:52  cheshire
 593 Define symbol MAX_ESCAPED_DOMAIN_NAME to indicate recommended buffer size for ConvertDomainNameToCString
 594
 595 Revision 1.118  2003/11/14 19:18:34  cheshire
 596 Move AssignDomainName macro to mDNSEmbeddedAPI.h to that client layers can use it too
 597
 598 Revision 1.117  2003/11/08 23:32:24  cheshire
 599 Gave name to anonymous struct, to avoid errors on certain compilers.
 600 (Thanks to ramaprasad.kr@hp.com for reporting this.)
 601
 602 Revision 1.116  2003/11/07 03:32:56  cheshire
 603 <rdar://problem/3472153> mDNSResponder delivers answers in inconsistent order
 604 This is the real fix. Checkin 1.312 was overly simplistic; Calling GetFreeCacheRR() can sometimes
 605 purge records from the cache, causing tail pointer *rp to be stale on return. The correct fix is
 606 to maintain a system-wide tail pointer for each cache slot, and then if neccesary GetFreeCacheRR()
 607 can update this pointer, so that mDNSCoreReceiveResponse() appends records in the right place.
 608
 609 Revision 1.115  2003/09/23 00:53:54  cheshire
 610 NumFailedProbes should be unsigned
 611
 612 Revision 1.114  2003/08/29 19:44:15  cheshire
 613 <rdar://problem/3400967> Traffic reduction: Eliminate synchronized QUs when a new service appears
 614 1. Use m->RandomQueryDelay to impose a random delay in the range 0-500ms on queries
 615    that already have at least one unique answer in the cache
 616 2. For these queries, go straight to QM, skipping QU
 617
 618 Revision 1.113  2003/08/21 19:31:58  cheshire
 619 Cosmetic: Swap order of fields
 620
 621 Revision 1.112  2003/08/21 19:27:36  cheshire
 622 <rdar://problem/3387878> Traffic reduction: No need to announce record for longer than TTL
 623
 624 Revision 1.111  2003/08/21 02:21:50  cheshire
 625 <rdar://problem/3386473> Efficiency: Reduce repeated queries
 626
 627 Revision 1.110  2003/08/20 23:39:31  cheshire
 628 <rdar://problem/3344098> Review syslog messages, and remove as appropriate
 629
 630 Revision 1.109  2003/08/19 22:24:10  cheshire
 631 Comment change
 632
 633 Revision 1.108  2003/08/19 22:20:00  cheshire
 634 <rdar://problem/3376721> Don't use IPv6 on interfaces that have a routable IPv4 address configured
 635 More minor refinements
 636
 637 Revision 1.107  2003/08/19 06:48:25  cheshire
 638 <rdar://problem/3376552> Guard against excessive record updates
 639 Each record starts with 10 UpdateCredits.
 640 Every update consumes one UpdateCredit.
 641 UpdateCredits are replenished at a rate of one one per minute, up to a maximum of 10.
 642 As the number of UpdateCredits declines, the number of announcements is similarly scaled back.
 643 When fewer than 5 UpdateCredits remain, the first announcement is also delayed by an increasing amount.
 644
 645 Revision 1.106  2003/08/19 04:49:28  cheshire
 646 <rdar://problem/3368159> Interaction between v4, v6 and dual-stack hosts not working quite right
 647 1. A dual-stack host should only suppress its own query if it sees the same query from other hosts on BOTH IPv4 and IPv6.
 648 2. When we see the first v4 (or first v6) member of a group, we re-trigger questions and probes on that interface.
 649 3. When we see the last v4 (or v6) member of a group go away, we revalidate all the records received on that interface.
 650
 651 Revision 1.105  2003/08/19 02:33:37  cheshire
 652 Update comments
 653
 654 Revision 1.104  2003/08/19 02:31:11  cheshire
 655 <rdar://problem/3378386> mDNSResponder overenthusiastic with final expiration queries
 656 Final expiration queries now only mark the question for sending on the particular interface
 657 pertaining to the record that's expiring.
 658
 659 Revision 1.103  2003/08/18 19:05:44  cheshire
 660 <rdar://problem/3382423> UpdateRecord not working right
 661 Added "newrdlength" field to hold new length of updated rdata
 662
 663 Revision 1.102  2003/08/16 03:39:00  cheshire
 664 <rdar://problem/3338440> InterfaceID -1 indicates "local only"
 665
 666 Revision 1.101  2003/08/15 20:16:02  cheshire
 667 <rdar://problem/3366590> mDNSResponder takes too much RPRVT
 668 We want to avoid touching the rdata pages, so we don't page them in.
 669 1. RDLength was stored with the rdata, which meant touching the page just to find the length.
 670    Moved this from the RData to the ResourceRecord object.
 671 2. To avoid unnecessarily touching the rdata just to compare it,
 672    compute a hash of the rdata and store the hash in the ResourceRecord object.
 673
 674 Revision 1.100  2003/08/14 19:29:04  cheshire
 675 <rdar://problem/3378473> Include cache records in SIGINFO output
 676 Moved declarations of DNSTypeName() and GetRRDisplayString to mDNSEmbeddedAPI.h so daemon.c can use them
 677
 678 Revision 1.99  2003/08/14 02:17:05  cheshire
 679 <rdar://problem/3375491> Split generic ResourceRecord type into two separate types: AuthRecord and CacheRecord
 680
 681 Revision 1.98  2003/08/12 19:56:23  cheshire
 682 Update to APSL 2.0
 683
 684 Revision 1.97  2003/08/12 14:59:27  cheshire
 685 <rdar://problem/3374490> Rate-limiting blocks some legitimate responses
 686 When setting LastMCTime also record LastMCInterface. When checking LastMCTime to determine
 687 whether to suppress the response, also check LastMCInterface to see if it matches.
 688
 689 Revision 1.96  2003/08/12 13:57:04  cheshire
 690 <rdar://problem/3323817> Improve cache performance
 691 Changed the number of hash table slots from 37 to 499
 692
 693 Revision 1.95  2003/08/09 00:55:02  cheshire
 694 <rdar://problem/3366553> mDNSResponder is taking 20-30% of the CPU
 695 Don't scan the whole cache after every packet.
 696
 697 Revision 1.94  2003/08/09 00:35:29  cheshire
 698
 699 Revision 1.93  2003/08/08 18:55:48  cheshire
 700 <rdar://problem/3370365> Guard against time going backwards
 701
 702 Revision 1.92  2003/08/08 18:36:04  cheshire
 703 <rdar://problem/3344154> Only need to revalidate on interface removal on platforms that have the PhantomInterfaces bug
 704
 705 Revision 1.91  2003/08/06 21:33:39  cheshire
 706 Fix compiler warnings on PocketPC 2003 (Windows CE)
 707
 708 Revision 1.90  2003/08/06 20:30:17  cheshire
 709 Add structure definition for rdataMX (not currently used, but good to have it for completeness)
 710
 711 Revision 1.89  2003/08/06 18:58:19  cheshire
 712 Update comments
 713
 714 Revision 1.88  2003/07/24 23:45:44  cheshire
 715 To eliminate compiler warnings, changed definition of mDNSBool from
 716 "unsigned char" to "int", since "int" is in fact truly the type that C uses
 717 for the result of comparison operators (a<b) and logical operators (a||b)
 718
 719 Revision 1.87  2003/07/22 23:57:20  cheshire
 720 Move platform-layer function prototypes from mDNSEmbeddedAPI.h to mDNSPlatformFunctions.h where they belong
 721
 722 Revision 1.86  2003/07/20 03:52:02  ksekar
 723 <rdar://problem/3320722>: Feature: New DNS-SD APIs (#7875) (mDNSResponder component)
 724 Added error type for incompatibility between daemon and client versions
 725
 726 Revision 1.85  2003/07/19 03:23:13  cheshire
 727 <rdar://problem/2986147> mDNSResponder needs to receive and cache larger records
 728
 729 Revision 1.84  2003/07/18 23:52:12  cheshire
 730 To improve consistency of field naming, global search-and-replace:
 731 NextProbeTime    -> NextScheduledProbe
 732 NextResponseTime -> NextScheduledResponse
 733
 734 Revision 1.83  2003/07/18 00:29:59  cheshire
 735 <rdar://problem/3268878> Remove mDNSResponder version from packet header and use HINFO record instead
 736
 737 Revision 1.82  2003/07/17 17:35:04  cheshire
 738 <rdar://problem/3325583> Rate-limit responses, to guard against packet flooding
 739
 740 Revision 1.81  2003/07/16 05:01:36  cheshire
 741 Add fields 'LargeAnswers' and 'ExpectUnicastResponse' in preparation for
 742 <rdar://problem/3315761> Need to implement "unicast response" request, using top bit of qclass
 743
 744 Revision 1.80  2003/07/15 01:55:12  cheshire
 745 <rdar://problem/3315777> Need to implement service registration with subtypes
 746
 747 Revision 1.79  2003/07/13 02:28:00  cheshire
 748 <rdar://problem/3325166> SendResponses didn't all its responses
 749 Delete all references to RRInterfaceActive -- it's now superfluous
 750
 751 Revision 1.78  2003/07/13 01:47:53  cheshire
 752 Fix one error and one warning in the Windows build
 753
 754 Revision 1.77  2003/07/11 01:32:38  cheshire
 755 Syntactic cleanup (no change to funcationality): Now that we only have one host name,
 756 rename field "hostname1" to "hostname", and field "RR_A1" to "RR_A".
 757
 758 Revision 1.76  2003/07/11 01:28:00  cheshire
 759 <rdar://problem/3161289> No more local.arpa
 760
 761 Revision 1.75  2003/07/02 21:19:45  cheshire
 762 <rdar://problem/3313413> Update copyright notices, etc., in source code comments
 763
 764 Revision 1.74  2003/07/02 02:41:23  cheshire
 765 <rdar://problem/2986146> mDNSResponder needs to start with a smaller cache and then grow it as needed
 766
 767 Revision 1.73  2003/06/10 04:24:39  cheshire
 768 <rdar://problem/3283637> React when we observe other people query unsuccessfully for a record that's in our cache
 769 Some additional refinements:
 770 Don't try to do this for unicast-response queries
 771 better tracking of Qs and KAs in multi-packet KA lists
 772
 773 Revision 1.72  2003/06/10 01:46:27  cheshire
 774 Add better comments explaining how these data structures are intended to be used from the client layer
 775
 776 Revision 1.71  2003/06/07 06:45:05  cheshire
 777 <rdar://problem/3283666> No need for multiple machines to all be sending the same queries
 778
 779 Revision 1.70  2003/06/07 04:50:53  cheshire
 780 <rdar://problem/3283637> React when we observe other people query unsuccessfully for a record that's in our cache
 781
 782 Revision 1.69  2003/06/07 04:22:17  cheshire
 783 Add MsgBuffer for error log and debug messages
 784
 785 Revision 1.68  2003/06/07 01:46:38  cheshire
 786 <rdar://problem/3283540> When query produces zero results, call mDNS_Reconfirm() on any antecedent records
 787
 788 Revision 1.67  2003/06/07 01:22:14  cheshire
 789 <rdar://problem/3283516> mDNSResponder needs an mDNS_Reconfirm() function
 790
 791 Revision 1.66  2003/06/07 00:59:43  cheshire
 792 <rdar://problem/3283454> Need some randomness to spread queries on the network
 793
 794 Revision 1.65  2003/06/06 21:41:11  cheshire
 795 For consistency, mDNS_StopQuery() should return an mStatus result, just like all the other mDNSCore routines
 796
 797 Revision 1.64  2003/06/06 21:38:55  cheshire
 798 Renamed 'NewData' as 'FreshData' (The data may not be new data, just a refresh of data that we
 799 already had in our cache. This refreshes our TTL on the data, but the data itself stays the same.)
 800
 801 Revision 1.63  2003/06/06 17:20:14  cheshire
 802 For clarity, rename question fields name/rrtype/rrclass as qname/qtype/qclass
 803 (Global search-and-replace; no functional change to code execution.)
 804
 805 Revision 1.62  2003/06/04 01:25:33  cheshire
 806 <rdar://problem/3274950> Cannot perform multi-packet known-answer suppression messages
 807 Display time interval between first and subsequent queries
 808
 809 Revision 1.61  2003/06/03 05:02:16  cheshire
 810 <rdar://problem/3277080> Duplicate registrations not handled as efficiently as they should be
 811
 812 Revision 1.60  2003/05/31 00:09:49  cheshire
 813 <rdar://problem/3274862> Add ability to discover what services are on a network
 814
 815 Revision 1.59  2003/05/29 06:11:35  cheshire
 816 <rdar://problem/3272214>:       Report if there appear to be too many "Resolve" callbacks
 817
 818 Revision 1.58  2003/05/29 05:48:06  cheshire
 819 Minor fix for when generating printf warnings: mDNS_snprintf arguments are now 3,4
 820
 821 Revision 1.57  2003/05/26 03:21:27  cheshire
 822 Tidy up address structure naming:
 823 mDNSIPAddr         => mDNSv4Addr (for consistency with mDNSv6Addr)
 824 mDNSAddr.addr.ipv4 => mDNSAddr.ip.v4
 825 mDNSAddr.addr.ipv6 => mDNSAddr.ip.v6
 826
 827 Revision 1.56  2003/05/26 03:01:27  cheshire
 828 <rdar://problem/3268904> sprintf/vsprintf-style functions are unsafe; use snprintf/vsnprintf instead
 829
 830 Revision 1.55  2003/05/26 00:47:30  cheshire
 831 Comment clarification
 832
 833 Revision 1.54  2003/05/24 16:39:48  cheshire
 834 <rdar://problem/3268631> SendResponses also needs to handle multihoming better
 835
 836 Revision 1.53  2003/05/23 02:15:37  cheshire
 837 Fixed misleading use of the term "duplicate suppression" where it should have
 838 said "known answer suppression". (Duplicate answer suppression is something
 839 different, and duplicate question suppression is yet another thing, so the use
 840 of the completely vague term "duplicate suppression" was particularly bad.)
 841
 842 Revision 1.52  2003/05/22 02:29:22  cheshire
 843 <rdar://problem/2984918> SendQueries needs to handle multihoming better
 844 Complete rewrite of SendQueries. Works much better now :-)
 845
 846 Revision 1.51  2003/05/21 20:14:55  cheshire
 847 Fix comments and warnings
 848
 849 Revision 1.50  2003/05/14 07:08:36  cheshire
 850 <rdar://problem/3159272> mDNSResponder should be smarter about reconfigurations
 851 Previously, when there was any network configuration change, mDNSResponder
 852 would tear down the entire list of active interfaces and start again.
 853 That was very disruptive, and caused the entire cache to be flushed,
 854 and caused lots of extra network traffic. Now it only removes interfaces
 855 that have really gone, and only adds new ones that weren't there before.
 856
 857 Revision 1.49  2003/05/07 01:49:36  cheshire
 858 Remove "const" in ConstructServiceName prototype
 859
 860 Revision 1.48  2003/05/07 00:18:44  cheshire
 861 Fix typo: "kDNSQClass_Mask" should be "kDNSClass_Mask"
 862
 863 Revision 1.47  2003/05/06 00:00:46  cheshire
 864 <rdar://problem/3248914> Rationalize naming of domainname manipulation functions
 865
 866 Revision 1.46  2003/04/30 20:39:09  cheshire
 867 Add comment
 868
 869 Revision 1.45  2003/04/29 00:40:50  cheshire
 870 Fix compiler warnings
 871
 872 Revision 1.44  2003/04/26 02:41:56  cheshire
 873 <rdar://problem/3241281> Change timenow from a local variable to a structure member
 874
 875 Revision 1.43  2003/04/25 01:45:56  cheshire
 876 <rdar://problem/3240002> mDNS_RegisterNoSuchService needs to include a host name
 877
 878 Revision 1.42  2003/04/15 20:58:31  jgraessl
 879
 880 <rdar://problem/3229014> Added a hash to lookup records in the cache.
 881
 882 Revision 1.41  2003/04/15 18:09:13  jgraessl
 883
 884 <rdar://problem/3228892>
 885 Reviewed by: Stuart Cheshire
 886 Added code to keep track of when the next cache item will expire so we can
 887 call TidyRRCache only when necessary.
 888
 889 Revision 1.40  2003/03/29 01:55:19  cheshire
 890 <rdar://problem/3212360> mDNSResponder sometimes suffers false self-conflicts when it sees its own packets
 891 Solution: Major cleanup of packet timing and conflict handling rules
 892
 893 Revision 1.39  2003/03/27 03:30:55  cheshire
 894 <rdar://problem/3210018> Name conflicts not handled properly, resulting in memory corruption, and eventual crash
 895 Problem was that HostNameCallback() was calling mDNS_DeregisterInterface(), which is not safe in a callback
 896 Fixes:
 897 1. Make mDNS_DeregisterInterface() safe to call from a callback
 898 2. Make HostNameCallback() use mDNS_DeadvertiseInterface() instead
 899    (it never really needed to deregister the interface at all)
 900
 901 Revision 1.38  2003/03/15 04:40:36  cheshire
 902 Change type called "mDNSOpaqueID" to the more descriptive name "mDNSInterfaceID"
 903
 904 Revision 1.37  2003/03/14 21:34:11  cheshire
 905 <rdar://problem/3176950> Can't setup and print to Lexmark PS printers via Airport Extreme
 906 Increase size of cache rdata from 512 to 768
 907
 908 Revision 1.36  2003/03/05 03:38:35  cheshire
 909 <rdar://problem/3185731> Bogus error message in console: died or deallocated, but no record of client can be found!
 910 Fixed by leaving client in list after conflict, until client explicitly deallocates
 911
 912 Revision 1.35  2003/02/21 02:47:54  cheshire
 913 <rdar://problem/3099194> mDNSResponder needs performance improvements
 914 Several places in the code were calling CacheRRActive(), which searched the entire
 915 question list every time, to see if this cache resource record answers any question.
 916 Instead, we now have a field "CRActiveQuestion" in the resource record structure
 917
 918 Revision 1.34  2003/02/21 01:54:08  cheshire
 919 <rdar://problem/3099194> mDNSResponder needs performance improvements
 920 Switched to using new "mDNS_Execute" model (see "Implementer Notes.txt")
 921
 922 Revision 1.33  2003/02/20 06:48:32  cheshire
 923 <rdar://problem/3169535> Xserve RAID needs to do interface-specific registrations
 924 Reviewed by: Josh Graessley, Bob Bradley
 925
 926 Revision 1.32  2003/01/31 03:35:59  cheshire
 927 <rdar://problem/3147097> mDNSResponder sometimes fails to find the correct results
 928 When there were *two* active questions in the list, they were incorrectly
 929 finding *each other* and *both* being marked as duplicates of another question
 930
 931 Revision 1.31  2003/01/29 02:46:37  cheshire
 932 Fix for IPv6:
 933 A physical interface is identified solely by its InterfaceID (not by IP and type).
 934 On a given InterfaceID, mDNSCore may send both v4 and v6 multicasts.
 935 In cases where the requested outbound protocol (v4 or v6) is not supported on
 936 that InterfaceID, the platform support layer should simply discard that packet.
 937
 938 Revision 1.30  2003/01/29 01:47:08  cheshire
 939 Rename 'Active' to 'CRActive' or 'InterfaceActive' for improved clarity
 940
 941 Revision 1.29  2003/01/28 05:23:43  cheshire
 942 <rdar://problem/3147097> mDNSResponder sometimes fails to find the correct results
 943 Add 'Active' flag for interfaces
 944
 945 Revision 1.28  2003/01/28 01:35:56  cheshire
 946 Revise comment about ThisQInterval to reflect new semantics
 947
 948 Revision 1.27  2003/01/13 23:49:42  jgraessl
 949 Merged changes for the following fixes in to top of tree:
 950 <rdar://problem/3086540>  computer name changes not handled properly
 951 <rdar://problem/3124348>  service name changes are not properly handled
 952 <rdar://problem/3124352>  announcements sent in pairs, failing chattiness test
 953
 954 Revision 1.26  2002/12/23 22:13:28  jgraessl
 955
 956 Reviewed by: Stuart Cheshire
 957 Initial IPv6 support for mDNSResponder.
 958
 959 Revision 1.25  2002/09/21 20:44:49  zarzycki
 960 Added APSL info
 961
 962 Revision 1.24  2002/09/19 23:47:35  cheshire
 963 Added mDNS_RegisterNoSuchService() function for assertion of non-existence
 964 of a particular named service
 965
 966 Revision 1.23  2002/09/19 21:25:34  cheshire
 967 mDNS_snprintf() doesn't need to be in a separate file
 968
 969 Revision 1.22  2002/09/19 04:20:43  cheshire
 970 Remove high-ascii characters that confuse some systems
 971
 972 Revision 1.21  2002/09/17 01:06:35  cheshire
 973 Change mDNS_AdvertiseLocalAddresses to be a parameter to mDNS_Init()
 974
 975 Revision 1.20  2002/09/16 18:41:41  cheshire
 976 Merge in license terms from Quinn's copy, in preparation for Darwin release
 977
 978 */
 979
 980 #ifndef __mDNSClientAPI_h
 981 #define __mDNSClientAPI_h
 982
 983 #include <stdarg.h>             // stdarg.h is required for for va_list support for the mDNS_vsnprintf declaration
 984 #include "mDNSDebug.h"
 985
 986 #ifdef __cplusplus
 987         extern "C" {
 988 #endif
 989
 990 // ***************************************************************************
 991 // Function scope indicators
 992
 993 // If you see "mDNSlocal" before a function name in a C file, it means the function is not callable outside this file
 994 #ifndef mDNSlocal
 995 #define mDNSlocal static
 996 #endif
 997 // If you see "mDNSexport" before a symbol in a C file, it means the symbol is exported for use by clients
 998 // For every "mDNSexport" in a C file, there needs to be a corresponding "extern" declaration in some header file
 999 // (When a C file #includes a header file, the "extern" declarations tell the compiler:
1000 // "This symbol exists -- but not necessarily in this C file.")
1001 #ifndef mDNSexport
1002 #define mDNSexport
1003 #endif
1004
1005 // ***************************************************************************
1006 // Structure packing macro
1007
1008 // If we're not using GNUC, it's not fatal.
1009 // Most compilers naturally pack the on-the-wire structures correctly anyway, so a plain "struct" is usually fine.
1010 // In the event that structures are not packed correctly, mDNS_Init() will detect this and report an error, so the
1011 // developer will know what's wrong, and can investigate what needs to be done on that compiler to provide proper packing.
1012 #ifndef packedstruct
1013  #if ((__GNUC__ > 2) || ((__GNUC__ == 2) && (__GNUC_MINOR__ >= 9)))
1014   #define packedstruct struct __attribute__((__packed__))
1015   #define packedunion  union  __attribute__((__packed__))
1016  #else
1017   #define packedstruct struct
1018   #define packedunion  union
1019  #endif
1020 #endif
1021
1022 // ***************************************************************************
1023 #if 0
1024 #pragma mark - DNS Resource Record class and type constants
1025 #endif
1026
1027 typedef enum                                                    // From RFC 1035
1028         {
1029         kDNSClass_IN               = 1,         // Internet
1030         kDNSClass_CS               = 2,         // CSNET
1031         kDNSClass_CH               = 3,         // CHAOS
1032         kDNSClass_HS               = 4,         // Hesiod
1033         kDNSClass_NONE             = 254,       // Used in DNS UPDATE [RFC 2136]
1034
1035         kDNSClass_Mask             = 0x7FFF,// Multicast DNS uses the bottom 15 bits to identify the record class...
1036         kDNSClass_UniqueRRSet      = 0x8000,// ... and the top bit indicates that all other cached records are now invalid
1037
1038         kDNSQClass_ANY             = 255,       // Not a DNS class, but a DNS query class, meaning "all classes"
1039         kDNSQClass_UnicastResponse = 0x8000     // Top bit set in a question means "unicast response acceptable"
1040         } DNS_ClassValues;
1041
1042 typedef enum                            // From RFC 1035
1043         {
1044         kDNSType_A = 1,                 //  1 Address
1045         kDNSType_NS,                    //  2 Name Server
1046         kDNSType_MD,                    //  3 Mail Destination
1047         kDNSType_MF,                    //  4 Mail Forwarder
1048         kDNSType_CNAME,                 //  5 Canonical Name
1049         kDNSType_SOA,                   //  6 Start of Authority
1050         kDNSType_MB,                    //  7 Mailbox
1051         kDNSType_MG,                    //  8 Mail Group
1052         kDNSType_MR,                    //  9 Mail Rename
1053         kDNSType_NULL,                  // 10 NULL RR
1054         kDNSType_WKS,                   // 11 Well-known-service
1055         kDNSType_PTR,                   // 12 Domain name pointer
1056         kDNSType_HINFO,                 // 13 Host information
1057         kDNSType_MINFO,                 // 14 Mailbox information
1058         kDNSType_MX,                    // 15 Mail Exchanger
1059         kDNSType_TXT,                   // 16 Arbitrary text string
1060
1061         kDNSType_AAAA = 28,             // 28 IPv6 address
1062         kDNSType_SRV  = 33,             // 33 Service record
1063         kDNSType_OPT  = 41,     // EDNS0 OPT record
1064         kDNSType_TSIG = 250,    // 250 Transaction Signature
1065
1066         kDNSQType_ANY = 255             // Not a DNS type, but a DNS query type, meaning "all types"
1067         } DNS_TypeValues;
1068
1069 // ***************************************************************************
1070 #if 0
1071 #pragma mark - Simple types
1072 #endif
1073
1074 // mDNS defines its own names for these common types to simplify portability across
1075 // multiple platforms that may each have their own (different) names for these types.
1076 typedef          int   mDNSBool;
1077 typedef   signed char  mDNSs8;
1078 typedef unsigned char  mDNSu8;
1079 typedef   signed short mDNSs16;
1080 typedef unsigned short mDNSu16;
1081
1082 // <http://gcc.gnu.org/onlinedocs/gcc-3.3.3/cpp/Common-Predefined-Macros.html> says
1083 //   __LP64__ _LP64
1084 //   These macros are defined, with value 1, if (and only if) the compilation is
1085 //   for a target where long int and pointer both use 64-bits and int uses 32-bit.
1086 // <http://www.intel.com/software/products/compilers/clin/docs/ug/lin1077.htm> says
1087 //   Macro Name __LP64__ Value 1
1088 // A quick Google search for "defined(__LP64__)" OR "#ifdef __LP64__" gives 2590 hits and
1089 // a search for "#if __LP64__" gives only 12, so I think we'll go with the majority and use defined()
1090 #if defined(_LP64) || defined(__LP64__)
1091 typedef   signed int   mDNSs32;
1092 typedef unsigned int   mDNSu32;
1093 #elif defined(_ILP64) || defined(__ILP64__)
1094 typedef   signed int32 mDNSs32;
1095 typedef unsigned int32 mDNSu32;
1096 #else
1097 typedef   signed long  mDNSs32;
1098 typedef unsigned long  mDNSu32;
1099 #endif
1100
1101 // To enforce useful type checking, we make mDNSInterfaceID be a pointer to a dummy struct
1102 // This way, mDNSInterfaceIDs can be assigned, and compared with each other, but not with other types
1103 // Declaring the type to be the typical generic "void *" would lack this type checking
1104 typedef struct mDNSInterfaceID_dummystruct { void *dummy; } *mDNSInterfaceID;
1105
1106 // These types are for opaque two- and four-byte identifiers.
1107 // The "NotAnInteger" fields of the unions allow the value to be conveniently passed around in a
1108 // register for the sake of efficiency, and compared for equality or inequality, but don't forget --
1109 // just because it is in a register doesn't mean it is an integer. Operations like greater than,
1110 // less than, add, multiply, increment, decrement, etc., are undefined for opaque identifiers,
1111 // and if you make the mistake of trying to do those using the NotAnInteger field, then you'll
1112 // find you get code that doesn't work consistently on big-endian and little-endian machines.
1113 typedef packedunion { mDNSu8 b[ 2]; mDNSu16 NotAnInteger; } mDNSOpaque16;
1114 typedef packedunion { mDNSu8 b[ 4]; mDNSu32 NotAnInteger; } mDNSOpaque32;
1115 typedef packedunion { mDNSu8 b[ 6]; mDNSu16 w[3]; mDNSu32 l[1]; } mDNSOpaque48;
1116 typedef packedunion { mDNSu8 b[16]; mDNSu16 w[8]; mDNSu32 l[4]; } mDNSOpaque128;
1117
1118 typedef mDNSOpaque16  mDNSIPPort;               // An IP port is a two-byte opaque identifier (not an integer)
1119 typedef mDNSOpaque32  mDNSv4Addr;               // An IP address is a four-byte opaque identifier (not an integer)
1120 typedef mDNSOpaque128 mDNSv6Addr;               // An IPv6 address is a 16-byte opaque identifier (not an integer)
1121 typedef mDNSOpaque48  mDNSEthAddr;              // An Ethernet address is a six-byte opaque identifier (not an integer)
1122
1123 enum
1124         {
1125         mDNSAddrType_None    = 0,
1126         mDNSAddrType_IPv4    = 4,
1127         mDNSAddrType_IPv6    = 6,
1128         mDNSAddrType_Unknown = ~0       // Special marker value used in known answer list recording
1129         };
1130
1131 typedef struct
1132         {
1133         mDNSs32 type;
1134         union { mDNSv6Addr v6; mDNSv4Addr v4; } ip;
1135         } mDNSAddr;
1136
1137 enum { mDNSfalse = 0, mDNStrue = 1 };
1138
1139 #define mDNSNULL 0L
1140
1141 enum
1142         {
1143         mStatus_Waiting           = 1,
1144         mStatus_NoError           = 0,
1145
1146         // mDNS return values are in the range FFFE FF00 (-65792) to FFFE FFFF (-65537)
1147         // The top end of the range (FFFE FFFF) is used for error codes;
1148         // the bottom end of the range (FFFE FF00) is used for non-error values;
1149
1150         // Error codes:
1151         mStatus_UnknownErr        = -65537,             // First value: 0xFFFE FFFF
1152         mStatus_NoSuchNameErr     = -65538,
1153         mStatus_NoMemoryErr       = -65539,
1154         mStatus_BadParamErr       = -65540,
1155         mStatus_BadReferenceErr   = -65541,
1156         mStatus_BadStateErr       = -65542,
1157         mStatus_BadFlagsErr       = -65543,
1158         mStatus_UnsupportedErr    = -65544,
1159         mStatus_NotInitializedErr = -65545,
1160         mStatus_NoCache           = -65546,
1161         mStatus_AlreadyRegistered = -65547,
1162         mStatus_NameConflict      = -65548,
1163         mStatus_Invalid           = -65549,
1164         mStatus_Firewall          = -65550,
1165         mStatus_Incompatible      = -65551,
1166         mStatus_BadInterfaceErr   = -65552,
1167         mStatus_Refused           = -65553,
1168         mStatus_NoSuchRecord      = -65554,
1169         mStatus_NoAuth            = -65555,
1170         mStatus_NoSuchKey         = -65556,
1171         mStatus_NATTraversal      = -65557,
1172         mStatus_DoubleNAT         = -65558,
1173         mStatus_BadTime           = -65559,
1174         mStatus_BadSig            = -65560,     // while we define this per RFC 2845, BIND 9 returns Refused for bad/missing signatures
1175         mStatus_BadKey            = -65561,
1176         mStatus_TransientErr      = -65562,     // transient failures, e.g. sending packets shortly after a network transition or wake from sleep
1177         // -65563 to -65786 currently unused; available for allocation
1178
1179         // tcp connection status
1180         mStatus_ConnPending       = -65787,
1181         mStatus_ConnFailed        = -65788,
1182         mStatus_ConnEstablished   = -65789,
1183
1184         // Non-error values:
1185         mStatus_GrowCache         = -65790,
1186         mStatus_ConfigChanged     = -65791,
1187         mStatus_MemFree           = -65792              // Last value: 0xFFFE FF00
1188
1189         // mStatus_MemFree is the last legal mDNS error code, at the end of the range allocated for mDNS
1190         };
1191
1192 typedef mDNSs32 mStatus;
1193
1194 // RFC 1034/1035 specify that a domain label consists of a length byte plus up to 63 characters
1195 #define MAX_DOMAIN_LABEL 63
1196 typedef struct { mDNSu8 c[ 64]; } domainlabel;          // One label: length byte and up to 63 characters
1197
1198 // RFC 1034/1035 specify that a domain name, including length bytes, data bytes, and terminating zero, may be up to 255 bytes long
1199 #define MAX_DOMAIN_NAME 255
1200 typedef struct { mDNSu8 c[256]; } domainname;           // Up to 255 bytes of length-prefixed domainlabels
1201
1202 typedef struct { mDNSu8 c[256]; } UTF8str255;           // Null-terminated C string
1203
1204 // The longest legal textual form of a DNS name is 1005 bytes, including the C-string terminating NULL at the end.
1205 // Explanation:
1206 // When a native domainname object is converted to printable textual form using ConvertDomainNameToCString(),
1207 // non-printing characters are represented in the conventional DNS way, as '\ddd', where ddd is a three-digit decimal number.
1208 // The longest legal domain name is 255 bytes, in the form of four labels as shown below:
1209 // Length byte, 63 data bytes, length byte, 63 data bytes, length byte, 63 data bytes, length byte, 61 data bytes, zero byte.
1210 // Each label is encoded textually as characters followed by a trailing dot.
1211 // If every character has to be represented as a four-byte escape sequence, then this makes the maximum textual form four labels
1212 // plus the C-string terminating NULL as shown below:
1213 // 63*4+1 + 63*4+1 + 63*4+1 + 61*4+1 + 1 = 1005.
1214 // Note that MAX_ESCAPED_DOMAIN_LABEL is not normally used: If you're only decoding a single label, escaping is usually not required.
1215 // It is for domain names, where dots are used as label separators, that proper escaping is vital.
1216 #define MAX_ESCAPED_DOMAIN_LABEL 254
1217 #define MAX_ESCAPED_DOMAIN_NAME 1005
1218
1219 // Most records have a TTL of 75 minutes, so that their 80% cache-renewal query occurs once per hour.
1220 // For records containing a hostname (in the name on the left, or in the rdata on the right),
1221 // like A, AAAA, reverse-mapping PTR, and SRV, we use a two-minute TTL by default, because we don't want
1222 // them to hang around for too long in the cache if the host in question crashes or otherwise goes away.
1223 // Wide-area service discovery records have a very short TTL to aviod poluting intermediate caches with
1224 // dynamic records.  When discovered via Long Lived Queries (with change notifications), resource record
1225 // TTLs can be safely ignored.
1226
1227 #define kStandardTTL (3600UL * 100 / 80)
1228 #define kHostNameTTL 120UL
1229 #define kWideAreaTTL 3
1230
1231 #define DefaultTTLforRRType(X) (((X) == kDNSType_A || (X) == kDNSType_AAAA || (X) == kDNSType_SRV) ? kHostNameTTL : kStandardTTL)
1232
1233 // ***************************************************************************
1234 #if 0
1235 #pragma mark - DNS Message structures
1236 #endif
1237
1238 #define mDNS_numZones   numQuestions
1239 #define mDNS_numPrereqs numAnswers
1240 #define mDNS_numUpdates numAuthorities
1241
1242 typedef packedstruct
1243         {
1244         mDNSOpaque16 id;
1245         mDNSOpaque16 flags;
1246         mDNSu16 numQuestions;
1247         mDNSu16 numAnswers;
1248         mDNSu16 numAuthorities;
1249         mDNSu16 numAdditionals;
1250         } DNSMessageHeader;
1251
1252 // We can send and receive packets up to 9000 bytes (Ethernet Jumbo Frame size, if that ever becomes widely used)
1253 // However, in the normal case we try to limit packets to 1500 bytes so that we don't get IP fragmentation on standard Ethernet
1254 // 40 (IPv6 header) + 8 (UDP header) + 12 (DNS message header) + 1440 (DNS message body) = 1500 total
1255 #define AbsoluteMaxDNSMessageData 8940
1256 #define NormalMaxDNSMessageData 1440
1257 typedef packedstruct
1258         {
1259         DNSMessageHeader h;                                             // Note: Size 12 bytes
1260         mDNSu8 data[AbsoluteMaxDNSMessageData]; // 40 (IPv6) + 8 (UDP) + 12 (DNS header) + 8940 (data) = 9000
1261         } DNSMessage;
1262
1263 // ***************************************************************************
1264 #if 0
1265 #pragma mark - Resource Record structures
1266 #endif
1267
1268 // Authoritative Resource Records:
1269 // There are four basic types: Shared, Advisory, Unique, Known Unique
1270
1271 // * Shared Resource Records do not have to be unique
1272 // -- Shared Resource Records are used for DNS-SD service PTRs
1273 // -- It is okay for several hosts to have RRs with the same name but different RDATA
1274 // -- We use a random delay on responses to reduce collisions when all the hosts respond to the same query
1275 // -- These RRs typically have moderately high TTLs (e.g. one hour)
1276 // -- These records are announced on startup and topology changes for the benefit of passive listeners
1277 // -- These records send a goodbye packet when deregistering
1278 //
1279 // * Advisory Resource Records are like Shared Resource Records, except they don't send a goodbye packet
1280 //
1281 // * Unique Resource Records should be unique among hosts within any given mDNS scope
1282 // -- The majority of Resource Records are of this type
1283 // -- If two entities on the network have RRs with the same name but different RDATA, this is a conflict
1284 // -- Responses may be sent immediately, because only one host should be responding to any particular query
1285 // -- These RRs typically have low TTLs (e.g. a few minutes)
1286 // -- On startup and after topology changes, a host issues queries to verify uniqueness
1287
1288 // * Known Unique Resource Records are treated like Unique Resource Records, except that mDNS does
1289 // not have to verify their uniqueness because this is already known by other means (e.g. the RR name
1290 // is derived from the host's IP or Ethernet address, which is already known to be a unique identifier).
1291
1292 // Summary of properties of different record types:
1293 // Probe?    Does this record type send probes before announcing?
1294 // Conflict? Does this record type react if we observe an apparent conflict?
1295 // Goodbye?  Does this record type send a goodbye packet on departure?
1296 //
1297 //               Probe? Conflict? Goodbye? Notes
1298 // Unregistered                            Should not appear in any list (sanity check value)
1299 // Shared         No      No       Yes     e.g. Service PTR record
1300 // Deregistering  No      No       Yes     Shared record about to announce its departure and leave the list
1301 // Advisory       No      No       No
1302 // Unique         Yes     Yes      No      Record intended to be unique -- will probe to verify
1303 // Verified       Yes     Yes      No      Record has completed probing, and is verified unique
1304 // KnownUnique    No      Yes      No      Record is assumed by other means to be unique
1305
1306 // Valid lifecycle of a record:
1307 // Unregistered ->                   Shared      -> Deregistering -(goodbye)-> Unregistered
1308 // Unregistered ->                   Advisory                               -> Unregistered
1309 // Unregistered -> Unique -(probe)-> Verified                               -> Unregistered
1310 // Unregistered ->                   KnownUnique                            -> Unregistered
1311
1312 // Each Authoritative kDNSRecordType has only one bit set. This makes it easy to quickly see if a record
1313 // is one of a particular set of types simply by performing the appropriate bitwise masking operation.
1314
1315 // Cache Resource Records (received from the network):
1316 // There are four basic types: Answer, Unique Answer, Additional, Unique Additional
1317 // Bit 7 (the top bit) of kDNSRecordType is always set for Cache Resource Records; always clear for Authoritative Resource Records
1318 // Bit 6 (value 0x40) is set for answer records; clear for additional records
1319 // Bit 5 (value 0x20) is set for records received with the kDNSClass_UniqueRRSet
1320
1321 enum
1322         {
1323         kDNSRecordTypeUnregistered     = 0x00,  // Not currently in any list
1324         kDNSRecordTypeDeregistering    = 0x01,  // Shared record about to announce its departure and leave the list
1325
1326         kDNSRecordTypeUnique           = 0x02,  // Will become a kDNSRecordTypeVerified when probing is complete
1327
1328         kDNSRecordTypeAdvisory         = 0x04,  // Like Shared, but no goodbye packet
1329         kDNSRecordTypeShared           = 0x08,  // Shared means record name does not have to be unique -- use random delay on responses
1330
1331         kDNSRecordTypeVerified         = 0x10,  // Unique means mDNS should check that name is unique (and then send immediate responses)
1332         kDNSRecordTypeKnownUnique      = 0x20,  // Known Unique means mDNS can assume name is unique without checking
1333                                                 // For Dynamic Update records, Known Unique means the record must already exist on the server.
1334         kDNSRecordTypeUniqueMask       = (kDNSRecordTypeUnique | kDNSRecordTypeVerified | kDNSRecordTypeKnownUnique),
1335         kDNSRecordTypeActiveMask       = (kDNSRecordTypeAdvisory | kDNSRecordTypeShared | kDNSRecordTypeVerified | kDNSRecordTypeKnownUnique),
1336
1337         kDNSRecordTypePacketAdd        = 0x80,  // Received in the Additional  Section of a DNS Response
1338         kDNSRecordTypePacketAddUnique  = 0x90,  // Received in the Additional  Section of a DNS Response with kDNSClass_UniqueRRSet set
1339         kDNSRecordTypePacketAuth       = 0xA0,  // Received in the Authorities Section of a DNS Response
1340         kDNSRecordTypePacketAuthUnique = 0xB0,  // Received in the Authorities Section of a DNS Response with kDNSClass_UniqueRRSet set
1341         kDNSRecordTypePacketAns        = 0xC0,  // Received in the Answer      Section of a DNS Response
1342         kDNSRecordTypePacketAnsUnique  = 0xD0,  // Received in the Answer      Section of a DNS Response with kDNSClass_UniqueRRSet set
1343
1344         kDNSRecordTypePacketAnsMask    = 0x40,  // True for PacketAns and    PacketAnsUnique
1345         kDNSRecordTypePacketUniqueMask = 0x10   // True for PacketAddUnique, PacketAnsUnique, PacketAuthUnique
1346         };
1347
1348 typedef packedstruct { mDNSu16 priority; mDNSu16 weight; mDNSIPPort port; domainname target;   } rdataSRV;
1349 typedef packedstruct { mDNSu16 preference;                                domainname exchange; } rdataMX;
1350 typedef packedstruct
1351         {
1352         domainname mname;
1353         domainname rname;
1354         mDNSs32 serial;         // Modular counter; increases when zone changes
1355         mDNSu32 refresh;        // Time in seconds that a slave waits after successful replication of the database before it attempts replication again
1356         mDNSu32 retry;          // Time in seconds that a slave waits after an unsuccessful replication attempt before it attempts replication again
1357         mDNSu32 expire;         // Time in seconds that a slave holds on to old data while replication attempts remain unsuccessful
1358         mDNSu32 min;            // Nominally the minimum record TTL for this zone, in seconds; also used for negative caching.
1359         } rdataSOA;
1360
1361 typedef packedstruct
1362         {
1363         mDNSu16 vers;
1364         mDNSu16 llqOp;
1365         mDNSu16 err;
1366         mDNSu8 id[8];
1367         mDNSu32 lease;
1368         } LLQOptData;
1369
1370 // NOTE: rdataOpt format may be repeated an arbitrary number of times in a single resource record
1371 typedef packedstruct
1372         {
1373         mDNSu16 opt;
1374         mDNSu16 optlen;
1375         union { LLQOptData llq; mDNSu32 lease; } OptData;
1376         } rdataOpt;
1377
1378 // StandardAuthRDSize is 264 (256+8), which is large enough to hold a maximum-sized SRV record
1379 // MaximumRDSize is 8K the absolute maximum we support (at least for now)
1380 #define StandardAuthRDSize 264
1381 #define MaximumRDSize 8192
1382
1383 // InlineCacheRDSize is 68
1384 // Records received from the network with rdata this size or less have their rdata stored right in the CacheRecord object
1385 // Records received from the network with rdata larger than this have additional storage allocated for the rdata
1386 // A quick unscientific sample from a busy network at Apple with lots of machines revealed this:
1387 // 1461 records in cache
1388 // 292 were one-byte TXT records
1389 // 136 were four-byte A records
1390 // 184 were sixteen-byte AAAA records
1391 // 780 were various PTR, TXT and SRV records from 12-64 bytes
1392 // Only 69 records had rdata bigger than 64 bytes
1393 // Note that since CacheRecord object and a CacheGroup object are allocated out of the same pool, it's sensible to
1394 // have them both be the same size. Making one smaller without making the other smaller won't actually save any memory.
1395 #define InlineCacheRDSize 68
1396
1397 #define InlineCacheGroupNameSize 144
1398
1399 typedef union
1400         {
1401         mDNSu8      data[StandardAuthRDSize];
1402         mDNSv4Addr  ipv4;               // For 'A' record
1403         mDNSv6Addr  ipv6;               // For 'AAAA' record
1404         domainname  name;               // For PTR, NS, and CNAME records
1405         UTF8str255  txt;                // For TXT record
1406         rdataSRV    srv;                // For SRV record
1407         rdataMX     mx;                 // For MX record
1408         rdataSOA    soa;        // For SOA record
1409         rdataOpt    opt;        // For eDNS0 opt record
1410         } RDataBody;
1411
1412 typedef struct
1413         {
1414         mDNSu16    MaxRDLength; // Amount of storage allocated for rdata (usually sizeof(RDataBody))
1415         RDataBody  u;
1416         } RData;
1417 #define sizeofRDataHeader (sizeof(RData) - sizeof(RDataBody))
1418
1419 typedef struct AuthRecord_struct AuthRecord;
1420 typedef struct CacheRecord_struct CacheRecord;
1421 typedef struct CacheGroup_struct CacheGroup;
1422 typedef struct DNSQuestion_struct DNSQuestion;
1423 typedef struct mDNS_struct mDNS;
1424 typedef struct mDNS_PlatformSupport_struct mDNS_PlatformSupport;
1425 typedef struct NATTraversalInfo_struct NATTraversalInfo;
1426
1427 // Note: Within an mDNSRecordCallback mDNS all API calls are legal except mDNS_Init(), mDNS_Close(), mDNS_Execute()
1428 typedef void mDNSRecordCallback(mDNS *const m, AuthRecord *const rr, mStatus result);
1429
1430 // Note:
1431 // Restrictions: An mDNSRecordUpdateCallback may not make any mDNS API calls.
1432 // The intent of this callback is to allow the client to free memory, if necessary.
1433 // The internal data structures of the mDNS code may not be in a state where mDNS API calls may be made safely.
1434 typedef void mDNSRecordUpdateCallback(mDNS *const m, AuthRecord *const rr, RData *OldRData);
1435
1436 typedef struct
1437         {
1438         mDNSu8          RecordType;                     // See enum above
1439         mDNSInterfaceID InterfaceID;            // Set if this RR is specific to one interface
1440                                                                                 // For records received off the wire, InterfaceID is *always* set to the receiving interface
1441                                                                                 // For our authoritative records, InterfaceID is usually zero, except for those few records
1442                                                                                 // that are interface-specific (e.g. address records, especially linklocal addresses)
1443         domainname     *name;
1444         mDNSu16         rrtype;
1445         mDNSu16         rrclass;
1446         mDNSu32         rroriginalttl;          // In seconds
1447         mDNSu16         rdlength;                       // Size of the raw rdata, in bytes
1448         mDNSu16         rdestimate;                     // Upper bound on size of rdata after name compression
1449         mDNSu32         namehash;                       // Name-based (i.e. case-insensitive) hash of name
1450         mDNSu32         rdatahash;                      // For rdata containing domain name (e.g. PTR, SRV, CNAME etc.), case-insensitive name hash
1451                                                                                 // else, for all other rdata, 32-bit hash of the raw rdata
1452                                                                                 // Note: This requirement is important. Various routines like AddAdditionalsToResponseList(),
1453                                                                                 // ReconfirmAntecedents(), etc., use rdatahash as a pre-flight check to see
1454                                                                                 // whether it's worth doing a full SameDomainName() call. If the rdatahash
1455                                                                                 // is not a correct case-insensitive name hash, they'll get false negatives.
1456         RData           *rdata;                         // Pointer to storage for this rdata
1457         } ResourceRecord;
1458
1459 // Unless otherwise noted, states may apply to either independent record registrations or service registrations
1460 typedef enum
1461         {
1462         regState_FetchingZoneData  = 1,     // getting info - update not sent
1463         regState_Pending           = 2,     // update sent, reply not received
1464         regState_Registered        = 3,     // update sent, reply received
1465         regState_DeregPending      = 4,     // dereg sent, reply not received
1466         regState_DeregDeferred     = 5,     // dereg requested while in Pending state - send dereg AFTER registration is confirmed
1467         regState_Cancelled         = 6,     // update not sent, reg. cancelled by client
1468         regState_Unregistered      = 8,     // not in any list
1469         regState_Refresh           = 9,     // outstanding refresh (or target change) message
1470         regState_NATMap            = 10,    // establishing NAT port mapping or learning public address
1471         regState_UpdatePending     = 11,    // update in flight as result of mDNS_Update call
1472         regState_NoTarget          = 12,    // service registration pending registration of hostname (ServiceRegistrations only)
1473     regState_ExtraQueued       = 13,    // extra record to be registered upon completion of service registration (RecordRegistrations only)
1474         regState_NATError          = 14     // unable to complete NAT traversal
1475         } regState_t;
1476
1477 // context for both ServiceRecordSet and individual AuthRec structs
1478 typedef struct
1479         {
1480         // registration/lease state
1481         regState_t   state;
1482         mDNSBool     lease;    // dynamic update contains (should contain) lease option
1483         mDNSs32      expire;   // expiration of lease (-1 for static)
1484         mDNSBool     TestForSelfConflict;  // on name conflict, check if we're just seeing our own orphaned records
1485
1486         // identifier to match update request and response
1487         mDNSOpaque16 id;
1488
1489         // server info
1490         domainname   zone;     // the zone that is updated
1491         mDNSAddr     ns;       // primary name server for the record's zone    !!!KRS not technically correct to cache longer than TTL
1492         mDNSIPPort   port;     // port on which server accepts dynamic updates
1493
1494         // NAT traversal context
1495         NATTraversalInfo *NATinfo; // may be NULL
1496
1497         // state for deferred operations
1498     mDNSBool     ClientCallbackDeferred;  // invoke client callback on completion of pending operation(s)
1499         mStatus      DeferredStatus;          // status to deliver when above flag is set
1500     mDNSBool     SRVUpdateDeferred;       // do we need to change target or port once current operation completes?
1501     mDNSBool     SRVChanged;              // temporarily deregistered service because its SRV target or port changed
1502
1503     // uDNS_UpdateRecord support fields
1504         mDNSBool     UpdateQueued; // Update the rdata once the current pending operation completes
1505         RData       *UpdateRData;  // Pointer to new RData while a record update is in flight
1506         mDNSu16      UpdateRDLen;  // length of above field
1507         mDNSRecordUpdateCallback *UpdateRDCallback; // client callback to free old rdata
1508         } uDNS_RegInfo;
1509
1510 struct AuthRecord_struct
1511         {
1512         // For examples of how to set up this structure for use in mDNS_Register(),
1513         // see mDNS_AdvertiseInterface() or mDNS_RegisterService().
1514         // Basically, resrec and persistent metadata need to be set up before calling mDNS_Register().
1515         // mDNS_SetupResourceRecord() is avaliable as a helper routine to set up most fields to sensible default values for you
1516
1517         AuthRecord     *next;                           // Next in list; first element of structure for efficiency reasons
1518         // Field Group 1: Common ResourceRecord fields
1519         ResourceRecord  resrec;
1520         uDNS_RegInfo uDNS_info;
1521
1522         // Field Group 2: Persistent metadata for Authoritative Records
1523         AuthRecord     *Additional1;            // Recommended additional record to include in response
1524         AuthRecord     *Additional2;            // Another additional
1525         AuthRecord     *DependentOn;            // This record depends on another for its uniqueness checking
1526         AuthRecord     *RRSet;                          // This unique record is part of an RRSet
1527         mDNSRecordCallback *RecordCallback;     // Callback function to call for state changes, and to free memory asynchronously on deregistration
1528         void           *RecordContext;          // Context parameter for the callback function
1529         mDNSu8          HostTarget;                     // Set if the target of this record (PTR, CNAME, SRV, etc.) is our host name
1530         mDNSu8          AllowRemoteQuery;       // Set if we allow hosts not on the local link to query this record
1531         mDNSu8          ForceMCast;                     // Set by client to advertise solely via multicast, even for apparently unicast names
1532
1533         // Field Group 3: Transient state for Authoritative Records
1534         mDNSu8          Acknowledged;           // Set if we've given the success callback to the client
1535         mDNSu8          ProbeCount;                     // Number of probes remaining before this record is valid (kDNSRecordTypeUnique)
1536         mDNSu8          AnnounceCount;          // Number of announcements remaining (kDNSRecordTypeShared)
1537         mDNSu8          RequireGoodbye;         // Set if this RR has been announced on the wire and will require a goodbye packet
1538         mDNSu8          LocalAnswer;            // Set if this RR has been delivered to LocalOnly questions
1539         mDNSu8          IncludeInProbe;         // Set if this RR is being put into a probe right now
1540         mDNSInterfaceID ImmedAnswer;            // Someone on this interface issued a query we need to answer (all-ones for all interfaces)
1541         mDNSu8          ImmedUnicast;           // Set if we may send our response directly via unicast to the requester
1542 #if MDNS_LOG_ANSWER_SUPPRESSION_TIMES
1543         mDNSs32         ImmedAnswerMarkTime;
1544 #endif
1545         mDNSInterfaceID ImmedAdditional;        // Hint that we might want to also send this record, just to be helpful
1546         mDNSInterfaceID SendRNow;                       // The interface this query is being sent on right now
1547         mDNSv4Addr      v4Requester;            // Recent v4 query for this record, or all-ones if more than one recent query
1548         mDNSv6Addr      v6Requester;            // Recent v6 query for this record, or all-ones if more than one recent query
1549         AuthRecord     *NextResponse;           // Link to the next element in the chain of responses to generate
1550         const mDNSu8   *NR_AnswerTo;            // Set if this record was selected by virtue of being a direct answer to a question
1551         AuthRecord     *NR_AdditionalTo;        // Set if this record was selected by virtue of being additional to another
1552         mDNSs32         ThisAPInterval;         // In platform time units: Current interval for announce/probe
1553         mDNSs32         AnnounceUntil;          // In platform time units: Creation time + TTL
1554         mDNSs32         LastAPTime;                     // In platform time units: Last time we sent announcement/probe
1555         mDNSs32         LastMCTime;                     // Last time we multicast this record (used to guard against packet-storm attacks)
1556         mDNSInterfaceID LastMCInterface;        // Interface this record was multicast on at the time LastMCTime was recorded
1557         RData          *NewRData;                       // Set if we are updating this record with new rdata
1558         mDNSu16         newrdlength;            // ... and the length of the new RData
1559         mDNSRecordUpdateCallback *UpdateCallback;
1560         mDNSu32         UpdateCredits;          // Token-bucket rate limiting of excessive updates
1561         mDNSs32         NextUpdateCredit;       // Time next token is added to bucket
1562         mDNSs32         UpdateBlocked;          // Set if update delaying is in effect
1563
1564         domainname      namestorage;
1565         RData           rdatastorage;           // Normally the storage is right here, except for oversized records
1566         // rdatastorage MUST be the last thing in the structure -- when using oversized AuthRecords, extra bytes
1567         // are appended after the end of the AuthRecord, logically augmenting the size of the rdatastorage
1568         // DO NOT ADD ANY MORE FIELDS HERE
1569         };
1570
1571 // Wrapper struct for Auth Records for higher-level code that cannot use the AuthRecord's ->next pointer field
1572 typedef struct ARListElem
1573         {
1574         struct ARListElem *next;
1575         AuthRecord ar;          // Note: Must be last struct in field to accomodate oversized AuthRecords
1576         } ARListElem;
1577
1578 struct CacheGroup_struct                                // Header object for a list of CacheRecords with the same name
1579         {
1580         CacheGroup     *next;                           // Next CacheGroup object in this hash table bucket
1581         mDNSu32         namehash;                       // Name-based (i.e. case insensitive) hash of name
1582         CacheRecord    *members;                        // List of CacheRecords with this same name
1583         CacheRecord   **rrcache_tail;           // Tail end of that list
1584         domainname     *name;                           // Common name for all CacheRecords in this list
1585         mDNSu8          namestorage[InlineCacheGroupNameSize];
1586         };
1587
1588 struct CacheRecord_struct
1589         {
1590         CacheRecord    *next;                           // Next in list; first element of structure for efficiency reasons
1591         ResourceRecord  resrec;
1592
1593         // Transient state for Cache Records
1594         CacheRecord    *NextInKAList;           // Link to the next element in the chain of known answers to send
1595         mDNSs32         TimeRcvd;                       // In platform time units
1596         mDNSs32         DelayDelivery;          // Set if we want to defer delivery of this answer to local clients
1597         mDNSs32         NextRequiredQuery;      // In platform time units
1598         mDNSs32         LastUsed;                       // In platform time units
1599         DNSQuestion    *CRActiveQuestion;       // Points to an active question referencing this answer
1600         mDNSu32         UnansweredQueries;      // Number of times we've issued a query for this record without getting an answer
1601         mDNSs32         LastUnansweredTime;     // In platform time units; last time we incremented UnansweredQueries
1602         mDNSu32         MPUnansweredQ;          // Multi-packet query handling: Number of times we've seen a query for this record
1603         mDNSs32         MPLastUnansweredQT;     // Multi-packet query handling: Last time we incremented MPUnansweredQ
1604         mDNSu32         MPUnansweredKA;         // Multi-packet query handling: Number of times we've seen this record in a KA list
1605         mDNSBool        MPExpectingKA;          // Multi-packet query handling: Set when we increment MPUnansweredQ; allows one KA
1606         CacheRecord    *NextInCFList;           // Set if this is in the list of records we just received with the cache flush bit set
1607
1608         struct { mDNSu16 MaxRDLength; mDNSu8 data[InlineCacheRDSize]; } rdatastorage;   // Storage for small records is right here
1609         };
1610
1611 // Storage sufficient to hold either a CacheGroup header or a CacheRecord
1612 typedef union CacheEntity_union CacheEntity;
1613 union CacheEntity_union { CacheEntity *next; CacheGroup cg; CacheRecord cr; };
1614
1615 typedef struct
1616         {
1617         CacheRecord r;
1618         mDNSu8 _extradata[MaximumRDSize-InlineCacheRDSize];             // Glue on the necessary number of extra bytes
1619         domainname namestorage;                                                                 // Needs to go *after* the extra rdata bytes
1620         } LargeCacheRecord;
1621
1622 typedef struct uDNS_HostnameInfo
1623         {
1624         struct uDNS_HostnameInfo *next;
1625         AuthRecord *ar;                           // registered address record
1626         mDNSRecordCallback *StatusCallback;       // callback to deliver success or error code to client layer
1627         const void *StatusContext;                // Client Context
1628         } uDNS_HostnameInfo;
1629
1630 typedef struct DNSServer
1631         {
1632     struct DNSServer *next;
1633     mDNSAddr addr;
1634     domainname domain;       // name->server matching for "split dns"
1635     int flag;                // temporary marker for list intersection
1636         } DNSServer;
1637
1638 typedef struct NetworkInterfaceInfo_struct NetworkInterfaceInfo;
1639
1640 // A NetworkInterfaceInfo_struct serves two purposes:
1641 // 1. It holds the address, PTR and HINFO records to advertise a given IP address on a given physical interface
1642 // 2. It tells mDNSCore which physical interfaces are available; each physical interface has its own unique InterfaceID.
1643 //    Since there may be multiple IP addresses on a single physical interface,
1644 //    there may be multiple NetworkInterfaceInfo_structs with the same InterfaceID.
1645 //    In this case, to avoid sending the same packet n times, when there's more than one
1646 //    struct with the same InterfaceID, mDNSCore picks one member of the set to be the
1647 //    active representative of the set; all others have the 'InterfaceActive' flag unset.
1648
1649 struct NetworkInterfaceInfo_struct
1650         {
1651         // Internal state fields. These are used internally by mDNSCore; the client layer needn't be concerned with them.
1652         NetworkInterfaceInfo *next;
1653
1654         mDNSBool        InterfaceActive;        // Set if interface is sending & receiving packets (see comment above)
1655         mDNSBool        IPv4Available;          // If InterfaceActive, set if v4 available on this InterfaceID
1656         mDNSBool        IPv6Available;          // If InterfaceActive, set if v6 available on this InterfaceID
1657
1658         // Standard AuthRecords that every Responder host should have (one per active IP address)
1659         AuthRecord RR_A;                                        // 'A' or 'AAAA' (address) record for our ".local" name
1660         AuthRecord RR_PTR;                                      // PTR (reverse lookup) record
1661         AuthRecord RR_HINFO;
1662
1663         // Client API fields: The client must set up these fields *before* calling mDNS_RegisterInterface()
1664         mDNSInterfaceID InterfaceID;            // Identifies physical interface; MUST NOT be 0, -1, or -2
1665         mDNSAddr        ip;                                     // The IPv4 or IPv6 address to advertise
1666         mDNSAddr        mask;
1667         char            ifname[64];                     // Windows uses a GUID string for the interface name, which doesn't fit in 16 bytes
1668         mDNSBool        Advertise;                      // False if you are only searching on this interface
1669         mDNSBool        McastTxRx;                      // Send/Receive multicast on this { InterfaceID, address family } ?
1670         };
1671
1672 typedef struct ExtraResourceRecord_struct ExtraResourceRecord;
1673 struct ExtraResourceRecord_struct
1674         {
1675         ExtraResourceRecord *next;
1676     mDNSu32 ClientID;  // Opaque ID field to be used by client to map an AddRecord call to a set of Extra records
1677         AuthRecord r;
1678         // Note: Add any additional fields *before* the AuthRecord in this structure, not at the end.
1679         // In some cases clients can allocate larger chunks of memory and set r->rdata->MaxRDLength to indicate
1680         // that this extra memory is available, which would result in any fields after the AuthRecord getting smashed
1681         };
1682
1683 // Note: Within an mDNSServiceCallback mDNS all API calls are legal except mDNS_Init(), mDNS_Close(), mDNS_Execute()
1684 typedef struct ServiceRecordSet_struct ServiceRecordSet;
1685 typedef void mDNSServiceCallback(mDNS *const m, ServiceRecordSet *const sr, mStatus result);
1686 struct ServiceRecordSet_struct
1687         {
1688         // Internal state fields. These are used internally by mDNSCore; the client layer needn't be concerned with them.
1689         // No fields need to be set up by the client prior to calling mDNS_RegisterService();
1690         // all required data is passed as parameters to that function.
1691         ServiceRecordSet    *next;
1692         uDNS_RegInfo        uDNS_info;
1693         mDNSServiceCallback *ServiceCallback;
1694         void                *ServiceContext;
1695         ExtraResourceRecord *Extras;    // Optional list of extra AuthRecords attached to this service registration
1696         mDNSu32              NumSubTypes;
1697         AuthRecord          *SubTypes;
1698         mDNSBool             Conflict;  // Set if this record set was forcibly deregistered because of a conflict
1699         domainname           Host;              // Set if this service record does not use the standard target host name
1700         AuthRecord           RR_ADV;    // e.g. _services._dns-sd._udp.local. PTR _printer._tcp.local.
1701         AuthRecord           RR_PTR;    // e.g. _printer._tcp.local.        PTR Name._printer._tcp.local.
1702         AuthRecord           RR_SRV;    // e.g. Name._printer._tcp.local.   SRV 0 0 port target
1703         AuthRecord           RR_TXT;    // e.g. Name._printer._tcp.local.   TXT PrintQueueName
1704         // Don't add any fields after AuthRecord RR_TXT.
1705         // This is where the implicit extra space goes if we allocate a ServiceRecordSet containing an oversized RR_TXT record
1706         };
1707
1708 // ***************************************************************************
1709 #if 0
1710 #pragma mark - Question structures
1711 #endif
1712
1713 // We record the last eight instances of each duplicate query
1714 // This gives us v4/v6 on each of Ethernet/AirPort and Firewire, and two free slots "for future expansion"
1715 // If the host has more active interfaces that this it is not fatal -- duplicate question suppression will degrade gracefully.
1716 // Since we will still remember the last eight, the busiest interfaces will still get the effective duplicate question suppression.
1717 #define DupSuppressInfoSize 8
1718
1719 typedef struct
1720         {
1721         mDNSs32               Time;
1722         mDNSInterfaceID       InterfaceID;
1723         mDNSs32               Type;                             // v4 or v6?
1724         } DupSuppressInfo;
1725
1726 typedef enum
1727         {
1728         // Setup states
1729         LLQ_UnInit            = 0,
1730         LLQ_GetZoneInfo       = 1,
1731         LLQ_InitialRequest    = 2,
1732         LLQ_SecondaryRequest  = 3,
1733         LLQ_Refresh           = 4,
1734         LLQ_Retry             = 5,
1735         LLQ_Established       = 6,
1736         LLQ_Suspended         = 7,
1737         LLQ_SuspendDeferred   = 8, // suspend once we get zone info
1738         LLQ_SuspendedPoll     = 9, // suspended from polling state
1739         LLQ_NatMapWait        = 10,
1740
1741         // Established/error states
1742         LLQ_Static            = 16,
1743         LLQ_Poll              = 17,
1744         LLQ_Error             = 18,
1745         LLQ_Cancelled         = 19
1746         } LLQ_State;
1747
1748 typedef struct
1749         {
1750         LLQ_State state;
1751         mDNSAddr servAddr;
1752         mDNSIPPort servPort;
1753         DNSQuestion *question;
1754         mDNSu32 origLease;  // seconds (relative)
1755         mDNSs32 retry;  // ticks (absolute)
1756         mDNSs32 expire; // ticks (absolute)
1757     mDNSs16 ntries;
1758         mDNSu8 id[8];
1759         mDNSBool deriveRemovesOnResume;
1760     mDNSBool NATMap;        // does this LLQ use the global LLQ NAT mapping?
1761         } LLQ_Info;
1762
1763 // LLQ constants
1764 #define kDNSOpt_LLQ        1
1765 #define kDNSOpt_Lease  2
1766 #define kLLQ_Vers      1
1767 #define kLLQ_DefLease  7200 // 2 hours
1768 #define kLLQ_MAX_TRIES 3    // retry an operation 3 times max
1769 #define kLLQ_INIT_RESEND 2 // resend an un-ack'd packet after 2 seconds, then double for each additional
1770 #define kLLQ_DEF_RETRY 1800 // retry a failed operation after 30 minutes
1771 // LLQ Operation Codes
1772 #define kLLQOp_Setup     1
1773 #define kLLQOp_Refresh   2
1774 #define kLLQOp_Event     3
1775
1776 #define LLQ_OPT_SIZE (2 * sizeof(mDNSu16)) + sizeof(LLQOptData)
1777 #define LEASE_OPT_SIZE (2 * sizeof(mDNSu16)) + sizeof(mDNSs32)
1778
1779 // LLQ Errror Codes
1780 enum
1781         {
1782         LLQErr_NoError = 0,
1783         LLQErr_ServFull = 1,
1784         LLQErr_Static = 2,
1785         LLQErr_FormErr = 3,
1786         LLQErr_NoSuchLLQ = 4,
1787         LLQErr_BadVers = 5,
1788         LLQErr_UnknownErr = 6
1789         };
1790
1791 typedef void (*InternalResponseHndlr)(mDNS *const m, DNSMessage *msg, const  mDNSu8 *end, DNSQuestion *question, void *internalContext);
1792 typedef struct
1793         {
1794         mDNSOpaque16          id;
1795         mDNSBool              internal;
1796         InternalResponseHndlr responseCallback;   // NULL if internal field is false
1797         LLQ_Info              *llq;               // NULL for 1-shot queries
1798     mDNSBool              Answered;           // have we received an answer (including NXDOMAIN) for this question?
1799     CacheRecord           *knownAnswers;
1800     mDNSs32               RestartTime;        // Mark when we restart a suspended query
1801     void *context;
1802         } uDNS_QuestionInfo;
1803
1804 // Note: Within an mDNSQuestionCallback mDNS all API calls are legal except mDNS_Init(), mDNS_Close(), mDNS_Execute()
1805 typedef void mDNSQuestionCallback(mDNS *const m, DNSQuestion *question, const ResourceRecord *const answer, mDNSBool AddRecord);
1806 struct DNSQuestion_struct
1807         {
1808         // Internal state fields. These are used internally by mDNSCore; the client layer needn't be concerned with them.
1809         DNSQuestion          *next;
1810         mDNSu32               qnamehash;
1811         mDNSs32               DelayAnswering;   // Set if we want to defer answering this question until the cache settles
1812         mDNSs32               LastQTime;                // Last scheduled transmission of this Q on *all* applicable interfaces
1813         mDNSs32               ThisQInterval;    // LastQTime + ThisQInterval is the next scheduled transmission of this Q
1814                                                                                         // ThisQInterval > 0 for an active question;
1815                                                                                         // ThisQInterval = 0 for a suspended question that's still in the list
1816                                                                                         // ThisQInterval = -1 for a cancelled question that's been removed from the list
1817         mDNSs32               LastAnswerPktNum; // The sequence number of the last response packet containing an answer to this Q
1818         mDNSu32               RecentAnswerPkts; // Number of answers since the last time we sent this query
1819         mDNSu32               CurrentAnswers;   // Number of records currently in the cache that answer this question
1820         mDNSu32               LargeAnswers;             // Number of answers with rdata > 1024 bytes
1821         mDNSu32               UniqueAnswers;    // Number of answers received with kDNSClass_UniqueRRSet bit set
1822         DNSQuestion          *DuplicateOf;
1823         DNSQuestion          *NextInDQList;
1824         DupSuppressInfo       DupSuppress[DupSuppressInfoSize];
1825         mDNSInterfaceID       SendQNow;                 // The interface this query is being sent on right now
1826         mDNSBool              SendOnAll;                // Set if we're sending this question on all active interfaces
1827         mDNSu32               RequestUnicast;   // Non-zero if we want to send query with kDNSQClass_UnicastResponse bit set
1828         mDNSs32               LastQTxTime;              // Last time this Q was sent on one (but not necessarily all) interfaces
1829         uDNS_QuestionInfo     uDNS_info;
1830
1831         // Client API fields: The client must set up these fields *before* calling mDNS_StartQuery()
1832         mDNSInterfaceID       InterfaceID;              // Non-zero if you want to issue queries only on a single specific IP interface
1833         mDNSAddr              Target;                   // Non-zero if you want to direct queries to a specific unicast target address
1834         mDNSIPPort            TargetPort;               // Must be set if Target is set
1835         mDNSOpaque16          TargetQID;                // Must be set if Target is set
1836         domainname            qname;
1837         mDNSu16               qtype;
1838         mDNSu16               qclass;
1839         mDNSBool              LongLived;        // Set by client for calls to mDNS_StartQuery to indicate LLQs to unicast layer.
1840         mDNSBool              ExpectUnique;             // Set by client if it's expecting unique RR(s) for this question, not shared RRs
1841         mDNSBool              ForceMCast;               // Set by client to force mDNS query, even for apparently uDNS names
1842         mDNSQuestionCallback *QuestionCallback;
1843         void                 *QuestionContext;
1844         };
1845
1846 typedef struct
1847         {
1848         // Client API fields: The client must set up name and InterfaceID *before* calling mDNS_StartResolveService()
1849         // When the callback is invoked, ip, port, TXTlen and TXTinfo will have been filled in with the results learned from the network.
1850         domainname      name;
1851         mDNSInterfaceID InterfaceID;            // ID of the interface the response was received on
1852         mDNSAddr        ip;                                     // Remote (destination) IP address where this service can be accessed
1853         mDNSIPPort      port;                           // Port where this service can be accessed
1854         mDNSu16         TXTlen;
1855         mDNSu8          TXTinfo[2048];          // Additional demultiplexing information (e.g. LPR queue name)
1856         } ServiceInfo;
1857
1858 // Note: Within an mDNSServiceInfoQueryCallback mDNS all API calls are legal except mDNS_Init(), mDNS_Close(), mDNS_Execute()
1859 typedef struct ServiceInfoQuery_struct ServiceInfoQuery;
1860 typedef void mDNSServiceInfoQueryCallback(mDNS *const m, ServiceInfoQuery *query);
1861 struct ServiceInfoQuery_struct
1862         {
1863         // Internal state fields. These are used internally by mDNSCore; the client layer needn't be concerned with them.
1864         // No fields need to be set up by the client prior to calling mDNS_StartResolveService();
1865         // all required data is passed as parameters to that function.
1866         // The ServiceInfoQuery structure memory is working storage for mDNSCore to discover the requested information
1867         // and place it in the ServiceInfo structure. After the client has called mDNS_StopResolveService(), it may
1868         // dispose of the ServiceInfoQuery structure while retaining the results in the ServiceInfo structure.
1869         DNSQuestion                   qSRV;
1870         DNSQuestion                   qTXT;
1871         DNSQuestion                   qAv4;
1872         DNSQuestion                   qAv6;
1873         mDNSu8                        GotSRV;
1874         mDNSu8                        GotTXT;
1875         mDNSu8                        GotADD;
1876         mDNSu32                       Answers;
1877         ServiceInfo                  *info;
1878         mDNSServiceInfoQueryCallback *ServiceInfoQueryCallback;
1879         void                         *ServiceInfoQueryContext;
1880         };
1881
1882 // ***************************************************************************
1883 #if 0
1884 #pragma mark - NAT Traversal structures and constants
1885 #endif
1886
1887 #define NATMAP_INIT_RETRY (mDNSPlatformOneSecond / 4)          // start at 250ms w/ exponential decay
1888 #define NATMAP_MAX_RETRY mDNSPlatformOneSecond                 // back off to once per second
1889 #define NATMAP_MAX_TRIES 3                                     // for max 3 tries
1890 #define NATMAP_DEFAULT_LEASE (60 * 60)  // lease life in seconds
1891 #define NATMAP_VERS 0
1892 #define NATMAP_PORT 5351
1893 #define NATMAP_RESPONSE_MASK 0x80
1894
1895 typedef enum
1896         {
1897         NATOp_AddrRequest = 0,
1898         NATOp_MapUDP      = 1,
1899         NATOp_MapTCP      = 2
1900         } NATOp_t;
1901
1902 enum
1903         {
1904         NATErr_None = 0,
1905         NATErr_Vers = 1,
1906         NATErr_Refused = 2,
1907         NATErr_NetFail = 3,
1908         NATErr_Res = 4,
1909         NATErr_Opcode = 5
1910         };
1911
1912 typedef mDNSu16 NATErr_t;
1913
1914 typedef enum
1915         {
1916         NATState_Init         = 0,
1917         NATState_Request      = 1,
1918         NATState_Established  = 2,
1919         NATState_Legacy       = 3,
1920         NATState_Error        = 4,
1921         NATState_Refresh      = 5,
1922         NATState_Deleted      = 6
1923         } NATState_t;
1924 // Note: we have no explicit "cancelled" state, where a service/interface is deregistered while we
1925  // have an outstanding NAT request.  This is conveyed by the "reg" pointer being set to NULL
1926
1927 typedef packedstruct
1928         {
1929         mDNSu8 vers;
1930         mDNSu8 opcode;
1931         } NATAddrRequest;
1932
1933 typedef packedstruct
1934         {
1935         mDNSu8 vers;
1936         mDNSu8 opcode;
1937         mDNSOpaque16 err;
1938         mDNSOpaque32 uptime;
1939         mDNSv4Addr   PubAddr;
1940         } NATAddrReply;
1941
1942 typedef packedstruct
1943         {
1944         mDNSu8 vers;
1945         mDNSu8 opcode;
1946         mDNSOpaque16 unused;
1947         mDNSIPPort priv;
1948         mDNSIPPort pub;
1949         mDNSOpaque32 lease;
1950         } NATPortMapRequest;
1951
1952 typedef packedstruct
1953         {
1954         mDNSu8 vers;
1955         mDNSu8 opcode;
1956         mDNSOpaque16 err;
1957         mDNSOpaque32 uptime;
1958         mDNSIPPort priv;
1959         mDNSIPPort pub;
1960         mDNSOpaque32 lease;
1961         } NATPortMapReply;
1962
1963 // Pass NULL for pkt on error (including timeout)
1964 typedef mDNSBool (*NATResponseHndlr)(NATTraversalInfo *n, mDNS *m, mDNSu8 *pkt, mDNSu16 len);
1965
1966 struct NATTraversalInfo_struct
1967         {
1968         NATOp_t op;
1969         NATResponseHndlr ReceiveResponse;
1970         union { AuthRecord *RecordRegistration; ServiceRecordSet *ServiceRegistration; } reg;
1971     mDNSAddr Router;
1972     mDNSIPPort PublicPort;
1973     union { NATAddrRequest AddrReq; NATPortMapRequest PortReq; } request;
1974         mDNSs32 retry;                   // absolute time when we retry
1975         mDNSs32 RetryInterval;           // delta between time sent and retry
1976         int ntries;
1977         NATState_t state;
1978         NATTraversalInfo *next;
1979         };
1980
1981 // ***************************************************************************
1982 #if 0
1983 #pragma mark - Main mDNS object, used to hold all the mDNS state
1984 #endif
1985
1986 typedef void mDNSCallback(mDNS *const m, mStatus result);
1987
1988 #define CACHE_HASH_SLOTS 499
1989
1990 enum
1991         {
1992         mDNS_KnownBug_PhantomInterfaces = 1
1993         };
1994
1995 typedef struct
1996         {
1997         mDNSs32          nextevent;
1998         DNSQuestion      *ActiveQueries;     //!!!KRS this should be a hashtable (hash on messageID)
1999         DNSQuestion      *CurrentQuery;      // pointer to ActiveQueries list being examined in a loop.  Functions that remove
2000                                                                                  // elements from the ActiveQueries list must update this pointer (if non-NULL) as necessary.
2001                                                                                  //!!!KRS do the same for registration lists
2002         ServiceRecordSet *ServiceRegistrations;
2003         AuthRecord       *RecordRegistrations;
2004         NATTraversalInfo *NATTraversals;
2005         mDNSu16          NextMessageID;
2006     DNSServer        *Servers;           // list of DNS servers
2007         mDNSAddr         Router;
2008         mDNSAddr         PrimaryIP;          // Address of primary interface
2009         mDNSAddr         MappedPrimaryIP;    // Cache of public address if PrimaryIP is behind a NAT
2010     NATTraversalInfo *LLQNatInfo;        // Nat port mapping to receive LLQ events
2011         domainname       ServiceRegDomain;   // (going away w/ multi-user support)
2012         struct uDNS_AuthInfo *AuthInfoList;  // list of domains requiring authentication for updates.
2013         uDNS_HostnameInfo *Hostnames;        // List of registered hostnames + hostname metadata
2014     DNSQuestion      ReverseMap;         // Reverse-map query to find  static hostname for service target
2015     mDNSBool         ReverseMapActive;   // Is above query active?
2016     domainname       StaticHostname;     // Current answer to reverse-map query (above)
2017     mDNSBool         DelaySRVUpdate;     // Delay SRV target/port update to avoid "flap"
2018     mDNSs32          NextSRVUpdate;      // Time to perform delayed update
2019         } uDNS_GlobalInfo;
2020
2021 struct mDNS_struct
2022         {
2023         // Internal state fields. These hold the main internal state of mDNSCore;
2024         // the client layer needn't be concerned with them.
2025         // No fields need to be set up by the client prior to calling mDNS_Init();
2026         // all required data is passed as parameters to that function.
2027
2028         mDNS_PlatformSupport *p;                        // Pointer to platform-specific data of indeterminite size
2029         mDNSu32  KnownBugs;
2030         mDNSBool CanReceiveUnicastOn5353;
2031         mDNSBool AdvertiseLocalAddresses;
2032         mStatus mDNSPlatformStatus;
2033         mDNSIPPort UnicastPort4;
2034         mDNSIPPort UnicastPort6;
2035         mDNSCallback *MainCallback;
2036         void         *MainContext;
2037
2038         // For debugging: To catch and report locking failures
2039         mDNSu32 mDNS_busy;                                      // Incremented between mDNS_Lock/mDNS_Unlock section
2040         mDNSu32 mDNS_reentrancy;                        // Incremented when calling a client callback
2041         mDNSu8  mDNS_shutdown;                          // Set when we're shutting down, allows us to skip some unnecessary steps
2042         mDNSu8  lock_rrcache;                           // For debugging: Set at times when these lists may not be modified
2043         mDNSu8  lock_Questions;
2044         mDNSu8  lock_Records;
2045         char MsgBuffer[80];                                     // Temp storage used while building error log messages
2046
2047         // Task Scheduling variables
2048         mDNSs32  timenow;                                       // The time that this particular activation of the mDNS code started
2049         mDNSs32  timenow_last;                          // The time the last time we ran
2050         mDNSs32  timenow_adjust;                        // Correction applied if we ever discover time went backwards
2051         mDNSs32  NextScheduledEvent;            // Derived from values below
2052         mDNSs32  SuppressSending;                       // Don't send *any* packets during this time
2053         mDNSs32  NextCacheCheck;                        // Next time to refresh cache record before it expires
2054         mDNSs32  NextScheduledQuery;            // Next time to send query in its exponential backoff sequence
2055         mDNSs32  NextScheduledProbe;            // Next time to probe for new authoritative record
2056         mDNSs32  NextScheduledResponse;         // Next time to send authoritative record(s) in responses
2057         mDNSs32  ExpectUnicastResponse;         // Set when we send a query with the kDNSQClass_UnicastResponse bit set
2058         mDNSs32  RandomQueryDelay;                      // For de-synchronization of query packets on the wire
2059         mDNSs32  PktNum;                                        // Unique sequence number assigned to each received packet
2060         mDNSBool SendDeregistrations;           // Set if we need to send deregistrations (immediately)
2061         mDNSBool SendImmediateAnswers;          // Set if we need to send answers (immediately -- or as soon as SuppressSending clears)
2062         mDNSBool SleepState;                            // Set if we're sleeping (send no more packets)
2063
2064         // These fields only required for mDNS Searcher...
2065         DNSQuestion *Questions;                         // List of all registered questions, active and inactive
2066         DNSQuestion *NewQuestions;                      // Fresh questions not yet answered from cache
2067         DNSQuestion *CurrentQuestion;           // Next question about to be examined in AnswerLocalQuestions()
2068         DNSQuestion *LocalOnlyQuestions;        // Questions with InterfaceID set to mDNSInterface_LocalOnly
2069         DNSQuestion *NewLocalOnlyQuestions;     // Fresh local-only questions not yet answered
2070         mDNSu32 rrcache_size;                           // Total number of available cache entries
2071         mDNSu32 rrcache_totalused;                      // Number of cache entries currently occupied
2072         mDNSu32 rrcache_active;                         // Number of cache entries currently occupied by records that answer active questions
2073         mDNSu32 rrcache_report;
2074         CacheEntity *rrcache_free;
2075         CacheGroup *rrcache_hash[CACHE_HASH_SLOTS];
2076
2077         // Fields below only required for mDNS Responder...
2078         domainlabel nicelabel;                          // Rich text label encoded using canonically precomposed UTF-8
2079         domainlabel hostlabel;                          // Conforms to RFC 1034 "letter-digit-hyphen" ARPANET host name rules
2080         domainname  MulticastHostname;          // Fully Qualified "dot-local" Host Name, e.g. "Foo.local."
2081         UTF8str255  HIHardware;
2082         UTF8str255  HISoftware;
2083         AuthRecord *ResourceRecords;
2084         AuthRecord *DuplicateRecords;           // Records currently 'on hold' because they are duplicates of existing records
2085         AuthRecord *NewLocalRecords;            // Fresh local-only records not yet delivered to local-only questions
2086         AuthRecord *CurrentRecord;                      // Next AuthRecord about to be examined
2087         NetworkInterfaceInfo *HostInterfaces;
2088         mDNSs32 ProbeFailTime;
2089         mDNSu32 NumFailedProbes;
2090         mDNSs32 SuppressProbes;
2091
2092         // unicast-specific data
2093         uDNS_GlobalInfo uDNS_info;
2094
2095         // Fixed storage, to avoid creating large objects on the stack
2096         DNSMessage imsg;                // Incoming message received from wire
2097         DNSMessage omsg;                // Outgoing message we're building
2098         LargeCacheRecord rec;   // Resource Record extracted from received message
2099         };
2100
2101 #define FORALL_CACHERECORDS(SLOT,CG,CR)                          \
2102         for ((SLOT) = 0; (SLOT) < CACHE_HASH_SLOTS; (SLOT)++)        \
2103                 for((CG)=m->rrcache_hash[(SLOT)]; (CG); (CG)=(CG)->next) \
2104                         for ((CR) = (CG)->members; (CR); (CR)=(CR)->next)
2105
2106 // ***************************************************************************
2107 #if 0
2108 #pragma mark - Useful Static Constants
2109 #endif
2110
2111 extern const mDNSIPPort      zeroIPPort;
2112 extern const mDNSv4Addr      zerov4Addr;
2113 extern const mDNSv6Addr      zerov6Addr;
2114 extern const mDNSEthAddr     zeroEthAddr;
2115 extern const mDNSv4Addr      onesIPv4Addr;
2116 extern const mDNSv6Addr      onesIPv6Addr;
2117 extern const mDNSAddr        zeroAddr;
2118
2119 extern const mDNSInterfaceID mDNSInterface_Any;                         // Zero
2120 extern const mDNSInterfaceID mDNSInterface_LocalOnly;           // Special value
2121
2122 extern const mDNSIPPort      UnicastDNSPort;
2123 extern const mDNSIPPort      MulticastDNSPort;
2124 extern const mDNSv4Addr      AllDNSAdminGroup;
2125 extern const mDNSv4Addr      AllDNSLinkGroupv4;
2126 extern const mDNSv6Addr      AllDNSLinkGroupv6;
2127 extern const mDNSAddr        AllDNSLinkGroup_v4;
2128 extern const mDNSAddr        AllDNSLinkGroup_v6;
2129
2130 extern const mDNSOpaque16 zeroID;
2131 extern const mDNSOpaque16 QueryFlags;
2132 extern const mDNSOpaque16 ResponseFlags;
2133 extern const mDNSOpaque16 UpdateReqFlags;
2134 extern const mDNSOpaque16 UpdateRespFlags;
2135
2136 #define localdomain (*(const domainname *)"\x5local")
2137 #define LocalReverseMapomain (*(const domainname *)"\x3" "254" "\x3" "169" "\x7" "in-addr" "\x4" "arpa")
2138
2139 // ***************************************************************************
2140 #if 0
2141 #pragma mark - Inline functions
2142 #endif
2143
2144 #if (defined(_MSC_VER))
2145         #define mDNSinline static __inline
2146 #elif ((__GNUC__ > 2) || ((__GNUC__ == 2) && (__GNUC_MINOR__ >= 9)))
2147         #define mDNSinline static inline
2148 #endif
2149
2150 // If we're not doing inline functions, then this header needs to have the extern declarations
2151 #if !defined(mDNSinline)
2152 extern mDNSs32      NonZeroTime(mDNSs32 t);
2153 extern mDNSu16      mDNSVal16(mDNSOpaque16 x);
2154 extern mDNSu32      mDNSVal32(mDNSOpaque32 x);
2155 extern mDNSOpaque16 mDNSOpaque16fromIntVal(mDNSu16 v);
2156 extern mDNSOpaque32 mDNSOpaque32fromIntVal(mDNSu32 v);
2157 #endif
2158
2159 // If we're compiling the particular C file that instantiates our inlines, then we
2160 // define "mDNSinline" (to empty string) so that we generate code in the following section
2161 #if (!defined(mDNSinline) && mDNS_InstantiateInlines)
2162 #define mDNSinline
2163 #endif
2164
2165 #ifdef mDNSinline
2166
2167 mDNSinline mDNSs32 NonZeroTime(mDNSs32 t) { if (t) return(t); else return(1); }
2168
2169 mDNSinline mDNSu16 mDNSVal16(mDNSOpaque16 x) { return((mDNSu16)((mDNSu16)x.b[0] <<  8 | (mDNSu16)x.b[1])); }
2170 mDNSinline mDNSu32 mDNSVal32(mDNSOpaque32 x) { return((mDNSu32)((mDNSu32)x.b[0] << 24 | (mDNSu32)x.b[1] << 16 | (mDNSu32)x.b[2] << 8 | (mDNSu32)x.b[3])); }
2171
2172 mDNSinline mDNSOpaque16 mDNSOpaque16fromIntVal(mDNSu16 v)
2173         {
2174         mDNSOpaque16 x;
2175         x.b[0] = (mDNSu8)(v >> 8);
2176         x.b[1] = (mDNSu8)(v & 0xFF);
2177         return(x);
2178         }
2179
2180 mDNSinline mDNSOpaque32 mDNSOpaque32fromIntVal(mDNSu32 v)
2181         {
2182         mDNSOpaque32 x;
2183         x.b[0] = (mDNSu8) (v >> 24)        ;
2184         x.b[1] = (mDNSu8)((v >> 16) & 0xFF);
2185         x.b[2] = (mDNSu8)((v >> 8 ) & 0xFF);
2186         x.b[3] = (mDNSu8)((v      ) & 0xFF);
2187         return x;
2188         }
2189
2190 #endif
2191
2192 // ***************************************************************************
2193 #if 0
2194 #pragma mark - Main Client Functions
2195 #endif
2196
2197 // Every client should call mDNS_Init, passing in storage for the mDNS object and the mDNS_PlatformSupport object.
2198 //
2199 // Clients that are only advertising services should use mDNS_Init_NoCache and mDNS_Init_ZeroCacheSize.
2200 // Clients that plan to perform queries (mDNS_StartQuery, mDNS_StartBrowse, mDNS_StartResolveService, etc.)
2201 // need to provide storage for the resource record cache, or the query calls will return 'mStatus_NoCache'.
2202 // The rrcachestorage parameter is the address of memory for the resource record cache, and
2203 // the rrcachesize parameter is the number of entries in the CacheRecord array passed in.
2204 // (i.e. the size of the cache memory needs to be sizeof(CacheRecord) * rrcachesize).
2205 // OS X 10.3 Panther uses an initial cache size of 64 entries, and then mDNSCore sends an
2206 // mStatus_GrowCache message if it needs more.
2207 //
2208 // Most clients should use mDNS_Init_AdvertiseLocalAddresses. This causes mDNSCore to automatically
2209 // create the correct address records for all the hosts interfaces. If you plan to advertise
2210 // services being offered by the local machine, this is almost always what you want.
2211 // There are two cases where you might use mDNS_Init_DontAdvertiseLocalAddresses:
2212 // 1. A client-only device, that browses for services but doesn't advertise any of its own.
2213 // 2. A proxy-registration service, that advertises services being offered by other machines, and takes
2214 //    the appropriate steps to manually create the correct address records for those other machines.
2215 // In principle, a proxy-like registration service could manually create address records for its own machine too,
2216 // but this would be pointless extra effort when using mDNS_Init_AdvertiseLocalAddresses does that for you.
2217 //
2218 // When mDNS has finished setting up the client's callback is called
2219 // A client can also spin and poll the mDNSPlatformStatus field to see when it changes from mStatus_Waiting to mStatus_NoError
2220 //
2221 // Call mDNS_Close to tidy up before exiting
2222 //
2223 // Call mDNS_Register with a completed AuthRecord object to register a resource record
2224 // If the resource record type is kDNSRecordTypeUnique (or kDNSknownunique) then if a conflicting resource record is discovered,
2225 // the resource record's mDNSRecordCallback will be called with error code mStatus_NameConflict. The callback should deregister
2226 // the record, and may then try registering the record again after picking a new name (e.g. by automatically appending a number).
2227 // Following deregistration, the RecordCallback will be called with result mStatus_MemFree to signal that it is safe to deallocate
2228 // the record's storage (memory must be freed asynchronously to allow for goodbye packets and dynamic update deregistration).
2229 //
2230 // Call mDNS_StartQuery to initiate a query. mDNS will proceed to issue Multicast DNS query packets, and any time a response
2231 // is received containing a record which matches the question, the DNSQuestion's mDNSAnswerCallback function will be called
2232 // Call mDNS_StopQuery when no more answers are required
2233 //
2234 // Care should be taken on multi-threaded or interrupt-driven environments.
2235 // The main mDNS routines call mDNSPlatformLock() on entry and mDNSPlatformUnlock() on exit;
2236 // each platform layer needs to implement these appropriately for its respective platform.
2237 // For example, if the support code on a particular platform implements timer callbacks at interrupt time, then
2238 // mDNSPlatformLock/Unlock need to disable interrupts or do similar concurrency control to ensure that the mDNS
2239 // code is not entered by an interrupt-time timer callback while in the middle of processing a client call.
2240
2241 extern mStatus mDNS_Init      (mDNS *const m, mDNS_PlatformSupport *const p,
2242                                                                 CacheEntity *rrcachestorage, mDNSu32 rrcachesize,
2243                                                                 mDNSBool AdvertiseLocalAddresses,
2244                                                                 mDNSCallback *Callback, void *Context);
2245 // See notes above on use of NoCache/ZeroCacheSize
2246 #define mDNS_Init_NoCache                     mDNSNULL
2247 #define mDNS_Init_ZeroCacheSize               0
2248 // See notes above on use of Advertise/DontAdvertiseLocalAddresses
2249 #define mDNS_Init_AdvertiseLocalAddresses     mDNStrue
2250 #define mDNS_Init_DontAdvertiseLocalAddresses mDNSfalse
2251 #define mDNS_Init_NoInitCallback              mDNSNULL
2252 #define mDNS_Init_NoInitCallbackContext       mDNSNULL
2253
2254 extern void    mDNS_GrowCache (mDNS *const m, CacheEntity *storage, mDNSu32 numrecords);
2255 extern void    mDNS_Close     (mDNS *const m);
2256 extern mDNSs32 mDNS_Execute   (mDNS *const m);
2257
2258 extern mStatus mDNS_Register  (mDNS *const m, AuthRecord *const rr);
2259 extern mStatus mDNS_Update    (mDNS *const m, AuthRecord *const rr, mDNSu32 newttl,
2260                                                                 const mDNSu16 newrdlength, RData *const newrdata, mDNSRecordUpdateCallback *Callback);
2261 extern mStatus mDNS_Deregister(mDNS *const m, AuthRecord *const rr);
2262
2263 extern mStatus mDNS_StartQuery(mDNS *const m, DNSQuestion *const question);
2264 extern mStatus mDNS_StopQuery (mDNS *const m, DNSQuestion *const question);
2265 extern mStatus mDNS_Reconfirm (mDNS *const m, CacheRecord *const cacherr);
2266 extern mStatus mDNS_ReconfirmByValue(mDNS *const m, ResourceRecord *const rr);
2267 extern mDNSs32 mDNS_TimeNow(const mDNS *const m);
2268
2269 // ***************************************************************************
2270 #if 0
2271 #pragma mark - Platform support functions that are accessible to the client layer too
2272 #endif
2273
2274 extern mDNSs32  mDNSPlatformOneSecond;
2275
2276 // ***************************************************************************
2277 #if 0
2278 #pragma mark - General utility and helper functions
2279 #endif
2280
2281 // mDNS_RegisterService is a single call to register the set of resource records associated with a given named service.
2282 //
2283 // mDNS_StartResolveService is single call which is equivalent to multiple calls to mDNS_StartQuery,
2284 // to find the IP address, port number, and demultiplexing information for a given named service.
2285 // As with mDNS_StartQuery, it executes asynchronously, and calls the ServiceInfoQueryCallback when the answer is
2286 // found. After the service is resolved, the client should call mDNS_StopResolveService to complete the transaction.
2287 // The client can also call mDNS_StopResolveService at any time to abort the transaction.
2288 //
2289 // mDNS_AddRecordToService adds an additional record to a Service Record Set.  This record may be deregistered
2290 // via mDNS_RemoveRecordFromService, or by deregistering the service.  mDNS_RemoveRecordFromService is passed a
2291 // callback to free the memory associated with the extra RR when it is safe to do so.  The ExtraResourceRecord
2292 // object  can be found in the record's context pointer.
2293
2294 // mDNS_GetBrowseDomains is a special case of the mDNS_StartQuery call, where the resulting answers
2295 // are a list of PTR records indicating (in the rdata) domains that are recommended for browsing.
2296 // After getting the list of domains to browse, call mDNS_StopQuery to end the search.
2297 // mDNS_GetDefaultBrowseDomain returns the name of the domain that should be highlighted by default.
2298 //
2299 // mDNS_GetRegistrationDomains and mDNS_GetDefaultRegistrationDomain are the equivalent calls to get the list
2300 // of one or more domains that should be offered to the user as choices for where they may register their service,
2301 // and the default domain in which to register in the case where the user has made no selection.
2302
2303 extern void    mDNS_SetupResourceRecord(AuthRecord *rr, RData *RDataStorage, mDNSInterfaceID InterfaceID,
2304                mDNSu16 rrtype, mDNSu32 ttl, mDNSu8 RecordType, mDNSRecordCallback Callback, void *Context);
2305
2306 extern mStatus mDNS_RegisterService  (mDNS *const m, ServiceRecordSet *sr,
2307                const domainlabel *const name, const domainname *const type, const domainname *const domain,
2308                const domainname *const host, mDNSIPPort port, const mDNSu8 txtinfo[], mDNSu16 txtlen,
2309                AuthRecord *SubTypes, mDNSu32 NumSubTypes,
2310                const mDNSInterfaceID InterfaceID, mDNSServiceCallback Callback, void *Context);
2311 extern mStatus mDNS_AddRecordToService(mDNS *const m, ServiceRecordSet *sr, ExtraResourceRecord *extra, RData *rdata, mDNSu32 ttl);
2312 extern mStatus mDNS_RemoveRecordFromService(mDNS *const m, ServiceRecordSet *sr, ExtraResourceRecord *extra, mDNSRecordCallback MemFreeCallback, void *Context);
2313 extern mStatus mDNS_RenameAndReregisterService(mDNS *const m, ServiceRecordSet *const sr, const domainlabel *newname);
2314 extern mStatus mDNS_DeregisterService(mDNS *const m, ServiceRecordSet *sr);
2315
2316 extern mStatus mDNS_RegisterNoSuchService(mDNS *const m, AuthRecord *const rr,
2317                const domainlabel *const name, const domainname *const type, const domainname *const domain,
2318                const domainname *const host,
2319                const mDNSInterfaceID InterfaceID, mDNSRecordCallback Callback, void *Context);
2320 #define        mDNS_DeregisterNoSuchService mDNS_Deregister
2321
2322 extern mStatus mDNS_StartBrowse(mDNS *const m, DNSQuestion *const question,
2323                const domainname *const srv, const domainname *const domain,
2324                const mDNSInterfaceID InterfaceID, mDNSBool ForceMCast, mDNSQuestionCallback *Callback, void *Context);
2325 #define        mDNS_StopBrowse mDNS_StopQuery
2326
2327 extern mStatus mDNS_StartResolveService(mDNS *const m, ServiceInfoQuery *query, ServiceInfo *info, mDNSServiceInfoQueryCallback *Callback, void *Context);
2328 extern void    mDNS_StopResolveService (mDNS *const m, ServiceInfoQuery *query);
2329
2330 typedef enum
2331         {
2332         mDNS_DomainTypeBrowse              = 0,
2333         mDNS_DomainTypeBrowseDefault       = 1,
2334         mDNS_DomainTypeBrowseLegacy        = 2,
2335         mDNS_DomainTypeRegistration        = 3,
2336         mDNS_DomainTypeRegistrationDefault = 4,
2337
2338         mDNS_DomainTypeMax = 4
2339         } mDNS_DomainType;
2340
2341 extern const char *const mDNS_DomainTypeNames[];
2342
2343 extern mStatus mDNS_GetDomains(mDNS *const m, DNSQuestion *const question, mDNS_DomainType DomainType, const domainname *dom,
2344                                                                 const mDNSInterfaceID InterfaceID, mDNSQuestionCallback *Callback, void *Context);
2345 #define        mDNS_StopGetDomains mDNS_StopQuery
2346 extern mStatus mDNS_AdvertiseDomains(mDNS *const m, AuthRecord *rr, mDNS_DomainType DomainType, const mDNSInterfaceID InterfaceID, char *domname);
2347 #define        mDNS_StopAdvertiseDomains mDNS_Deregister
2348
2349 // ***************************************************************************
2350 #if 0
2351 #pragma mark - DNS name utility functions
2352 #endif
2353
2354 // In order to expose the full capabilities of the DNS protocol (which allows any arbitrary eight-bit values
2355 // in domain name labels, including unlikely characters like ascii nulls and even dots) all the mDNS APIs
2356 // work with DNS's native length-prefixed strings. For convenience in C, the following utility functions
2357 // are provided for converting between C's null-terminated strings and DNS's length-prefixed strings.
2358
2359 // Assignment
2360 // A simple C structure assignment of a domainname can cause a protection fault by accessing unmapped memory,
2361 // because that object is defined to be 256 bytes long, but not all domainname objects are truly the full size.
2362 // This macro uses mDNSPlatformMemCopy() to make sure it only touches the actual bytes that are valid.
2363 #define AssignDomainName(DST, SRC) mDNSPlatformMemCopy((SRC)->c, (DST)->c, DomainNameLength((SRC)))
2364
2365 // Comparison functions
2366 extern mDNSBool SameDomainLabel(const mDNSu8 *a, const mDNSu8 *b);
2367 extern mDNSBool SameDomainName(const domainname *const d1, const domainname *const d2);
2368 extern mDNSBool IsLocalDomain(const domainname *d);     // returns true for domains that by default should be looked up using link-local multicast
2369
2370 // Get total length of domain name, in native DNS format, including terminal root label
2371 //   (e.g. length of "com." is 5 (length byte, three data bytes, final zero)
2372 extern mDNSu16  DomainNameLength(const domainname *const name);
2373
2374 // Append functions to append one or more labels to an existing native format domain name:
2375 //   AppendLiteralLabelString adds a single label from a literal C string, with no escape character interpretation.
2376 //   AppendDNSNameString      adds zero or more labels from a C string using conventional DNS dots-and-escaping interpretation
2377 //   AppendDomainLabel        adds a single label from a native format domainlabel
2378 //   AppendDomainName         adds zero or more labels from a native format domainname
2379 extern mDNSu8  *AppendLiteralLabelString(domainname *const name, const char *cstr);
2380 extern mDNSu8  *AppendDNSNameString     (domainname *const name, const char *cstr);
2381 extern mDNSu8  *AppendDomainLabel       (domainname *const name, const domainlabel *const label);
2382 extern mDNSu8  *AppendDomainName        (domainname *const name, const domainname *const append);
2383
2384 // Convert from null-terminated string to native DNS format:
2385 //   The DomainLabel form makes a single label from a literal C string, with no escape character interpretation.
2386 //   The DomainName form makes native format domain name from a C string using conventional DNS interpretation:
2387 //     dots separate labels, and within each label, '\.' represents a literal dot, '\\' represents a literal
2388 //     backslash and backslash with three decimal digits (e.g. \000) represents an arbitrary byte value.
2389 extern mDNSBool MakeDomainLabelFromLiteralString(domainlabel *const label, const char *cstr);
2390 extern mDNSu8  *MakeDomainNameFromDNSNameString (domainname  *const name,  const char *cstr);
2391
2392 // Convert native format domainlabel or domainname back to C string format
2393 // IMPORTANT:
2394 // When using ConvertDomainLabelToCString, the target buffer must be MAX_ESCAPED_DOMAIN_LABEL (254) bytes long
2395 // to guarantee there will be no buffer overrun. It is only safe to use a buffer shorter than this in rare cases
2396 // where the label is known to be constrained somehow (for example, if the label is known to be either "_tcp" or "_udp").
2397 // Similarly, when using ConvertDomainNameToCString, the target buffer must be MAX_ESCAPED_DOMAIN_NAME (1005) bytes long.
2398 // See definitions of MAX_ESCAPED_DOMAIN_LABEL and MAX_ESCAPED_DOMAIN_NAME for more detailed explanation.
2399 extern char    *ConvertDomainLabelToCString_withescape(const domainlabel *const name, char *cstr, char esc);
2400 #define         ConvertDomainLabelToCString_unescaped(D,C) ConvertDomainLabelToCString_withescape((D), (C), 0)
2401 #define         ConvertDomainLabelToCString(D,C)           ConvertDomainLabelToCString_withescape((D), (C), '\\')
2402 extern char    *ConvertDomainNameToCString_withescape(const domainname *const name, char *cstr, char esc);
2403 #define         ConvertDomainNameToCString_unescaped(D,C) ConvertDomainNameToCString_withescape((D), (C), 0)
2404 #define         ConvertDomainNameToCString(D,C)           ConvertDomainNameToCString_withescape((D), (C), '\\')
2405
2406 extern void     ConvertUTF8PstringToRFC1034HostLabel(const mDNSu8 UTF8Name[], domainlabel *const hostlabel);
2407
2408 extern mDNSu8  *ConstructServiceName(domainname *const fqdn, const domainlabel *name, const domainname *type, const domainname *const domain);
2409 extern mDNSBool DeconstructServiceName(const domainname *const fqdn, domainlabel *const name, domainname *const type, domainname *const domain);
2410
2411 // Note: Some old functions have been replaced by more sensibly-named versions.
2412 // You can uncomment the hash-defines below if you don't want to have to change your source code right away.
2413 // When updating your code, note that (unlike the old versions) *all* the new routines take the target object
2414 // as their first parameter.
2415 //#define ConvertCStringToDomainName(SRC,DST)  MakeDomainNameFromDNSNameString((DST),(SRC))
2416 //#define ConvertCStringToDomainLabel(SRC,DST) MakeDomainLabelFromLiteralString((DST),(SRC))
2417 //#define AppendStringLabelToName(DST,SRC)     AppendLiteralLabelString((DST),(SRC))
2418 //#define AppendStringNameToName(DST,SRC)      AppendDNSNameString((DST),(SRC))
2419 //#define AppendDomainLabelToName(DST,SRC)     AppendDomainLabel((DST),(SRC))
2420 //#define AppendDomainNameToName(DST,SRC)      AppendDomainName((DST),(SRC))
2421
2422 // ***************************************************************************
2423 #if 0
2424 #pragma mark - Other utility functions and macros
2425 #endif
2426
2427 extern mDNSu32 mDNS_vsnprintf(char *sbuffer, mDNSu32 buflen, const char *fmt, va_list arg);
2428 extern mDNSu32 mDNS_snprintf(char *sbuffer, mDNSu32 buflen, const char *fmt, ...) IS_A_PRINTF_STYLE_FUNCTION(3,4);
2429 extern mDNSu32 NumCacheRecordsForInterfaceID(const mDNS *const m, mDNSInterfaceID id);
2430 extern char *DNSTypeName(mDNSu16 rrtype);
2431 extern char *GetRRDisplayString_rdb(const ResourceRecord *rr, RDataBody *rd, char *buffer);
2432 #define RRDisplayString(m, rr) GetRRDisplayString_rdb(rr, &(rr)->rdata->u, (m)->MsgBuffer)
2433 #define ARDisplayString(m, rr) GetRRDisplayString_rdb(&(rr)->resrec, &(rr)->resrec.rdata->u, (m)->MsgBuffer)
2434 #define CRDisplayString(m, rr) GetRRDisplayString_rdb(&(rr)->resrec, &(rr)->resrec.rdata->u, (m)->MsgBuffer)
2435 extern mDNSBool mDNSSameAddress(const mDNSAddr *ip1, const mDNSAddr *ip2);
2436 extern void IncrementLabelSuffix(domainlabel *name, mDNSBool RichText);
2437 extern mDNSBool IsPrivateV4Addr(mDNSAddr *addr);  // returns true for RFC1918 private addresses
2438
2439 #define mDNSSameIPv4Address(A,B) ((A).NotAnInteger == (B).NotAnInteger)
2440 #define mDNSSameIPv6Address(A,B) ((A).l[0] == (B).l[0] && (A).l[1] == (B).l[1] && (A).l[2] == (B).l[2] && (A).l[3] == (B).l[3])
2441 #define mDNSSameEthAddress(A,B)  ((A)->w[0] == (B)->w[0] && (A)->w[1] == (B)->w[1] && (A)->w[2] == (B)->w[2])
2442
2443 #define mDNSIPv4AddressIsZero(A) mDNSSameIPv4Address((A), zerov4Addr)
2444 #define mDNSIPv6AddressIsZero(A) mDNSSameIPv6Address((A), zerov6Addr)
2445
2446 #define mDNSIPv4AddressIsOnes(A) mDNSSameIPv4Address((A), onesIPv4Addr)
2447 #define mDNSIPv6AddressIsOnes(A) mDNSSameIPv6Address((A), onesIPv6Addr)
2448
2449 #define mDNSAddressIsAllDNSLinkGroup(X) (                                                     \
2450         ((X)->type == mDNSAddrType_IPv4 && mDNSSameIPv4Address((X)->ip.v4, AllDNSLinkGroupv4)) || \
2451         ((X)->type == mDNSAddrType_IPv6 && mDNSSameIPv6Address((X)->ip.v6, AllDNSLinkGroupv6))    )
2452
2453 #define mDNSAddressIsZero(X) (                                                \
2454         ((X)->type == mDNSAddrType_IPv4 && mDNSIPv4AddressIsZero((X)->ip.v4))  || \
2455         ((X)->type == mDNSAddrType_IPv6 && mDNSIPv6AddressIsZero((X)->ip.v6))     )
2456
2457 #define mDNSAddressIsValidNonZero(X) (                                        \
2458         ((X)->type == mDNSAddrType_IPv4 && !mDNSIPv4AddressIsZero((X)->ip.v4)) || \
2459         ((X)->type == mDNSAddrType_IPv6 && !mDNSIPv6AddressIsZero((X)->ip.v6))    )
2460
2461 #define mDNSAddressIsOnes(X) (                                                \
2462         ((X)->type == mDNSAddrType_IPv4 && mDNSIPv4AddressIsOnes((X)->ip.v4))  || \
2463         ((X)->type == mDNSAddrType_IPv6 && mDNSIPv6AddressIsOnes((X)->ip.v6))     )
2464
2465 #define mDNSAddressIsValid(X) (                                                                                             \
2466         ((X)->type == mDNSAddrType_IPv4) ? !(mDNSIPv4AddressIsZero((X)->ip.v4) || mDNSIPv4AddressIsOnes((X)->ip.v4)) :          \
2467         ((X)->type == mDNSAddrType_IPv6) ? !(mDNSIPv6AddressIsZero((X)->ip.v6) || mDNSIPv6AddressIsOnes((X)->ip.v6)) : mDNSfalse)
2468
2469
2470 // ***************************************************************************
2471 #if 0
2472 #pragma mark - Authentication Support
2473 #endif
2474
2475 #define HMAC_LEN    64
2476 #define HMAC_IPAD   0x36
2477 #define HMAC_OPAD   0x5c
2478 #define MD5_LEN     16
2479
2480 // padded keys for inned/outer hash rounds
2481 typedef struct
2482         {
2483         mDNSu8 ipad[HMAC_LEN];
2484         mDNSu8 opad[HMAC_LEN];
2485         } HMAC_Key;
2486
2487 // Internal data structure to maintain authentication information for an update domain
2488 typedef struct uDNS_AuthInfo
2489         {
2490         domainname zone;
2491         domainname keyname;
2492         HMAC_Key key;
2493         struct uDNS_AuthInfo *next;
2494         } uDNS_AuthInfo;
2495
2496 // Unicast DNS and Dynamic Update specific Client Calls
2497 //
2498 // mDNS_SetSecretForZone tells the core to authenticate (via TSIG with an HMAC_MD5 hash of the shared secret)
2499 // when dynamically updating a given zone (and its subdomains).  The key used in authentication must be in
2500 // domain name format.  The shared secret must be a null-terminated base64 encoded string.  A minimum size of
2501 // 16 bytes (128 bits) is recommended for an MD5 hash as per RFC 2485.
2502 // Calling this routine multiple times for a zone replaces previously entered values.  Call with a NULL key
2503 // to dissable authentication for the zone.
2504
2505 extern mStatus mDNS_SetSecretForZone(mDNS *m, const domainname *zone, const domainname *key, const char *sharedSecret);
2506
2507 // Hostname/Unicast Interface Configuration
2508
2509 // All hostnames advertised point to a single IP address, set via SetPrimaryInterfaceInfo.  Invoking this routine
2510 // updates all existing hostnames to point to the new address.
2511
2512 // A hostname is added via AddDynDNSHostName, which points to the primary interface's IP address.
2513
2514 // The status callback is invoked to convey success or failure codes - the callback should not modify the AuthRecord or free memory.
2515 // Added hostnames may be removed (deregistered) via mDNS_RemoveDynDNSHostName.
2516
2517 // Host domains added prior to specification of the primary interface address and computer name will be deferred until
2518 // these values are initialized.
2519
2520 // When routable V4 interfaces are added or removed, mDNS_UpdateLLQs should be called to re-estabish LLQs in case the
2521 // destination address for events (i.e. the route) has changed.  For performance reasons, the caller is responsible for
2522 // batching changes, e.g.  calling the routine only once if multiple interfaces are simultanously removed or added.
2523
2524 // DNS servers used to resolve unicast queries are specified by mDNS_AddDNSServer, and may later be removed via mDNS_DeleteDNSServers.
2525 // For "split" DNS configurations, in which queries for different domains are sent to different servers (e.g. VPN and external),
2526 // a domain may be associated with a DNS server.  For standard configurations, specify the root label (".") or NULL.
2527
2528 extern void mDNS_AddDynDNSHostName(mDNS *m, const domainname *fqdn, mDNSRecordCallback *StatusCallback, const void *StatusContext);
2529 extern void mDNS_RemoveDynDNSHostName(mDNS *m, const domainname *fqdn);
2530 extern void mDNS_SetPrimaryInterfaceInfo(mDNS *m, const mDNSAddr *addr, const mDNSAddr *router);
2531 extern void mDNS_UpdateLLQs(mDNS *m);
2532 extern void mDNS_AddDNSServer(mDNS *const m, const mDNSAddr *dnsAddr, const domainname *domain);
2533 extern void mDNS_DeleteDNSServers(mDNS *const m);
2534
2535 // Routines called by the core, exported by DNSDigest.c
2536
2537 // Convert a base64 encoded key into a binary byte stream
2538 extern mDNSs32 DNSDigest_Base64ToBin(const char *src, mDNSu8 *target, mDNSu32 targsize);
2539
2540 // Convert an arbitrary binary key (of any length) into an HMAC key (stored in AuthInfo struct)
2541 extern void DNSDigest_ConstructHMACKey(uDNS_AuthInfo *info, const mDNSu8 *key, mDNSu32 len);
2542
2543 // sign a DNS message.  The message must be compete, with all values in network byte order.  end points to the end
2544 // of the message, and is modified by this routine.  numAdditionals is a pointer to the number of additional
2545 // records in HOST byte order, which is incremented upon successful completion of this routine.  The function returns
2546 // the new end pointer on success, and NULL on failure.
2547 extern mDNSu8 *DNSDigest_SignMessage(DNSMessage *msg, mDNSu8 **end, mDNSu16 *numAdditionals, uDNS_AuthInfo *info);
2548
2549 // ***************************************************************************
2550 #if 0
2551 #pragma mark - PlatformSupport interface
2552 #endif
2553
2554 // This section defines the interface to the Platform Support layer.
2555 // Normal client code should not use any of types defined here, or directly call any of the functions defined here.
2556 // The definitions are placed here because sometimes clients do use these calls indirectly, via other supported client operations.
2557 // For example, AssignDomainName is a macro defined using mDNSPlatformMemCopy()
2558
2559 // Every platform support module must provide the following functions.
2560 // mDNSPlatformInit() typically opens a communication endpoint, and starts listening for mDNS packets.
2561 // When Setup is complete, the platform support layer calls mDNSCoreInitComplete().
2562 // mDNSPlatformSendUDP() sends one UDP packet
2563 // When a packet is received, the PlatformSupport code calls mDNSCoreReceive()
2564 // mDNSPlatformClose() tidies up on exit
2565 //
2566 // Note: mDNSPlatformMemAllocate/mDNSPlatformMemFree are only required for handling oversized resource records and unicast DNS.
2567 // If your target platform has a well-defined specialized application, and you know that all the records it uses
2568 // are InlineCacheRDSize or less, then you can just make a simple mDNSPlatformMemAllocate() stub that always returns
2569 // NULL. InlineCacheRDSize is a compile-time constant, which is set by default to 64. If you need to handle records
2570 // a little larger than this and you don't want to have to implement run-time allocation and freeing, then you
2571 // can raise the value of this constant to a suitable value (at the expense of increased memory usage).
2572 //
2573 // USE CAUTION WHEN CALLING mDNSPlatformRawTime: The m->timenow_adjust correction factor needs to be added
2574 // Generally speaking:
2575 // Code that's protected by the main mDNS lock should just use the m->timenow value
2576 // Code outside the main mDNS lock should use mDNS_TimeNow(m) to get properly adjusted time
2577 //
2578 // mDNSPlatformUTC returns the time, in seconds, since Jan 1st 1970 UTC and is required for generating TSIG records
2579
2580 extern mStatus  mDNSPlatformInit        (mDNS *const m);
2581 extern void     mDNSPlatformClose       (mDNS *const m);
2582 extern mStatus  mDNSPlatformSendUDP(const mDNS *const m, const void *const msg, const mDNSu8 *const end,
2583 mDNSInterfaceID InterfaceID, const mDNSAddr *dst, mDNSIPPort dstport);
2584
2585 extern void     mDNSPlatformLock        (const mDNS *const m);
2586 extern void     mDNSPlatformUnlock      (const mDNS *const m);
2587
2588 extern void     mDNSPlatformStrCopy     (const void *src,       void *dst);
2589 extern mDNSu32  mDNSPlatformStrLen      (const void *src);
2590 extern void     mDNSPlatformMemCopy     (const void *src,       void *dst, mDNSu32 len);
2591 extern mDNSBool mDNSPlatformMemSame     (const void *src, const void *dst, mDNSu32 len);
2592 extern void     mDNSPlatformMemZero     (                       void *dst, mDNSu32 len);
2593 extern void *   mDNSPlatformMemAllocate (mDNSu32 len);
2594 extern void     mDNSPlatformMemFree     (void *mem);
2595 extern mDNSu32  mDNSPlatformRandomSeed  (void);
2596 extern mStatus  mDNSPlatformTimeInit    (void);
2597 extern mDNSs32  mDNSPlatformRawTime     (void);
2598 extern mDNSs32  mDNSPlatformUTC         (void);
2599
2600 // Platform support modules should provide the following functions to map between opaque interface IDs
2601 // and interface indexes in order to support the DNS-SD API. If your target platform does not support
2602 // multiple interfaces and/or does not support the DNS-SD API, these functions can be empty.
2603 extern mDNSInterfaceID mDNSPlatformInterfaceIDfromInterfaceIndex(const mDNS *const m, mDNSu32 index);
2604 extern mDNSu32 mDNSPlatformInterfaceIndexfromInterfaceID(const mDNS *const m, mDNSInterfaceID id);
2605
2606 // Every platform support module must provide the following functions if it is to support unicast DNS
2607 // and Dynamic Update.
2608 // All TCP socket operations implemented by the platform layer MUST NOT BLOCK.
2609 // mDNSPlatformTCPConnect initiates a TCP connection with a peer, adding the socket descriptor to the
2610 // main event loop.  The return value indicates whether the connection succeeded, failed, or is pending
2611 // (i.e. the call would block.)  On return, the descriptor parameter is set to point to the connected socket.
2612 // The TCPConnectionCallback is subsequently invoked when the connection
2613 // completes (in which case the ConnectionEstablished parameter is true), or data is available for
2614 // reading on the socket (indicated by the ConnectionEstablished parameter being false.)  If the connection
2615 // asynchronously fails, the TCPConnectionCallback should be invoked as usual, with the error being
2616 // returned in subsequent calls to PlatformReadTCP or PlatformWriteTCP.  (This allows for platforms
2617 // with limited asynchronous error detection capabilities.)  PlatformReadTCP and PlatformWriteTCP must
2618 // return the number of bytes read/written, 0 if the call would block, and -1 if an error.
2619 // PlatformTCPCloseConnection must close the connection to the peer and remove the descriptor from the
2620 // event loop.  CloseConnectin may be called at any time, including in a ConnectionCallback.
2621
2622 typedef void (*TCPConnectionCallback)(int sd, void *context, mDNSBool ConnectionEstablished);
2623 extern mStatus mDNSPlatformTCPConnect(const mDNSAddr *dst, mDNSOpaque16 dstport, mDNSInterfaceID InterfaceID,
2624                                                                                   TCPConnectionCallback callback, void *context, int *descriptor);
2625 extern void mDNSPlatformTCPCloseConnection(int sd);
2626 extern int mDNSPlatformReadTCP(int sd, void *buf, int buflen);
2627 extern int mDNSPlatformWriteTCP(int sd, const char *msg, int len);
2628
2629 // Platforms that support unicast browsing and dynamic update registration for clients who do not specify a domain
2630 // in browse/registration calls must implement these routines to get the "default" browse/registration list.
2631 // The Get() functions must return a linked list of DNameListElem structs, allocated via mDNSPlatformMemAllocate.
2632 // Platforms may implement the Get() calls via the mDNS_CopyDNameList() helper routine.
2633 // Callers should free lists obtained via the Get() calls with th mDNS_FreeDNameList routine, provided by the core.
2634
2635 typedef struct DNameListElem
2636         {
2637         domainname name;
2638         struct DNameListElem *next;
2639         } DNameListElem;
2640
2641 extern DNameListElem *mDNSPlatformGetSearchDomainList(void);
2642 extern DNameListElem *mDNSPlatformGetRegDomainList(void);
2643
2644 // Helper functions provided by the core
2645 extern DNameListElem *mDNS_CopyDNameList(const DNameListElem *orig);
2646 extern void mDNS_FreeDNameList(DNameListElem *list);
2647
2648 #ifdef _LEGACY_NAT_TRAVERSAL_
2649 // Support for legacy NAT traversal protocols, implemented by the platform layer and callable by the core.
2650
2651 #define DYN_PORT_MIN 49152 // ephemeral port range
2652 #define DYN_PORT_MAX 65535
2653 #define LEGACY_NATMAP_MAX_TRIES 4 // if our desired mapping is taken, how many times we try mapping to a random port
2654
2655 extern mStatus LNT_GetPublicIP(mDNSOpaque32 *ip);
2656 extern mStatus LNT_MapPort(mDNSIPPort priv, mDNSIPPort pub, mDNSBool tcp);
2657 extern mStatus LNT_UnmapPort(mDNSIPPort PubPort, mDNSBool tcp);
2658 #endif // _LEGACY_NAT_TRAVERSAL_
2659
2660 // The core mDNS code provides these functions, for the platform support code to call at appropriate times
2661 //
2662 // mDNS_SetFQDN() is called once on startup (typically from mDNSPlatformInit())
2663 // and then again on each subsequent change of the host name.
2664 //
2665 // mDNS_RegisterInterface() is used by the platform support layer to inform mDNSCore of what
2666 // physical and/or logical interfaces are available for sending and receiving packets.
2667 // Typically it is called on startup for each available interface, but register/deregister may be
2668 // called again later, on multiple occasions, to inform the core of interface configuration changes.
2669 // If set->Advertise is set non-zero, then mDNS_RegisterInterface() also registers the standard
2670 // resource records that should be associated with every publicised IP address/interface:
2671 // -- Name-to-address records (A/AAAA)
2672 // -- Address-to-name records (PTR)
2673 // -- Host information (HINFO)
2674 // IMPORTANT: The specified mDNSInterfaceID MUST NOT be 0, -1, or -2; these values have special meaning
2675 // mDNS_RegisterInterface does not result in the registration of global hostnames via dynamic update -
2676 // see mDNS_SetPrimaryInterfaceInfo, mDNS_AddDynDNSHostName, etc. for this purpose.
2677 // Note that the set may be deallocated immediately after it is deregistered via mDNS_DeegisterInterface.
2678 //
2679 // mDNS_RegisterDNS() is used by the platform support layer to provide the core with the addresses of
2680 // available domain name servers for unicast queries/updates.  RegisterDNS() should be called once for
2681 // each name server, typically at startup, or when a new name server becomes available.  DeregiterDNS()
2682 // must be called whenever a registered name server becomes unavailable.  DeregisterDNSList deregisters
2683 // all registered servers.  mDNS_DNSRegistered() returns true if one or more servers are registered in the core.
2684 //
2685 // mDNSCoreInitComplete() is called when the platform support layer is finished.
2686 // Typically this is at the end of mDNSPlatformInit(), but may be later
2687 // (on platforms like OT that allow asynchronous initialization of the networking stack).
2688 //
2689 // mDNSCoreReceive() is called when a UDP packet is received
2690 //
2691 // mDNSCoreMachineSleep() is called when the machine sleeps or wakes
2692 // (This refers to heavyweight laptop-style sleep/wake that disables network access,
2693 // not lightweight second-by-second CPU power management modes.)
2694
2695 extern void     mDNS_SetFQDN(mDNS *const m);
2696 extern mStatus  mDNS_RegisterInterface  (mDNS *const m, NetworkInterfaceInfo *set, mDNSs32 delay);
2697 extern void     mDNS_DeregisterInterface(mDNS *const m, NetworkInterfaceInfo *set);
2698 extern void     mDNSCoreInitComplete(mDNS *const m, mStatus result);
2699 extern void     mDNSCoreReceive(mDNS *const m, void *const msg, const mDNSu8 *const end,
2700                                                                 const mDNSAddr *const srcaddr, const mDNSIPPort srcport,
2701                                                                 const mDNSAddr *const dstaddr, const mDNSIPPort dstport, const mDNSInterfaceID InterfaceID);
2702 extern void     mDNSCoreMachineSleep(mDNS *const m, mDNSBool wake);
2703
2704 extern mDNSBool mDNSAddrIsDNSMulticast(const mDNSAddr *ip);
2705
2706 // ***************************************************************************
2707 #if 0
2708 #pragma mark - Compile-Time assertion checks
2709 #endif
2710
2711 // Some C compiler cleverness. We can make the compiler check certain things for
2712 // us, and report compile-time errors if anything is wrong. The usual way to do
2713 // this would be to use a run-time "if" statement, but then you don't find out
2714 // what's wrong until you run the software. This way, if the assertion condition
2715 // is false, the array size is negative, and the complier complains immediately.
2716
2717 struct mDNS_CompileTimeAssertionChecks
2718         {
2719         // Check that the compiler generated our on-the-wire packet format structure definitions
2720         // properly packed, without adding padding bytes to align fields on 32-bit or 64-bit boundaries.
2721         char assert0[(sizeof(rdataSRV)         == 262                          ) ? 1 : -1];
2722         char assert1[(sizeof(DNSMessageHeader) ==  12                          ) ? 1 : -1];
2723         char assert2[(sizeof(DNSMessage)       ==  12+AbsoluteMaxDNSMessageData) ? 1 : -1];
2724         char assert3[(sizeof(mDNSs8)           ==   1                          ) ? 1 : -1];
2725         char assert4[(sizeof(mDNSu8)           ==   1                          ) ? 1 : -1];
2726         char assert5[(sizeof(mDNSs16)          ==   2                          ) ? 1 : -1];
2727         char assert6[(sizeof(mDNSu16)          ==   2                          ) ? 1 : -1];
2728         char assert7[(sizeof(mDNSs32)          ==   4                          ) ? 1 : -1];
2729         char assert8[(sizeof(mDNSu32)          ==   4                          ) ? 1 : -1];
2730         char assert9[(sizeof(mDNSOpaque16)     ==   2                          ) ? 1 : -1];
2731         char assertA[(sizeof(mDNSOpaque32)     ==   4                          ) ? 1 : -1];
2732         char assertB[(sizeof(mDNSOpaque128)    ==  16                          ) ? 1 : -1];
2733         char assertC[(sizeof(CacheRecord  )    >=  sizeof(CacheGroup)          ) ? 1 : -1];
2734         };
2735
2736 // ***************************************************************************
2737
2738 #ifdef __cplusplus
2739         }
2740 #endif
2741
2742 #endif