Legacy Document

Inside Macintosh: More Macintosh Toolbox /

Chapter 6 - Component Manager / Using the Component Manager

Opening Connections to Components

When your application requires the services of a component, you typically perform these steps:

• open a connection to the desired component
• use the services of the component
• close the connection to the component

The following sections describe each of these steps in more detail.

Opening a Connection to a Default Component

Your application must use the Component Manager to gain access to a component. The first step is to locate an appropriate component. You can locate the component yourself, or you can allow the Component Manager to locate a suitable component for you. Your application then opens a connection to that component. Once you have opened a connection to a component, you can use the services provided by that component. When you have finished using the component, you should close the connection.

If you are interested only in using a component of a particular type-subtype and you do not need to specify any other characteristics of the component, use the OpenDefaultComponent function and specify only the component type and subtype--the Component Manager then selects a component for you and opens a connection to that component. This is the easiest technique for opening a component connection. The OpenDefaultComponent function searches its list of available components and attempts to open a connection to a component with the specified type and subtype.
If more than one component of the specified type and subtype is available, OpenDefaultComponent selects the first one in the list. If successful,
the OpenDefaultComponent function returns a component instance that identifies your connection to the component. You can then use that connection to employ the services of the selected component.

This code demonstrates the use of the OpenDefaultComponent function. The code opens a connection to a component of type 'draw' and subtype 'oval'--a drawing component that draws an oval.

VAR
   aDrawOvalComp: ComponentInstance;

   aDrawOvalComp := OpenDefaultComponent('draw', 'oval');

If it cannot find or open a component of the specified type-subtype, the OpenDefaultComponent function returns a function result of NIL.

To open a connection to a component with a specific type-subtype-manufacturer code or with other specified characteristics, first use the FindNextComponent function to find the desired component, then open the component using the OpenComponent function. These operations are described in the next two sections.

Finding a Specific Component

If you are interested in asserting greater control over the selection of a component, you can use the Component Manager to find a component that provides a specified service. For example, you can use the FindNextComponent function in a loop to retrieve information about all the components that are registered on a given computer. Each time you call this function, the Component Manager returns information about a single component. You can obtain a count of all the components on a given computer by calling the CountComponents function. Both of these functions allow you to specify search criteria, for example, by component type and subtype, or by manufacturer. By using these criteria to narrow your search, you can quickly and easily find a component that meets your needs.

You specify the search criteria for the component using a component description record. A component description record is defined by the ComponentDescription data type. For more information on the fields of this record, see "The Component Description Record" beginning on page 6-36.

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

By default, the Component Manager considers all fields of the component description record when performing a search. Your application can override the default behavior of which fields the Component Manager considers for a search. Specify 0 in any field of the component description record to prevent the Component Manager from considering the information in that field when performing the search.

Listing 6-1 shows an application-defined procedure, MyFindVideoComponent, that fills out a component description record to specify the search criteria for the desired component. The MyFindVideoComponent procedure then uses the FindNextComponent function to return the first component with the specified characteristics--in this example, any component with the type VideoDigitizerComponentType.

Listing 6-1 Finding a component

PROCEDURE MyFindVideoComponent(VAR videoCompID: Component);
VAR 
   videoDesc: ComponentDescription;
BEGIN
   {find a video digitizer component}  
   videoDesc.componentType := VideoDigitizerComponentType;
   videoDesc.componentSubType := OSType(0);     {any subtype}
   videoDesc.componentManufacturer:= OSType(0);{any manufacturer}
   videoDesc.componentFlags := 0;         
   videoDesc.componentFlagsMask := 0;        
   videoCompID := FindNextComponent(Component(0), videoDesc);  
END;

The FindNextComponent function requires two parameters: a value that indicates which component to begin the search with and a component description record. You can specify 0 in the first parameter to start the search at the beginning of the component list. Alternatively, you can specify a component identifier obtained from a previous call to FindNextComponent.

The FindNextComponent function returns a component identifier to your
application. The returned component identifier identifies a given component to the Component Manager. You can use this identifier to retrieve more information about the component or to open a connection to the component. The next two sections describe these tasks.

Opening a Connection to a Specific Component

You can open a connection to a specific component by calling the OpenComponent function (alternatively, you can use the OpenDefaultComponent function, as discussed in "Opening a Connection to a Default Component" on page 6-7). Your application must provide a component identifier to the OpenComponent function. You get a component identifier from the FindNextComponent function, as described in the previous section.

The OpenComponent function returns a component instance that identifies your connection to the component. Listing 6-2 shows how to use the OpenComponent function to gain access to a specific component. The application-defined procedure MyGetComponent uses the MyFindVideoComponent procedure (defined in
Listing 6-1) to find a video digitizer component and then opens the component.

Listing 6-2 Opening a specific component

PROCEDURE MyGetComponent
                     (VAR videoCompInstance: ComponentInstance);
VAR
   videoCompID:         Component;
BEGIN
   {first find a video digitizer component}  
   MyFindVideoComponent(videoCompID);
   {now open it}
   IF videoCompID <> NIL THEN
      videoCompInstance := OpenComponent(videoCompID);
END;