/Mac/Modules/cg/CFMLateImport.h

  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
 53extern "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
120typedef 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	
134extern 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
246extern 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
260extern 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