/* * Copyright (c) 2002-2003 Apple Computer, Inc. All rights reserved. * * @APPLE_LICENSE_HEADER_START@ * * Copyright (c) 1999-2003 Apple Computer, Inc. All Rights Reserved. * * This file contains Original Code and/or Modifications of Original Code * as defined in and that are subject to the Apple Public Source License * Version 2.0 (the 'License'). You may not use this file except in * compliance with the License. Please obtain a copy of the License at * http://www.opensource.apple.com/apsl/ and read it before using this * file. * * The Original Code and all software distributed under the License are * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES, * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY, * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT. * Please see the License for the specific language governing rights and * limitations under the License. * * @APPLE_LICENSE_HEADER_END@ Change History (most recent first): $Log: mDNSClientAPI.h,v $ Revision 1.177 2004/06/05 00:04:26 cheshire : wide-area domains should be returned in reg. domain enumeration Revision 1.176 2004/06/04 08:58:29 ksekar : Keychain integration for secure dynamic update Revision 1.175 2004/06/04 00:15:06 cheshire Move misplaced brackets Revision 1.174 2004/06/03 23:30:16 cheshire Remove extraneous blank lines and white space Revision 1.173 2004/06/03 03:09:58 ksekar : Garbage Collection for Dynamic Updates Revision 1.172 2004/06/01 23:46:50 ksekar : DynDNS: dynamically look up LLQ/Update ports Revision 1.171 2004/05/28 23:42:37 ksekar : Feature: DNS server->client notification on record changes (#7805) Revision 1.170 2004/05/18 23:51:25 cheshire Tidy up all checkin comments to use consistent "" format for bug numbers Revision 1.169 2004/05/13 04:54:20 ksekar Unified list copy/free code. Added symetric list for Revision 1.168 2004/05/12 22:03:09 ksekar Made GetSearchDomainList a true platform-layer call (declaration moved from mDNSMacOSX.h to mDNSClientAPI.h), impelemted to return "local" only on non-OSX platforms. Changed call to return a copy of the list to avoid shared memory issues. Added a routine to free the list. Revision 1.167 2004/04/22 04:07:01 cheshire Fix from Bob Bradley: Don't try to do inline functions on compilers that don't support it Revision 1.166 2004/04/22 03:15:56 cheshire Fix use of "struct __attribute__((__packed__))" so it only applies on GCC >= 2.9 Revision 1.165 2004/04/22 03:05:28 cheshire kDNSClass_ANY should be kDNSQClass_ANY Revision 1.164 2004/04/21 02:55:03 cheshire Update comments describing 'InterfaceActive' field Revision 1.163 2004/04/21 02:49:11 cheshire To reduce future confusion, renamed 'TxAndRx' to 'McastTxRx' Revision 1.162 2004/04/15 00:51:28 bradley Minor tweaks for Windows and C++ builds. Added casts for signed/unsigned integers and 64-bit pointers. Prefix some functions with mDNS to avoid conflicts. Disable benign warnings on Microsoft compilers. Revision 1.161 2004/04/14 23:09:28 ksekar Support for TSIG signed dynamic updates. Revision 1.160 2004/04/09 17:40:26 cheshire Remove unnecessary "Multicast" field -- it duplicates the semantics of the existing McastTxRx field Revision 1.159 2004/04/09 16:37:15 cheshire Suggestion from Bob Bradley: Move NumCacheRecordsForInterfaceID() to DNSCommon.c so it's available to all platform layers Revision 1.158 2004/04/02 19:38:33 cheshire Update comment about typical RR TTLs Revision 1.157 2004/04/02 19:35:53 cheshire Add clarifying comments about legal mDNSInterfaceID values Revision 1.156 2004/04/02 19:19:48 cheshire Add code to do optional logging of multi-packet KA list time intervals Revision 1.155 2004/03/24 00:29:45 ksekar Make it safe to call StopQuery in a unicast question callback Revision 1.154 2004/03/20 01:05:49 cheshire Test __LP64__ and __ILP64__ to compile properly on a wider range of 64-bit architectures Revision 1.153 2004/03/13 01:57:33 ksekar : DynDNS: Dynamic update of service records Revision 1.152 2004/03/09 02:27:16 cheshire Remove erroneous underscore in 'packed_struct' (makes no difference now, but might in future) Revision 1.151 2004/03/02 03:21:56 cheshire Properly support "_services._dns-sd._udp" meta-queries Revision 1.150 2004/02/21 02:06:24 cheshire Can't use anonymous unions -- they're non-standard and don't work on all compilers Revision 1.149 2004/02/06 23:04:19 ksekar Basic Dynamic Update support via mDNS_Register (dissabled via UNICAST_REGISTRATION #define) Revision 1.148 2004/02/03 19:47:36 ksekar Added an asyncronous state machine mechanism to uDNS.c, including calls to find the parent zone for a domain name. Changes include code in repository previously dissabled via "#if 0 //incomplete". Codepath is currently unused, and will be called to create update records, etc. Revision 1.147 2004/02/03 18:57:35 cheshire Update comment for "IsLocalDomain()" Revision 1.146 2004/01/30 02:20:24 bradley Map inline to __inline when building with Microsoft C compilers since they do not support C99 inline. Revision 1.145 2004/01/29 02:59:17 ksekar Unicast DNS: Changed from a resource record oriented question/response matching to packet based matching. New callback architecture allows collections of records in a response to be processed differently depending on the nature of the request, and allows the same structure to be used for internal and client-driven queries with different processing needs. Revision 1.144 2004/01/28 20:20:45 ksekar Unified ActiveQueries and ActiveInternalQueries lists, using a flag to demux them. Check-in includes work-in-progress code, #ifdef'd out. Revision 1.143 2004/01/28 03:41:00 cheshire : Need ability to do targeted queries as well as multicast queries Revision 1.142 2004/01/28 02:30:07 ksekar Added default Search Domains to unicast browsing, controlled via Networking sharing prefs pane. Stopped sending unicast messages on every interface. Fixed unicast resolving via mach-port API. Revision 1.141 2004/01/27 20:15:22 cheshire : Time to prune obsolete code for listening on port 53 Revision 1.140 2004/01/24 23:37:08 cheshire At Kiren's suggestion, made functions to convert mDNSOpaque16s to/from integer values Revision 1.139 2004/01/24 08:46:26 bradley Added InterfaceID<->Index platform interfaces since they are now used by all platforms for the DNS-SD APIs. Revision 1.138 2004/01/24 04:59:15 cheshire Fixes so that Posix/Linux, OS9, Windows, and VxWorks targets build again Revision 1.137 2004/01/24 03:40:56 cheshire Move mDNSAddrIsDNSMulticast() from DNSCommon.h to mDNSClientAPI.h so clients can use it Revision 1.136 2004/01/24 03:38:27 cheshire Fix minor syntactic error: Headers should use "extern" declarations, not "mDNSexport" Revision 1.135 2004/01/23 23:23:15 ksekar Added TCP support for truncated unicast messages. Revision 1.134 2004/01/22 03:54:11 cheshire Create special meta-interface 'mDNSInterface_ForceMCast' (-2), which means "do this query via multicast, even if it's apparently a unicast domain" Revision 1.133 2004/01/22 03:48:41 cheshire Make sure uDNS client doesn't accidentally use query ID zero Revision 1.132 2004/01/22 03:43:08 cheshire Export constants like mDNSInterface_LocalOnly so that the client layers can use them Revision 1.131 2004/01/21 21:53:18 cheshire : Don't try to receive unicast responses if we're not the first to bind to the UDP port Revision 1.130 2003/12/14 05:05:29 cheshire Add comments explaining mDNS_Init_NoCache and mDNS_Init_ZeroCacheSize Revision 1.129 2003/12/13 03:05:27 ksekar : DynDNS: Unicast query of service records Revision 1.128 2003/12/01 21:44:23 cheshire Add mStatus_BadInterfaceErr = -65552 for consistency with dns_sd.h Revision 1.127 2003/12/01 18:26:37 cheshire Also pack the OpaqueXX union types. Otherwise, on some systems, mDNSOpaque16 is four bytes! Revision 1.126 2003/12/01 18:23:48 cheshire : Scalar size problem in mDNS code on some 64-bit architectures Revision 1.125 2003/11/22 00:18:27 cheshire Add compile-time asserts to verify correct sizes of mDNSu32, mDNSOpaque16, etc. Revision 1.124 2003/11/20 22:59:54 cheshire Changed runtime checks in mDNS.c to be compile-time checks in mDNSClientAPI.h Thanks to Bob Bradley for suggesting the ingenious compiler trick to make this work. Revision 1.123 2003/11/20 22:53:01 cheshire Add comment about MAX_ESCAPED_DOMAIN_LABEL Revision 1.122 2003/11/20 20:49:53 cheshire Another fix from HP: Use packedstruct macro to ensure proper packing for on-the-wire packet structures Revision 1.121 2003/11/20 05:01:38 cheshire Update comments; add explanation of Advertise/DontAdvertiseLocalAddresses Revision 1.120 2003/11/14 20:59:08 cheshire Clients can't use AssignDomainName macro because mDNSPlatformMemCopy is defined in mDNSPlatformFunctions.h. Best solution is just to combine mDNSClientAPI.h and mDNSPlatformFunctions.h into a single file. Revision 1.119 2003/11/14 19:47:52 cheshire Define symbol MAX_ESCAPED_DOMAIN_NAME to indicate recommended buffer size for ConvertDomainNameToCString Revision 1.118 2003/11/14 19:18:34 cheshire Move AssignDomainName macro to mDNSClientAPI.h to that client layers can use it too Revision 1.117 2003/11/08 23:32:24 cheshire Gave name to anonymous struct, to avoid errors on certain compilers. (Thanks to ramaprasad.kr@hp.com for reporting this.) Revision 1.116 2003/11/07 03:32:56 cheshire mDNSResponder delivers answers in inconsistent order This is the real fix. Checkin 1.312 was overly simplistic; Calling GetFreeCacheRR() can sometimes purge records from the cache, causing tail pointer *rp to be stale on return. The correct fix is to maintain a system-wide tail pointer for each cache slot, and then if neccesary GetFreeCacheRR() can update this pointer, so that mDNSCoreReceiveResponse() appends records in the right place. Revision 1.115 2003/09/23 00:53:54 cheshire NumFailedProbes should be unsigned Revision 1.114 2003/08/29 19:44:15 cheshire Traffic reduction: Eliminate synchronized QUs when a new service appears 1. Use m->RandomQueryDelay to impose a random delay in the range 0-500ms on queries that already have at least one unique answer in the cache 2. For these queries, go straight to QM, skipping QU Revision 1.113 2003/08/21 19:31:58 cheshire Cosmetic: Swap order of fields Revision 1.112 2003/08/21 19:27:36 cheshire Traffic reduction: No need to announce record for longer than TTL Revision 1.111 2003/08/21 02:21:50 cheshire Efficiency: Reduce repeated queries Revision 1.110 2003/08/20 23:39:31 cheshire Review syslog messages, and remove as appropriate Revision 1.109 2003/08/19 22:24:10 cheshire Comment change Revision 1.108 2003/08/19 22:20:00 cheshire Don't use IPv6 on interfaces that have a routable IPv4 address configured More minor refinements Revision 1.107 2003/08/19 06:48:25 cheshire Guard against excessive record updates Each record starts with 10 UpdateCredits. Every update consumes one UpdateCredit. UpdateCredits are replenished at a rate of one one per minute, up to a maximum of 10. As the number of UpdateCredits declines, the number of announcements is similarly scaled back. When fewer than 5 UpdateCredits remain, the first announcement is also delayed by an increasing amount. Revision 1.106 2003/08/19 04:49:28 cheshire Interaction between v4, v6 and dual-stack hosts not working quite right 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. 2. When we see the first v4 (or first v6) member of a group, we re-trigger questions and probes on that interface. 3. When we see the last v4 (or v6) member of a group go away, we revalidate all the records received on that interface. Revision 1.105 2003/08/19 02:33:37 cheshire Update comments Revision 1.104 2003/08/19 02:31:11 cheshire mDNSResponder overenthusiastic with final expiration queries Final expiration queries now only mark the question for sending on the particular interface pertaining to the record that's expiring. Revision 1.103 2003/08/18 19:05:44 cheshire UpdateRecord not working right Added "newrdlength" field to hold new length of updated rdata Revision 1.102 2003/08/16 03:39:00 cheshire InterfaceID -1 indicates "local only" Revision 1.101 2003/08/15 20:16:02 cheshire mDNSResponder takes too much RPRVT We want to avoid touching the rdata pages, so we don't page them in. 1. RDLength was stored with the rdata, which meant touching the page just to find the length. Moved this from the RData to the ResourceRecord object. 2. To avoid unnecessarily touching the rdata just to compare it, compute a hash of the rdata and store the hash in the ResourceRecord object. Revision 1.100 2003/08/14 19:29:04 cheshire Include cache records in SIGINFO output Moved declarations of DNSTypeName() and GetRRDisplayString to mDNSClientAPI.h so daemon.c can use them Revision 1.99 2003/08/14 02:17:05 cheshire Split generic ResourceRecord type into two separate types: AuthRecord and CacheRecord Revision 1.98 2003/08/12 19:56:23 cheshire Update to APSL 2.0 Revision 1.97 2003/08/12 14:59:27 cheshire Rate-limiting blocks some legitimate responses When setting LastMCTime also record LastMCInterface. When checking LastMCTime to determine whether to suppress the response, also check LastMCInterface to see if it matches. Revision 1.96 2003/08/12 13:57:04 cheshire Improve cache performance Changed the number of hash table slots from 37 to 499 Revision 1.95 2003/08/09 00:55:02 cheshire mDNSResponder is taking 20-30% of the CPU Don't scan the whole cache after every packet. Revision 1.94 2003/08/09 00:35:29 cheshire Revision 1.93 2003/08/08 18:55:48 cheshire Guard against time going backwards Revision 1.92 2003/08/08 18:36:04 cheshire Only need to revalidate on interface removal on platforms that have the PhantomInterfaces bug Revision 1.91 2003/08/06 21:33:39 cheshire Fix compiler warnings on PocketPC 2003 (Windows CE) Revision 1.90 2003/08/06 20:30:17 cheshire Add structure definition for rdataMX (not currently used, but good to have it for completeness) Revision 1.89 2003/08/06 18:58:19 cheshire Update comments Revision 1.88 2003/07/24 23:45:44 cheshire To eliminate compiler warnings, changed definition of mDNSBool from "unsigned char" to "int", since "int" is in fact truly the type that C uses for the result of comparison operators (a: Feature: New Rendezvous APIs (#7875) (mDNSResponder component) Added error type for incompatibility between daemon and client versions Revision 1.85 2003/07/19 03:23:13 cheshire mDNSResponder needs to receive and cache larger records Revision 1.84 2003/07/18 23:52:12 cheshire To improve consistency of field naming, global search-and-replace: NextProbeTime -> NextScheduledProbe NextResponseTime -> NextScheduledResponse Revision 1.83 2003/07/18 00:29:59 cheshire Remove mDNSResponder version from packet header and use HINFO record instead Revision 1.82 2003/07/17 17:35:04 cheshire Rate-limit responses, to guard against packet flooding Revision 1.81 2003/07/16 05:01:36 cheshire Add fields 'LargeAnswers' and 'ExpectUnicastResponse' in preparation for Need to implement "unicast response" request, using top bit of qclass Revision 1.80 2003/07/15 01:55:12 cheshire Need to implement service registration with subtypes Revision 1.79 2003/07/13 02:28:00 cheshire SendResponses didn't all its responses Delete all references to RRInterfaceActive -- it's now superfluous Revision 1.78 2003/07/13 01:47:53 cheshire Fix one error and one warning in the Windows build Revision 1.77 2003/07/11 01:32:38 cheshire Syntactic cleanup (no change to funcationality): Now that we only have one host name, rename field "hostname1" to "hostname", and field "RR_A1" to "RR_A". Revision 1.76 2003/07/11 01:28:00 cheshire No more local.arpa Revision 1.75 2003/07/02 21:19:45 cheshire Update copyright notices, etc., in source code comments Revision 1.74 2003/07/02 02:41:23 cheshire mDNSResponder needs to start with a smaller cache and then grow it as needed Revision 1.73 2003/06/10 04:24:39 cheshire React when we observe other people query unsuccessfully for a record that's in our cache Some additional refinements: Don't try to do this for unicast-response queries better tracking of Qs and KAs in multi-packet KA lists Revision 1.72 2003/06/10 01:46:27 cheshire Add better comments explaining how these data structures are intended to be used from the client layer Revision 1.71 2003/06/07 06:45:05 cheshire No need for multiple machines to all be sending the same queries Revision 1.70 2003/06/07 04:50:53 cheshire React when we observe other people query unsuccessfully for a record that's in our cache Revision 1.69 2003/06/07 04:22:17 cheshire Add MsgBuffer for error log and debug messages Revision 1.68 2003/06/07 01:46:38 cheshire When query produces zero results, call mDNS_Reconfirm() on any antecedent records Revision 1.67 2003/06/07 01:22:14 cheshire mDNSResponder needs an mDNS_Reconfirm() function Revision 1.66 2003/06/07 00:59:43 cheshire Need some randomness to spread queries on the network Revision 1.65 2003/06/06 21:41:11 cheshire For consistency, mDNS_StopQuery() should return an mStatus result, just like all the other mDNSCore routines Revision 1.64 2003/06/06 21:38:55 cheshire Renamed 'NewData' as 'FreshData' (The data may not be new data, just a refresh of data that we already had in our cache. This refreshes our TTL on the data, but the data itself stays the same.) Revision 1.63 2003/06/06 17:20:14 cheshire For clarity, rename question fields name/rrtype/rrclass as qname/qtype/qclass (Global search-and-replace; no functional change to code execution.) Revision 1.62 2003/06/04 01:25:33 cheshire Cannot perform multi-packet known-answer suppression messages Display time interval between first and subsequent queries Revision 1.61 2003/06/03 05:02:16 cheshire Duplicate registrations not handled as efficiently as they should be Revision 1.60 2003/05/31 00:09:49 cheshire Add ability to discover what services are on a network Revision 1.59 2003/05/29 06:11:35 cheshire : Report if there appear to be too many "Resolve" callbacks Revision 1.58 2003/05/29 05:48:06 cheshire Minor fix for when generating printf warnings: mDNS_snprintf arguments are now 3,4 Revision 1.57 2003/05/26 03:21:27 cheshire Tidy up address structure naming: mDNSIPAddr => mDNSv4Addr (for consistency with mDNSv6Addr) mDNSAddr.addr.ipv4 => mDNSAddr.ip.v4 mDNSAddr.addr.ipv6 => mDNSAddr.ip.v6 Revision 1.56 2003/05/26 03:01:27 cheshire sprintf/vsprintf-style functions are unsafe; use snprintf/vsnprintf instead Revision 1.55 2003/05/26 00:47:30 cheshire Comment clarification Revision 1.54 2003/05/24 16:39:48 cheshire SendResponses also needs to handle multihoming better Revision 1.53 2003/05/23 02:15:37 cheshire Fixed misleading use of the term "duplicate suppression" where it should have said "known answer suppression". (Duplicate answer suppression is something different, and duplicate question suppression is yet another thing, so the use of the completely vague term "duplicate suppression" was particularly bad.) Revision 1.52 2003/05/22 02:29:22 cheshire SendQueries needs to handle multihoming better Complete rewrite of SendQueries. Works much better now :-) Revision 1.51 2003/05/21 20:14:55 cheshire Fix comments and warnings Revision 1.50 2003/05/14 07:08:36 cheshire mDNSResponder should be smarter about reconfigurations Previously, when there was any network configuration change, mDNSResponder would tear down the entire list of active interfaces and start again. That was very disruptive, and caused the entire cache to be flushed, and caused lots of extra network traffic. Now it only removes interfaces that have really gone, and only adds new ones that weren't there before. Revision 1.49 2003/05/07 01:49:36 cheshire Remove "const" in ConstructServiceName prototype Revision 1.48 2003/05/07 00:18:44 cheshire Fix typo: "kDNSQClass_Mask" should be "kDNSClass_Mask" Revision 1.47 2003/05/06 00:00:46 cheshire Rationalize naming of domainname manipulation functions Revision 1.46 2003/04/30 20:39:09 cheshire Add comment Revision 1.45 2003/04/29 00:40:50 cheshire Fix compiler warnings Revision 1.44 2003/04/26 02:41:56 cheshire Change timenow from a local variable to a structure member Revision 1.43 2003/04/25 01:45:56 cheshire mDNS_RegisterNoSuchService needs to include a host name Revision 1.42 2003/04/15 20:58:31 jgraessl Added a hash to lookup records in the cache. Revision 1.41 2003/04/15 18:09:13 jgraessl Reviewed by: Stuart Cheshire Added code to keep track of when the next cache item will expire so we can call TidyRRCache only when necessary. Revision 1.40 2003/03/29 01:55:19 cheshire mDNSResponder sometimes suffers false self-conflicts when it sees its own packets Solution: Major cleanup of packet timing and conflict handling rules Revision 1.39 2003/03/27 03:30:55 cheshire Name conflicts not handled properly, resulting in memory corruption, and eventual crash Problem was that HostNameCallback() was calling mDNS_DeregisterInterface(), which is not safe in a callback Fixes: 1. Make mDNS_DeregisterInterface() safe to call from a callback 2. Make HostNameCallback() use mDNS_DeadvertiseInterface() instead (it never really needed to deregister the interface at all) Revision 1.38 2003/03/15 04:40:36 cheshire Change type called "mDNSOpaqueID" to the more descriptive name "mDNSInterfaceID" Revision 1.37 2003/03/14 21:34:11 cheshire Can't setup and print to Lexmark PS printers via Airport Extreme Increase size of cache rdata from 512 to 768 Revision 1.36 2003/03/05 03:38:35 cheshire Bogus error message in console: died or deallocated, but no record of client can be found! Fixed by leaving client in list after conflict, until client explicitly deallocates Revision 1.35 2003/02/21 02:47:54 cheshire mDNSResponder needs performance improvements Several places in the code were calling CacheRRActive(), which searched the entire question list every time, to see if this cache resource record answers any question. Instead, we now have a field "CRActiveQuestion" in the resource record structure Revision 1.34 2003/02/21 01:54:08 cheshire mDNSResponder needs performance improvements Switched to using new "mDNS_Execute" model (see "Implementer Notes.txt") Revision 1.33 2003/02/20 06:48:32 cheshire Xserve RAID needs to do interface-specific registrations Reviewed by: Josh Graessley, Bob Bradley Revision 1.32 2003/01/31 03:35:59 cheshire mDNSResponder sometimes fails to find the correct results When there were *two* active questions in the list, they were incorrectly finding *each other* and *both* being marked as duplicates of another question Revision 1.31 2003/01/29 02:46:37 cheshire Fix for IPv6: A physical interface is identified solely by its InterfaceID (not by IP and type). On a given InterfaceID, mDNSCore may send both v4 and v6 multicasts. In cases where the requested outbound protocol (v4 or v6) is not supported on that InterfaceID, the platform support layer should simply discard that packet. Revision 1.30 2003/01/29 01:47:08 cheshire Rename 'Active' to 'CRActive' or 'InterfaceActive' for improved clarity Revision 1.29 2003/01/28 05:23:43 cheshire mDNSResponder sometimes fails to find the correct results Add 'Active' flag for interfaces Revision 1.28 2003/01/28 01:35:56 cheshire Revise comment about ThisQInterval to reflect new semantics Revision 1.27 2003/01/13 23:49:42 jgraessl Merged changes for the following fixes in to top of tree: computer name changes not handled properly service name changes are not properly handled announcements sent in pairs, failing chattiness test Revision 1.26 2002/12/23 22:13:28 jgraessl Reviewed by: Stuart Cheshire Initial IPv6 support for mDNSResponder. Revision 1.25 2002/09/21 20:44:49 zarzycki Added APSL info Revision 1.24 2002/09/19 23:47:35 cheshire Added mDNS_RegisterNoSuchService() function for assertion of non-existance of a particular named service Revision 1.23 2002/09/19 21:25:34 cheshire mDNS_snprintf() doesn't need to be in a separate file Revision 1.22 2002/09/19 04:20:43 cheshire Remove high-ascii characters that confuse some systems Revision 1.21 2002/09/17 01:06:35 cheshire Change mDNS_AdvertiseLocalAddresses to be a parameter to mDNS_Init() Revision 1.20 2002/09/16 18:41:41 cheshire Merge in license terms from Quinn's copy, in preparation for Darwin release */ #ifndef __mDNSClientAPI_h #define __mDNSClientAPI_h #include // stdarg.h is required for for va_list support for the mDNS_vsnprintf declaration #include "mDNSDebug.h" #ifdef __cplusplus extern "C" { #endif // *************************************************************************** // Function scope indicators // If you see "mDNSlocal" before a function name in a C file, it means the function is not callable outside this file #ifndef mDNSlocal #define mDNSlocal static #endif // If you see "mDNSexport" before a symbol in a C file, it means the symbol is exported for use by clients // For every "mDNSexport" in a C file, there needs to be a corresponding "extern" declaration in some header file // (When a C file #includes a header file, the "extern" declarations tell the compiler: // "This symbol exists -- but not necessarily in this C file.") #ifndef mDNSexport #define mDNSexport #endif // *************************************************************************** // Structure packing macro // If we're not using GNUC, it's not fatal. // Most compilers naturally pack the on-the-wire structures correctly anyway, so a plain "struct" is usually fine. // In the event that structures are not packed correctly, mDNS_Init() will detect this and report an error, so the // developer will know what's wrong, and can investigate what needs to be done on that compiler to provide proper packing. #ifndef packedstruct #if ((__GNUC__ > 2) || ((__GNUC__ == 2) && (__GNUC_MINOR__ >= 9))) #define packedstruct struct __attribute__((__packed__)) #define packedunion union __attribute__((__packed__)) #else #define packedstruct struct #define packedunion union #endif #endif // *************************************************************************** #if 0 #pragma mark - DNS Resource Record class and type constants #endif typedef enum // From RFC 1035 { kDNSClass_IN = 1, // Internet kDNSClass_CS = 2, // CSNET kDNSClass_CH = 3, // CHAOS kDNSClass_HS = 4, // Hesiod kDNSClass_NONE = 254, // Used in DNS UPDATE [RFC 2136] kDNSClass_Mask = 0x7FFF,// Multicast DNS uses the bottom 15 bits to identify the record class... kDNSClass_UniqueRRSet = 0x8000,// ... and the top bit indicates that all other cached records are now invalid kDNSQClass_ANY = 255, // Not a DNS class, but a DNS query class, meaning "all classes" kDNSQClass_UnicastResponse = 0x8000 // Top bit set in a question means "unicast response acceptable" } DNS_ClassValues; typedef enum // From RFC 1035 { kDNSType_A = 1, // 1 Address kDNSType_NS, // 2 Name Server kDNSType_MD, // 3 Mail Destination kDNSType_MF, // 4 Mail Forwarder kDNSType_CNAME, // 5 Canonical Name kDNSType_SOA, // 6 Start of Authority kDNSType_MB, // 7 Mailbox kDNSType_MG, // 8 Mail Group kDNSType_MR, // 9 Mail Rename kDNSType_NULL, // 10 NULL RR kDNSType_WKS, // 11 Well-known-service kDNSType_PTR, // 12 Domain name pointer kDNSType_HINFO, // 13 Host information kDNSType_MINFO, // 14 Mailbox information kDNSType_MX, // 15 Mail Exchanger kDNSType_TXT, // 16 Arbitrary text string kDNSType_AAAA = 28, // 28 IPv6 address kDNSType_SRV = 33, // 33 Service record kDNSType_OPT = 41, // EDNS0 OPT record kDNSType_TSIG = 250, // 250 Transaction Signature kDNSQType_ANY = 255 // Not a DNS type, but a DNS query type, meaning "all types" } DNS_TypeValues; // *************************************************************************** #if 0 #pragma mark - Simple types #endif // mDNS defines its own names for these common types to simplify portability across // multiple platforms that may each have their own (different) names for these types. typedef int mDNSBool; typedef signed char mDNSs8; typedef unsigned char mDNSu8; typedef signed short mDNSs16; typedef unsigned short mDNSu16; // says // __LP64__ _LP64 // These macros are defined, with value 1, if (and only if) the compilation is // for a target where long int and pointer both use 64-bits and int uses 32-bit. // says // Macro Name __LP64__ Value 1 // A quick Google search for "defined(__LP64__)" OR "#ifdef __LP64__" gives 2590 hits and // a search for "#if __LP64__" gives only 12, so I think we'll go with the majority and use defined() #if defined(_LP64) || defined(__LP64__) typedef signed int mDNSs32; typedef unsigned int mDNSu32; #elif defined(_ILP64) || defined(__ILP64__) typedef signed int32 mDNSs32; typedef unsigned int32 mDNSu32; #else typedef signed long mDNSs32; typedef unsigned long mDNSu32; #endif // To enforce useful type checking, we make mDNSInterfaceID be a pointer to a dummy struct // This way, mDNSInterfaceIDs can be assigned, and compared with each other, but not with other types // Declaring the type to be the typical generic "void *" would lack this type checking typedef struct mDNSInterfaceID_dummystruct { void *dummy; } *mDNSInterfaceID; // These types are for opaque two- and four-byte identifiers. // The "NotAnInteger" fields of the unions allow the value to be conveniently passed around in a // register for the sake of efficiency, and compared for equality or inequality, but don't forget -- // just because it is in a register doesn't mean it is an integer. Operations like greater than, // less than, add, multiply, increment, decrement, etc., are undefined for opaque identifiers, // and if you make the mistake of trying to do those using the NotAnInteger field, then you'll // find you get code that doesn't work consistently on big-endian and little-endian machines. typedef packedunion { mDNSu8 b[2]; mDNSu16 NotAnInteger; } mDNSOpaque16; typedef packedunion { mDNSu8 b[4]; mDNSu32 NotAnInteger; } mDNSOpaque32; typedef packedunion { mDNSu8 b[16]; mDNSu16 w[8]; mDNSu32 l[4]; } mDNSOpaque128; typedef mDNSOpaque16 mDNSIPPort; // An IP port is a two-byte opaque identifier (not an integer) typedef mDNSOpaque32 mDNSv4Addr; // An IP address is a four-byte opaque identifier (not an integer) typedef mDNSOpaque128 mDNSv6Addr; // An IPv6 address is a 16-byte opaque identifier (not an integer) enum { mDNSAddrType_None = 0, mDNSAddrType_IPv4 = 4, mDNSAddrType_IPv6 = 6, mDNSAddrType_Unknown = ~0 // Special marker value used in known answer list recording }; typedef struct { mDNSs32 type; union { mDNSv6Addr v6; mDNSv4Addr v4; } ip; } mDNSAddr; enum { mDNSfalse = 0, mDNStrue = 1 }; #define mDNSNULL 0L enum { mStatus_Waiting = 1, mStatus_NoError = 0, // mDNS return values are in the range FFFE FF00 (-65792) to FFFE FFFF (-65537) // The top end of the range (FFFE FFFF) is used for error codes; // the bottom end of the range (FFFE FF00) is used for non-error values; // Error codes: mStatus_UnknownErr = -65537, // 0xFFFE FFFF mStatus_NoSuchNameErr = -65538, mStatus_NoMemoryErr = -65539, mStatus_BadParamErr = -65540, mStatus_BadReferenceErr = -65541, mStatus_BadStateErr = -65542, mStatus_BadFlagsErr = -65543, mStatus_UnsupportedErr = -65544, mStatus_NotInitializedErr = -65545, mStatus_NoCache = -65546, mStatus_AlreadyRegistered = -65547, mStatus_NameConflict = -65548, mStatus_Invalid = -65549, // = -65550, mStatus_Incompatible = -65551, mStatus_BadInterfaceErr = -65552, mStatus_Refused = -65553, mStatus_NoSuchRecord = -65554, mStatus_NoAuth = -65555, // -65556 - -65789 currently unused // Non-error values: mStatus_GrowCache = -65790, mStatus_ConfigChanged = -65791, mStatus_MemFree = -65792, // 0xFFFE FF00 // tcp connection status mStatus_ConnectionPending = -65793, mStatus_ConnectionFailed = -65794, mStatus_ConnectionEstablished = -65795 }; typedef mDNSs32 mStatus; // RFC 1034/1035 specify that a domain label consists of a length byte plus up to 63 characters #define MAX_DOMAIN_LABEL 63 typedef struct { mDNSu8 c[ 64]; } domainlabel; // One label: length byte and up to 63 characters // RFC 1034/1035 specify that a domain name, including length bytes, data bytes, and terminating zero, may be up to 255 bytes long #define MAX_DOMAIN_NAME 255 typedef struct { mDNSu8 c[256]; } domainname; // Up to 255 bytes of length-prefixed domainlabels typedef struct { mDNSu8 c[256]; } UTF8str255; // Null-terminated C string // The longest legal textual form of a DNS name is 1005 bytes, including the C-string terminating NULL at the end. // Explanation: // When a native domainname object is converted to printable textual form using ConvertDomainNameToCString(), // non-printing characters are represented in the conventional DNS way, as '\ddd', where ddd is a three-digit decimal number. // The longest legal domain name is 255 bytes, in the form of four labels as shown below: // Length byte, 63 data bytes, length byte, 63 data bytes, length byte, 63 data bytes, length byte, 61 data bytes, zero byte. // Each label is encoded textually as characters followed by a trailing dot. // If every character has to be represented as a four-byte escape sequence, then this makes the maximum textual form four labels // plus the C-string terminating NULL as shown below: // 63*4+1 + 63*4+1 + 63*4+1 + 61*4+1 + 1 = 1005. // Note that MAX_ESCAPED_DOMAIN_LABEL is not normally used: If you're only decoding a single label, escaping is usually not required. // It is for domain names, where dots are used as label separators, that proper escaping is vital. #define MAX_ESCAPED_DOMAIN_LABEL 254 #define MAX_ESCAPED_DOMAIN_NAME 1005 // *************************************************************************** #if 0 #pragma mark - DNS Message structures #endif #define mDNS_numZones numQuestions #define mDNS_numPrereqs numAnswers #define mDNS_numUpdates numAuthorities typedef packedstruct { mDNSOpaque16 id; mDNSOpaque16 flags; mDNSu16 numQuestions; mDNSu16 numAnswers; mDNSu16 numAuthorities; mDNSu16 numAdditionals; } DNSMessageHeader; // We can send and receive packets up to 9000 bytes (Ethernet Jumbo Frame size, if that ever becomes widely used) // However, in the normal case we try to limit packets to 1500 bytes so that we don't get IP fragmentation on standard Ethernet // 40 (IPv6 header) + 8 (UDP header) + 12 (DNS message header) + 1440 (DNS message body) = 1500 total #define AbsoluteMaxDNSMessageData 8940 #define NormalMaxDNSMessageData 1440 typedef packedstruct { DNSMessageHeader h; // Note: Size 12 bytes mDNSu8 data[AbsoluteMaxDNSMessageData]; // 40 (IPv6) + 8 (UDP) + 12 (DNS header) + 8940 (data) = 9000 } DNSMessage; // *************************************************************************** #if 0 #pragma mark - Resource Record structures #endif // Authoritative Resource Records: // There are four basic types: Shared, Advisory, Unique, Known Unique // * Shared Resource Records do not have to be unique // -- Shared Resource Records are used for DNS-SD service PTRs // -- It is okay for several hosts to have RRs with the same name but different RDATA // -- We use a random delay on responses to reduce collisions when all the hosts respond to the same query // -- These RRs typically have moderately high TTLs (e.g. one hour) // -- These records are announced on startup and topology changes for the benefit of passive listeners // -- These records send a goodbye packet when deregistering // // * Advisory Resource Records are like Shared Resource Records, except they don't send a goodbye packet // // * Unique Resource Records should be unique among hosts within any given mDNS scope // -- The majority of Resource Records are of this type // -- If two entities on the network have RRs with the same name but different RDATA, this is a conflict // -- Responses may be sent immediately, because only one host should be responding to any particular query // -- These RRs typically have low TTLs (e.g. a few minutes) // -- On startup and after topology changes, a host issues queries to verify uniqueness // * Known Unique Resource Records are treated like Unique Resource Records, except that mDNS does // not have to verify their uniqueness because this is already known by other means (e.g. the RR name // is derived from the host's IP or Ethernet address, which is already known to be a unique identifier). // Summary of properties of different record types: // Probe? Does this record type send probes before announcing? // Conflict? Does this record type react if we observe an apparent conflict? // Goodbye? Does this record type send a goodbye packet on departure? // // Probe? Conflict? Goodbye? Notes // Unregistered Should not appear in any list (sanity check value) // Shared No No Yes e.g. Service PTR record // Deregistering No No Yes Shared record about to announce its departure and leave the list // Advisory No No No // Unique Yes Yes No Record intended to be unique -- will probe to verify // Verified Yes Yes No Record has completed probing, and is verified unique // KnownUnique No Yes No Record is assumed by other means to be unique // Valid lifecycle of a record: // Unregistered -> Shared -> Deregistering -(goodbye)-> Unregistered // Unregistered -> Advisory -> Unregistered // Unregistered -> Unique -(probe)-> Verified -> Unregistered // Unregistered -> KnownUnique -> Unregistered // Each Authoritative kDNSRecordType has only one bit set. This makes it easy to quickly see if a record // is one of a particular set of types simply by performing the appropriate bitwise masking operation. // Cache Resource Records (received from the network): // There are four basic types: Answer, Unique Answer, Additional, Unique Additional // Bit 7 (the top bit) of kDNSRecordType is always set for Cache Resource Records; always clear for Authoritative Resource Records // Bit 6 (value 0x40) is set for answer records; clear for additional records // Bit 5 (value 0x20) is set for records received with the kDNSClass_UniqueRRSet enum { kDNSRecordTypeUnregistered = 0x00, // Not currently in any list kDNSRecordTypeDeregistering = 0x01, // Shared record about to announce its departure and leave the list kDNSRecordTypeUnique = 0x02, // Will become a kDNSRecordTypeVerified when probing is complete kDNSRecordTypeAdvisory = 0x04, // Like Shared, but no goodbye packet kDNSRecordTypeShared = 0x08, // Shared means record name does not have to be unique -- use random delay on responses kDNSRecordTypeVerified = 0x10, // Unique means mDNS should check that name is unique (and then send immediate responses) kDNSRecordTypeKnownUnique = 0x20, // Known Unique means mDNS can assume name is unique without checking // For Dynamic Update records, Known Unique means the record must already exist on the server. kDNSRecordTypeUniqueMask = (kDNSRecordTypeUnique | kDNSRecordTypeVerified | kDNSRecordTypeKnownUnique), kDNSRecordTypeActiveMask = (kDNSRecordTypeAdvisory | kDNSRecordTypeShared | kDNSRecordTypeVerified | kDNSRecordTypeKnownUnique), kDNSRecordTypePacketAdd = 0x80, // Received in the Additional Section of a DNS Response kDNSRecordTypePacketAddUnique = 0xA0, // Received in the Additional Section of a DNS Response with kDNSClass_UniqueRRSet set kDNSRecordTypePacketAns = 0xC0, // Received in the Answer Section of a DNS Response kDNSRecordTypePacketAnsUnique = 0xE0, // Received in the Answer Section of a DNS Response with kDNSClass_UniqueRRSet set kDNSRecordTypePacketAnsMask = 0x40, // True for PacketAns and PacketAnsUnique kDNSRecordTypePacketUniqueMask = 0x20 // True for PacketAddUnique and PacketAnsUnique }; typedef packedstruct { mDNSu16 priority; mDNSu16 weight; mDNSIPPort port; domainname target; } rdataSRV; typedef packedstruct { mDNSu16 preference; domainname exchange; } rdataMX; typedef packedstruct { domainname mname; domainname rname; mDNSOpaque32 serial; mDNSOpaque32 refresh; mDNSOpaque32 retry; mDNSOpaque32 expire; mDNSOpaque32 min; } rdataSOA; typedef packedstruct { mDNSu16 vers; mDNSu16 llqOp; mDNSu16 err; mDNSu8 id[8]; mDNSu32 lease; } LLQOptData; // NOTE: rdataOpt format may be repeated an arbitrary number of times in a single resource record typedef packedstruct { mDNSu16 opt; mDNSu16 optlen; union { LLQOptData llq; mDNSu32 lease; } OptData; } rdataOpt; // StandardAuthRDSize is 264 (256+8), which is large enough to hold a maximum-sized SRV record // MaximumRDSize is 8K the absolute maximum we support (at least for now) #define StandardAuthRDSize 264 #define MaximumRDSize 8192 // InlineCacheRDSize is 64 // Records received from the network with rdata this size or less have their rdata stored right in the CacheRecord object // Records received from the network with rdata larger than this have additional storage allocated for the rdata // A quick unscientific sample from a busy network at Apple with lots of machines revealed this: // 1461 records in cache // 292 were one-byte TXT records // 136 were four-byte A records // 184 were sixteen-byte AAAA records // 780 were various PTR, TXT and SRV records from 12-64 bytes // Only 69 records had rdata bigger than 64 bytes #define InlineCacheRDSize 64 typedef union { mDNSu8 data[StandardAuthRDSize]; mDNSv4Addr ip; // For 'A' record mDNSv6Addr ipv6; // For 'AAAA' record domainname name; // For PTR, NS, and CNAME records UTF8str255 txt; // For TXT record rdataSRV srv; // For SRV record rdataMX mx; // For MX record rdataSOA soa; // For SOA record rdataOpt opt; // For eDNS0 opt record } RDataBody; typedef struct { mDNSu16 MaxRDLength; // Amount of storage allocated for rdata (usually sizeof(RDataBody)) RDataBody u; } RData; #define sizeofRDataHeader (sizeof(RData) - sizeof(RDataBody)) typedef struct AuthRecord_struct AuthRecord; typedef struct CacheRecord_struct CacheRecord; typedef struct ResourceRecord_struct ResourceRecord; typedef struct DNSQuestion_struct DNSQuestion; typedef struct mDNS_struct mDNS; typedef struct mDNS_PlatformSupport_struct mDNS_PlatformSupport; // Note: Within an mDNSRecordCallback mDNS all API calls are legal except mDNS_Init(), mDNS_Close(), mDNS_Execute() typedef void mDNSRecordCallback(mDNS *const m, AuthRecord *const rr, mStatus result); // Note: // Restrictions: An mDNSRecordUpdateCallback may not make any mDNS API calls. // The intent of this callback is to allow the client to free memory, if necessary. // The internal data structures of the mDNS code may not be in a state where mDNS API calls may be made safely. typedef void mDNSRecordUpdateCallback(mDNS *const m, AuthRecord *const rr, RData *OldRData); struct ResourceRecord_struct { mDNSu8 RecordType; // See enum above mDNSInterfaceID InterfaceID; // Set if this RR is specific to one interface // For records received off the wire, InterfaceID is *always* set to the receiving interface // For our authoritative records, InterfaceID is usually zero, except for those few records // that are interface-specific (e.g. address records, especially linklocal addresses) domainname name; mDNSu16 rrtype; mDNSu16 rrclass; mDNSu32 rroriginalttl; // In seconds mDNSu16 rdlength; // Size of the raw rdata, in bytes mDNSu16 rdestimate; // Upper bound on size of rdata after name compression mDNSu32 namehash; // Name-based (i.e. case insensitive) hash of name mDNSu32 rdatahash; // 32-bit hash of the raw rdata mDNSu32 rdnamehash; // Set if this rdata contains a domain name (e.g. PTR, SRV, CNAME etc.) RData *rdata; // Pointer to storage for this rdata }; enum { regState_FetchingZoneData = 1, // getting info - update not sent regState_Pending = 2, // update sent, reply not received regState_Registered = 3, // update sent, reply received regState_DeregPending = 4, // dereg sent, reply not received regState_DeregDeferred = 5, // dereg requested while in Pending state - send dereg AFTER registration is confirmed regState_Cancelled = 6, // update not sent, reg. cancelled by client regState_TargetChange = 7, // host name change update pending regState_Unregistered = 8, // not in any list regState_Refresh = 9 // outstanding refresh message }; typedef mDNSu16 regState_t; typedef struct { regState_t state; mDNSOpaque16 id; domainname zone; // the zone that is updated mDNSAddr ns; // primary name server for the record's zone !!!KRS not technically correct to cache longer than TTL mDNSIPPort port; // port on which server accepts dynamic updates mDNSBool add; // !!!KRS this should really be an enumerated state struct uDNS_AuthInfo *AuthInfo; // authentication info (may be null) mDNSBool lease; // dynamic update contains (should contain) lease option mDNSs32 expire; // expiration of lease (-1 for static) } uDNS_RegInfo; struct AuthRecord_struct { // For examples of how to set up this structure for use in mDNS_Register(), // see mDNS_AdvertiseInterface() or mDNS_RegisterService(). // Basically, resrec and persistent metadata need to be set up before calling mDNS_Register(). // mDNS_SetupResourceRecord() is avaliable as a helper routine to set up most fields to sensible default values for you AuthRecord *next; // Next in list; first element of structure for efficiency reasons ResourceRecord resrec; uDNS_RegInfo uDNS_info; // Persistent metadata for Authoritative Records AuthRecord *Additional1; // Recommended additional record to include in response AuthRecord *Additional2; // Another additional AuthRecord *DependentOn; // This record depends on another for its uniqueness checking AuthRecord *RRSet; // This unique record is part of an RRSet mDNSRecordCallback *RecordCallback; // Callback function to call for state changes void *RecordContext; // Context parameter for the callback function mDNSu8 HostTarget; // Set if the target of this record (PTR, CNAME, SRV, etc.) is our host name // Transient state for Authoritative Records mDNSu8 Acknowledged; // Set if we've given the success callback to the client mDNSu8 ProbeCount; // Number of probes remaining before this record is valid (kDNSRecordTypeUnique) mDNSu8 AnnounceCount; // Number of announcements remaining (kDNSRecordTypeShared) mDNSu8 IncludeInProbe; // Set if this RR is being put into a probe right now mDNSInterfaceID ImmedAnswer; // Someone on this interface issued a query we need to answer (all-ones for all interfaces) #if MDNS_LOG_ANSWER_SUPPRESSION_TIMES mDNSs32 ImmedAnswerMarkTime; #endif mDNSInterfaceID ImmedAdditional; // Hint that we might want to also send this record, just to be helpful mDNSInterfaceID SendRNow; // The interface this query is being sent on right now mDNSv4Addr v4Requester; // Recent v4 query for this record, or all-ones if more than one recent query mDNSv6Addr v6Requester; // Recent v6 query for this record, or all-ones if more than one recent query AuthRecord *NextResponse; // Link to the next element in the chain of responses to generate const mDNSu8 *NR_AnswerTo; // Set if this record was selected by virtue of being a direct answer to a question AuthRecord *NR_AdditionalTo; // Set if this record was selected by virtue of being additional to another mDNSs32 ThisAPInterval; // In platform time units: Current interval for announce/probe mDNSs32 AnnounceUntil; // In platform time units: Creation time + TTL mDNSs32 LastAPTime; // In platform time units: Last time we sent announcement/probe mDNSs32 LastMCTime; // Last time we multicast this record (used to guard against packet-storm attacks) mDNSInterfaceID LastMCInterface; // Interface this record was multicast on at the time LastMCTime was recorded RData *NewRData; // Set if we are updating this record with new rdata mDNSu16 newrdlength; // ... and the length of the new RData mDNSRecordUpdateCallback *UpdateCallback; mDNSu32 UpdateCredits; // Token-bucket rate limiting of excessive updates mDNSs32 NextUpdateCredit; // Time next token is added to bucket mDNSs32 UpdateBlocked; // Set if update delaying is in effect RData rdatastorage; // Normally the storage is right here, except for oversized records // rdatastorage MUST be the last thing in the structure -- when using oversized AuthRecords, extra bytes // are appended after the end of the AuthRecord, logically augmenting the size of the rdatastorage // DO NOT ADD ANY MORE FIELDS HERE }; struct CacheRecord_struct { CacheRecord *next; // Next in list; first element of structure for efficiency reasons ResourceRecord resrec; // Transient state for Cache Records CacheRecord *NextInKAList; // Link to the next element in the chain of known answers to send mDNSs32 TimeRcvd; // In platform time units mDNSs32 NextRequiredQuery; // In platform time units mDNSs32 LastUsed; // In platform time units mDNSu32 UseCount; // Number of times this RR has been used to answer a question DNSQuestion *CRActiveQuestion; // Points to an active question referencing this answer mDNSu32 UnansweredQueries; // Number of times we've issued a query for this record without getting an answer mDNSs32 LastUnansweredTime; // In platform time units; last time we incremented UnansweredQueries mDNSu32 MPUnansweredQ; // Multi-packet query handling: Number of times we've seen a query for this record mDNSs32 MPLastUnansweredQT; // Multi-packet query handling: Last time we incremented MPUnansweredQ mDNSu32 MPUnansweredKA; // Multi-packet query handling: Number of times we've seen this record in a KA list mDNSBool MPExpectingKA; // Multi-packet query handling: Set when we increment MPUnansweredQ; allows one KA CacheRecord *NextInCFList; // Set if this is in the list of records we just received with the cache flush bit set struct { mDNSu16 MaxRDLength; mDNSu8 data[InlineCacheRDSize]; } rdatastorage; // Storage for small records is right here }; typedef struct { CacheRecord r; mDNSu8 _extradata[MaximumRDSize-InlineCacheRDSize]; // Glue on the necessary number of extra bytes } LargeCacheRecord; typedef struct NetworkInterfaceInfo_struct NetworkInterfaceInfo; typedef struct { AuthRecord RR_A; mDNSBool registered; // True if a name for the interface is globally registered domainname regname; // the name registered to the update server } uDNS_NetworkInterfaceInfo; // A NetworkInterfaceInfo_struct serves two purposes: // 1. It holds the address, PTR and HINFO records to advertise a given IP address on a given physical interface // 2. It tells mDNSCore which physical interfaces are available; each physical interface has its own unique InterfaceID. // Since there may be multiple IP addresses on a single physical interface, // there may be multiple NetworkInterfaceInfo_structs with the same InterfaceID. // In this case, to avoid sending the same packet n times, when there's more than one // struct with the same InterfaceID, mDNSCore picks one member of the set to be the // active representative of the set; all others have the 'InterfaceActive' flag unset. struct NetworkInterfaceInfo_struct { // Internal state fields. These are used internally by mDNSCore; the client layer needn't be concerned with them. NetworkInterfaceInfo *next; mDNSBool InterfaceActive; // Set if interface is sending & receiving packets (see comment above) mDNSBool IPv4Available; // If InterfaceActive, set if v4 available on this InterfaceID mDNSBool IPv6Available; // If InterfaceActive, set if v6 available on this InterfaceID // Standard AuthRecords that every Responder host should have (one per active IP address) AuthRecord RR_A; // 'A' or 'AAAA' (address) record for our ".local" name AuthRecord RR_PTR; // PTR (reverse lookup) record AuthRecord RR_HINFO; uDNS_NetworkInterfaceInfo uDNS_info; // Client API fields: The client must set up these fields *before* calling mDNS_RegisterInterface() mDNSInterfaceID InterfaceID; // Identifies physical interface; MUST NOT be 0, -1, or -2 mDNSAddr ip; // The IPv4 or IPv6 address to advertise mDNSBool Advertise; // False if you are only searching on this interface mDNSBool McastTxRx; // Send/Receive multicast on this { InterfaceID, address family } ? }; typedef struct ExtraResourceRecord_struct ExtraResourceRecord; struct ExtraResourceRecord_struct { ExtraResourceRecord *next; AuthRecord r; // Note: Add any additional fields *before* the AuthRecord in this structure, not at the end. // In some cases clients can allocate larger chunks of memory and set r->rdata->MaxRDLength to indicate // that this extra memory is available, which would result in any fields after the AuthRecord getting smashed }; // Note: Within an mDNSServiceCallback mDNS all API calls are legal except mDNS_Init(), mDNS_Close(), mDNS_Execute() typedef struct ServiceRecordSet_struct ServiceRecordSet; typedef void mDNSServiceCallback(mDNS *const m, ServiceRecordSet *const sr, mStatus result); struct ServiceRecordSet_struct { // Internal state fields. These are used internally by mDNSCore; the client layer needn't be concerned with them. // No fields need to be set up by the client prior to calling mDNS_RegisterService(); // all required data is passed as parameters to that function. ServiceRecordSet *next; uDNS_RegInfo uDNS_info; mDNSServiceCallback *ServiceCallback; void *ServiceContext; ExtraResourceRecord *Extras; // Optional list of extra AuthRecords attached to this service registration mDNSu32 NumSubTypes; AuthRecord *SubTypes; mDNSBool Conflict; // Set if this record set was forcibly deregistered because of a conflict domainname Host; // Set if this service record does not use the standard target host name AuthRecord RR_ADV; // e.g. _services._dns-sd._udp.local. PTR _printer._tcp.local. AuthRecord RR_PTR; // e.g. _printer._tcp.local. PTR Name._printer._tcp.local. AuthRecord RR_SRV; // e.g. Name._printer._tcp.local. SRV 0 0 port target AuthRecord RR_TXT; // e.g. Name._printer._tcp.local. TXT PrintQueueName // Don't add any fields after AuthRecord RR_TXT. // This is where the implicit extra space goes if we allocate a ServiceRecordSet containing an oversized RR_TXT record }; // *************************************************************************** #if 0 #pragma mark - Question structures #endif // We record the last eight instances of each duplicate query // This gives us v4/v6 on each of Ethernet/AirPort and Firewire, and two free slots "for future expansion" // If the host has more active interfaces that this it is not fatal -- duplicate question suppression will degrade gracefully. // Since we will still remember the last eight, the busiest interfaces will still get the effective duplicate question suppression. #define DupSuppressInfoSize 8 typedef struct { mDNSs32 Time; mDNSInterfaceID InterfaceID; mDNSs32 Type; // v4 or v6? } DupSuppressInfo; typedef enum { LLQ_UnInit = 0, LLQ_GetZoneInfo = 1, LLQ_InitialRequest = 2, LLQ_SecondaryRequest = 3, LLQ_Established = 4, LLQ_Refresh = 5, LLQ_Retry = 6, LLQ_Suspended = 7, // safe to re-start LLQ before this point LLQ_Static = 16, LLQ_Poll = 17, LLQ_Error = 18, LLQ_Cancelled = 19 } LLQ_State; typedef struct { LLQ_State state; mDNSAddr servAddr; mDNSIPPort servPort; DNSQuestion *question; mDNSu32 origLease; // seconds (relative) mDNSs32 retry; // ticks (absolute) mDNSs32 expire; // ticks (absolute) mDNSs16 ntries; mDNSu8 id[8]; mDNSBool deriveRemovesOnResume; } LLQ_Info; // LLQ constants #define kDNSOpt_LLQ 1 //!!!KRS #define kDNSOpt_Lease 2 //!!!KRS #define kLLQ_Vers 0 // prerelease #define kLLQ_DefLease 7200 // 2 hours #define kUpdate_DefLease 7200 #define kLLQ_MAX_TRIES 3 // retry an operation 3 times max #define kLLQ_INIT_RESEND 2 // resend an un-ack'd packet after 2 seconds, then double for each additional #define kLLQ_DEF_RETRY 1800 // retry a failed operation after 30 minutes // LLQ Operation Codes #define kLLQ_Setup 1 #define kLLQ_Refresh 2 #define LLQ_OPT_SIZE (2 * sizeof(mDNSu16)) + sizeof(LLQOptData) #define LEASE_OPT_SIZE (2 * sizeof(mDNSu16)) + sizeof(mDNSs32) // LLQ Errror Codes enum { LLQErr_NoError = 0, LLQErr_ServFull = 1, LLQErr_Static = 2, LLQErr_FormErr = 3, LLQErr_NoSuchLLQ = 4, LLQErr_BadVers = 5, LLQErr_UnknownErr = 6 }; typedef void (*InternalResponseHndlr)(mDNS *const m, DNSMessage *msg, const mDNSu8 *end, DNSQuestion *question, void *internalContext); typedef struct { mDNSOpaque16 id; mDNSs32 timestamp; mDNSBool internal; InternalResponseHndlr responseCallback; // NULL if internal field is false LLQ_Info *llq; // NULL for 1-shot queries CacheRecord *knownAnswers; void *context; } uDNS_QuestionInfo; // Note: Within an mDNSQuestionCallback mDNS all API calls are legal except mDNS_Init(), mDNS_Close(), mDNS_Execute() typedef void mDNSQuestionCallback(mDNS *const m, DNSQuestion *question, const ResourceRecord *const answer, mDNSBool AddRecord); struct DNSQuestion_struct { // Internal state fields. These are used internally by mDNSCore; the client layer needn't be concerned with them. DNSQuestion *next; mDNSu32 qnamehash; mDNSs32 LastQTime; // Last scheduled transmission of this Q on *all* applicable interfaces mDNSs32 ThisQInterval; // LastQTime + ThisQInterval is the next scheduled transmission of this Q // ThisQInterval > 0 for an active question; // ThisQInterval = 0 for a suspended question that's still in the list // ThisQInterval = -1 for a cancelled question that's been removed from the list mDNSu32 RecentAnswers; // Number of answers since the last time we sent this query mDNSu32 CurrentAnswers; // Number of records currently in the cache that answer this question mDNSu32 LargeAnswers; // Number of answers with rdata > 1024 bytes mDNSu32 UniqueAnswers; // Number of answers received with kDNSClass_UniqueRRSet bit set DNSQuestion *DuplicateOf; DNSQuestion *NextInDQList; DupSuppressInfo DupSuppress[DupSuppressInfoSize]; mDNSInterfaceID SendQNow; // The interface this query is being sent on right now mDNSBool SendOnAll; // Set if we're sending this question on all active interfaces mDNSs32 LastQTxTime; // Last time this Q was sent on one (but not necessarily all) interfaces uDNS_QuestionInfo uDNS_info; // Client API fields: The client must set up these fields *before* calling mDNS_StartQuery() mDNSInterfaceID InterfaceID; // Non-zero if you want to issue queries only on a single specific IP interface mDNSAddr Target; // Non-zero if you want to direct queries to a specific unicast target address mDNSIPPort TargetPort; // Must be set if Target is set mDNSOpaque16 TargetQID; // Must be set if Target is set domainname qname; mDNSu16 qtype; mDNSu16 qclass; mDNSQuestionCallback *QuestionCallback; void *QuestionContext; mDNSBool LongLived; // Set by client for calls to mDNS_StartQuery to indicate LLQs to unicast layer. // Set by mDNS.c in mDNS_StartBrowse. }; typedef struct { // Client API fields: The client must set up name and InterfaceID *before* calling mDNS_StartResolveService() // When the callback is invoked, ip, port, TXTlen and TXTinfo will have been filled in with the results learned from the network. domainname name; mDNSInterfaceID InterfaceID; // ID of the interface the response was received on mDNSAddr ip; // Remote (destination) IP address where this service can be accessed mDNSIPPort port; // Port where this service can be accessed mDNSu16 TXTlen; mDNSu8 TXTinfo[2048]; // Additional demultiplexing information (e.g. LPR queue name) } ServiceInfo; // Note: Within an mDNSServiceInfoQueryCallback mDNS all API calls are legal except mDNS_Init(), mDNS_Close(), mDNS_Execute() typedef struct ServiceInfoQuery_struct ServiceInfoQuery; typedef void mDNSServiceInfoQueryCallback(mDNS *const m, ServiceInfoQuery *query); struct ServiceInfoQuery_struct { // Internal state fields. These are used internally by mDNSCore; the client layer needn't be concerned with them. // No fields need to be set up by the client prior to calling mDNS_StartResolveService(); // all required data is passed as parameters to that function. // The ServiceInfoQuery structure memory is working storage for mDNSCore to discover the requested information // and place it in the ServiceInfo structure. After the client has called mDNS_StopResolveService(), it may // dispose of the ServiceInfoQuery structure while retaining the results in the ServiceInfo structure. DNSQuestion qSRV; DNSQuestion qTXT; DNSQuestion qAv4; DNSQuestion qAv6; mDNSu8 GotSRV; mDNSu8 GotTXT; mDNSu8 GotADD; mDNSu32 Answers; ServiceInfo *info; mDNSServiceInfoQueryCallback *ServiceInfoQueryCallback; void *ServiceInfoQueryContext; }; // *************************************************************************** #if 0 #pragma mark - Main mDNS object, used to hold all the mDNS state #endif typedef void mDNSCallback(mDNS *const m, mStatus result); #define CACHE_HASH_SLOTS 499 enum { mDNS_KnownBug_PhantomInterfaces = 1 }; typedef struct { mDNSs32 nextevent; DNSQuestion *ActiveQueries; //!!!KRS this should be a hashtable (hash on messageID) DNSQuestion *CurrentQuery; // pointer to ActiveQueries list being examined in a loop. Functions that remove // elements from the ActiveQueries list must update this pointer (if non-NULL) as necessary. //!!!KRS do the same for registration lists ServiceRecordSet *ServiceRegistrations; AuthRecord *RecordRegistrations; mDNSu16 NextMessageID; mDNSAddr Servers[32]; //!!!KRS this should be a dynamically allocated linked list domainname hostname; // global name for dynamic registration of address records char NameRegDomain[MAX_ESCAPED_DOMAIN_NAME]; // domain in which above hostname is registered // currently set by the platform layer at startup // do not set if services / address records are not to be globally registered to an update server // !!!KRS this must go away once we can learn the reg domain from the network or prefs char ServiceRegDomain[MAX_ESCAPED_DOMAIN_NAME]; // if set, all services that don't explicitly specify a domain upon registration will be // registered in this domain. if not set, .local will be used by default struct uDNS_AuthInfo *AuthInfoList; // list of domains required authentication for updates. !!!KRS this shoudl be a hashtable } uDNS_GlobalInfo; struct mDNS_struct { // Internal state fields. These hold the main internal state of mDNSCore; // the client layer needn't be concerned with them. // No fields need to be set up by the client prior to calling mDNS_Init(); // all required data is passed as parameters to that function. mDNS_PlatformSupport *p; // Pointer to platform-specific data of indeterminite size mDNSu32 KnownBugs; mDNSBool CanReceiveUnicast; mDNSBool AdvertiseLocalAddresses; mStatus mDNSPlatformStatus; mDNSCallback *MainCallback; void *MainContext; // For debugging: To catch and report locking failures mDNSu32 mDNS_busy; // Incremented between mDNS_Lock/mDNS_Unlock section mDNSu32 mDNS_reentrancy; // Incremented when calling a client callback mDNSu8 mDNS_shutdown; // Set when we're shutting down, allows us to skip some unnecessary steps mDNSu8 lock_rrcache; // For debugging: Set at times when these lists may not be modified mDNSu8 lock_Questions; mDNSu8 lock_Records; char MsgBuffer[80]; // Temp storage used while building error log messages // Task Scheduling variables mDNSs32 timenow; // The time that this particular activation of the mDNS code started mDNSs32 timenow_last; // The time the last time we ran mDNSs32 timenow_adjust; // Correction applied if we ever discover time went backwards mDNSs32 NextScheduledEvent; // Derived from values below mDNSs32 SuppressSending; // Don't send *any* packets during this time mDNSs32 NextCacheCheck; // Next time to refresh cache record before it expires mDNSs32 NextScheduledQuery; // Next time to send query in its exponential backoff sequence mDNSs32 NextScheduledProbe; // Next time to probe for new authoritative record mDNSs32 NextScheduledResponse; // Next time to send authoritative record(s) in responses mDNSs32 ExpectUnicastResponse; // Set when we send a query with the kDNSQClass_UnicastResponse bit set mDNSs32 RandomQueryDelay; // For de-synchronization of query packets on the wire mDNSBool SendDeregistrations; // Set if we need to send deregistrations (immediately) mDNSBool SendImmediateAnswers; // Set if we need to send answers (immediately -- or as soon as SuppressSending clears) mDNSBool SleepState; // Set if we're sleeping (send no more packets) // These fields only required for mDNS Searcher... DNSQuestion *Questions; // List of all registered questions, active and inactive DNSQuestion *NewQuestions; // Fresh questions not yet answered from cache DNSQuestion *CurrentQuestion; // Next question about to be examined in AnswerLocalQuestions() DNSQuestion *LocalOnlyQuestions; // Questions with InterfaceID set to mDNSInterface_LocalOnly DNSQuestion *NewLocalOnlyQuestions; // Fresh local-only questions not yet answered mDNSu32 rrcache_size; // Total number of available cache entries mDNSu32 rrcache_totalused; // Number of cache entries currently occupied mDNSu32 rrcache_active; // Number of cache entries currently occupied by records that answer active questions mDNSu32 rrcache_report; CacheRecord *rrcache_free; CacheRecord *rrcache_hash[CACHE_HASH_SLOTS]; CacheRecord **rrcache_tail[CACHE_HASH_SLOTS]; mDNSu32 rrcache_used[CACHE_HASH_SLOTS]; // Fields below only required for mDNS Responder... domainlabel nicelabel; // Rich text label encoded using canonically precomposed UTF-8 domainlabel hostlabel; // Conforms to RFC 1034 "letter-digit-hyphen" ARPANET host name rules domainname hostname; // Host Name, e.g. "Foo.local." UTF8str255 HIHardware; UTF8str255 HISoftware; AuthRecord *ResourceRecords; AuthRecord *DuplicateRecords; // Records currently 'on hold' because they are duplicates of existing records AuthRecord *LocalOnlyRecords; // Local records registered with InterfaceID set to mDNSInterface_LocalOnly AuthRecord *NewLocalOnlyRecords; // Fresh local-only records not yet delivered to local-only questions mDNSBool DiscardLocalOnlyRecords;// Set when we have "remove" events we need to deliver to local-only questions AuthRecord *CurrentRecord; // Next AuthRecord about to be examined NetworkInterfaceInfo *HostInterfaces; mDNSs32 ProbeFailTime; mDNSu32 NumFailedProbes; mDNSs32 SuppressProbes; // unicast-specific data uDNS_GlobalInfo uDNS_info; }; // *************************************************************************** #if 0 #pragma mark - Useful Static Constants #endif extern const mDNSIPPort zeroIPPort; extern const mDNSv4Addr zeroIPAddr; extern const mDNSv6Addr zerov6Addr; extern const mDNSv4Addr onesIPv4Addr; extern const mDNSv6Addr onesIPv6Addr; extern const mDNSAddr zeroAddr; extern const mDNSInterfaceID mDNSInterface_Any; // Zero extern const mDNSInterfaceID mDNSInterface_LocalOnly; // (mDNSInterfaceID)-1; extern const mDNSInterfaceID mDNSInterface_ForceMCast; // (mDNSInterfaceID)-2; extern const mDNSIPPort UnicastDNSPort; extern const mDNSIPPort MulticastDNSPort; extern const mDNSv4Addr AllDNSAdminGroup; extern const mDNSv4Addr AllDNSLinkGroup; extern const mDNSv6Addr AllDNSLinkGroupv6; extern const mDNSAddr AllDNSLinkGroup_v4; extern const mDNSAddr AllDNSLinkGroup_v6; extern const mDNSOpaque16 zeroID; extern const mDNSOpaque16 QueryFlags; extern const mDNSOpaque16 ResponseFlags; extern const mDNSOpaque16 UpdateReqFlags; extern const mDNSOpaque16 UpdateRespFlags; // *************************************************************************** #if 0 #pragma mark - Inline functions #endif #if (defined(_MSC_VER)) #define mDNSinline static __inline #elif ((__GNUC__ > 2) || ((__GNUC__ == 2) && (__GNUC_MINOR__ >= 9))) #define mDNSinline static inline #endif // If we're not doing inline functions, then this header needs to have the extern declarations #if !defined(mDNSinline) extern mDNSu16 mDNSVal16(mDNSOpaque16 x); extern mDNSu32 mDNSVal32(mDNSOpaque32 x); extern mDNSOpaque16 mDNSOpaque16fromIntVal(mDNSu16 v); extern mDNSOpaque32 mDNSOpaque32fromIntVal(mDNSu32 v); #endif // If we're compiling the particular C file that instantiates our inlines, then we // define "mDNSinline" (to empty string) so that we generate code in the following section #if (!defined(mDNSinline) && mDNS_InstantiateInlines) #define mDNSinline #endif #ifdef mDNSinline mDNSinline mDNSu16 mDNSVal16(mDNSOpaque16 x) { return((mDNSu16)((mDNSu16)x.b[0] << 8 | (mDNSu16)x.b[1])); } 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])); } mDNSinline mDNSOpaque16 mDNSOpaque16fromIntVal(mDNSu16 v) { mDNSOpaque16 x; x.b[0] = (mDNSu8)(v >> 8); x.b[1] = (mDNSu8)(v & 0xFF); return(x); } mDNSinline mDNSOpaque32 mDNSOpaque32fromIntVal(mDNSu32 v) { mDNSOpaque32 x; x.b[0] = (mDNSu8) (v >> 24) ; x.b[1] = (mDNSu8)((v >> 16) & 0xFF); x.b[2] = (mDNSu8)((v >> 8 ) & 0xFF); x.b[3] = (mDNSu8)((v ) & 0xFF); return x; } #endif // *************************************************************************** #if 0 #pragma mark - Main Client Functions #endif // Every client should call mDNS_Init, passing in storage for the mDNS object and the mDNS_PlatformSupport object. // // Clients that are only advertising services should use mDNS_Init_NoCache and mDNS_Init_ZeroCacheSize. // Clients that plan to perform queries (mDNS_StartQuery, mDNS_StartBrowse, mDNS_StartResolveService, etc.) // need to provide storage for the resource record cache, or the query calls will return 'mStatus_NoCache'. // The rrcachestorage parameter is the address of memory for the resource record cache, and // the rrcachesize parameter is the number of entries in the CacheRecord array passed in. // (i.e. the size of the cache memory needs to be sizeof(CacheRecord) * rrcachesize). // OS X 10.3 Panther uses an initial cache size of 64 entries, and then mDNSCore sends an // mStatus_GrowCache message if it needs more. // // Most clients should use mDNS_Init_AdvertiseLocalAddresses. This causes mDNSCore to automatically // create the correct address records for all the hosts interfaces. If you plan to advertise // services being offered by the local machine, this is almost always what you want. // There are two cases where you might use mDNS_Init_DontAdvertiseLocalAddresses: // 1. A client-only device, that browses for services but doesn't advertise any of its own. // 2. A proxy-registration service, that advertises services being offered by other machines, and takes // the appropriate steps to manually create the correct address records for those other machines. // In principle, a proxy-like registration service could manually create address records for its own machine too, // but this would be pointless extra effort when using mDNS_Init_AdvertiseLocalAddresses does that for you. // // When mDNS has finished setting up the client's callback is called // A client can also spin and poll the mDNSPlatformStatus field to see when it changes from mStatus_Waiting to mStatus_NoError // // Call mDNS_Close to tidy up before exiting // // Call mDNS_Register with a completed AuthRecord object to register a resource record // If the resource record type is kDNSRecordTypeUnique (or kDNSknownunique) then if a conflicting resource record is discovered, // the resource record's mDNSRecordCallback will be called with error code mStatus_NameConflict. The callback should deregister // the record, and may then try registering the record again after picking a new name (e.g. by automatically appending a number). // // Call mDNS_StartQuery to initiate a query. mDNS will proceed to issue Multicast DNS query packets, and any time a response // is received containing a record which matches the question, the DNSQuestion's mDNSAnswerCallback function will be called // Call mDNS_StopQuery when no more answers are required // // Care should be taken on multi-threaded or interrupt-driven environments. // The main mDNS routines call mDNSPlatformLock() on entry and mDNSPlatformUnlock() on exit; // each platform layer needs to implement these appropriately for its respective platform. // For example, if the support code on a particular platform implements timer callbacks at interrupt time, then // mDNSPlatformLock/Unlock need to disable interrupts or do similar concurrency control to ensure that the mDNS // code is not entered by an interrupt-time timer callback while in the middle of processing a client call. extern mStatus mDNS_Init (mDNS *const m, mDNS_PlatformSupport *const p, CacheRecord *rrcachestorage, mDNSu32 rrcachesize, mDNSBool AdvertiseLocalAddresses, mDNSCallback *Callback, void *Context); // See notes above on use of NoCache/ZeroCacheSize #define mDNS_Init_NoCache mDNSNULL #define mDNS_Init_ZeroCacheSize 0 // See notes above on use of Advertise/DontAdvertiseLocalAddresses #define mDNS_Init_AdvertiseLocalAddresses mDNStrue #define mDNS_Init_DontAdvertiseLocalAddresses mDNSfalse #define mDNS_Init_NoInitCallback mDNSNULL #define mDNS_Init_NoInitCallbackContext mDNSNULL extern void mDNS_GrowCache (mDNS *const m, CacheRecord *storage, mDNSu32 numrecords); extern void mDNS_Close (mDNS *const m); extern mDNSs32 mDNS_Execute (mDNS *const m); extern mStatus mDNS_Register (mDNS *const m, AuthRecord *const rr); extern mStatus mDNS_Update (mDNS *const m, AuthRecord *const rr, mDNSu32 newttl, const mDNSu16 newrdlength, RData *const newrdata, mDNSRecordUpdateCallback *Callback); extern mStatus mDNS_Deregister(mDNS *const m, AuthRecord *const rr); extern mStatus mDNS_StartQuery(mDNS *const m, DNSQuestion *const question); extern mStatus mDNS_StopQuery (mDNS *const m, DNSQuestion *const question); extern mStatus mDNS_Reconfirm (mDNS *const m, CacheRecord *const cacherr); extern mStatus mDNS_ReconfirmByValue(mDNS *const m, ResourceRecord *const rr); // *************************************************************************** #if 0 #pragma mark - Platform support functions that are accessible to the client layer too #endif extern mDNSs32 mDNSPlatformOneSecond; extern mDNSs32 mDNSPlatformTimeNow(void); // *************************************************************************** #if 0 #pragma mark - General utility and helper functions #endif // mDNS_RegisterService is a single call to register the set of resource records associated with a given named service. // // mDNS_StartResolveService is single call which is equivalent to multiple calls to mDNS_StartQuery, // to find the IP address, port number, and demultiplexing information for a given named service. // As with mDNS_StartQuery, it executes asynchronously, and calls the ServiceInfoQueryCallback when the answer is // found. After the service is resolved, the client should call mDNS_StopResolveService to complete the transaction. // The client can also call mDNS_StopResolveService at any time to abort the transaction. // // mDNS_GetBrowseDomains is a special case of the mDNS_StartQuery call, where the resulting answers // are a list of PTR records indicating (in the rdata) domains that are recommended for browsing. // After getting the list of domains to browse, call mDNS_StopQuery to end the search. // mDNS_GetDefaultBrowseDomain returns the name of the domain that should be highlighted by default. // // mDNS_GetRegistrationDomains and mDNS_GetDefaultRegistrationDomain are the equivalent calls to get the list // of one or more domains that should be offered to the user as choices for where they may register their service, // and the default domain in which to register in the case where the user has made no selection. extern void mDNS_SetupResourceRecord(AuthRecord *rr, RData *RDataStorage, mDNSInterfaceID InterfaceID, mDNSu16 rrtype, mDNSu32 ttl, mDNSu8 RecordType, mDNSRecordCallback Callback, void *Context); extern mStatus mDNS_RegisterService (mDNS *const m, ServiceRecordSet *sr, const domainlabel *const name, const domainname *const type, const domainname *const domain, const domainname *const host, mDNSIPPort port, const mDNSu8 txtinfo[], mDNSu16 txtlen, AuthRecord *SubTypes, mDNSu32 NumSubTypes, const mDNSInterfaceID InterfaceID, mDNSServiceCallback Callback, void *Context); extern mStatus mDNS_AddRecordToService(mDNS *const m, ServiceRecordSet *sr, ExtraResourceRecord *extra, RData *rdata, mDNSu32 ttl); extern mStatus mDNS_RemoveRecordFromService(mDNS *const m, ServiceRecordSet *sr, ExtraResourceRecord *extra); extern mStatus mDNS_RenameAndReregisterService(mDNS *const m, ServiceRecordSet *const sr, const domainlabel *newname); extern mStatus mDNS_DeregisterService(mDNS *const m, ServiceRecordSet *sr); extern mStatus mDNS_RegisterNoSuchService(mDNS *const m, AuthRecord *const rr, const domainlabel *const name, const domainname *const type, const domainname *const domain, const domainname *const host, const mDNSInterfaceID InterfaceID, mDNSRecordCallback Callback, void *Context); #define mDNS_DeregisterNoSuchService mDNS_Deregister extern mStatus mDNS_StartBrowse(mDNS *const m, DNSQuestion *const question, const domainname *const srv, const domainname *const domain, const mDNSInterfaceID InterfaceID, mDNSQuestionCallback *Callback, void *Context); #define mDNS_StopBrowse mDNS_StopQuery extern mStatus mDNS_StartResolveService(mDNS *const m, ServiceInfoQuery *query, ServiceInfo *info, mDNSServiceInfoQueryCallback *Callback, void *Context); extern void mDNS_StopResolveService (mDNS *const m, ServiceInfoQuery *query); typedef enum { mDNS_DomainTypeBrowse = 0, mDNS_DomainTypeBrowseDefault = 1, mDNS_DomainTypeRegistration = 2, mDNS_DomainTypeRegistrationDefault = 3 } mDNS_DomainType; extern mStatus mDNS_GetDomains(mDNS *const m, DNSQuestion *const question, mDNS_DomainType DomainType, const domainname *dom, const mDNSInterfaceID InterfaceID, mDNSQuestionCallback *Callback, void *Context); #define mDNS_StopGetDomains mDNS_StopQuery extern mStatus mDNS_AdvertiseDomains(mDNS *const m, AuthRecord *rr, mDNS_DomainType DomainType, const mDNSInterfaceID InterfaceID, char *domname); #define mDNS_StopAdvertiseDomains mDNS_Deregister // *************************************************************************** #if 0 #pragma mark - DNS name utility functions #endif // In order to expose the full capabilities of the DNS protocol (which allows any arbitrary eight-bit values // in domain name labels, including unlikely characters like ascii nulls and even dots) all the mDNS APIs // work with DNS's native length-prefixed strings. For convenience in C, the following utility functions // are provided for converting between C's null-terminated strings and DNS's length-prefixed strings. // Assignment // A simple C structure assignment of a domainname can cause a protection fault by accessing unmapped memory, // because that object is defined to be 256 bytes long, but not all domainname objects are truly the full size. // This macro uses mDNSPlatformMemCopy() to make sure it only touches the actual bytes that are valid. #define AssignDomainName(DST, SRC) mDNSPlatformMemCopy((SRC).c, (DST).c, DomainNameLength(&(SRC))) // Comparison functions extern mDNSBool SameDomainLabel(const mDNSu8 *a, const mDNSu8 *b); extern mDNSBool SameDomainName(const domainname *const d1, const domainname *const d2); extern mDNSBool IsLocalDomain(const domainname *d); // returns true for domains that by default should be looked up using link-local multicast // Get total length of domain name, in native DNS format, including terminal root label // (e.g. length of "com." is 5 (length byte, three data bytes, final zero) extern mDNSu16 DomainNameLength(const domainname *const name); // Append functions to append one or more labels to an existing native format domain name: // AppendLiteralLabelString adds a single label from a literal C string, with no escape character interpretation. // AppendDNSNameString adds zero or more labels from a C string using conventional DNS dots-and-escaping interpretation // AppendDomainLabel adds a single label from a native format domainlabel // AppendDomainName adds zero or more labels from a native format domainname extern mDNSu8 *AppendLiteralLabelString(domainname *const name, const char *cstr); extern mDNSu8 *AppendDNSNameString (domainname *const name, const char *cstr); extern mDNSu8 *AppendDomainLabel (domainname *const name, const domainlabel *const label); extern mDNSu8 *AppendDomainName (domainname *const name, const domainname *const append); // Convert from null-terminated string to native DNS format: // The DomainLabel form makes a single label from a literal C string, with no escape character interpretation. // The DomainName form makes native format domain name from a C string using conventional DNS interpretation: // dots separate labels, and within each label, '\.' represents a literal dot, '\\' represents a literal // backslash and backslash with three decimal digits (e.g. \000) represents an arbitrary byte value. extern mDNSBool MakeDomainLabelFromLiteralString(domainlabel *const label, const char *cstr); extern mDNSu8 *MakeDomainNameFromDNSNameString (domainname *const name, const char *cstr); // Convert native format domainlabel or domainname back to C string format // IMPORTANT: // When using ConvertDomainLabelToCString, the target buffer must be MAX_ESCAPED_DOMAIN_LABEL (254) bytes long // to guarantee there will be no buffer overrun. It is only safe to use a buffer shorter than this in rare cases // where the label is known to be constrained somehow (for example, if the label is known to be either "_tcp" or "_udp"). // Similarly, when using ConvertDomainNameToCString, the target buffer must be MAX_ESCAPED_DOMAIN_NAME (1005) bytes long. // See definitions of MAX_ESCAPED_DOMAIN_LABEL and MAX_ESCAPED_DOMAIN_NAME for more detailed explanation. extern char *ConvertDomainLabelToCString_withescape(const domainlabel *const name, char *cstr, char esc); #define ConvertDomainLabelToCString_unescaped(D,C) ConvertDomainLabelToCString_withescape((D), (C), 0) #define ConvertDomainLabelToCString(D,C) ConvertDomainLabelToCString_withescape((D), (C), '\\') extern char *ConvertDomainNameToCString_withescape(const domainname *const name, char *cstr, char esc); #define ConvertDomainNameToCString_unescaped(D,C) ConvertDomainNameToCString_withescape((D), (C), 0) #define ConvertDomainNameToCString(D,C) ConvertDomainNameToCString_withescape((D), (C), '\\') extern void ConvertUTF8PstringToRFC1034HostLabel(const mDNSu8 UTF8Name[], domainlabel *const hostlabel); extern mDNSu8 *ConstructServiceName(domainname *const fqdn, const domainlabel *name, const domainname *type, const domainname *const domain); extern mDNSBool DeconstructServiceName(const domainname *const fqdn, domainlabel *const name, domainname *const type, domainname *const domain); // Note: Some old functions have been replaced by more sensibly-named versions. // You can uncomment the hash-defines below if you don't want to have to change your source code right away. // When updating your code, note that (unlike the old versions) *all* the new routines take the target object // as their first parameter. //#define ConvertCStringToDomainName(SRC,DST) MakeDomainNameFromDNSNameString((DST),(SRC)) //#define ConvertCStringToDomainLabel(SRC,DST) MakeDomainLabelFromLiteralString((DST),(SRC)) //#define AppendStringLabelToName(DST,SRC) AppendLiteralLabelString((DST),(SRC)) //#define AppendStringNameToName(DST,SRC) AppendDNSNameString((DST),(SRC)) //#define AppendDomainLabelToName(DST,SRC) AppendDomainLabel((DST),(SRC)) //#define AppendDomainNameToName(DST,SRC) AppendDomainName((DST),(SRC)) // *************************************************************************** #if 0 #pragma mark - Other utility functions #endif extern mDNSu32 mDNS_vsnprintf(char *sbuffer, mDNSu32 buflen, const char *fmt, va_list arg); extern mDNSu32 mDNS_snprintf(char *sbuffer, mDNSu32 buflen, const char *fmt, ...) IS_A_PRINTF_STYLE_FUNCTION(3,4); extern mDNSu32 NumCacheRecordsForInterfaceID(const mDNS *const m, mDNSInterfaceID id); extern char *DNSTypeName(mDNSu16 rrtype); extern char *GetRRDisplayString_rdb(mDNS *const m, const ResourceRecord *rr, RDataBody *rd); #define GetRRDisplayString(m, rr) GetRRDisplayString_rdb((m), &(rr)->resrec, &(rr)->resrec.rdata->u) extern mDNSBool mDNSSameAddress(const mDNSAddr *ip1, const mDNSAddr *ip2); extern void IncrementLabelSuffix(domainlabel *name, mDNSBool RichText); // *************************************************************************** #if 0 #pragma mark - Authentication Support #endif #define HMAC_LEN 64 #define HMAC_IPAD 0x36 #define HMAC_OPAD 0x5c #define MD5_LEN 16 // padded keys for inned/outer hash rounds typedef struct { mDNSu8 ipad[HMAC_LEN]; mDNSu8 opad[HMAC_LEN]; } HMAC_Key; // Internal data structure to maintain authentication information for an update domain typedef struct uDNS_AuthInfo { domainname zone; domainname keyname; HMAC_Key key; struct uDNS_AuthInfo *next; } uDNS_AuthInfo; // Platform Support for computing MD5 // mDNSPlatformUTC returns the time, in seconds, since Jan 1st 1970 UTC and is required for generating TSIG records extern mDNSs32 mDNSPlatformUTC(void); // Client Calls // mDNS_UpdateDomainRequiresAuthentication tells the core to authenticate (via TSIG with an HMAC_MD5 hash) // when dynamically updating a given zone (and its subdomains). The key used in authentication must be in // domain name format. The shared secret must be a base64 encoded string with the base64 parameter set to // true, or binary data with the base64 parameter set to false. The length is the size of the secret in // bytes. (A minimum size of 16 bytes (128 bits) is recommended for an MD5 hash as per RFC 2485). // The This routine is normally called once for each secure domain at startup, though it can be called at any time. // mDNS_ClearAuthenticationList clears from the core's internal structures all domains previously passed to // mDNS_UpdateDomainRequiresAuthentication. extern mStatus mDNS_UpdateDomainRequiresAuthentication(mDNS *m, domainname *zone, domainname *key, mDNSu8 *sharedSecret, mDNSu32 ssLen, mDNSBool base64); extern void mDNS_ClearAuthenticationList(mDNS *m); // Routines called by the core, exported by DNSDigest.c // Convert a base64 encoded key into a binary byte stream extern mDNSs32 DNSDigest_Base64ToBin(const char *src, mDNSu8 *target, mDNSu32 targsize); // Convert an arbitrary binary key (of any length) into an HMAC key (stored in AuthInfo struct) extern void DNSDigest_ConstructHMACKey(uDNS_AuthInfo *info, mDNSu8 *key, mDNSu32 len); // sign a DNS message. The message must be compete, with all values in network byte order. end points to the end // of the message, and is modified by this routine. numAdditionals is a pointer to the number of additional // records in HOST byte order, which is incremented upon successful completion of this routine. The function returns // the new end pointer on success, and NULL on failure. extern mDNSu8 *DNSDigest_SignMessage(DNSMessage *msg, mDNSu8 **end, mDNSu16 *numAdditionals, uDNS_AuthInfo *info); // MD5 hash function used by the core for signing TSIG records (impemented in DNSDigest.c) extern mStatus DNSDigest_MD5(const DNSMessage *msg, mDNSu32 msglen, mDNSOpaque16 *digest); // *************************************************************************** #if 0 #pragma mark - PlatformSupport interface #endif // This section defines the interface to the Platform Support layer. // Normal client code should not use any of types defined here, or directly call any of the functions defined here. // The definitions are placed here because sometimes clients do use these calls indirectly, via other supported client operations. // For example, AssignDomainName is a macro defined using mDNSPlatformMemCopy() // Every platform support module must provide the following functions. // mDNSPlatformInit() typically opens a communication endpoint, and starts listening for mDNS packets. // When Setup is complete, the platform support layer calls mDNSCoreInitComplete(). // mDNSPlatformSendUDP() sends one UDP packet // When a packet is received, the PlatformSupport code calls mDNSCoreReceive() // mDNSPlatformClose() tidies up on exit // Note: mDNSPlatformMemAllocate/mDNSPlatformMemFree are only required for handling oversized resource records and unicast DNS. // If your target platform has a well-defined specialized application, and you know that all the records it uses // are InlineCacheRDSize or less, then you can just make a simple mDNSPlatformMemAllocate() stub that always returns // NULL. InlineCacheRDSize is a compile-time constant, which is set by default to 64. If you need to handle records // a little larger than this and you don't want to have to implement run-time allocation and freeing, then you // can raise the value of this constant to a suitable value (at the expense of increased memory usage). extern mStatus mDNSPlatformInit (mDNS *const m); extern void mDNSPlatformClose (mDNS *const m); extern mStatus mDNSPlatformSendUDP(const mDNS *const m, const DNSMessage *const msg, const mDNSu8 *const end, mDNSInterfaceID InterfaceID, const mDNSAddr *dst, mDNSIPPort dstport); extern void mDNSPlatformLock (const mDNS *const m); extern void mDNSPlatformUnlock (const mDNS *const m); extern void mDNSPlatformStrCopy (const void *src, void *dst); extern mDNSu32 mDNSPlatformStrLen (const void *src); extern void mDNSPlatformMemCopy (const void *src, void *dst, mDNSu32 len); extern mDNSBool mDNSPlatformMemSame (const void *src, const void *dst, mDNSu32 len); extern void mDNSPlatformMemZero ( void *dst, mDNSu32 len); extern void * mDNSPlatformMemAllocate (mDNSu32 len); extern void mDNSPlatformMemFree (void *mem); extern mStatus mDNSPlatformTimeInit (mDNSs32 *timenow); // Platform support modules should provide the following functions to map between opaque interface IDs // and interface indexes in order to support the DNS-SD API. If your target platform does not support // multiple interfaces and/or does not support the DNS-SD API, these functions can be empty. extern mDNSInterfaceID mDNSPlatformInterfaceIDfromInterfaceIndex(const mDNS *const m, mDNSu32 index); extern mDNSu32 mDNSPlatformInterfaceIndexfromInterfaceID(const mDNS *const m, mDNSInterfaceID id); // Every platform support module must provide the following functions if it is to support unicast DNS // and Dynamic Update. // All TCP socket operations implemented by the platform layer MUST NOT BLOCK. // mDNSPlatformTCPConnect initiates a TCP connection with a peer, adding the socket descriptor to the // main event loop. The return value indicates whether the connection succeeded, failed, or is pending // (i.e. the call would block.) On return, the descriptor parameter is set to point to the connected socket. // The TCPConnectionCallback is subsequently invoked when the connection // completes (in which case the ConnectionEstablished parameter is true), or data is available for // reading on the socket (indicated by the ConnectionEstablished parameter being false.) If the connection // asyncronously fails, the TCPConnectionCallback should be invoked as usual, with the error being // returned in subsequent calls to PlatformReadTCP or PlatformWriteTCP. (This allows for platforms // with limited asyncronous error detection capabilities.) PlatformReadTCP and PlatformWriteTCP must // return the number of bytes read/written, 0 if the call would block, and -1 if an error. // PlatformTCPCloseConnection must close the connection to the peer and remove the descriptor from the // event loop. CloseConnectin may be called at any time, including in a ConnectionCallback. typedef void (*TCPConnectionCallback)(int sd, void *context, mDNSBool ConnectionEstablished); extern mStatus mDNSPlatformTCPConnect(const mDNSAddr *dst, mDNSOpaque16 dstport, mDNSInterfaceID InterfaceID, TCPConnectionCallback callback, void *context, int *descriptor); extern void mDNSPlatformTCPCloseConnection(int sd); extern int mDNSPlatformReadTCP(int sd, void *buf, int buflen); extern int mDNSPlatformWriteTCP(int sd, const char *msg, int len); // Platforms that support unicast browsing and dynamic update registration for clients who do not specify a domain // in browse/registration calls must implement these routines to get the "default" browse/registration list. // The Get() functions must return a linked list of DNameListElem structs, allocated via mDNSPlatformMemAllocate. // Platforms may implement the Get() calls via the mDNS_CopyDNameList() helper routine. // Callers should free lists obtained via the Get() calls with th mDNS_FreeDNameList routine, provided by the core. typedef struct DNameListElem { domainname name; struct DNameListElem *next; } DNameListElem; extern DNameListElem *mDNSPlatformGetSearchDomainList(void); extern DNameListElem *mDNSPlatformGetRegDomainList(void); // Helper functions provided by the core extern DNameListElem *mDNS_CopyDNameList(const DNameListElem *orig); extern void mDNS_FreeDNameList(DNameListElem *list); // The core mDNS code provides these functions, for the platform support code to call at appropriate times // // mDNS_GenerateFQDN() is called once on startup (typically from mDNSPlatformInit()) // and then again on each subsequent change of the dot-local host name. // // !!!KRS // mDNS_GenerateGlobalFQDN() is called to register a domain name via Dynamic DNS update. It should be // called on startup (after acquiring an IP address and DNS server) and on each change to the machine name // or registration domain. The domain parameter is the domain in which the address record is to be registered, // e.g. "mycompany.com". The full name is formed by appending this domain to the machine's host label. // // mDNS_RegisterInterface() is used by the platform support layer to inform mDNSCore of what // physical and/or logical interfaces are available for sending and receiving packets. // Typically it is called on startup for each available interface, but register/deregister may be // called again later, on multiple occasions, to inform the core of interface configuration changes. // If set->Advertise is set non-zero, then mDNS_RegisterInterface() also registers the standard // resource records that should be associated with every publicised IP address/interface: // -- Name-to-address records (A/AAAA) // -- Address-to-name records (PTR) // -- Host information (HINFO) // IMPORTANT: The specified mDNSInterfaceID MUST NOT be 0, -1, or -2; these values have special meaning // // mDNS_SetDynamicRegistrationDomain is used to enable dynamic update registrations of address records // in the specified domain. // // mDNS_RegisterDNS() is used by the platform support layer to provide the core with the addresses of // available domain name servers for unicast queries/updates. RegisterDNS() should be called once for // each name server, typically at startup, or when a new name server becomes available. DeregiterDNS() // must be called whenever a registered name server becomes unavailable. DeregisterDNSList deregisters // all registered servers. mDNS_DNSRegistered() returns true if one or more servers are registered in the core. // // mDNSCoreInitComplete() is called when the platform support layer is finished. // Typically this is at the end of mDNSPlatformInit(), but may be later // (on platforms like OT that allow asynchronous initialization of the networking stack). // // mDNSCoreReceive() is called when a UDP packet is received // // mDNSCoreMachineSleep() is called when the machine sleeps or wakes // (This refers to heavyweight laptop-style sleep/wake that disables network access, // not lightweight second-by-second CPU power management modes.) extern void mDNS_GenerateFQDN(mDNS *const m); extern void mDNS_GenerateGlobalFQDN(mDNS *const m); extern mStatus mDNS_RegisterInterface (mDNS *const m, NetworkInterfaceInfo *set); extern void mDNS_DeregisterInterface(mDNS *const m, NetworkInterfaceInfo *set); extern void mDNS_RegisterDNS(mDNS *const m, mDNSv4Addr *const dnsAddr); extern void mDNS_DeregisterDNS(mDNS *const m, mDNSv4Addr *const dnsAddr); extern void mDNS_DeregisterDNSList(mDNS *const m); extern mDNSBool mDNS_DNSRegistered(mDNS *const m); extern void mDNSCoreInitComplete(mDNS *const m, mStatus result); extern void mDNSCoreReceive(mDNS *const m, DNSMessage *const msg, const mDNSu8 *const end, const mDNSAddr *const srcaddr, const mDNSIPPort srcport, const mDNSAddr *const dstaddr, const mDNSIPPort dstport, const mDNSInterfaceID InterfaceID, mDNSu8 ttl); extern void mDNSCoreMachineSleep(mDNS *const m, mDNSBool wake); extern mDNSBool mDNSAddrIsDNSMulticast(const mDNSAddr *ip); // *************************************************************************** #if 0 #pragma mark - Compile-Time assertion checks #endif // Some C compiler cleverness. We can make the compiler check certain things for // us, and report compile-time errors if anything is wrong. The usual way to do // this would be to use a run-time "if" statement, but then you don't find out // what's wrong until you run the software. This way, if the assertion condition // is false, the array size is negative, and the complier complains immediately. struct mDNS_CompileTimeAssertionChecks { // Check that the compiler generated our on-the-wire packet format structure definitions // properly packed, without adding padding bytes to align fields on 32-bit or 64-bit boundaries. char assert0[(sizeof(rdataSRV) == 262 ) ? 1 : -1]; char assert1[(sizeof(DNSMessageHeader) == 12 ) ? 1 : -1]; char assert2[(sizeof(DNSMessage) == 12+AbsoluteMaxDNSMessageData) ? 1 : -1]; char assert3[(sizeof(mDNSs8) == 1 ) ? 1 : -1]; char assert4[(sizeof(mDNSu8) == 1 ) ? 1 : -1]; char assert5[(sizeof(mDNSs16) == 2 ) ? 1 : -1]; char assert6[(sizeof(mDNSu16) == 2 ) ? 1 : -1]; char assert7[(sizeof(mDNSs32) == 4 ) ? 1 : -1]; char assert8[(sizeof(mDNSu32) == 4 ) ? 1 : -1]; char assert9[(sizeof(mDNSOpaque16) == 2 ) ? 1 : -1]; char assertA[(sizeof(mDNSOpaque32) == 4 ) ? 1 : -1]; char assertB[(sizeof(mDNSOpaque128) == 16 ) ? 1 : -1]; }; // *************************************************************************** #ifdef __cplusplus } #endif #endif