Apple Developer Connection
Member Login Log In | Not a Member? Contact ADC

Next Page > Hide TOC

Component Manager Reference

Framework
CoreServices/CoreServices.h
Declared in
Components.h

Overview

You can use the Component Manager to allow your application to find and utilize various software objects (components) at run time. You can create your own components, and you can use the Component Manager to help manage your components. A component is a piece of code that provides a defined set of services to one or more clients. Applications, system extensions, as well as other components can use the services of a component. A component typically provides a specific type of service to its clients. For example, a component might provide image compression or image decompression capabilities; an application could call such a component, providing the image to compress, and the component could perform the desired operation and return the compressed image to the application. The Component Manager provides access to components and manages them by, for example, keeping track of the currently available components and routing requests to the appropriate component.

Functions by Task

Finding Components

Opening and Closing Components

Getting Information About Components

Retrieving Component Errors

Calling Component Functions

Accessing the Thread Safety Mode

Creating and Managing Universal Procedure Pointers

Registering Components

Dispatching to Component Functions

Managing Component Connections

Setting Component Errors

Working With Component Reference Constants

Accessing a Component’s Resource File

Calling Other Components

Capturing Components

Changing the Default Search Order

Functions

CallComponentCanDo

ComponentResult CallComponentCanDo (
   ComponentInstance ci,
   SInt16 ftnNumber
);

Parameters
ci
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentClose

ComponentResult CallComponentClose (
   ComponentInstance ci,
   ComponentInstance self
);

Parameters
ci
self
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentDispatch

ComponentResult CallComponentDispatch (
   ComponentParameters *cp
);

Parameters
cp
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentFunction

Invokes the specified function of your component.

ComponentResult CallComponentFunction (
   ComponentParameters *params,
   ComponentFunctionUPP func
);

Parameters
params

A pointer to the ComponentDescription structure that your component received from the Component Manager. These are the parameters originally provided by the application that called your component.

func

A universal procedure pointer to the component function that is to handle the request. The Component Manager calls the function referred to by the func parameter, using Pascal calling conventions, with the parameters that were originally provided by the application that called your component. The function referred to by this parameter must return a function result of type ComponentResult indicating the success or failure of the operation. See the ComponentRoutineProcPtr callback for more information on component functions.

Return Value

The value that is returned by the function referred to by the func parameter. Your component should use this value to set the current error for this connection. You can use the SetComponentInstanceError function to set the current error.

Discussion

When an application requests service from your component, your component receives a component parameters structure containing the parameters that the application provided when it called your component. Your component can use this structure to access the parameters directly. Alternatively, you can use either this function or CallComponentFunctionWithStorage to extract those parameters and pass them to a subroutine of your component. By taking advantage of these functions, you can simplify the structure of your component code.

If your component subroutine does not need global data, your component should use this function. If your component subroutine requires memory in which to store global data for the component, your component must use CallComponentFunctionWithStorage.

Availability
Declared In
Components.h

CallComponentFunctionWithStorage

Invokes the specified function of your component. 

ComponentResult CallComponentFunctionWithStorage (
   Handle storage,
   ComponentParameters *params,
   ComponentFunctionUPP func
);

Parameters
storage

A handle to the memory associated with the current connection. The Component Manager provides this handle to your component along with the request.

params

A pointer to the ComponentParameters structure that your component received from the Component Manager. These are the parameters originally provided by the application that called your component.

func

A universal procedure pointer to the component function that is to handle the request. The Component Manager calls the function referred to by the func parameter, using Pascal calling conventions, with the parameters that were originally provided by the application that called your component. These parameters are preceded by a handle to the memory associated with the current connection. The function referred to by the func parameter must return a function result of type ComponentResult indicating the success or failure of the operation. See the ComponentRoutineProcPtr callback for more information on component functions.

Return Value

The value that is returned by the function referred to by the func parameter. Your component should use this value to set the current error for this connection. Use the SetComponentInstanceError function to set the current error for a connection.

Discussion

When an application requests service from your component, your component receives a component parameters structure containing the parameters that the application provided when it called your component. Your component can use this structure to access the parameters directly. Alternatively, you can use either the CallComponentFunction function or this function to extract those parameters and pass them to a subroutine of your component. By taking advantage of these functions, you can simplify the structure of your component code.

If your component subroutine requires a handle to the memory associated with the connection, you must use this function. You allocate the memory for a given connection each time your component is opened. You inform the Component Manager that a connection has memory associated with it by calling the SetComponentInstanceError function.

Subroutines of a component that don’t need global data should use CallComponentFunction instead.

Availability
Declared In
Components.h

CallComponentFunctionWithStorageProcInfo

ComponentResult CallComponentFunctionWithStorageProcInfo (
   Handle storage,
   ComponentParameters *params,
   ProcPtr func,
   ProcInfoType funcProcInfo
);

Parameters
storage
params
funcProcInfo
Availability
Declared In
Components.h

CallComponentGetMPWorkFunction

ComponentResult CallComponentGetMPWorkFunction (
   ComponentInstance ci,
   ComponentMPWorkFunctionUPP *workFunction,
   void **refCon
);

Parameters
ci
workFunction
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentGetPublicResource

ComponentResult CallComponentGetPublicResource (
   ComponentInstance ci,
   OSType resourceType,
   SInt16 resourceID,
   Handle *resource
);

Parameters
ci
resourceType
resource
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentOpen

ComponentResult CallComponentOpen (
   ComponentInstance ci,
   ComponentInstance self
);

Parameters
ci
self
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentRegister

ComponentResult CallComponentRegister (
   ComponentInstance ci
);

Parameters
ci
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentTarget

ComponentResult CallComponentTarget (
   ComponentInstance ci,
   ComponentInstance target
);

Parameters
ci
target
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentUnregister

ComponentResult CallComponentUnregister (
   ComponentInstance ci
);

Parameters
ci
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CallComponentVersion

ComponentResult CallComponentVersion (
   ComponentInstance ci
);

Parameters
ci
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

CaptureComponent

Allows your component to capture another component. 

Component CaptureComponent (
   Component capturedComponent,
   Component capturingComponent
);

Parameters
capturedComponent

The component to be captured. Your component can obtain this identifier from the FindNextComponent function or from the component registration functions. You can use a component instance here, but you must coerce the data type appropriately.

capturingComponent

Your component. Note that you can use the component instance (appropriately coerced) that your component received in its open request in this parameter.

Return Value

A new component identifier. Your component can use this new identifier to refer to the captured component. For example, your component can open the captured component by providing this identifier to the OpenComponent structure. Your component must provide this identifier to the UncaptureComponent function to specify the component to be restored to the search list. If the component you wish to capture is already captured, the component identifier is set to NULL. See the description of the Component data type.

Discussion

Typically, your component captures another component when you want to override all or some of the features provided by a component or to provide new features. For example, a component called NewMath might capture a component called OldMath. Suppose the NewMath component provides a new function, DoExponent. Whenever NewMath gets an exponent request, it can handle the request itself. For all other requests, NewMath might call the OldMath component to perform the request.

After capturing a component, your component might choose to target a particular instance of the captured component.

In response to this function, the Component Manager removes the specified component from the list of available components. As a result, applications cannot retrieve information about the captured component or gain access to it. Current clients of the captured component are not affected by this function.

Availability
Declared In
Components.h

CloseComponent

Terminates your application’s connection to a component. 

OSErr CloseComponent (
   ComponentInstance aComponentInstance
);

Parameters
aComponentInstance

The connection you wish to close. Your application obtains the component instance from the OpenComponent function or the OpenDefaultComponent function. You can use a component identifier here, but you must coerce the data type appropriately.

Return Value

A result code. See “Component Manager Result Codes.”

Discussion

This function closes only a single connection. If your application has several connections to a single component, you must call it once for each connection.

Availability
Declared In
Components.h

CloseComponentResFile

Closes the resource file that your component opened previously with the OpenComponentResFile function. 

OSErr CloseComponentResFile (
   ResFileRefNum refnum
);

Parameters
refnum

The reference number that identifies the resource file to be closed. Your component obtains this value from the OpenComponentResFile function. Your component must close any open resource files before returning to the calling application.

Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

CountComponentInstances

Determines the number of open connections being managed by a specified component. 

long CountComponentInstances (
   Component aComponent
);

Parameters
aComponent

The component for which you want a count of open connections. You can use a component instance here, but you must coerce the data type appropriately.

Return Value

The number of open connections for the specified component.

Discussion

This function can be useful if you want to restrict the number of connections for your component or if your component needs to perform special processing based on the number of open connections.

Availability
Declared In
Components.h

CountComponents

Returns the number of registered components that meet the selection criteria specified by your application. 

long CountComponents (
   ComponentDescription *looking
);

Parameters
looking

A pointer to a ComponentDescription structure. Your application specifies the criteria for the component search in the fields of this structure.

The Component Manager ignores fields in the component description structure that are set to 0. For example, if you set all the fields to 0, the Component Manager returns the number of components registered in the system. Similarly, if you set all fields to 0 except for the componentManufacturer field, the Component Manager returns the number of registered components supplied by the manufacturer you specify.

Return Value

The number of components that meet the specified search criteria.

Availability
Declared In
Components.h

CSGetComponentsThreadMode

Indicates whether using thread-unsafe components is allowed in the current thread. 

CSComponentsThreadMode CSGetComponentsThreadMode (
   void
);

Return Value

A flag that indicates whether using thread-unsafe components is allowed in the current thread.

Availability
Declared In
Components.h

CSSetComponentsThreadMode

Sets whether or not using thread-unsafe components is allowed in the current thread. 

void CSSetComponentsThreadMode (
   CSComponentsThreadMode mode
);

Parameters
mode

A flag that determines whether the current thread is restricted to calling components that are thread-safe. You should set this flag to kCSAcceptThreadSafeComponentsOnlyMode whenever you want the current thread to call only components that are thread-safe.

Discussion

Core Services maintains a component thread-mode flag for each thread in the current process. The default value of this flag is kCSAcceptAllComponentsMode, which means the thread can call any component regardless of whether the component is thread-safe. Applications and other high-level code that call component-based APIs (such as QuickTime) from preemptive threads should call this function from their thread beforehand and pass in the value kCSAcceptThreadSafeComponentsOnlyMode.

A thread’s component thread-mode flag can safely retain its default value only if the thread is the main thread or if it participates in cooperative locking, such as Carbon Thread Manager-style cooperative threads and application threads that perform their own private locking.

Availability
Declared In
Components.h

DelegateComponentCall

Allows your component to pass on a request to a specified component. 

ComponentResult DelegateComponentCall (
   ComponentParameters *originalParams,
   ComponentInstance ci
);

Parameters
originalParams

A pointer to the ComponentParameters structure provided to your component by the Component Manager.

ci

The component instance that is to process the request. The Component Manager provides a component instance to your component when it opens a connection to another component with the OpenComponent or OpenDefaultComponent function. You must specify a component instance; this function does not accept a component identifier.

Return Value

The component result returned by the specified component.

Discussion

Your component may supplement its capabilities by using the services of another component to directly satisfy application requests using this function. For example, you might want to create two similar components that provide different levels of service to applications. Rather than completely implementing both components, you could design one to rely on the capabilities of the other. In this manner, you have to implement only that portion of the more capable component that provides additional services.

You may also invoke the services of another component using the standard mechanisms used by applications. The Component Manager then passes the requests to the appropriate component, and your component receives the results of those requests.

Your component must open a connection to the component to which the requests are to be passed. Your component must close that connection when it has finished using the services of the other component.

Your component should never use this function with open or close requests from the Component Manager—always use the OpenComponent and CloseComponent functions to manage connections with other components.

Availability
Declared In
Components.h

DisposeComponentFunctionUPP

void DisposeComponentFunctionUPP (
   ComponentFunctionUPP userUPP
);

Parameters
userUPP
Availability
Declared In
Components.h

DisposeComponentMPWorkFunctionUPP

void DisposeComponentMPWorkFunctionUPP (
   ComponentMPWorkFunctionUPP userUPP
);

Parameters
userUPP
Availability
Declared In
Components.h

DisposeComponentRoutineUPP

Disposes of the universal procedure pointer (UPP) to a component routine callback function.

void DisposeComponentRoutineUPP (
   ComponentRoutineUPP userUPP
);

Parameters
userUPP
Discussion

See the ComponentRoutineProcPtr callback for more information.

Availability
Declared In
Components.h

DisposeGetMissingComponentResourceUPP

void DisposeGetMissingComponentResourceUPP (
   GetMissingComponentResourceUPP userUPP
);

Parameters
userUPP
Availability
Declared In
Components.h

FindNextComponent

Returns the component identifier for the next registered component that meets the selection criteria specified by your application. 

Component FindNextComponent (
   Component aComponent,
   ComponentDescription *looking
);

Parameters
aComponent

The starting point for the search. Set this field to 0 to start the search at the beginning of the component list. If you are continuing a search, you can specify a component identifier previously returned by this function. The function then searches the remaining components.

looking

A pointer to a ComponentDescription structure. Your application specifies the criteria for the component search in the fields of this structure.

The Component Manager ignores fields in the component description structure that are set to 0. For example, if you set all the fields to 0, all components meet the search criteria. In this case, your application can retrieve information about all of the components that are registered in the system by repeatedly calling FindNextComponent and GetComponentInfo until the search is complete. Similarly, if you set all fields to 0 except for the componentManufacturer field, the Component Manager searches all registered components for a component supplied by the manufacturer you specify. Note that this function does not modify the contents of the component description structure you supply. To retrieve detailed information about a component, you need to use the GetComponentInfo function to get the component description structure for each returned component.

Return Value

The component identifier of a component that meets the search criteria or 0 when there are no more matching components. Your application can use the component identifier returned by this function to get more information about the component, using GetComponentInfo, or to open the component, using either the OpenDefaultComponent function or the OpenComponent function. See the description of the Component data type.

Availability
Declared In
Components.h

GetComponentIconSuite

Returns a handle to a component’s icon suite to your application.

OSErr GetComponentIconSuite (
   Component aComponent,
   Handle *iconSuite
);

Parameters
aComponent

The component whose icon suite you wish to obtain. Your application obtains a component identifier from the FindNextComponent function. If your application registers a component, it can also obtain a component identifier from the RegisterComponent or RegisterComponentResource function. You can use a component instance here, but you must coerce the data type appropriately.

iconSuite

On return, a pointer to a handle for the component’s icon suite or, if the component has not provided an icon suite, NULL. A component provides the resource ID of its icon family to the Component Manager in the optional extensions to the component resource. Your application is responsible for disposing of the returned icon suite handle.

Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

GetComponentIndString

OSErr GetComponentIndString (
   Component aComponent,
   Str255 theString,
   SInt16 strListID,
   SInt16 index
);

Parameters
aComponent
theString
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

GetComponentInfo

Returns to your application the registration information for a component. 

OSErr GetComponentInfo (
   Component aComponent,
   ComponentDescription *cd,
   Handle componentName,
   Handle componentInfo,
   Handle componentIcon
);

Parameters
aComponent

The component about which you wish to obtain information. Your application obtains a component identifier from the FindNextComponent function. If your application registers a component, it can also obtain a component identifier from the RegisterComponent or RegisterComponentResource function.

You may supply a component instance rather than a component identifier to this function, but you must coerce the data type appropriately. Your application can obtain a component instance from the OpenComponent or OpenDefaultComponent functions.

cd

A pointer to a ComponentDescription structure. The function returns information about the specified component in this structure.

componentName

On return, a handle to the component’s name. If the component does not have a name, an empty handle. Set this field to NULL if you do not want to receive the component’s name.

componentInfo

On return, a handle to the component’s information string. If the component does not have an information string, an empty handle. Set this field to NULL if you do not want to receive the component’s information string.

componentIcon

On return, a handle to the component’s icon. If the component does not have an icon, an empty handle. Set this field to NULL if you do not want to receive the component’s icon. To get a handle to the component’s icon suite, if it provides one, use the GetComponentIconSuite function.

Return Value

A result code. See “Component Manager Result Codes.”

Discussion

For information on registering components, see “Registering Components”.

Availability
Declared In
Components.h

GetComponentInstanceError

Returns to your application the last error generated by a specific connection to a component.

OSErr GetComponentInstanceError (
   ComponentInstance aComponentInstance
);

Parameters
aComponentInstance

The component instance from which you want error information. Your application obtains the component instance from the OpenDefaultComponent function or the OpenComponent function. You can use a component identifier here, but you must coerce the data type appropriately.

Return Value

A result code. See “Component Manager Result Codes.”

Discussion

Some component functions return error information as their function result. Other component functions set an error code that your application can retrieve using this function. Refer to the documentation supplied with the component for information on how that particular component handles errors.

Once you have retrieved an error code, the Component Manager clears the error code for the connection. If you want to retain that error value, you should save it in your application’s local storage.

Availability
Declared In
Components.h

GetComponentInstanceStorage

Allows your component to retrieve a handle to the memory associated with a connection. 

Handle GetComponentInstanceStorage (
   ComponentInstance aComponentInstance
);

Parameters
aComponentInstance

The connection for which to retrieve the associated memory. The Component Manager provides a component instance to your component when the connection is opened. You can use a component identifier here, but you must coerce the data type appropriately.

Return Value

A handle to the memory associated with the specified connection.

Discussion

Typically, your component does not need to use this function, because the Component Manager provides this handle to your component each time the client application requests service from this connection.

Your component tells the Component Manager about the memory associated with a connection by calling the SetComponentInstanceStorage function.

Availability
Declared In
Components.h

GetComponentListModSeed

Allows your application to determine if the list of registered components has changed. 

SInt32 GetComponentListModSeed (
   void
);

Parameters
Return Value

The component registration seed number. Each time the Component Manager registers or unregisters a component it generates a new, unique seed number. By comparing the return value to values previously returned by this function, you can determine whether the list has changed. Your application may use this information to rebuild its internal component lists or to trigger other activity that is necessary whenever new components are available.

Availability
Declared In
Components.h

GetComponentPublicIndString

OSErr GetComponentPublicIndString (
   Component aComponent,
   Str255 theString,
   SInt16 strListID,
   SInt16 index
);

Parameters
aComponent
theString
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

GetComponentPublicResource

OSErr GetComponentPublicResource (
   Component aComponent,
   OSType resourceType,
   SInt16 resourceID,
   Handle *theResource
);

Parameters
aComponent
resourceType
theResource
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

GetComponentPublicResourceList

OSErr GetComponentPublicResourceList (
   OSType resourceType,
   SInt16 resourceID,
   SInt32 flags,
   ComponentDescription *cd,
   GetMissingComponentResourceUPP missingProc,
   void *refCon,
   void *atomContainerPtr
);

Parameters
resourceType
cd
missingProc
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

GetComponentRefcon

Retrieves the value of the reference constant for your component. 

long GetComponentRefcon (
   Component aComponent
);

Parameters
aComponent

The component whose reference constant you wish to get. You can use a component instance here, but you must coerce the data type appropriately.

Return Value

The reference constant for the specified component.

Discussion

There is one reference constant for each component, regardless of the number of connections to that component. When your component is registered, the Component Manager sets this reference constant to 0.

The reference constant is a 4-byte value that your component can use in any way you decide. For example, you might use the reference constant to store the address of a data structure that is shared by all connections maintained by your component. You should allocate shared structures in the system heap. Your component should deallocate the structure when its last connection is closed or when it is unregistered.

Availability
Declared In
Components.h

GetComponentResource

OSErr GetComponentResource (
   Component aComponent,
   OSType resType,
   SInt16 resID,
   Handle *theResource
);

Parameters
aComponent
resType
theResource
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

GetComponentTypeModSeed

SInt32 GetComponentTypeModSeed (
   OSType componentType
);

Parameters
componentType
Availability
Declared In
Components.h

InvokeComponentMPWorkFunctionUPP

ComponentResult InvokeComponentMPWorkFunctionUPP (
   void *globalRefCon,
   ComponentMPWorkFunctionHeaderRecordPtr header,
   ComponentMPWorkFunctionUPP userUPP
);

Parameters
header
userUPP
Return Value

See the description of the ComponentResult data type.

Availability
Declared In
Components.h

InvokeComponentRoutineUPP

Calls your component routine callback function

ComponentResult InvokeComponentRoutineUPP (
   ComponentParameters *cp,
   Handle componentStorage,
   ComponentRoutineUPP userUPP
);

Parameters
cp
componentStorage
userUPP
Return Value

See the description of the ComponentResult data type.

Discussion

See the ComponentRoutineProcPtr callback for more information.

Availability
Declared In
Components.h

InvokeGetMissingComponentResourceUPP

OSErr InvokeGetMissingComponentResourceUPP (
   Component c,
   OSType resType,
   SInt16 resID,
   void *refCon,
   Handle *resource,
   GetMissingComponentResourceUPP userUPP
);

Parameters
c
resType
resource
userUPP
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

NewComponentFunctionUPP

ComponentFunctionUPP NewComponentFunctionUPP (
   ProcPtr userRoutine,
   ProcInfoType procInfo
);

Parameters
procInfo
Return Value

See the description of the ComponentFunctionUPP data type.

Availability
Declared In
Components.h

NewComponentMPWorkFunctionUPP

ComponentMPWorkFunctionUPP NewComponentMPWorkFunctionUPP (
   ComponentMPWorkFunctionProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the ComponentMPWorkFunctionUPP data type.

Availability
Declared In
Components.h

NewComponentRoutineUPP

Creates a new universal procedure pointer (UPP) to a component routine callback function.

ComponentRoutineUPP NewComponentRoutineUPP (
   ComponentRoutineProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the ComponentRoutineUPP data type.

Discussion

See the ComponentRoutineProcPtr callback for more information.

Availability
Declared In
Components.h

NewGetMissingComponentResourceUPP

GetMissingComponentResourceUPP NewGetMissingComponentResourceUPP (
   GetMissingComponentResourceProcPtr userRoutine
);

Parameters
userRoutine
Return Value

See the description of the GetMissingComponentResourceUPP data type.

Availability
Declared In
Components.h

OpenAComponent

OSErr OpenAComponent (
   Component aComponent,
   ComponentInstance *ci
);

Parameters
aComponent
ci
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

OpenAComponentResFile

OSErr OpenAComponentResFile (
   Component aComponent,
   ResFileRefNum *resRef
);

Parameters
aComponent
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

OpenADefaultComponent

OSErr OpenADefaultComponent (
   OSType componentType,
   OSType componentSubType,
   ComponentInstance *ci
);

Parameters
componentType
componentSubType
ci
Return Value

A result code. See “Component Manager Result Codes.”

Availability
Declared In
Components.h

OpenComponent

Opens a connection to the component with the component identifier specified by your application.

ComponentInstance OpenComponent (
   Component aComponent
);

Parameters
aComponent

The component you wish to open. Your application obtains this identifier from the FindNextComponent function. If your application registers a component, it can also obtain a component identifier from the RegisterComponent function or the RegisterComponentResource function.

Return Value

A component instance which identifies your application’s connection to the component. You must supply this component instance whenever you call the functions provided by the component. When you close the component, you must also supply this component instance to the CloseComponent function.

If it cannot open the specified component, the function returns NULL.

See the description of the ComponentInstance data type.

Discussion

Your application must open a component before it can call any component functions. To use this function, you must already have obtained a component identifier. Alternatively, you can use the OpenDefaultComponent function to open a component without calling FindNextComponent.

Note that your application may maintain several connections to a single component, or it may have connections to several components at the same time.

Availability
Declared In
Components.h

OpenComponentResFile

Allows your component to gain access to its resource file. 

ResFileRefNum OpenComponentResFile (
   Component aComponent
);

Parameters
aComponent

The component whose resource file you wish to open. Applications that register components may obtain this identifier from the RegisterComponentResource function. You can use a component instance here, but you must coerce the data type appropriately.

Return Value

A reference number that your component can use to read data from the appropriate resource file. If the specified component does not have an associated resource file or if the Component Manager cannot open the resource file, the function returns 0 or a negative number.

Discussion

This function opens the resource file with read-only permission. The Component Manager adds the resource file to the current resource chain. Your component must close the resource file with the CloseComponentResFile function before returning to the calling application. Note that there is only one resource file associated with a component.

Your component can use FSpOpenResFile or equivalent Resource Manager functions to open other resource files, but you must use this function to open your component’s resource file.

If you store your component in a component resource but register the component with the RegisterComponent function, rather than with the RegisterComponentResource or RegisterComponentResourceFile function, your component cannot access its resource file with this function.

Note that when working with resources, your component should always first save the current resource file, perform any resource operations, then restore the current resource file to its previous value before returning.

Availability
Declared In
Components.h

OpenDefaultComponent

Opens a connection to a registered component of the component type and subtype specified by your application. 

ComponentInstance OpenDefaultComponent (
   OSType componentType,
   OSType componentSubType
);

Parameters
componentType

The type of the component. All components of a particular type support a common set of interface functions. Use this parameter to search for components of a given type.

componentSubType

The subtype of the component. Different subtypes of a component type may support additional features or provide interfaces that extend beyond the standard functions for a given component type. For example, the subtype of an image compressor component indicates the compression algorithm employed by the compressor.

Your application can use the componentSubType parameter to perform a more specific lookup operation than is possible using only the componentType parameter. For example, you may want your application to use only components of a certain component type ('draw') that also have a specific subtype ('oval'). Set this parameter to 0 to select a component with any subtype value.

Return Value

A component instance that identifies the connection opened to the component which matches your search criteria. You must supply this component instance whenever you call the functions provided by the component. When you close the component, you must also supply this component instance to the CloseComponent function.

If more than one component in the list of registered components meets the search criteria, the function opens the first one that it finds in its list. If it cannot open the specified component, it returns NULL.

See the description of the ComponentInstance data type.

Discussion

Your application must open a component before it can call any component functions. This function searches for a component by type and subtype. You do not have to supply a component description structure or call the FindNextComponent function to use this function. If you want to exert more control over the selection process, you can use the FindNextComponent and OpenComponent functions.

Availability
Declared In
Components.h

RegisterComponent

Registers a component stored in memory.

Component RegisterComponent (
   ComponentDescription *cd,
   ComponentRoutineUPP componentEntryPoint,
   SInt16 global,
   Handle componentName,
   Handle componentInfo,
   Handle componentIcon
);

Parameters
cd

A pointer to a ComponentDescription structure that describes the component to be registered. You must correctly fill in the fields of this structure before calling this function. When applications search for components using the FindNextComponent function, the Component Manager compares the attributes you specify here with those specified by the application. If the attributes match, the Component Manager returns the component identifier to the application.

componentEntryPoint

A universal procedure pointer (UPP) to your component’s main entry point. The function referred to by this parameter receives all requests for the component. See the ComponentRoutineProcPtr callback for more information on creating a component function.

global

A set of flags that control the scope of component registration. See Register Component Resource flags for a description of the flags.

componentName

A handle to the component’s name. Set this parameter to NULL if you do not want to assign a name to the component.

componentInfo

A handle to the component’s information string. Set this parameter to NULL if you do not want to assign an information string to the component.

componentIcon

A handle to the component’s icon (a 32-by-32 pixel black-and-white icon). Set this parameter to NULL if you do not want to supply an icon for this component. Note that this icon is not used by the Finder you supply an icon only so that other components or applications can display your component’s icon if needed.

Return Value

The unique component identifier assigned to the component by the Component Manager or, if it cannot register the component, NULL. See the description of the Component data type.

Discussion

Before a component can be used by an application, the component must be registered with the Component Manager. Applications can then find and open the component using the standard Component Manager functions.

Components you register with the RegisterComponent function must be in memory when you call this function. If you want to register a component that is stored in the resource fork of a file, use the RegisterComponentResource function. Use the RegisterComponentResourceFile function to register all components in the resource fork of a file. The Component Manager automatically registers component resources stored in files with file types of 'thng' that are stored in the Extensions folder. See “Resources” for more information on component resource files.

Note that a component residing in your application heap remains registered until your application unregisters it or quits. When an application quits, the Component Manager automatically closes any component connections to that application. In addition, if the application has registered components that reside in its heap space, the Component Manager automatically unregisters those components. A component residing in the system heap and registered by your application remains registered until your application unregisters it or until the computer is shut down.

Availability
Declared In
Components.h

RegisterComponentFileRef