CFPlugIn Reference

Overview

CFPlugIn provides a standard architecture for application extensions. With CFPlugIn, you can design your application as a host framework that uses a set of executable code modules called plug-ins to provide certain well-defined areas of functionality. This approach allows third-party developers to add features to your application without requiring access to your source code. You can also bundle together plug-ins for multiple platforms and let CFPlugIn transparently load the appropriate plug-in at runtime. You can use CFPlugIn to add plug-in capability to, or write a plug-in for, your application.

Functions by Task

Creating Plug-ins

• CFPlugInCreate
• CFPlugInInstanceCreate

Registration

• CFPlugInRegisterFactoryFunction
• CFPlugInRegisterFactoryFunctionByName
• CFPlugInRegisterPlugInType
• CFPlugInUnregisterFactory
• CFPlugInUnregisterPlugInType

CFPlugIn Miscellaneous Functions

• CFPlugInAddInstanceForFactory
• CFPlugInFindFactoriesForPlugInType
• CFPlugInFindFactoriesForPlugInTypeInPlugIn
• CFPlugInGetBundle
• CFPlugInGetTypeID
• CFPlugInIsLoadOnDemand
• CFPlugInRemoveInstanceForFactory
• CFPlugInSetLoadOnDemand

Functions

CFPlugInAddInstanceForFactory

Registers a new instance of a type with CFPlugIn.

void CFPlugInAddInstanceForFactory (
   CFUUIDRef factoryID
);

CFPlugInCreate

Creates a CFPlugIn given its URL.

CFPlugInRef CFPlugInCreate (
   CFAllocatorRef allocator,
   CFURLRef plugInURL
);

CFPlugInFindFactoriesForPlugInType

Searches all registered plug-ins for factory functions capable of creating an instance of the given type.

CFArrayRef CFPlugInFindFactoriesForPlugInType (
   CFUUIDRef typeUUID
);

CFPlugInFindFactoriesForPlugInTypeInPlugIn

Searches the given plug-in for factory functions capable of creating an instance of the given type.

CFArrayRef CFPlugInFindFactoriesForPlugInTypeInPlugIn (
   CFUUIDRef typeUUID,
   CFPlugInRef plugIn
);

CFPlugInGetBundle

Returns a plug-in's bundle.

CFBundleRef CFPlugInGetBundle (
   CFPlugInRef plugIn
);

CFPlugInGetTypeID

Returns the type identifier for the CFPlugIn opaque type.

CFTypeID CFPlugInGetTypeID (
   void
);

CFPlugInInstanceCreate

Creates a CFPlugIn instance of a given type using a given factory.

void * CFPlugInInstanceCreate (
   CFAllocatorRef allocator,
   CFUUIDRef factoryUUID,
   CFUUIDRef typeUUID
);

CFPlugInIsLoadOnDemand

Determines whether or not a plug-in is loaded on demand.

Boolean CFPlugInIsLoadOnDemand (
   CFPlugInRef plugIn
);

CFPlugInRegisterFactoryFunction

Registers a factory function and its UUID with a CFPlugIn object.

Boolean CFPlugInRegisterFactoryFunction (
   CFUUIDRef factoryUUID,
   CFPlugInFactoryFunction func
);

CFPlugInRegisterFactoryFunctionByName

Registers a factory function with a CFPlugIn object using the function's name instead of its UUID.

Boolean CFPlugInRegisterFactoryFunctionByName (
   CFUUIDRef factoryUUID,
   CFPlugInRef plugIn,
   CFStringRef functionName
);

CFPlugInRegisterPlugInType

Registers a type and its corresponding factory function with a CFPlugIn object.

Boolean CFPlugInRegisterPlugInType (
   CFUUIDRef factoryUUID,
   CFUUIDRef typeUUID
);

CFPlugInRemoveInstanceForFactory

Unregisters an instance of a type with CFPlugIn.

void CFPlugInRemoveInstanceForFactory (
   CFUUIDRef factoryID
);

CFPlugInSetLoadOnDemand

Enables or disables load on demand for plug-ins that do dynamic registration (only when a client requests an instance of a supported type).

void CFPlugInSetLoadOnDemand (
   CFPlugInRef plugIn,
   Boolean flag
);

CFPlugInUnregisterFactory

Removes the given function from a plug-in’s list of registered factory functions.

Boolean CFPlugInUnregisterFactory (
   CFUUIDRef factoryUUID
);

CFPlugInUnregisterPlugInType

Removes the given type from a plug-in’s list of registered types.

Boolean CFPlugInUnregisterPlugInType (
   CFUUIDRef factoryUUID,
   CFUUIDRef typeUUID
);

Callbacks

CFPlugInDynamicRegisterFunction

A callback which provides a plug-in the opportunity to dynamically register its types with a host.

typedef void (*CFPlugInDynamicRegisterFunction) (
   CFPlugInRef plugIn
);

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

void MyCallBack (
   CFPlugInRef plugIn
);

CFPlugInFactoryFunction

Callback function that a plug-in author must implement to create a plug-in instance.

typedef void *(*CFPlugInFactoryFunction) (
   CFAllocatorRef allocator,
   CFUUIDRef typeUUID
);

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

void *MyCallBack (
   CFAllocatorRef allocator,
   CFUUIDRef typeUUID
);

CFPlugInUnloadFunction

Callback function that is called, if present, just before a plug-in's code is unloaded.

typedef void (*CFPlugInUnloadFunction) (
   CFPlugInRef plugIn
);

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

void MyCallBack (
   CFPlugInRef plugIn
);

Data Types

CFPlugInRef

A reference to a CFPlugin object.

typedef struct __CFBundle *CFPlugInRef;

Constants

Information Property List Keys

A plug-in’s information property list can contain these keys used for registering types, factories, and interfaces.

const CFStringRef kCFPlugInDynamicRegistrationKey;
const CFStringRef kCFPlugInDynamicRegisterFunctionKey;
const CFStringRef kCFPlugInUnloadFunctionKey;
const CFStringRef kCFPlugInFactoriesKey;
const CFStringRef kCFPlugInTypesKey;

Constants

kCFPlugInDynamicRegistrationKey

Indicates whether a plug-in requires dynamic registration.

Available in OS X v10.0 and later.

Declared in CFPlugIn.h.

kCFPlugInDynamicRegisterFunctionKey

Used to specify a plug-in’s registration function.

Available in OS X v10.0 and later.

Declared in CFPlugIn.h.

kCFPlugInUnloadFunctionKey

Used to specify a plug-in’s unload function.

Available in OS X v10.0 and later.

Declared in CFPlugIn.h.

kCFPlugInFactoriesKey

Used to statically register factory functions.

Available in OS X v10.0 and later.

Declared in CFPlugIn.h.

kCFPlugInTypesKey

Used to statically register the factories that can create each supported type.

Available in OS X v10.0 and later.

Declared in CFPlugIn.h.