/Mac/Modules/cg/CFMLateImport.h

http://unladen-swallow.googlecode.com/ · C Header · 272 lines · 31 code · 14 blank · 227 comment · 0 complexity · 91ac43cd2faa19dce732770762e5fea5 MD5 · raw file

  1. /*
  2. File: CFMLateImport.h
  3. Contains: Interface to CFM late import library.
  4. Written by: Quinn
  5. Copyright: Copyright Š 1999 by Apple Computer, Inc., all rights reserved.
  6. You may incorporate this Apple sample source code into your program(s) without
  7. restriction. This Apple sample source code has been provided "AS IS" and the
  8. responsibility for its operation is yours. You are not permitted to redistribute
  9. this Apple sample source code as "Apple sample source code" after having made
  10. changes. If you're going to re-distribute the source, we require that you make
  11. it clear in the source that the code was descended from Apple sample source
  12. code, but that you've made changes.
  13. Change History (most recent first):
  14. <6> 21/9/01 Quinn Changes for CWPro7 Mach-O build.
  15. <5> 19/9/01 Quinn Change comments to reflect the fact that an unpacked data
  16. section is no longer required.
  17. <4> 19/9/01 Quinn Simplified API and implementation after a suggestion by Eric
  18. Grant. You no longer have to CFM export a dummy function; you
  19. can just pass in the address of your fragment's init routine.
  20. <3> 16/11/00 Quinn Allow symbol finding via a callback and use that to implement
  21. CFBundle support.
  22. <2> 18/10/99 Quinn Renamed CFMLateImport to CFMLateImportLibrary to allow for
  23. possible future API expansion.
  24. <1> 15/6/99 Quinn First checked in.
  25. */
  26. #pragma once
  27. /////////////////////////////////////////////////////////////////
  28. // MoreIsBetter Setup
  29. //#include "MoreSetup.h"
  30. // Mac OS Interfaces
  31. #if ! MORE_FRAMEWORK_INCLUDES
  32. #include <MacTypes.h>
  33. #include <CodeFragments.h>
  34. #include <Devices.h>
  35. #include <CFBundle.h>
  36. #endif
  37. /////////////////////////////////////////////////////////////////
  38. #ifdef __cplusplus
  39. extern "C" {
  40. #endif
  41. /* FAQ
  42. ---
  43. Q: What does this library do?
  44. A: It allows you to resolve a weak linked library at runtime,
  45. by supply a CFM connection to the library that should substitute
  46. for the weak linked one.
  47. Q: Does the substituted library have to have the same name as the
  48. weak linked library.
  49. A: No.
  50. Q: What's this useful for?
  51. A: The most obvious example of where this is useful is when
  52. you rely on shared libraries that the user might delete
  53. or move. To can find the shared library (possibly even
  54. using CatSearch), call GetDiskFragment to open a connection
  55. to it, late import it using this library, and then the
  56. rest of your code can continue to use the shared library
  57. as if nothing had happened. No more defining thousands
  58. of stub routines which call through routine pointers.
  59. There are, however, numerous less obvious uses. You can
  60. use this code to make a 'self repairing' application. If
  61. the user removes your shared library from the Extensions
  62. folder, the startup code for your application can offer
  63. tor re-install it. If the user agrees, you can then
  64. re-install your shared library, late import it, and then
  65. continue running your application if nothing happened.
  66. You can even use this code to free yourself from the
  67. Extensions folder entirely. Say you have a suite of
  68. applications that currently installs a dozen shared
  69. libraries in the Extensions folder. You can move those
  70. libraries to another folder entirely and each application's
  71. startup code can track down the library (using an alias
  72. in the Preferences file) and late import it.
  73. An even cooler use is to provide easy abstraction layers.
  74. Say you have a network code for both the MacTCP
  75. API and the Open Transport API. Typically, you would be
  76. force to do this by having an abstraction layer where every
  77. routine contains a switch between MacTCP and OT. Your
  78. OpenSocket routine might look like:
  79. static int OpenSocket(void)
  80. {
  81. if (gOTAvailable) {
  82. return OpenSocketOT();
  83. } else {
  84. return OpenSocketMacTCP();
  85. }
  86. }
  87. With this code, you can avoid that entirely. Simply
  88. weak link to a shared library that you know is never
  89. going to be implemented ("crea;MySocketsDummy") and then,
  90. at runtime, decide whether the system has MacTCP or OT
  91. and late import the relevant real implementation
  92. ("crea;MySocketsMacTCP" or "crea;MySocketsOT").
  93. One benefit of this approach is that only the MacTCP or
  94. the OT code is resident in memory on any given system.
  95. */
  96. typedef pascal OSStatus (*CFMLateImportLookupProc)(ConstStr255Param symName, CFragSymbolClass symClass,
  97. void **symAddr, void *refCon);
  98. // CFMLateImportLookupProc defines a callback for CFMLateImportCore.
  99. // The routine is expected to look up the address of the symbol named
  100. // symName and return it in *symAddr. The symbol should be of class
  101. // symClass, although the callback decides whether a class mismatch is
  102. // an error. refCon is an application defined value that was originally
  103. // passed in to CFMLateImportCore.
  104. //
  105. // If this routine returns an error, a symbol address of 0 is assumed.
  106. // If the symbol is marked as a weak import, the CFMLateImportCore will
  107. // continue, otherwise the CFMLateImportCore routine will fail with the
  108. // error.
  109. extern pascal OSStatus CFMLateImportCore(const CFragSystem7DiskFlatLocator *fragToFixLocator,
  110. CFragConnectionID fragToFixConnID,
  111. CFragInitFunction fragToFixInitRoutine,
  112. ConstStr255Param weakLinkedLibraryName,
  113. CFMLateImportLookupProc lookup,
  114. void *refCon);
  115. // This routine will link you, at runtime, to some library
  116. // that you were weak linked to and wasn't present when your
  117. // fragment was prepared. As well as the obvious functionality
  118. // of being able to resolve weak links after prepare time,
  119. // this functionality can be put to a number of less obvious uses,
  120. // some of which are discussed at the top of this header file.
  121. //
  122. // To call this routine, you need a number of pieces of information:
  123. //
  124. // 1. fragToFixLocator, fragToFixConnID: The location of your own
  125. // code fragment on disk and the CFM connection ID to your own
  126. // code fragment. Typically you get this information from your
  127. // fragment's CFM init routine. You must ensure that
  128. // fragToFixLocator->fileSpec points to an FSSpec of the
  129. // file which holds your code fragment.
  130. //
  131. // IMPORTANT:
  132. // The fact that you pass in a CFragSystem7DiskFlatLocator as the
  133. // fragToFixLocator implies that the fragment to be fixed up must
  134. // be in the data fork of a file. The code could be modified
  135. // to remove this requirement, but on disk code fragments are the most
  136. // common case.
  137. //
  138. // IMPORTANT:
  139. // The fragment to fix may have a packed data section. Packing the
  140. // data section will reduce the size of your fragment on disk, but it
  141. // will significantly increase the memory needed by this routine
  142. // (it increases memory usage by the sum of the sizes of the packed
  143. // and unpacked data section). See below for instructions on how to
  144. // create an unpacked data section.
  145. //
  146. // 2. fragToFixInitRoutine: A pointer to your own code fragment's
  147. // fragment initialiser routine. You necessarily have one of these
  148. // because you need it to get values for the fragToFixLocator and
  149. // fragToFixConnID parameters. Just pass its address in as a parameter
  150. // as well.
  151. //
  152. // 3. weakLinkedLibraryName: The name of the weak linked library which
  153. // failed to link. You must have weak linked to this library.
  154. // It is oxymoric for you to pass a strong linked library here,
  155. // because your code would not have prepared if a strong linked
  156. // library failed to prepare, and so you couldn't supply a valid
  157. /// fragToFix.
  158. //
  159. // 4. lookup, refCon: A pointer to a callback function that the
  160. // routine calls to look up the address of a symbol, and a refCon
  161. // for that callback routine.
  162. //
  163. // Note:
  164. // The fragToFixLocator and fragToFixInitRoutine parameters
  165. // are artifacts of the way in which this functionality is implemented.
  166. // In an ideal world, where CFM exported decent introspection APIs
  167. // to third party developers, these parameters would not be necessary.
  168. // If you're using this code inside Apple, you probably should investigate
  169. // using the CFM private APIs for getting at the information these
  170. // parameters are needed for. See the comments inside the implementation
  171. // for more details.
  172. //
  173. // Note:
  174. // The extra memory taken when you use a packed data section is also an
  175. // artifact of my workaround for the lack of CFM introspection APIs. In
  176. // my opinion it's better to use an unpacked data section and consume more
  177. // space on disk while saving memory. In CodeWarrior you can switch to an
  178. // unpacked data section by checking the "Expand Uninitialized Data"
  179. // checkbox in the "PPC PEF" settings panel. In MPW, specified the
  180. // "-packdata off" option to PPCLink.
  181. //
  182. // When the routine returns, any symbols that you imported from the
  183. // library named weakLinkedLibraryName will be resolved to the address
  184. // of the symbol provided by the "lookup" callback routine.
  185. //
  186. // It is possible for an unresolved import to remain unresolved after
  187. // this routine returns. If the symbol import is marked as weak (as
  188. // opposed to the library, which *must* be marked as weak) and the symbol
  189. // is not found by the "lookup" callback, the routine will simple skip
  190. // that symbol. If the symbol isn't marked as weak, the routine will fail
  191. // in that case.
  192. //
  193. // Most of the possible error results are co-opted CFM errors. These
  194. // include:
  195. //
  196. // cfragFragmentFormatErr -- The fragment to fix is is an unknown format.
  197. // cfragNoSectionErr -- Could not find the loader section in the fragment to fix.
  198. // cfragNoLibraryErr -- The fragment to fix is not weak linked to weakLinkedLibraryName.
  199. // cfragFragmentUsageErr -- The fragment to fix doesn't have a data section.
  200. // -- The fragment to fix is strong linked to weakLinkedLibraryName.
  201. // -- The fragment doesn't have an init routine.
  202. // cfragFragmentCorruptErr -- Encountered an undefined relocation opcode.
  203. // unimpErr -- Encountered an unimplement relocation opcode. The
  204. // relocation engine only implements a subset of the CFM
  205. // relocation opcodes, the subset most commonly used by
  206. // MPW and CodeWarrior PEF containers. If you encounter
  207. // this error, you'll probably have to add the weird
  208. // relocation opcode to the engine, which shouldn't be
  209. // be too hard.
  210. // memFullErr -- It's likely that this error is triggered by the memory
  211. // needed to unpack your data section. Either make your
  212. // data section smaller, or unpack it (see above).
  213. // errors returned by FindSymbol
  214. // errors returned by Memory Manager
  215. //
  216. // The routine needs enough memory to hold the loader section of the fragment
  217. // to fix in memory. It allocates that memory using NewPtr and dispsoses of
  218. // it before it returns. You may want to change the memory allocator, which
  219. // is very simple.
  220. extern pascal OSStatus CFMLateImportLibrary(const CFragSystem7DiskFlatLocator *fragToFixLocator,
  221. CFragConnectionID fragToFixConnID,
  222. CFragInitFunction fragToFixInitRoutine,
  223. ConstStr255Param weakLinkedLibraryName,
  224. CFragConnectionID connIDToImport);
  225. // A wrapper around CFMLateImportCore that looks up symbols by calling
  226. // FindSymbol on a connection to a CFM library (connIDToImport).
  227. // You can get this connection ID through any standard CFM API, for example
  228. // GetSharedLibrary, GetDiskFragment, or GetMemFragment.
  229. //
  230. // IMPORTANT:
  231. // The fragment name for connIDToImport *does not* have to match
  232. // weakLinkedLibraryName. This is part of the power of this library.
  233. extern pascal OSStatus CFMLateImportBundle(const CFragSystem7DiskFlatLocator *fragToFixLocator,
  234. CFragConnectionID fragToFixConnID,
  235. CFragInitFunction fragToFixInitRoutine,
  236. ConstStr255Param weakLinkedLibraryName,
  237. CFBundleRef bundleToImport);
  238. // A wrapper around CFMLateImportCore that looks up symbols by calling
  239. // CFBundleGetFunctionPointerForName on a reference to a Core Foundation
  240. // bundle (bundleToImport). You can get this reference through any
  241. // Core Foundation bundle API, for example CFBundleCreate.
  242. #ifdef __cplusplus
  243. }
  244. #endif