Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 6 - Component Manager / Component Manager Reference

Data Structures for Components

This section describes the format and content of the data structures used by components.

Components, and applications that register components, use the component description record to identify a component. A component resource incorporates the information in a component description record and also includes other information. If you are developing a component or an application that registers components, you must be familiar with both the component description record and component resource; see "Resources" beginning on page 6-77 for a description of the component resource.

The Component Manager passes information about a request to your component in a component parameters record.

The Component Description Record

The component description record identifies the characteristics of a component, including the type of services offered by the component and the manufacturer of the component.

Components use component description records to identify themselves to
the Component Manager. If your component is stored in a component resource, the information in the component description record must be part of that resource (see the description of the component resource, on page 6-77). If you have developed an application that registers your component, that application must supply a component description record to the RegisterComponent function (see "Registering Components" on page 6-55 for information about registering components).

The ComponentDescription data type defines the component description record. Note that the valid values of fields in the component description record are determined by the component type specification. For example, all image compressor components must use the componentSubType field to specify the compression algorithm used by the compressor.

TYPE  ComponentDescription = 
      RECORD
         componentType:       OSType;     {type}
         componentSubType:    OSType;     {subtype}
         componentManufacturer:           {manufacturer}
                              OSType;     
         componentFlags:      LongInt;    {control flags}
         componentFlagsMask:  LongInt;    {reserved}
      END;

Field Description

componentType

A four-character code that identifies the type of component. All components of a particular type must support a common set of interface routines. For example, drawing components all have a component type of 'draw'.

Your component must support all of the standard routines for the component type specified by this field. Type codes with all lowercase characters are reserved for definition by Apple. You can define your own component type code as long as you register it with Apple's Component Registry Group.

componentSubType

A four-character code that identifies the subtype of the component. Different subtypes of a component type may support additional features or provide interfaces that extend beyond the standard routines for a given component. For example, the subtype of a drawing component indicates the type of object the component draws. Drawing components that draw ovals have a subtype of 'oval'.

Your component may use this field to indicate more specific information about the capabilities of the component. There are no restrictions on the content you assign to this field. If no additional information is appropriate for your component type, you may set the componentSubType field to 0.

componentManufacturer

A four-character code that identifies the manufacturer of the component. This field allows for further differentiation between individual components. For example, components made by a specific manufacturer may support an extended feature set. Components provided by Apple use a manufacturer value of 'appl'.

Your component uses this field to indicate the manufacturer of the component. You obtain your manufacturer code, which can be the same as your application signature, from Apple's Component Registry Group.

componentFlags

A 32-bit field that provides additional information about a particular component.

The high-order 8 bits are reserved for definition by the Component Manager and provide information about the component. The following bits are currently defined:

               CONST
                cmpWantsRegisterMessage = $80000000;
                cmpFastDispatch         = $40000000;

The setting of the cmpWantsRegisterMessage bit determines whether the Component Manager calls this component during registration. Set this bit to 1 if your component should be called when it is registered; otherwise, set this bit to 0. If you want to automatically dispatch requests to your component to the appropriate routine that handles the request (rather than your component calling CallComponentFunction or CallComponentFunctionWithStorage), set the cmpFastDispatch bit. If you set this bit, you must write your component's entry point in assembly language. If you set this
bit, the Component Manager calls your component's entry point with the call's parameters, the handle to that instance's storage, and the caller's return address already on the stack. The Component Manager passes the request code in register D0 and passes the stack location of the instance's storage in register A0. Your component can then use the request code in register D0 to directly dispatch the request itself (for example, by using this value as an index into a table of function addresses). Be sure to note that the standard request codes have negative values. Also note that the function parameter that the caller uses to specify the component instance instead contains a handle to the instance's storage. When the component function completes, control returns to the calling application.

For more information about component registration and initialization, see "Responding to the Register Request" on page 6-22.

The low-order 24 bits are specific to each component type. You can use these flags to indicate any special capabilities or features of your component. Your component may use all 24 bits, as appropriate to its component type. You must set all unused bits to 0.

componentFlagsMask

Reserved. (However, note that applications can use this field when performing search operations, as described on page 6-37.)

Your component must set the componentFlagsMask field in its component description record to 0.

The Component Parameters Record

The Component Manager uses the component parameters record to pass information to your component about a request from an application. The information in this record completely defines the request. Your component services the request as appropriate.

The ComponentParameters data type defines the component parameters record.

ComponentParameters = 
      PACKED RECORD
         flags:      Char;                   {reserved}
         paramSize:  Char;                   {size of parameters}
         what:       Integer;                {request code}
         params:     ARRAY[0..0] OF LongInt; {actual parameters}
      END;

Field Description

flags

Reserved for use by Apple.

paramSize

Specifies the number of bytes of parameter data for this request. The actual parameters are stored in the params field.

what

Specifies the type of request. Component designers define the meaning of positive values and assign them to requests that are supported by components of a given type. Negative values are reserved for definition by Apple. Apple has defined these request codes:

               CONST
                  kComponentOpenSelect       = -1; {required}
                  kComponentCloseSelect      = -2; {required}
                  kComponentCanDoSelect      = -3; {required}
                  kComponentVersionSelect    = -4; {required}
                  kComponentRegisterSelect   = -5; {optional}
                  kComponentTargetSelect     = -6; {optional}
                  kComponentUnregisterSelect = -7; {optional}

params

An array that contains the parameters specified by the
application that called your component.
You can use the CallComponentFunction or CallComponentFunctionWithStorage routine to convert this array into a Pascal-style invocation of a subroutine in your component.

For information on how your component responds to requests, see "Handling Requests for Service" beginning on page 6-18.