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