Important: The information in this document is obsolete and should not be used for new development.
Opening Connections to Components
When your application requires the services of a component, you typically perform these steps:
The following sections describe each of these steps in more detail.
- open a connection to the desired component
- use the services of the component
- close the connection to the component
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. TheOpenDefaultComponent
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,
theOpenDefaultComponent
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, theOpenDefaultComponent
function returns a function result ofNIL
.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 theOpenComponent
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 theFindNextComponent
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 theCountComponents
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. TheMyFindVideoComponent
procedure then uses theFindNextComponent
function to return the first component with the specified characteristics--in this example, any component with the typeVideoDigitizerComponentType
.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;TheFindNextComponent
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 toFindNextComponent
.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 theOpenComponent
function (alternatively, you can use theOpenDefaultComponent
function, as discussed in "Opening a Connection to a Default Component" on page 6-7). Your application must provide a component identifier to theOpenComponent
function. You get a component identifier from theFindNextComponent
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 theOpenComponent
function to gain access to a specific component. The application-defined procedureMyGetComponent
uses theMyFindVideoComponent
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;