mDNSCore/mDNSPlatformFunctions.h

   1 /*
   2  * Copyright (c) 2002-2003 Apple Computer, Inc. All rights reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22
  23     Change History (most recent first):
  24
  25 $Log: mDNSPlatformFunctions.h,v $
  26 Revision 1.22  2003/08/18 22:53:37  cheshire
  27 <rdar://problem/3382647> mDNSResponder divide by zero in mDNSPlatformTimeNow()
  28
  29 Revision 1.21  2003/08/15 20:16:57  cheshire
  30 Update comment for <rdar://problem/3366590> mDNSResponder takes too much RPRVT
  31
  32 Revision 1.20  2003/08/12 19:56:24  cheshire
  33 Update to APSL 2.0
  34
  35 Revision 1.19  2003/08/05 22:20:15  cheshire
  36 <rdar://problem/3330324> Need to check IP TTL on responses
  37
  38 Revision 1.18  2003/07/22 23:57:20  cheshire
  39 Move platform-layer function prototypes from mDNSClientAPI.h to mDNSPlatformFunctions.h where they belong
  40
  41 Revision 1.17  2003/07/19 03:15:15  cheshire
  42 Add generic MemAllocate/MemFree prototypes to mDNSPlatformFunctions.h,
  43 and add the obvious trivial implementations to each platform support layer
  44
  45 Revision 1.16  2003/07/02 21:19:46  cheshire
  46 <rdar://problem/3313413> Update copyright notices, etc., in source code comments
  47
  48 Revision 1.15  2003/05/23 22:39:45  cheshire
  49 <rdar://problem/3268151> Need to adjust maximum packet size for IPv6
  50
  51 Revision 1.14  2003/04/28 21:54:57  cheshire
  52 Fix compiler warning
  53
  54 Revision 1.13  2003/03/15 04:40:36  cheshire
  55 Change type called "mDNSOpaqueID" to the more descriptive name "mDNSInterfaceID"
  56
  57 Revision 1.12  2003/02/21 01:54:08  cheshire
  58 Bug #: 3099194 mDNSResponder needs performance improvements
  59 Switched to using new "mDNS_Execute" model (see "Implementer Notes.txt")
  60
  61 Revision 1.11  2002/12/23 22:13:29  jgraessl
  62
  63 Reviewed by: Stuart Cheshire
  64 Initial IPv6 support for mDNSResponder.
  65
  66 Revision 1.10  2002/09/21 20:44:49  zarzycki
  67 Added APSL info
  68
  69 Revision 1.9  2002/09/19 04:20:43  cheshire
  70 Remove high-ascii characters that confuse some systems
  71
  72 Revision 1.8  2002/09/16 23:12:14  cheshire
  73 Minor code tidying
  74
  75 Revision 1.7  2002/09/16 18:41:42  cheshire
  76 Merge in license terms from Quinn's copy, in preparation for Darwin release
  77
  78 */
  79
  80 #ifndef __mDNSPlatformFunctions_h
  81 #define __mDNSPlatformFunctions_h
  82
  83 // ***************************************************************************
  84 // Support functions which must be provided by each set of specific PlatformSupport files
  85
  86 // mDNSPlatformInit() typically opens a communication endpoint, and starts listening for mDNS packets.
  87 // When Setup is complete, the callback is called.
  88 // mDNSPlatformSendUDP() sends one UDP packet
  89 // When a packet is received, the PlatformSupport code calls mDNSCoreReceive()
  90 // mDNSPlatformClose() tidies up on exit
  91
  92 #ifdef  __cplusplus
  93         extern "C" {
  94 #endif
  95
  96 // ***************************************************************************
  97 // DNS protocol message format
  98
  99 typedef struct
 100         {
 101         mDNSOpaque16 id;
 102         mDNSOpaque16 flags;
 103         mDNSu16 numQuestions;
 104         mDNSu16 numAnswers;
 105         mDNSu16 numAuthorities;
 106         mDNSu16 numAdditionals;
 107         } DNSMessageHeader;
 108
 109 // We can send and receive packets up to 9000 bytes (Ethernet Jumbo Frame size, if that ever becomes widely used)
 110 // However, in the normal case we try to limit packets to 1500 bytes so that we don't get IP fragmentation on standard Ethernet
 111 // 40 (IPv6 header) + 8 (UDP header) + 12 (DNS message header) + 1440 (DNS message body) = 1500 total
 112 #define AbsoluteMaxDNSMessageData 8940
 113 #define NormalMaxDNSMessageData 1440
 114 typedef struct
 115         {
 116         DNSMessageHeader h;                                             // Note: Size 12 bytes
 117         mDNSu8 data[AbsoluteMaxDNSMessageData]; // 40 (IPv6) + 8 (UDP) + 12 (DNS header) + 8940 (data) = 9000
 118         } DNSMessage;
 119
 120 // ***************************************************************************
 121 // Functions
 122
 123 // Every platform support module must provide the following functions.
 124 // Note: mDNSPlatformMemAllocate/mDNSPlatformMemFree are only required for handling oversized resource records.
 125 // If your target platform has a well-defined specialized application, and you know that all the records it uses
 126 // are InlineCacheRDSize or less, then you can just make a simple mDNSPlatformMemAllocate() stub that always returns
 127 // NULL. InlineCacheRDSize is a compile-time constant, which is set by default to 64. If you need to handle records
 128 // a little larger than this and you don't want to have to implement run-time allocation and freeing, then you
 129 // can raise the value of this constant to a suitable value (at the expense of increased memory usage).
 130 extern mStatus  mDNSPlatformInit        (mDNS *const m);
 131 extern void     mDNSPlatformClose       (mDNS *const m);
 132 extern mStatus  mDNSPlatformSendUDP(const mDNS *const m, const DNSMessage *const msg, const mDNSu8 *const end,
 133         mDNSInterfaceID InterfaceID, mDNSIPPort srcport, const mDNSAddr *dst, mDNSIPPort dstport);
 134
 135 extern void     mDNSPlatformLock        (const mDNS *const m);
 136 extern void     mDNSPlatformUnlock      (const mDNS *const m);
 137
 138 extern void     mDNSPlatformStrCopy     (const void *src,       void *dst);
 139 extern mDNSu32  mDNSPlatformStrLen      (const void *src);
 140 extern void     mDNSPlatformMemCopy     (const void *src,       void *dst, mDNSu32 len);
 141 extern mDNSBool mDNSPlatformMemSame     (const void *src, const void *dst, mDNSu32 len);
 142 extern void     mDNSPlatformMemZero     (                       void *dst, mDNSu32 len);
 143 extern void *   mDNSPlatformMemAllocate (mDNSu32 len);
 144 extern void     mDNSPlatformMemFree     (void *mem);
 145 extern mStatus  mDNSPlatformTimeInit    (mDNSs32 *timenow);
 146
 147 // The core mDNS code provides these functions, for the platform support code to call at appropriate times
 148 //
 149 // mDNS_GenerateFQDN() is called once on startup (typically from mDNSPlatformInit())
 150 // and then again on each subsequent dot-local host name change.
 151 //
 152 // mDNS_RegisterInterface() is used by the platform support layer to inform mDNSCore of what
 153 // physical and/or logical interfaces are available for sending and receiving packets.
 154 // Typically it is called on startup for each available interface, but register/deregister may be
 155 // called again later, on multiple occasions, to inform the core of interface configuration changes.
 156 // If set->Advertise is set non-zero, then mDNS_RegisterInterface() also registers the standard
 157 // resource records that should be associated with every publicised IP address/interface:
 158 // -- Name-to-address records (A/AAAA)
 159 // -- Address-to-name records (PTR)
 160 // -- Host information (HINFO)
 161 //
 162 // mDNSCoreInitComplete() is called when the platform support layer is finished.
 163 // Typically this is at the end of mDNSPlatformInit(), but may be later
 164 // (on platforms like OT that allow asynchronous initialization of the networking stack).
 165 //
 166 // mDNSCoreReceive() is called when a UDP packet is received
 167 //
 168 // mDNSCoreMachineSleep() is called when the machine sleeps or wakes
 169 // (This refers to  heavyweight laptop-style sleep/wake that disables network access,
 170 // not lightweight second-by-second CPU power management modes.)
 171
 172 extern void     mDNS_GenerateFQDN(mDNS *const m);
 173 extern mStatus  mDNS_RegisterInterface  (mDNS *const m, NetworkInterfaceInfo *set);
 174 extern void     mDNS_DeregisterInterface(mDNS *const m, NetworkInterfaceInfo *set);
 175 extern void     mDNSCoreInitComplete(mDNS *const m, mStatus result);
 176 extern void     mDNSCoreReceive(mDNS *const m, DNSMessage *const msg, const mDNSu8 *const end,
 177                                                                 const mDNSAddr *const srcaddr, const mDNSIPPort srcport,
 178                                                                 const mDNSAddr *const dstaddr, const mDNSIPPort dstport, const mDNSInterfaceID InterfaceID, mDNSu8 ttl);
 179 extern void     mDNSCoreMachineSleep(mDNS *const m, mDNSBool wake);
 180
 181 #ifdef  __cplusplus
 182         }
 183 #endif
 184
 185 #endif