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

Callbacks

ComponentMPWorkFunctionProcPtr

typedef ComponentResult (*ComponentMPWorkFunctionProcPtr) (
   void * globalRefCon,
   ComponentMPWorkFunctionHeaderRecordPtr header
);

If you name your function MyComponentMPWorkFunctionProc, you would declare it like this:

ComponentResult MyComponentMPWorkFunctionProc (
   void * globalRefCon,
   ComponentMPWorkFunctionHeaderRecordPtr header
);

Parameters

header

Return Value

See the description of the ComponentResult data type.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentRoutineProcPtr

Defines a pointer to your component callback function, which serves as the main entry point into your component and performs the component’s services.

typedef ComponentResult (*ComponentRoutineProcPtr) (
   ComponentParameters * cp,
   Handle componentStorage
);

If you name your function MyComponentRoutineProc, you would declare it like this:

ComponentResult ComponentRoutineProcPtr (
   ComponentParameters * cp,
   Handle componentStorage
);

Parameters

cp: A ComponentParameters structure. The what field of the component parameters structure indicates the action your component should perform. The parameters that the client invoked your function with are contained in the params field of the component parameters structure. Your component can use the CallComponentFunction or CallComponentFunctionWithStorage function to extract the parameters from this structure.
componentStorage: A handle to any memory that your component has associated with the connection. Typically, upon receiving an open request, your component allocates memory and uses the SetComponentInstanceStorage function to associate the allocated memory with the component connection.

Return Value

Your component should return a value of type ComponentResult. If your component does not return error information as its function result, it should indicate errors using the SetComponentInstanceError function. See the description of the ComponentResult data type.

Discussion

You pass a pointer to your component callback function to the Component Manager when you register your component. The Component Manager can then call your component when another application or component requests its services. When your component receives a request, it should perform the action specified in the what field of the component parameters structure.

The pointer which you pass to the Component Manager should be a universal procedure pointer (UPP). The definition of the UPP data type for your component function is as follows:

typedef (ComponentRoutineProcPtr) ComponentRoutineUPP;

Before using your component function, you must first create a UPP for your callback function, using the NewComponentRoutineUPP function, as shown here:

ComponentRoutineUPP MyComponentRoutineUPP;

MyComponentRoutineUPP =             NewComponentRoutineUPP(&MyComponentRoutineProc)

You then pass MyComponentRoutineUPP to the Component Manager when you register your component. The Component Manager will call your function each time your component receives a request. If you wish to call your component function yourself, you can use the InvokeComponentRoutineUPP function.

result = InvokeComponentRoutineUPP &myParams, myStorage,              MyComponentRoutineUPP)

When you are finished with your component callback function, you should dispose of the universal procedure pointer associated with it, using the DisposeComponentRoutineUPP function.

DisposeComponentRoutineUPP(MyComponentRoutineUPP);

To provide a component, you define a component function and supply the appropriate registration information. You store your component function in a code resource and typically store your component’s registration information as resources in a component file.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

GetMissingComponentResourceProcPtr

typedef OSErr (*GetMissingComponentResourceProcPtr) (
   Component c,
   OSType resType,
   short resID,
   void * refCon,
   Handle * resource
);

If you name your function MyGetMissingComponentResourceProc, you would declare it like this:

OSErr GetMissingComponentResourceProcPtr (
   Component c,
   OSType resType,
   short resID,
   void * refCon,
   Handle * resource
);

Parameters

c
resType
resource

Return Value

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

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

Data Types

ComponentAliasResource

struct ComponentAliasResource {
   ComponentResource cr;
   ComponentDescription aliasCD;
};
typedef struct ComponentAliasResource ComponentAliasResource;

Fields

cr
aliasCD

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentDependencyArray

struct ComponentDependencyArray {
   SInt32 count;
   ComponentDescription descArray[1];
};

Fields

count
descArray

ComponentDescription

struct ComponentDescription {
   OSType componentType;
   OSType componentSubType;
   OSType componentManufacturer;
   unsigned long componentFlags;
   unsigned long componentFlagsMask;
};
typedef struct ComponentDescription ComponentDescription;

Fields

componentType

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

If you are developing an application which uses components, you can use this field to search for components of a given type by specifying the component type in this field of the component description structure you supply to the FindNextComponent function or the CountComponents function. A value of 0 operates as a wildcard.

If you are developing a component, it must support all of the standard functions 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 functions for a given component type. For example, the subtype of drawing components indicates the type of object the component draws. Drawing components that draw ovals have a subtype of 'oval'.

If you are developing an application which uses components, you can use the componentSubType field to perform a more specific lookup operation than is possible using only the componentType field. By specifying particular values for both fields in the component description structure that you supply to the FindNextComponent or CountComponents function, your application retrieves information about only those components that meet both of these search criteria. A value of 0 operates as a wildcard.

If you are developing a component, you 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'.

If you are developing an application which uses components, you can use this field to find components from a certain manufacturer. Specify the appropriate manufacturer code in this field of the component description structure you supply to the FindNextComponent or CountComponents function. A value of 0 operates as a wildcard.

If you are developing a 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. If you are developing an application, you should usually set these bits to 0.

The low-order 24 bits are specific to each component type. These flags can be used to indicate the presence of features or capabilities in a given component.

If you are developing an application which uses components, you can use these flags to further narrow the search criteria applied by the FindNextComponent or CountComponents function. If you use the componentFlags field in a component search, you use the componentFlagsMask field to indicate which flags are to be considered in the search.

If you are developing a component, you can use these flags to indicate any special capabilities or features of your component. You may use all 24 bits, as appropriate to its component type. You must set all unused bits to 0.

componentFlagsMask

A 32-bit field that indicates which flags in the componentFlags field are relevant to a particular component search operation.

If you are developing an application which uses components, your application should set each bit which corresponds to a flag in the componentFlags field that is to be considered as a search criterion by the FindNextComponent or CountComponents function to 1. The Component Manager considers only these flags during the search. You specify the desired flag value (either 0 or 1) in the componentFlags field.

For example, to look for a component with a specific control flag that is set to 0, set the appropriate bit in the ComponentFlags field to 0 and the same bit in the ComponentFlagsMask field to 1. To look for a component with a specific control flag that is set to 1, set the bit in the ComponentFlags field to 1 and the same bit in the ComponentFlagsMask field to 1. To ignore a flag, set the bit in the ComponentFlagsMask field to 0.

If you are developing a component, your component must set the componentFlagsMask field in its component description structure to 0.

Discussion

The ComponentDescription structure identifies the characteristics of a component, including the type of services offered by the component and its manufacturer.

Applications and components use component description structures in different ways. An application that uses components specifies the selection criteria for a component in a component description structure. The functions FindNextComponent , CountComponents , and GetComponentInfo all use the component description structure to specify the criteria for their search.

A component uses the component description structure to specify its registration information and capabilities and identify itself to the Component Manager. If your component is stored in a component resource, the information in the component description structure must be part of that resource. See the description of the component ‘thng’ resource. If you have developed an application that registers your component, that application must supply a component description structure to the RegisterComponent function. See “Registering Components” for information about registering components.

The ComponentDescription data type defines the component description structure. Note that the valid values of fields in the component description structure 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.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentFunctionUPP

typedef UniversalProcPtr ComponentFunctionUPP;

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentInstanceRecord

struct ComponentInstanceRecord {
   long data[1];
};
typedef struct ComponentInstanceRecord ComponentInstanceRecord;
   typedef ComponentInstanceRecord * ComponentInstance;

Fields

data

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentMPWorkFunctionHeaderRecord

struct ComponentMPWorkFunctionHeaderRecord {
   UInt32 headerSize;
   UInt32 recordSize;
   UInt32 workFlags;
   UInt16 processorCount;
   UInt8 unused;
   UInt8 isRunning;
};
typedef struct ComponentMPWorkFunctionHeaderRecord  ComponentMPWorkFunctionHeaderRecord;
   typedef ComponentMPWorkFunctionHeaderRecord *  ComponentMPWorkFunctionHeaderRecordPtr;

Fields

headerSize
recordSize
workFlags
processorCount
unused
isRunning

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentMPWorkFunctionUPP

typedef ComponentMPWorkFunctionProcPtr ComponentMPWorkFunctionUPP;

Discussion

For more information, see the description of the ComponentMPWorkFunctionUPP callback function.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentParameters

struct ComponentParameters {
   UInt8 flags;
   UInt8 paramSize;
   short what;
   long params[1];
};
typedef struct ComponentParameters ComponentParameters;

Fields

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. See “Result Codes” for Apple-defined request code values.
params: An array that contains the parameters specified by the application that called your component. You can use the CallComponentRoutine or CallComponentRoutineWithStorage function to convert this array into a Pascal-style invocation of a subroutine in your component.

Discussion

The Component Manager uses the component parameters structure to pass information to your component about a request from an application. Functions which use this data type are CallComponentFunction , CallComponentFunctionWithStorage , and DelegateComponentCall.The information in this structure completely defines the request. Your component services the request as appropriate.

The ComponentParameters data type defines the component parameters structure.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentPlatformInfo

struct ComponentPlatformInfo {
   long componentFlags;
   ResourceSpec component;
   short platformType;
};
typedef struct ComponentPlatformInfo ComponentPlatformInfo;

Fields

component

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentPlatformInfoArray

struct ComponentPlatformInfoArray {
   long count;
   ComponentPlatformInfo platformArray[1];
};
typedef struct ComponentPlatformInfoArray ComponentPlatformInfoArray;

Fields

platformArray

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentRecord

struct ComponentRecord {
   long data[1];
};
typedef struct ComponentRecord ComponentRecord;
   typedef ComponentRecord * Component;

Fields

data

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentResource

struct ComponentResource {
   ComponentDescription cd;
   ResourceSpec component;
   ResourceSpec componentName;
   ResourceSpec componentInfo;
   ResourceSpec componentIcon;
};
typedef struct ComponentResource ComponentResource;
   typedef ComponentResource * ComponentResourcePtr;

Fields

cd: A ComponentDescription structure that specifies the characteristics of the component.
component: A resource specification structure that specifies the type and ID of the component code resource. The resType field of the resource specification structure may contain any value. The component’s main entry point must be at offset 0 in the resource.
componentName: A resource specification structure that specifies the resource type and ID for the name of the component. This is a Pascal string. Typically, the name is stored in a resource of type 'STR '.
componentInfo: A resource specification structure that specifies the resource type and ID for the information string that describes the component. This is a Pascal string. Typically, the information string is stored in a resource of type 'STR '. You might use the information stored in this resource in a Get Info dialog box.
componentIcon: A resource specification structure that specifies the resource type and ID for the icon for a component. Component icons are stored as 32-by-32 bit maps. Typically, the icon is stored in a resource of type 'ICON'. 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 in a dialog box if needed.

Discussion

The ComponentResource data type defines the structure of a component resource. You can also optionally append to the end of this structure the information defined by the ComponentResourceExtension data type.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentResourceExtension

struct ComponentResourceExtension {
   long componentVersion;
   long componentRegisterFlags;
   short componentIconFamily;
};
typedef struct ComponentResourceExtension ComponentResourceExtension;

Fields

componentVersion: The version number of the component. If you specify the componentDoAutoVersion flag in componentRegisterFlags, the Component Manager must obtain the version number of your component when your component is registered. Either you can provide a version number in your component’s resource, or you can specify a value of 0 for its version number. If you specify 0, the Component Manager sends your component a version request to get the version number of your component.
componentRegisterFlags: A set of flags containing additional registration information. See “Component Resource Extension Flags” for the flag values.
componentIconFamily: The resource ID of an icon family. You can provide an icon family in addition to the icon provided in the componentIcon field. Note that members of this icon family are not used by the Finder you supply an icon family only so that other components or applications can display your component’s icon in a dialog box if needed.

Discussion

You can optionally include in your component resource the information defined by the ComponentResourceExtension data type:

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentResult

typedef long ComponentResult;

Discussion

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ComponentRoutineUPP

typedef ComponentRoutineProcPtr ComponentRoutineUPP;

Discussion

For more information, see the description of the ComponentRoutineUPP callback function.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ExtComponentResource

struct ExtComponentResource {
   ComponentDescription cd;
   ResourceSpec component;
   ResourceSpec componentName;
   ResourceSpec componentInfo;
   ResourceSpec componentIcon;
   long componentVersion;
   long componentRegisterFlags;
   short componentIconFamily;
   long count;
   ComponentPlatformInfo platformArray[1];
};
typedef struct ExtComponentResource ExtComponentResource;
   typedef ExtComponentResource * ExtComponentResourcePtr;

Fields

cd
component
componentName
componentInfo
componentIcon
platformArray

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

GetMissingComponentResourceUPP

typedef GetMissingComponentResourceProcPtr GetMissingComponentResourceUPP;

Discussion

For more information, see the description of the GetMissingComponentResourceUPP callback function.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

RegisteredComponentInstanceRecord

struct RegisteredComponentInstanceRecord {
   long data[1];
};
typedef struct RegisteredComponentInstanceRecord  RegisteredComponentInstanceRecord;
   typedef RegisteredComponentInstanceRecord *  RegisteredComponentInstanceRecordPtr;

Fields

data

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

RegisteredComponentRecord

struct RegisteredComponentRecord {
   long data[1];
};
typedef struct RegisteredComponentRecord RegisteredComponentRecord;
   typedef RegisteredComponentRecord * RegisteredComponentRecordPtr;

Fields

data

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

ResourceSpec

struct ResourceSpec {
   OSType resType;
   short resID;
};
typedef struct ResourceSpec ResourceSpec;

Fields

resType: The type of the resource.
resID: The ID of the resource.

Discussion

The ComponentResource structure uses the resource specification structure, defined by the ResourceSpec data type, to describe the component’s code, name, information string, or icon. The resources specified by the resource specification structures must reside in the same resource file as the component resource itself.

Availability

Available in OS X v10.0 and later.

Declared In

Components.h

Constants

cmpAliasNoFlags

enum {
   cmpAliasNoFlags = 0,
   cmpAliasOnlyThisFile = 1
};

Constants

cmpAliasNoFlags

Available in OS X v10.0 and later.

Declared in Components.h.

cmpAliasOnlyThisFile

Available in OS X v10.0 and later.

Declared in Components.h.

cmpIsMissing

enum {
   cmpThreadSafe = 1L << 28,
   cmpIsMissing = 1L << 29,
   cmpWantsRegisterMessage = 1L << 31
};

Constants

cmpThreadSafe

Available in OS X v10.3 and later.

Declared in Components.h.

cmpIsMissing

Available in OS X v10.0 and later.

Declared in Components.h.

cmpWantsRegisterMessage

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.

Available in OS X v10.0 and later.

Declared in Components.h.

Discussion

These values are used by the componentFlags field of the ComponentDescription structure to provide additional information about a component.

Component Resource Extension Flags

enum {
   componentDoAutoVersion = (1 << 0),
   componentWantsUnregister = (1 << 1),
   componentAutoVersionIncludeFlags = (1 << 2),
   componentHasMultiplePlatforms = (1 << 3),
   componentLoadResident = (1 << 4)
};

Constants

componentDoAutoVersion

Specify this flag if you want the Component Manager to resolve conflicts between different versions of the same component. If you specify this flag, the Component Manager registers your component only if there is no later version available. If an older version is already registered, the Component Manager unregisters it. If a newer version of the same component is registered after yours, the Component Manager automatically unregisters your component. You can use this automatic version control feature to make sure that the most recent version of your component is registered, regardless of the number of versions that are installed

Available in OS X v10.0 and later.

Declared in Components.h.

componentWantsUnregister

Specify this flag if you want your component to receive an unregister request when it is unregistered.

Available in OS X v10.0 and later.

Declared in Components.h.

componentAutoVersionIncludeFlags

Specify this flag if you want the Component Manager to include the componentFlags field of the component description structure when it searches for identical components in the process of performing automatic version control for your component. If you do not specify this flag, the Component Manager searches only the componentType, componentSubType, and componentManufacturer fields.

Note that the setting of the componentAutoVersionIncludeFlags flag affects automatic version control only and does not affect the search operations performed by FindNextComponent and CountComponents.

Available in OS X v10.0 and later.

Declared in Components.h.

componentHasMultiplePlatforms

Available in OS X v10.0 and later.

Declared in Components.h.

componentLoadResident

Available in OS X v10.0 and later.

Declared in Components.h.

Discussion

These values are used in the ComponentResourceExtension structure to specify additional information about component registration.

CSComponentsThreadMode

typedef UInt32 CSComponentsThreadMode;
enum {
   kCSAcceptAllComponentsMode = 0,
   kCSAcceptThreadSafeComponentsOnlyMode = 1
};

Constants

kCSAcceptAllComponentsMode

Available in OS X v10.3 and later.

Declared in Components.h.

kCSAcceptThreadSafeComponentsOnlyMode

Available in OS X v10.3 and later.

Declared in Components.h.

kAnyComponentType

enum {
   kAnyComponentType = 0,
   kAnyComponentSubType = 0,
   kAnyComponentManufacturer = 0,
   kAnyComponentFlagsMask = 0
};

Constants

kAnyComponentType

Available in OS X v10.0 and later.

Declared in Components.h.

kAnyComponentSubType

Available in OS X v10.0 and later.

Declared in Components.h.

kAnyComponentManufacturer

Available in OS X v10.0 and later.

Declared in Components.h.

kAnyComponentFlagsMask

Available in OS X v10.0 and later.

Declared in Components.h.

kAppleManufacturer

enum {
   kAppleManufacturer = 'appl',
   kComponentResourceType = 'thng',
   kComponentAliasResourceType = 'thga'
};

Constants

kAppleManufacturer

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentResourceType

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentAliasResourceType

Available in OS X v10.0 and later.

Declared in Components.h.

mpWorkFlagDoWork

enum {
   mpWorkFlagDoWork = (1 << 0),
   mpWorkFlagDoCompletion = (1 << 1),
   mpWorkFlagCopyWorkBlock = (1 << 2),
   mpWorkFlagDontBlock = (1 << 3),
   mpWorkFlagGetProcessorCount = (1 << 4),
   mpWorkFlagGetIsRunning = (1 << 6)
};

Constants

mpWorkFlagDoWork

Available in OS X v10.0 and later.

Declared in Components.h.

mpWorkFlagDoCompletion

Available in OS X v10.0 and later.

Declared in Components.h.

mpWorkFlagCopyWorkBlock

Available in OS X v10.0 and later.

Declared in Components.h.

mpWorkFlagDontBlock

Available in OS X v10.0 and later.

Declared in Components.h.

mpWorkFlagGetProcessorCount

Available in OS X v10.0 and later.

Declared in Components.h.

mpWorkFlagGetIsRunning

Available in OS X v10.0 and later.

Declared in Components.h.

platform68k

enum {
   platform68k = 1,
   platformPowerPC = 2,
   platformInterpreted = 3,
   platformWin32 = 4,
   platformPowerPCNativeEntryPoint = 5,
   platformIA32NativeEntryPoint = 6
};

Constants

platform68k

Available in OS X v10.0 and later.

Declared in Components.h.

platformPowerPC

Available in OS X v10.0 and later.

Declared in Components.h.

platformInterpreted

Available in OS X v10.0 and later.

Declared in Components.h.

platformWin32

Available in OS X v10.0 and later.

Declared in Components.h.

platformPowerPCNativeEntryPoint

Available in OS X v10.0 and later.

Declared in Components.h.

platformIA32NativeEntryPoint

Available in OS X v10.3 and later.

Declared in Components.h.

Discussion

platformIRIXmips

enum {
   platformIRIXmips = 1000,
   platformSunOSsparc = 1100,
   platformSunOSintel = 1101,
   platformLinuxppc = 1200,
   platformLinuxintel = 1201,
   platformAIXppc = 1300,
   platformNeXTIntel = 1400,
   platformNeXTppc = 1401,
   platformNeXTsparc = 1402,
   platformNeXT68k = 1403,
   platformMacOSx86 = 1500
};

Constants

platformIRIXmips

Available in OS X v10.0 and later.

Declared in Components.h.

platformSunOSsparc

Available in OS X v10.0 and later.

Declared in Components.h.

platformSunOSintel

Available in OS X v10.0 and later.

Declared in Components.h.

platformLinuxppc

Available in OS X v10.0 and later.

Declared in Components.h.

platformLinuxintel

Available in OS X v10.0 and later.

Declared in Components.h.

platformAIXppc

Available in OS X v10.0 and later.

Declared in Components.h.

platformNeXTIntel

Available in OS X v10.0 and later.

Declared in Components.h.

platformNeXTppc

Available in OS X v10.0 and later.

Declared in Components.h.

platformNeXTsparc

Available in OS X v10.0 and later.

Declared in Components.h.

platformNeXT68k

Available in OS X v10.0 and later.

Declared in Components.h.

platformMacOSx86

Available in OS X v10.0 and later.

Declared in Components.h.

Register Component Resource flags

enum {
   registerComponentGlobal = 1,
   registerComponentNoDuplicates = 2,
   registerComponentAfterExisting = 4,
   registerComponentAliasesOnly = 8
};

Constants

registerComponentGlobal

Specify this flag to indicate that this component should be made available to other applications and clients as well as the one performing the registration. If you do not specify this flag, the component is available for use only by the registering application or component (that is, the component is local to the A5 world of the registering program).

Available in OS X v10.0 and later.

Declared in Components.h.

registerComponentNoDuplicates

Specify this flag to indicate that if a component with identical characteristics to the one being registered already exists, then the new one should not be registered (RegisterComponent returns 0 in this situation). If you do not specify this flag, the component is registered even if a component with identical characteristics to the one being registered already exists.

Available in OS X v10.0 and later.

Declared in Components.h.

registerComponentAfterExisting

Specify this flag to indicate that this component should be registered after all other components with the same component type. Usually components are registered before others with identical descriptions; specifying this flag overrides that behavior.

Available in OS X v10.0 and later.

Declared in Components.h.

registerComponentAliasesOnly

Available in OS X v10.0 and later.

Declared in Components.h.

Discussion

The functions RegisterComponent , RegisterComponentResource , and RegisterComponentResourceFile use these flags in the global parameter.

Request Codes

enum {
   kComponentOpenSelect = -1,
   kComponentCloseSelect = -2,
   kComponentCanDoSelect = -3,
   kComponentVersionSelect = -4,
   kComponentRegisterSelect = -5,
   kComponentTargetSelect = -6,
   kComponentUnregisterSelect = -7,
   kComponentGetMPWorkFunctionSelect = -8,
   kComponentExecuteWiredActionSelect = -9,
   kComponentGetPublicResourceSelect = -10
};

Constants

kComponentOpenSelect

A request to open a connection. Your component must respond to this request code.

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentCloseSelect

A request to close a connection. Your component must respond to this request code.

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentCanDoSelect

A request to determine whether your component supports a particular request. Your component must respond to this request code

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentVersionSelect

A request to return your component’s version number. Your component must respond to this request code.

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentRegisterSelect

A request to determine whether your component can operate in the current environment. Your component may or may not respond to this request code.

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentTargetSelect

A request to call another component whenever your component would call itself. Your component may or may not respond to this request code.

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentUnregisterSelect

A request to perform any operations necessary as a result of your component being unregistered. Your component may or may not respond to this request code

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentGetMPWorkFunctionSelect

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentExecuteWiredActionSelect

Available in OS X v10.0 and later.

Declared in Components.h.

kComponentGetPublicResourceSelect

Available in OS X v10.0 and later.

Declared in Components.h.

Discussion

These values are used in the ComponentParameters structure to specify the type of a request to a component. Apple has defined these request codes:

Set Default Component Flags

enum {
   defaultComponentIdentical = 0,
   defaultComponentAnyFlags = 1,
   defaultComponentAnyManufacturer = 2,
   defaultComponentAnySubType = 4,
   defaultComponentAnyFlagsAnyManufacturer = (defaultComponentAnyFlags  +  defaultComponentAnyManufacturer),
   defaultComponentAnyFlagsAnyManufacturerAnySubType =  (defaultComponentAnyFlags + defaultComponentAnyManufacturer +  defaultComponentAnySubType)
};

Constants

defaultComponentIdentical

The Component Manager places the component specified in the call to SetDefaultComponent in front of all other components that have the same component description.

Available in OS X v10.0 and later.

Declared in Components.h.

defaultComponentAnyFlags

The Component Manager ignores the value of the componentFlags field during the reorder operation.

Available in OS X v10.0 and later.

Declared in Components.h.

defaultComponentAnyManufacturer

The Component Manager ignores the value of the componentManufacturer field during the reorder operation.

Available in OS X v10.0 and later.

Declared in Components.h.

defaultComponentAnySubType

The Component Manager ignores the value of the componentSubType field during the reorder operation.

Available in OS X v10.0 and later.

Declared in Components.h.

defaultComponentAnyFlagsAnyManufacturer

Available in OS X v10.0 and later.

Declared in Components.h.

defaultComponentAnyFlagsAnyManufacturerAnySubType

Available in OS X v10.0 and later.

Declared in Components.h.

Discussion

The SetDefaultComponent function uses these values in the flags parameter to control which component description fields the Component Manager examines during the reorder operation.

Result Codes

The result codes defined by the Component Manager are listed below.

Result Code	Value	Description
`invalidComponentID`	-3000	Invalid component ID. Available in OS X v10.0 and later.
`validInstancesExist`	-3001	This component has open connections. Available in OS X v10.0 and later.
`componentNotCaptured`	-3002	This component has not been captured. Available in OS X v10.0 and later.
`componentDontRegister`	-3003	Available in OS X v10.0 and later.
`unresolvedComponentDLLErr`	-3004	Available in OS X v10.0 and later.
`retryComponentRegistrationErr`	-3005	Available in OS X v10.0 and later.
`badComponentSelector`	0x80008002	Component does not support the specified request code. Available in OS X v10.0 and later.
`badComponentInstance`	0x80008001	Invalid component passed to Component Manager. Available in OS X v10.0 and later.

Gestalt Constants

You can check for version and feature availability information by using the Component Manager selectors defined in the Gestalt Manager. For more information, see Gestalt Manager Reference.

Did this document help you?

Shop the Apple Online Store (1-800-MY-APPLE), visit an Apple Retail Store, or find a reseller.