home *** CD-ROM | disk | FTP | other *** search
- /*
- File: CodeFragments.h
-
- Contains: Public Code Fragment Manager Interfaces.
-
- Version: Technology: System 7 and System 8
- Release: Universal Interfaces 3.0d3 on Copland DR1
-
- Copyright: © 1984-1996 by Apple Computer, Inc. All rights reserved.
-
- Bugs?: If you find a problem with this file, send the file and version
- information (from above) and the problem description to:
-
- Internet: apple.bugs@applelink.apple.com
- AppleLink: APPLE.BUGS
-
- */
- /*
- •
- ===========================================================================================
- The Code Fragment Manager API
- =============================
- */
- #ifndef __CODEFRAGMENTS__
- #define __CODEFRAGMENTS__
-
- #ifndef __TYPES__
- #include <Types.h>
- #endif
- #ifndef __FILES__
- #include <Files.h>
- #endif
- #if FOR_SYSTEM8_PREEMPTIVE
- #ifndef __KERNEL__
- #include <Kernel.h>
- #endif
- #ifndef __FILEMANAGERTYPES__
- #include <FileManagerTypes.h>
- #endif
- #ifndef __TEXTOBJECTS__
- #include <TextObjects.h>
- #endif
- #endif
-
- #ifdef __cplusplus
- extern "C" {
- #endif
-
- #if PRAGMA_IMPORT_SUPPORTED
- #pragma import on
- #endif
-
- #if PRAGMA_ALIGN_SUPPORTED
- #pragma options align=mac68k
- #endif
-
- /*
- §
- ===========================================================================================
- Universal types and constants
- =============================
- */
- #if FOR_SYSTEM7_AND_SYSTEM8_PREEMPTIVE
- /*
- ----------------------------------------------------------------------------
- These declarations are for System 7 and all System 8 execution environments.
- */
-
- enum {
- kCFragResourceType = 'cfrg',
- kCFragResourceID = 0,
- kCFragLibraryFileType = 'shlb',
- kCFragAllFileTypes = 0xFFFFFFFF
- };
-
- typedef OSType CFragArchitecture;
-
- enum {
- kPowerPCCFragArch = 'pwpc',
- kMotorola68KCFragArch = 'm68k',
- kAnyCFragArch = 0x3F3F3F3F
- };
-
- #if GENERATINGPOWERPC
-
- enum {
- kCompiledCFragArch = kPowerPCCFragArch
- };
-
- #endif
- #if GENERATING68K
-
- enum {
- kCompiledCFragArch = kMotorola68KCFragArch
- };
-
- #endif
- typedef UInt32 CFragVersionNumber;
-
- enum {
- kNullCFragVersion = 0,
- kWildcardCFragVersion = 0xFFFFFFFF
- };
-
- typedef UInt8 CFragUsage;
-
- enum {
- kImportLibraryCFrag = 0, /* Standard CFM import library.*/
- kApplicationCFrag = 1, /* Macintosh application.*/
- kDropInAdditionCFrag = 2 /* Private extension to an application or library.*/
- };
-
-
- enum {
- kIsCompleteCFrag = 0, /* A "base" fragment, not an update.*/
- kFirstCFragUpdate = 1 /* The first update, others are numbered 2, 3, ...*/
- };
-
-
- enum {
- kCFragGoesToEOF = 0
- };
-
- typedef UInt8 CFragLocatorKind;
-
- enum {
- kMemoryCFragLocator = 0, /* Container is already addressable.*/
- kDataForkCFragLocator = 1, /* Container is in a file's data fork.*/
- kResourceCFragLocator = 2 /* Container is in a file's resource fork.*/
- };
-
- /*
- --------------------------------------------------------------------------------------
- A 'cfrg' resource consists of a header followed by a sequence of variable length
- members. The constant kDefaultCFragNameLen only provides for a legal ANSI declaration
- and for a reasonable display in a debugger. The actual name field is cut to fit.
- There may be "extensions" after the name, the memberSize field includes them. The
- general form of an extension is a 16 bit type code followed by a 16 bit size in bytes.
- Only one standard extension type is defined at present, it is used by SOM's searching
- mechanism.
- */
- union CFragUsage1Union { /* ! Meaning differs depending on value of "usage".*/
- UInt32 appStackSize; /* If the fragment is an application. (Not used by CFM!)*/
- };
- typedef union CFragUsage1Union CFragUsage1Union;
-
- union CFragUsage2Union { /* ! Meaning differs depending on value of "usage".*/
- SInt16 appSubdirID; /* If the fragment is an application.*/
- };
- typedef union CFragUsage2Union CFragUsage2Union;
-
- union CFragWhere1Union { /* ! Meaning differs depending on value of "where".*/
- UInt32 spaceID; /* If the fragment is in memory. (Actually an AddressSpaceID.)*/
- OSType forkKind; /* If the fragment is in an arbitrary byte stream fork.*/
- };
- typedef union CFragWhere1Union CFragWhere1Union;
-
- union CFragWhere2Union { /* ! Meaning differs depending on value of "where".*/
- UInt16 forkInstance; /* If the fragment is in an arbitrary byte stream fork.*/
- };
- typedef union CFragWhere2Union CFragWhere2Union;
-
-
- enum {
- kDefaultCFragNameLen = 16
- };
-
- struct CFragResourceMember {
- CFragArchitecture architecture;
- UInt16 reservedA; /* ! Must be zero!*/
- UInt8 reservedB; /* ! Must be zero!*/
- UInt8 updateLevel;
- CFragVersionNumber currentVersion;
- CFragVersionNumber oldDefVersion;
- CFragUsage1Union uUsage1;
- CFragUsage2Union uUsage2;
- CFragUsage usage;
- CFragLocatorKind where;
- UInt32 offset;
- UInt32 length;
- CFragWhere1Union uWhere1;
- CFragWhere2Union uWhere2;
- UInt16 extensionCount; /* The number of extensions beyond the name.*/
- UInt16 memberSize; /* Size in bytes, includes all extensions.*/
- unsigned char name[16]; /* ! Actually a sized PString.*/
- };
- typedef struct CFragResourceMember CFragResourceMember;
-
- typedef CFragResourceMember *CFragResourceMemberPtr;
- struct CFragResourceExtensionHeader {
- UInt16 extensionKind;
- UInt16 extensionSize;
- };
- typedef struct CFragResourceExtensionHeader CFragResourceExtensionHeader;
-
- typedef CFragResourceExtensionHeader *CFragResourceExtensionHeaderPtr;
- struct CFragResourceSearchExtension {
- CFragResourceExtensionHeader header;
- OSType libKind;
- unsigned char qualifiers[1]; /* ! Actually four PStrings.*/
- };
- typedef struct CFragResourceSearchExtension CFragResourceSearchExtension;
-
- typedef CFragResourceSearchExtension *CFragResourceSearchExtensionPtr;
-
- enum {
- kCFragResourceSearchExtensionKind = 0x30EE
- };
-
- struct CFragResource {
- UInt32 reservedA; /* ! Must be zero!*/
- UInt32 reservedB; /* ! Must be zero!*/
- UInt16 reservedC; /* ! Must be zero!*/
- UInt16 version;
- UInt32 reservedD; /* ! Must be zero!*/
- UInt32 reservedE; /* ! Must be zero!*/
- UInt32 reservedF; /* ! Must be zero!*/
- UInt32 reservedG; /* ! Must be zero!*/
- UInt16 reservedH; /* ! Must be zero!*/
- UInt16 memberCount;
- CFragResourceMember firstMember;
- };
- typedef struct CFragResource CFragResource;
-
- typedef CFragResource *CFragResourcePtr;
-
- enum {
- kCurrCFragResourceVersion = 1
- };
-
- #define AlignToFour(aValue) (((aValue) + 3) & ~3)
- #define kBaseCFragResourceMemberSize (offsetof ( CFragResourceMember, name ) )
- #define kBaseCFragResourceSize (offsetof ( CFragResource, firstMember.name ) )
- #define NextCFragResourceMemberPtr(aMemberPtr) \
- ((CFragResourceMemberPtr) ((BytePtr)aMemberPtr + aMemberPtr->memberSize))
- #define FirstCFragResourceExtensionPtr(aMemberPtr) \
- ((CFragResourceExtensionHeaderPtr) ((BytePtr)aMemberPtr + \
- AlignToFour ( kBaseCFragResourceMemberSize + \
- aMemberPtr->name[0] + 1 ) ))
- #define NextCFragResourceExtensionPtr(anExtensionPtr) \
- ((CFragResourceExtensionHeaderPtr) ((BytePtr)anExtensionPtr + \
- ((CFragResourceExtensionHeaderPtr)anExtensionPtr)->extensionSize ))
- #define FirstCFragResourceSearchQualifier(searchExtensionPtr) \
- ((StringPtr) ((BytePtr)searchExtensionPtr + \
- offsetof ( CFragResourceSearchExtension, qualifiers ) ))
- #define NextCFragResourceSearchQualifier(searchQualifierPtr) \
- ((StringPtr) ((BytePtr)searchQualifierPtr + searchQualifierPtr[0] + 1))
- typedef struct OpaqueCFragConnectionID* CFragConnectionID;
- typedef struct OpaqueCFragClosureID* CFragClosureID;
- typedef struct OpaqueCFragContainerID* CFragContainerID;
- typedef struct OpaqueCFragContextID* CFragContextID;
- typedef UInt32 CFragLoadOptions;
-
- enum {
- kLoadCFrag = 0x0001, /* Try to use existing copy, load if not found.*/
- kFindCFrag = 0x0002, /* Try find an existing copy, don't load if not found.*/
- kPrivateCFragCopy = kLoadCFrag | 0x0004 /* Load a new private copy.*/
- };
-
-
- enum {
- kUnresolvedCFragSymbolAddress = 0
- };
-
- typedef UInt8 CFragSymbolClass;
-
- enum {
- kCodeCFragSymbol = 0,
- kDataCFragSymbol = 1,
- kTVectorCFragSymbol = 2,
- kTOCCFragSymbol = 3,
- kGlueCFragSymbol = 4
- };
-
- #endif
- /*
- §
- ===========================================================================================
- System 7 Services (Deprecated in System 8)
- ==========================================
- */
- #if FOR_SYSTEM7_AND_SYSTEM8_DEPRECATED
- /*
- ---------------------------------------------------------------------------------
- These declarations are for System 7 and the System 8 cooperative environment, but
- should be avoided under System 8. Better alternatives exist for System 8.
- */
- #define IsFileLocation(where) \
- ( ((where) == kDataForkCFragLocator) || ((where) == kResourceCFragLocator) )
- extern pascal OSErr GetSharedLibrary(ConstStr63Param libName, CFragArchitecture archType, CFragLoadOptions loadFlags, CFragConnectionID *connID, Ptr *mainAddr, Str255 errMessage)
- THREEWORDINLINE(0x3F3C, 0x0001, 0xAA5A);
-
- extern pascal OSErr GetDiskFragment(const FSSpec *fileSpec, UInt32 offset, UInt32 length, ConstStr63Param fragName, CFragLoadOptions loadFlags, CFragConnectionID *connID, Ptr *mainAddr, Str255 errMessage)
- THREEWORDINLINE(0x3F3C, 0x0002, 0xAA5A);
-
- extern pascal OSErr GetMemFragment(void *memAddr, UInt32 length, ConstStr63Param fragName, CFragLoadOptions loadFlags, CFragConnectionID *connID, Ptr *mainAddr, Str255 errMessage)
- THREEWORDINLINE(0x3F3C, 0x0003, 0xAA5A);
-
- extern pascal OSErr CloseConnection(CFragConnectionID *connID)
- THREEWORDINLINE(0x3F3C, 0x0004, 0xAA5A);
-
- extern pascal OSErr FindSymbol(CFragConnectionID connID, ConstStr255Param symName, Ptr *symAddr, CFragSymbolClass *symClass)
- THREEWORDINLINE(0x3F3C, 0x0005, 0xAA5A);
-
- extern pascal OSErr CountSymbols(CFragConnectionID connID, long *symCount)
- THREEWORDINLINE(0x3F3C, 0x0006, 0xAA5A);
-
- extern pascal OSErr GetIndSymbol(CFragConnectionID connID, long symIndex, Str255 symName, Ptr *symAddr, CFragSymbolClass *symClass)
- THREEWORDINLINE(0x3F3C, 0x0007, 0xAA5A);
-
- #endif
- /*
- §
- ===========================================================================================
- System 8 Services (Not available in System 7)
- =============================================
- */
- #if FOR_SYSTEM8_PREEMPTIVE
- /*
- ---------------------------------------------------------------------------------
- These declarations are for all System 8 execution environments, but not System 7.
- */
-
- enum {
- kPatchCFragUpdateLevel = 255
- };
-
-
- enum {
- kByteStreamCFragLocator = 3,
- kNamedFragmentCFragLocator = 4
- };
-
-
- enum {
- kNamedLibraryCFragLocator = kNamedFragmentCFragLocator /* !!! Remove in D12!*/
- };
-
-
- enum {
- kPrivilegedCFragMask = 0x0010, /* ! May be removed in the future!*/
- kResidentCFragMask = 0x0020, /* ! May be removed in the future!*/
- kTreatCFragAsLibraryMask = 0x0040 /* Used in GetXyzFragment to recognize by name too.*/
- };
-
-
- enum {
- kPrivilegedCFragFlag = kPrivilegedCFragMask, /* !!! Remove in D12!*/
- kResidentCFragFlag = kResidentCFragMask /* !!! Remove in D12!*/
- };
-
-
- enum {
- kMainCFragSymbolIndex = -1,
- kInitCFragSymbolIndex = -2,
- kTermCFragSymbolIndex = -3
- };
-
- struct CFragRegisteredFileInfo {
- FSObjectRef fileRef;
- OSType fileType;
- ItemCount nestingDepth;
- };
- typedef struct CFragRegisteredFileInfo CFragRegisteredFileInfo;
-
-
- enum {
- kCFragRegisteredFileInfoVersion = 0x00010001
- };
-
- typedef UInt8 CFragCompatibility;
-
- enum {
- CFragBothCompatible = 0,
- CFragClientTooOld = 1,
- CFragProviderTooOld = 2
- };
-
- typedef UInt32 CFragShortVersionPair;
- #define ComposeCFragShortVersionPair(current,older) (current << 16 | older)
- #define GetCFragShortVersionCurrent(version) (version >> 16)
- #define GetCFragShortVersionOlder(version) (version & 0xFFFF)
- extern CFragCompatibility CFragCheckCompatibility(UInt32 clientPreferredVersion, UInt32 clientOldImpVersion, UInt32 providerCurrentVersion, UInt32 providerOldDefVersion);
-
- extern CFragCompatibility CFragCheckShortCompatibility(UInt32 clientVersions, UInt32 providerVersions);
-
- extern Boolean CFragHasFileLocation(CFragLocatorKind where);
-
- extern Boolean CFragHasUnresolvedImports(CFragConnectionID connID);
-
- extern OSStatus CFragPrepareNamedFragment(ConstStr63Param fragName, CFragUsage usage, CFragArchitecture archType, CFragVersionNumber preferredVersion, CFragVersionNumber oldestVersion, CFragLoadOptions loadFlags, CFragConnectionID *connID, LogicalAddress *mainAddr, TextObject optErrMsg);
-
- extern OSStatus CFragPrepareFromDiskFork(FSObjectRef fileSpec, FSForkType forkTag, ItemCount forkInstance, ByteCount offset, ByteCount length, ConstStr63Param fragName, CFragLoadOptions loadFlags, CFragConnectionID *connID, LogicalAddress *mainAddr, TextObject optErrMsg);
-
- extern OSStatus CFragPrepareFromMemory(LogicalAddress fragAddr, ByteCount length, ConstStr63Param fragName, CFragLoadOptions loadFlags, CFragConnectionID *connID, LogicalAddress *mainAddr, TextObject optErrMsg);
-
- extern OSStatus CFragCloseConnection(CFragConnectionID *connID);
-
- extern OSStatus CFragFindNamedSymbol(CFragConnectionID connID, ConstStr255Param symName, LogicalAddress *symAddr, CFragSymbolClass *symClass);
-
- extern OSStatus CFragCountSymbols(CFragConnectionID connID, ItemCount *symCount);
-
- extern OSStatus CFragGetIndexedSymbol(CFragConnectionID connID, SInt32 symIndex, Str255 symName, LogicalAddress *symAddr, CFragSymbolClass *symClass);
-
- extern OSStatus CFragGetFileSpec(CFragConnectionID connectionID, FSObjectRef *fileSpec);
-
- extern OSStatus CFragGetFragmentName(CFragConnectionID connectionID, Str63 name);
-
- extern OSStatus CFragRegisterFileFragments(KernelProcessID processID, FSObjectRef fileSpec, OSType fileType, ItemCount nestingDepth);
-
- extern OSStatus CFragUnregisterFileFragments(KernelProcessID processID, FSObjectRef fileSpec, OSType fileType, ItemCount nestingDepth);
-
- extern OSStatus CFragGetRegisteredFiles(KernelProcessID processID, ItemCount requestedCount, ItemCount *totalCount, PBVersion infoVersion, CFragRegisteredFileInfo *registeredFiles);
-
- #endif
- /*
- §
- ===========================================================================================
- Initialization & Termination Routines
- =====================================
- -----------------------------------------------------------------------------------------
- A fragment's initialization and termination routines are called when a new incarnation of
- the fragment is created or destroyed, respectively. Exactly when this occurs depends on
- what kinds of section sharing the fragment has and how the fragment is prepared. Import
- libraries have at most one incarnation per process. Fragments prepared with option
- kPrivateCFragCopy may have many incarnations per process.
- The initialization function is passed a pointer to an initialization information structure
- and returns an OSErr. If an initialization function returns a non-zero value the entire
- closure of which it is a part fails. The CFragInitBlock type has different visible parts
- under System 7 and System 8, but is of course the same internally. The C prototype for an
- initialization function is:
- pascal OSErr CFragInitFunction ( const CFragInitBlock * initBlock );
- The termination procedure takes no parameters and returns nothing. The C prototype for a
- termination procedure is:
- pascal void CFragTermProcedure ( void );
- */
- #if FOR_OPAQUE_SYSTEM_DATA_STRUCTURES
- /*
- --------------------------------------------------------------------------------------
- These declarations are the preferred form for System 8, hiding implementation details.
- */
- struct CFragOpaqueInitBlock {
- KernelProcessID processID;
- CFragClosureID closureID;
- CFragConnectionID connectionID;
- UInt32 reservedA[8];
- };
- typedef struct CFragOpaqueInitBlock CFragOpaqueInitBlock;
-
- typedef CFragOpaqueInitBlock *CFragOpaqueInitBlockPtr;
- typedef CFragOpaqueInitBlock CFragInitBlock;
- typedef CFragOpaqueInitBlockPtr CFragInitBlockPtr;
- #else
- /*
- --------------------------------------------------------------------------------------
- These declarations are for System 7. They may be used in System 8 but expose details.
- */
- struct CFragSystem7MemoryLocator {
- LogicalAddress address;
- UInt32 length;
- Boolean inPlace;
- UInt8 reservedA; /* ! Must be zero!*/
- UInt16 reservedB; /* ! Must be zero!*/
- };
- typedef struct CFragSystem7MemoryLocator CFragSystem7MemoryLocator;
-
- struct CFragSystem7DiskFlatLocator {
- FSSpecPtr fileSpec;
- UInt32 offset;
- UInt32 length;
- };
- typedef struct CFragSystem7DiskFlatLocator CFragSystem7DiskFlatLocator;
-
- /* ! This must have a file specification at the same offset as a disk flat locator!*/
- struct CFragSystem7SegmentedLocator {
- FSSpecPtr fileSpec;
- OSType rsrcType;
- SInt16 rsrcID;
- UInt16 reservedA; /* ! Must be zero!*/
- };
- typedef struct CFragSystem7SegmentedLocator CFragSystem7SegmentedLocator;
-
- struct CFragSystem7Locator {
- SInt32 where;
- union {
- CFragSystem7DiskFlatLocator onDisk;
- CFragSystem7MemoryLocator inMem;
- CFragSystem7SegmentedLocator inSegs;
- } u;
- };
- typedef struct CFragSystem7Locator CFragSystem7Locator;
-
- typedef CFragSystem7Locator *CFragSystem7LocatorPtr;
- struct CFragSystem7InitBlock {
- CFragContextID contextID;
- CFragClosureID closureID;
- CFragConnectionID connectionID;
- CFragSystem7Locator fragLocator;
- StringPtr libName;
- UInt32 reservedA; /* ! Must be zero!*/
- };
- typedef struct CFragSystem7InitBlock CFragSystem7InitBlock;
-
- typedef CFragSystem7InitBlock *CFragSystem7InitBlockPtr;
- typedef CFragSystem7InitBlock CFragInitBlock;
- typedef CFragSystem7InitBlockPtr CFragInitBlockPtr;
- #endif
- typedef OSErr (*CFragInitFunction)(const CFragInitBlock *initBlock);
- typedef void (*CFragTermProcedure)(void );
- /*
- §
- ===========================================================================================
- Old Name Spellings
- ==================
- -------------------------------------------------------------------------------------------
- We've tried to reduce the risk of name collisions in the future by introducing the phrase
- "CFrag" into constant and type names. The old names are defined below in terms of the new.
- */
- #if OLDROUTINENAMES
- typedef CFragConnectionID ConnectionID;
- typedef CFragLoadOptions LoadFlags;
- typedef CFragSymbolClass SymClass;
- typedef CFragInitBlock InitBlock;
- typedef CFragInitBlockPtr InitBlockPtr;
- #if !FOR_OPAQUE_SYSTEM_DATA_STRUCTURES
- typedef CFragSystem7MemoryLocator MemFragment;
- typedef CFragSystem7DiskFlatLocator DiskFragment;
- typedef CFragSystem7SegmentedLocator SegmentedFragment;
- typedef CFragSystem7Locator FragmentLocator;
- typedef CFragSystem7LocatorPtr FragmentLocatorPtr;
- typedef CFragSystem7MemoryLocator CFragHFSMemoryLocator;
- typedef CFragSystem7DiskFlatLocator CFragHFSDiskFlatLocator;
- typedef CFragSystem7SegmentedLocator CFragHFSSegmentedLocator;
- typedef CFragSystem7Locator CFragHFSLocator;
- typedef CFragSystem7LocatorPtr CFragHFSLocatorPtr;
- #endif
-
- enum {
- kPowerPCArch = kPowerPCCFragArch,
- kMotorola68KArch = kMotorola68KCFragArch,
- kAnyArchType = kAnyCFragArch,
- kNoLibName = 0,
- kNoConnectionID = 0,
- kLoadLib = kLoadCFrag,
- kFindLib = kFindCFrag,
- kNewCFragCopy = kPrivateCFragCopy,
- kLoadNewCopy = kPrivateCFragCopy,
- kUseInPlace = 0x80,
- kCodeSym = kCodeCFragSymbol,
- kDataSym = kDataCFragSymbol,
- kTVectSym = kTVectorCFragSymbol,
- kTOCSym = kTOCCFragSymbol,
- kGlueSym = kGlueCFragSymbol,
- kInMem = kMemoryCFragLocator,
- kOnDiskFlat = kDataForkCFragLocator,
- kOnDiskSegmented = kResourceCFragLocator,
- kIsLib = kImportLibraryCFrag,
- kIsApp = kApplicationCFrag,
- kIsDropIn = kDropInAdditionCFrag,
- kFullLib = kIsCompleteCFrag,
- kUpdateLib = kFirstCFragUpdate,
- kWholeFork = kCFragGoesToEOF,
- kCFMRsrcType = kCFragResourceType,
- kCFMRsrcID = kCFragResourceID,
- kSHLBFileType = kCFragLibraryFileType,
- kUnresolvedSymbolAddress = kUnresolvedCFragSymbolAddress
- };
-
-
- enum {
- kPowerPC = kPowerPCCFragArch,
- kMotorola68K = kMotorola68KCFragArch
- };
-
- #endif
-
- #if PRAGMA_ALIGN_SUPPORTED
- #pragma options align=reset
- #endif
-
- #if PRAGMA_IMPORT_SUPPORTED
- #pragma import off
- #endif
-
- #ifdef __cplusplus
- }
- #endif
-
- #endif /* __CODEFRAGMENTS__ */
-
-