| 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
|
|---|
