Legacy Document
Important: The information in this document is obsolete and should not be used for new development.
Important: The information in this document is obsolete and should not be used for new development.
Summary of the Component Manager
Pascal Summary
Constants
CONST gestaltComponentMgr = 'cpnt'; kComponentOpenSelect = -1; {open request} kComponentCloseSelect = -2; {close request} kComponentCanDoSelect = -3; {can do request} kComponentVersionSelect = -4; {version request} kComponentRegisterSelect = -5; {register request} kComponentTargetSelect = -6; {target request} kComponentUnregisterSelect = -7; {unregister request} {wildcard values for searches} kAnyComponentType = 0; {any type} kAnyComponentSubType = 0; {any subtype} kAnyComponentManufacturer = 0; {any manufacturer} kAnyComponentFlagsMask = 0; {any flags} {component description flag} cmpWantsRegisterMessage = $80000000; {send register request} {flags for optional extension to component resource} componentDoAutoVersion = 1; {provide version control} componentWantsUnregister = 2; {send unregister request} componentAutoVersionIncludeFlags = 4; {include flags in search} {flags for SetDefaultComponent function} defaultComponentIdentical = 0; defaultComponentAnyFlags = 1; defaultComponentAnyManufacturer = 2; defaultComponentAnySubType = 4; defaultComponentAnyFlagsAnyManufacturer = defaultComponentAnyFlags + defaultComponentAnyManufacturer; defaultComponentAnyFlagsAnyManufacturerAnySubType = defaultComponentAnyFlags + defaultComponentAnyManufacturer + defaultComponentAnySubType; {flags for the global parameter of RegisterComponentResourceFile function} registerCmpGlobal = 1; {other apps can communicate with component} registerCmpNoDuplicates = 2; {don't register if duplicate component } { exists} registerCompAfter = 4; {component registered after all others of } { same type}Data Types
TYPE ComponentDescription = RECORD componentType: OSType; {type} componentSubType: OSType; {subtype} componentManufacturer: OSType; {manufacturer} componentFlags: LongInt; {control flags} componentFlagsMask: LongInt; {mask for control flags } { (reserved when } { registering a component)} END; ResourceSpec = RECORD resType: OSType; {resource type} resID: Integer; {resource ID} END; ComponentResourcePtr = ^ComponentResource; ComponentResourceHandle = ^ComponentResourcePtr; ComponentResource = {component resource} RECORD cd: ComponentDescription; {registration information} component: ResourceSpec; {code resource} componentName: ResourceSpec; {name string resource} componentInfo: ResourceSpec; {info string resource} componentIcon: ResourceSpec; {icon resource} END; ComponentResourceExtension = {optional extension to resource} RECORD componentVersion: LongInt; {version of component} componentRegisterFlags: LongInt; {additional flags} componentIconFamily: Integer; {resource ID of icon } { family} END; {component parameters record} ComponentParameters = PACKED RECORD flags: Char; {reserved} paramSize: Char; {size in bytes of actual } { parameters passed to } { this routine} what: Integer; {request code- } { negative for requests } { defined by Component Mgr} params: ARRAY[0..0] OF LongInt; {actual parameters for } { the indicated routine} END; {component identifier} Component = ^ComponentRecord; ComponentRecord = RECORD data: ARRAY[0..0] OF LongInt; END; {component instance} ComponentInstance = ^ComponentInstanceRecord; ComponentInstanceRecord = RECORD data: ARRAY[0..0] OF LongInt; END; ComponentResult = LongInt; ComponentRoutine = ProcPtr; ComponentFunction = ProcPtr;Routines for Applications
Finding Components
FUNCTION FindNextComponent (aComponent: Component; looking: ComponentDescription): Component; FUNCTION CountComponents (looking: ComponentDescription): LongInt; FUNCTION GetComponentListModSeed: LongInt;Opening and Closing Components
FUNCTION OpenDefaultComponent (componentType: OSType; componentSubType: OSType): ComponentInstance; FUNCTION OpenComponent (aComponent: Component): ComponentInstance; FUNCTION CloseComponent (aComponentInstance: ComponentInstance): OSErr;Getting Information About Components
FUNCTION GetComponentInfo (aComponent: Component; VAR cd: ComponentDescription; componentName: Handle; componentInfo: Handle; componentIcon: Handle): OSErr; FUNCTION GetComponentIconSuite (aComponent: Component; VAR iconSuite: Handle): OSErr; FUNCTION GetComponentVersion (ci: ComponentInstance): LongInt; FUNCTION ComponentFunctionImplemented (ci: ComponentInstance; ftnNumber: Integer) : LongInt;Retrieving Component Errors
FUNCTION GetComponentInstanceError (aComponentInstance: ComponentInstance): OSErr;Routines for Components
Registering Components
FUNCTION RegisterComponent (cd: ComponentDescription; componentEntryPoint: ComponentRoutine; global: Integer; componentName: Handle; componentInfo: Handle; componentIcon: Handle): Component; FUNCTION RegisterComponentResource (cr: ComponentResourceHandle; global: Integer): Component; FUNCTION RegisterComponentResourceFile (resRefNum: integer; global: integer); LongInt; FUNCTION UnregisterComponent (aComponent: Component): OSErr;Dispatching to Component Routines
FUNCTION CallComponentFunction (params: ComponentParameters; func: ComponentFunction): LongInt; FUNCTION CallComponentFunctionWithStorage (storage: Handle; params: ComponentParameters; func: ComponentFunction): LongInt;Managing Component Connections
PROCEDURE SetComponentInstanceStorage (aComponentInstance: ComponentInstance; theStorage: Handle); FUNCTION GetComponentInstanceStorage (aComponentInstance: ComponentInstance): Handle; FUNCTION CountComponentInstances (aComponent: Component): LongInt; PROCEDURE SetComponentInstanceA5 (aComponentInstance: ComponentInstance; theA5: LongInt); FUNCTION GetComponentInstanceA5 (aComponentInstance: ComponentInstance) : LongInt;Setting Component Errors
PROCEDURE SetComponentInstanceError (aComponentInstance: ComponentInstance; theError: OSErr);Working With Component Reference Constants
PROCEDURE SetComponentRefcon (aComponent: Component; theRefcon: LongInt); FUNCTION GetComponentRefcon (aComponent: Component): LongInt;Accessing a Component's Resource File
FUNCTION OpenComponentResFile (aComponent: Component): Integer; FUNCTION CloseComponentResFile (refnum: Integer): OSErr;Calling Other Components
FUNCTION DelegateComponentCall (originalParams: ComponentParameters; ci: ComponentInstance): LongInt;Capturing Components
FUNCTION CaptureComponent (capturedComponent: Component; capturingComponent: Component): Component; FUNCTION UncaptureComponent (aComponent: Component): OSErr;
Targeting a Component InstanceFUNCTION ComponentSetTarget (ci: ComponentInstance; target: ComponentInstance): LongInt;Changing the Default Search Order
FUNCTION SetDefaultComponent (aComponent: Component; flags: Integer): OSErr;Application-Defined Routine
FUNCTION MyComponent (params: ComponentParameters; storage: Handle): ComponentResult;C Summary
Constants
#define gestaltComponentMgr 'cpnt' /*Gestalt selector*/ /*required component routines*/ #define kComponentOpenSelect -1 /*open request*/ #define kComponentCloseSelect -2 /*close request*/ #define kComponentCanDoSelect -3 /*can do request*/ #define kComponentVersionSelect -4 /*version request*/ #define kComponentRegisterSelect -5 /*register request*/ #define kComponentTargetSelect -6 /*target request*/ #define kComponentUnregisterSelect -7 /*unregister request*/ /*wildcard values for searches*/ #define kAnyComponentType 0 /*any type*/ #define kAnyComponentSubType 0 /*any subtype*/ #define kAnyComponentManufacturer 0 /*any manufacturer*/ #define kAnyComponentFlagsMask 0 /*any flags*/ /*component description flags*/ enum { cmpWantsRegisterMessage = 1L<<31 /*send register request*/ }; /*flags for optional extension to component resource*/ enum { componentDoAutoVersion = 1, /*provide version control*/ componentWantsUnregister = 2, /*send unregister request*/ componentAutoVersionIncludeFlags = 4 /*include flags in search*/ }; enum { /*flags for SetDefaultComponent function*/ defaultComponentIdentical = 0, defaultComponentAnyFlags = 1, defaultComponentAnyManufacturer = 2, defaultComponentAnySubType = 4, }; #define defaultComponentAnyFlagsAnyManufacturer (defaultComponentAnyFlags+defaultComponentAnyManufacturer) #define defaultComponentAnyFlagsAnyManufacturerAnySubType (defaultComponentAnyFlags+defaultComponentAnyManufacturer +defaultComponentAnySubType) enum { /*flags for the global parameter of RegisterComponentResourceFile function*/ registerCmpGlobal = 1, /*other apps can communicate with */ /* component*/ registerCmpNoDuplicates = 2, /*duplicate component exists*/ registerCompAfter = 4 /*component registered after all others */ /* of same type*/ };Data Structures
struct ComponentDescription { OSType componentType; /*type*/ OSType componentSubType; /*subtype*/ OSType componentManufacturer; /*manufacturer*/ unsigned long componentFlags; /*control flags*/ unsigned long componentFlagsMask; /*mask for control flags */ /* (reserved when registering */ /* a component)*/ }; typedef struct ComponentDescription ComponentDescription; struct ResourceSpec { OSType ResType; /*resource type*/ short ResID; /*resource ID*/ }; typedef struct ResourceSpec ResourceSpec; struct ComponentResource { ComponentDescription cd; /*registration information*/ ResourceSpec component; /*code resource*/ ResourceSpec componentName; /*name string resource*/ ResourceSpec componentInfo; /*info string resource*/ ResourceSpec componentIcon; /*icon resource*/ }; typedef struct ComponentResource ComponentResource; typedef ComponentResource *ComponentResourcePtr, **ComponentResourceHandle; /*optional extension to component resource*/ struct ComponentResourceExtension { long componentVersion; /*version number*/ long componentRegisterFlags; /*additional flags*/ short componentIconFamily; /*resource ID of icon family*/ }; typedef struct ComponentResourceExtension ComponentResourceExtension; /*structure received by component*/ struct ComponentParameters { unsigned char flags; /*reserved*/ unsigned char paramSize; /*size in bytes of actual parameters passed */ /* to this routine*/ short what; /*request code, negative for requests */ /* defined by Component Mgr*/ long params[1]; /*actual parameters for the indicated */ /* routine*/ }; typedef struct ComponentParameters ComponentParameters; /*component identifier*/ typedef struct privateComponentRecord *Component; /*component instance*/ typedef struct privateComponentInstanceRecord *ComponentInstance; typedef long ComponentResult; typedef pascal ComponentResult (*ComponentRoutine) (ComponentParameters *cp, Handle componentStorage); typedef pascal ComponentResult (*ComponentFunction)(); #define ComponentCallNow(callNumber, paramSize) \ {0x2F3C, paramSize, callNumber, 0x7000, 0xA82A}Routines for Applications
Finding Components
pascal Component FindNextComponent (Component aComponent, ComponentDescription *looking); pascal long CountComponents (ComponentDescription *looking); pascal long GetComponentListModSeed (void);Opening and Closing Components
pascal ComponentInstance OpenDefaultComponent (OSType componentType, OSType componentSubType); pascal ComponentInstance OpenComponent (Component aComponent); pascal OSErr CloseComponent (ComponentInstance aComponentInstance);Getting Information About Components
pascal OSErr GetComponentInfo (Component aComponent, ComponentDescription *cd, Handle componentName, Handle componentInfo, Handle componentIcon); pascal OSErr GetComponentIconSuite (Component aComponent, Handle *iconSuite); pascal long GetComponentVersion (ComponentInstance ci); pascal long ComponentFunctionImplemented (ComponentInstance ci, short ftnNumber);Retrieving Component Errors
pascal OSErr GetComponentInstanceError (ComponentInstance aComponentInstance);Routines for Components
Registering Components
pascal Component RegisterComponent (ComponentDescription *cd, ComponentRoutine componentEntryPoint, short global, Handle componentName, Handle componentInfo, Handle componentIcon); pascal Component RegisterComponentResource (ComponentResourceHandle cr, short global); pascal long RegisterComponentResourceFile (short resRefNum, short global); pascal OSErr UnregisterComponent (Component aComponent);Dispatching to Component Routines
pascal long CallComponentFunction (ComponentParameters *params, ComponentFunction func); pascal long CallComponentFunctionWithStorage (Handle storage, ComponentParameters *params, ComponentFunction func);Managing Component Connections
pascal void SetComponentInstanceStorage (ComponentInstance aComponentInstance, Handle theStorage); pascal Handle GetComponentInstanceStorage (ComponentInstance aComponentInstance); pascal long CountComponentInstances (Component aComponent); pascal void SetComponentInstanceA5 (ComponentInstance aComponentInstance, long theA5); pascal long GetComponentInstanceA5 (ComponentInstance aComponentInstance);Setting Component Errors
pascal void SetComponentInstanceError (ComponentInstance aComponentInstance, OSErr theError);Working With Component Reference Constants
pascal void SetComponentRefcon (Component aComponent, long theRefcon); pascal long GetComponentRefcon (Component aComponent);Accessing a Component's Resource File
pascal short OpenComponentResFile (Component aComponent); pascal OSErr CloseComponentResFile (short refnum);Calling Other Components
pascal long DelegateComponentCall (ComponentParameters *originalParams, ComponentInstance ci);Capturing Components
pascal Component CaptureComponent (Component capturedComponent, Component capturingComponent); pascal OSErr UncaptureComponent (Component aComponent);Targeting a Component Instance
pascal long ComponentSetTarget (ComponentInstance ci, ComponentInstance target);Changing the Default Search Order
pascal OSErr SetDefaultComponent (Component aComponent, short flags);Application-Defined Routine
pascal ComponentResult MyComponent (ComponentParameters* params, Handle storage);Assembly-Language Summary
Trap Macros
Trap Macros Requiring Routine Selectors
_ComponentDispatch
Selector Routine $7001 RegisterComponent $7002 UnregisterComponent $7003 CountComponents $7004 FindNextComponent $7005 GetComponentInfo $7006 GetComponentListModSeed $7007 OpenComponent $7008 CloseComponent $700A GetComponentInstanceError $700B SetComponentInstanceError $700C GetComponentInstanceStorage $700D SetComponentInstanceStorage $700E GetComponentInstanceA5 $700F SetComponentInstanceA5 $7010 GetComponentRefcon $7011 SetComponentRefcon $7012 RegisterComponentResource $7013 CountComponentInstances $7014 RegisterComponentResourceFile $7015 OpenComponentResFile $7018 CloseComponentResFile $701C CaptureComponent $701D UncaptureComponent $701E SetDefaultComponent $7021 OpenDefaultComponent $7024 DelegateComponentCall $70FF CallComponentFunction $70FF CallComponentFunctionWithStorage Result Codes