Inside Macintosh: More Macintosh Toolbox /

Chapter 6 - Component Manager

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 Instance

FUNCTION 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

noErr	0	No error
resFNotFound	-193	Resource file not found
invalidComponentID	-3000	No component has this component identifier
validInstancesExist	-3001	This component has open connections
componentNotCaptured	-3002	This component has not been captured
badComponentInstance	$800008001	Invalid component passed to Component Manager
badComponentSelector	$800008002	Component does not support the specified request code