iOS Developer Library

Developer

CoreFoundation Framework Reference CFPlugIn Reference

Options
Deployment Target:

On This Page
Language:

CFPlugIn Reference

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

  • Creates a CFPlugIn given its URL.

    Declaration

    Swift

    func CFPlugInCreate(_ allocator: CFAllocator!, _ plugInURL: CFURL!) -> CFPlugIn!

    Objective-C

    CFPlugInRef CFPlugInCreate ( CFAllocatorRef allocator, CFURLRef plugInURL );

    Parameters

    allocator

    The allocator to use to allocate memory for the new plug-in. Pass NULL or kCFAllocatorDefault to use the default allocator.

    plugInURL

    The location of the plug-in.

    Return Value

    A new plug-in. Ownership follows the Create Rule in Memory Management Programming Guide for Core Foundation.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInInstanceCreate(_ allocator: CFAllocator!, _ factoryUUID: CFUUID!, _ typeUUID: CFUUID!) -> UnsafeMutablePointer<Void>

    Objective-C

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

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the default allocator.

    factoryUUID

    The UUID representing the factory function to use to create a plug-in of the given type.

    typeUUID

    The UUID type.

    Return Value

    Returns the IUnknown interface for the new plug-in.

    Discussion

    The plug-in host uses this function to create an instance of the given type. Unless the plug-in is using dynamic registration, this function causes the plug-in's code to be loaded into memory.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInRegisterFactoryFunction(_ factoryUUID: CFUUID!, _ `func`: CFPlugInFactoryFunction) -> Boolean

    Objective-C

    Boolean CFPlugInRegisterFactoryFunction ( CFUUIDRef factoryUUID, CFPlugInFactoryFunction func );

    Parameters

    factoryUUID

    The CFUUID object representing the factory function to register.

    func

    The factory function pointer to register.

    Return Value

    true if the factory function was successfully registered, otherwise false.

    Discussion

    This function is used by a plug-in or host when performing dynamic registration.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInRegisterFactoryFunctionByName(_ factoryUUID: CFUUID!, _ plugIn: CFPlugIn!, _ functionName: CFString!) -> Boolean

    Objective-C

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

    Parameters

    factoryUUID

    The CFUUID object representing the factory function to register.

    plugIn

    The plug-in containing functionName.

    functionName

    The name of the factory function to register.

    Return Value

    true if the factory function was successfully registered, otherwise false.

    Discussion

    This function is used by a plug-in or host when performing dynamic registration.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInRegisterPlugInType(_ factoryUUID: CFUUID!, _ typeUUID: CFUUID!) -> Boolean

    Objective-C

    Boolean CFPlugInRegisterPlugInType ( CFUUIDRef factoryUUID, CFUUIDRef typeUUID );

    Parameters

    factoryUUID

    The CFUUID object representing the factory function that can create the type being registered.

    typeUUID

    The UUID type to register.

    Return Value

    true if the factory function was successfully registered, otherwise false.

    Discussion

    This function is used by a plug-in or host when performing dynamic registration.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInUnregisterFactory(_ factoryUUID: CFUUID!) -> Boolean

    Objective-C

    Boolean CFPlugInUnregisterFactory ( CFUUIDRef factoryUUID );

    Parameters

    factoryUUID

    The CFUUID object representing the factory to unregister.

    Return Value

    true if the factory function was successfully unregistered, otherwise false.

    Discussion

    Used by a plug-in or host when performing dynamic registration.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInUnregisterPlugInType(_ factoryUUID: CFUUID!, _ typeUUID: CFUUID!) -> Boolean

    Objective-C

    Boolean CFPlugInUnregisterPlugInType ( CFUUIDRef factoryUUID, CFUUIDRef typeUUID );

    Parameters

    factoryUUID

    The CFUUID object representing the factory function for the type to unregister.

    typeUUID

    The UUID type to unregister.

    Return Value

    true if the factory function was successfully unregistered, otherwise false.

    Discussion

    Used by a plug-in or host when performing dynamic registration.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Registers a new instance of a type with CFPlugIn.

    Declaration

    Swift

    func CFPlugInAddInstanceForFactory(_ factoryID: CFUUID!)

    Objective-C

    void CFPlugInAddInstanceForFactory ( CFUUIDRef factoryID );

    Parameters

    factoryID

    The CFUUID object representing the plug-in factory.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInFindFactoriesForPlugInType(_ typeUUID: CFUUID!) -> CFArray!

    Objective-C

    CFArrayRef CFPlugInFindFactoriesForPlugInType ( CFUUIDRef typeUUID );

    Parameters

    typeUUID

    A UUID type.

    Return Value

    An array of UUIDs for factory functions capable of creating an instance of the given type.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInFindFactoriesForPlugInTypeInPlugIn(_ typeUUID: CFUUID!, _ plugIn: CFPlugIn!) -> CFArray!

    Objective-C

    CFArrayRef CFPlugInFindFactoriesForPlugInTypeInPlugIn ( CFUUIDRef typeUUID, CFPlugInRef plugIn );

    Parameters

    typeUUID

    A UUID type.

    plugIn

    The plug-in to search.

    Return Value

    An array of UUIDs for factory functions capable of creating an instance of the given type.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns a plug-in's bundle.

    Declaration

    Swift

    func CFPlugInGetBundle(_ plugIn: CFPlugIn!) -> CFBundle!

    Objective-C

    CFBundleRef CFPlugInGetBundle ( CFPlugInRef plugIn );

    Parameters

    plugIn

    The plug-in whose bundle to obtain.

    Return Value

    The bundle for plugIn. Ownership follows the Get Rule in Memory Management Programming Guide for Core Foundation.

    Discussion

    You should always use this function to get a plug-in's bundle. Never attempt to access the plug-in directly as a bundle.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Returns the type identifier for the CFPlugIn opaque type.

    Declaration

    Swift

    func CFPlugInGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID CFPlugInGetTypeID ( void );

    Return Value

    The type identifier for the CFPlugIn opaque type.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInIsLoadOnDemand(_ plugIn: CFPlugIn!) -> Boolean

    Objective-C

    Boolean CFPlugInIsLoadOnDemand ( CFPlugInRef plugIn );

    Parameters

    plugIn

    The plug-in to query.

    Return Value

    true if the plug-in is loaded only when a client requests an instance of a supported type, otherwise false.

    Discussion

    Plug-ins that do static registration are load on demand by default. Plug-ins that do dynamic registration are not load on demand by default.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

  • Unregisters an instance of a type with CFPlugIn.

    Declaration

    Swift

    func CFPlugInRemoveInstanceForFactory(_ factoryID: CFUUID!)

    Objective-C

    void CFPlugInRemoveInstanceForFactory ( CFUUIDRef factoryID );

    Parameters

    factoryID

    The CFUUID object representing the plug-in factory.

    Discussion

    If the instance counts of every factory in a plug-in are zero, the plug-in can be unloaded.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Swift

    func CFPlugInSetLoadOnDemand(_ plugIn: CFPlugIn!, _ flag: Boolean)

    Objective-C

    void CFPlugInSetLoadOnDemand ( CFPlugInRef plugIn, Boolean flag );

    Parameters

    plugIn

    The plug-in to be loaded on demand.

    flag

    true to enable load on demand, false otherwise.

    Discussion

    Plug-ins that do static registration are load on demand by default. Plug-ins that do dynamic registration are not load on demand by default.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Callbacks

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

    Declaration

    Objective-C

    typedef void (*CFPlugInDynamicRegisterFunction) ( CFPlugInRef plugIn );

    Parameters

    plugIn

    The CFPlugIn object that is engaged in dynamic registration. When using in C++, this parameter functions as a this pointer for the plug-in.

    Discussion

    This callback is called as a plug-in is being loaded. This provides the plugin the means to dynamically register its types and factories with a plug-in’s host. The call is triggered by the presence of kCFPlugInDynamicRegistrationKey in the plug-in's information property list.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

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

    Parameters

    allocator

    The allocator to use to allocate memory for the new object. Pass NULL or kCFAllocatorDefault to use the default allocator.

    typeUUID

    The UUID type to instantiate.

    Discussion

    The plug-in author's implementation of this function is registered with CFPlugIn either statically in the plug-in's information property list, or dynamically. This function is executed as a result of a call to CFPlugInInstanceCreate by the plug-in host.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

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

    Declaration

    Objective-C

    typedef void (*CFPlugInUnloadFunction) ( CFPlugInRef plugIn );

    Parameters

    plugIn

    The CFPlugIn object that is about to be unloaded from memory. When writing in C++, this parameter functions as a this pointer for the plug-in.

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Data Types

Miscellaneous

  • A reference to a CFPlugin object.

    Declaration

    Swift

    typealias CFPlugInRef = CFPlugIn

    Objective-C

    typedef struct __CFBundle *CFPlugInRef;

    Import Statement

    import CoreFoundation

    Availability

    Available in iOS 2.0 and later.

Constants

Miscellaneous

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

    Declaration

    Swift

    let kCFPlugInDynamicRegistrationKey: CFString! let kCFPlugInDynamicRegisterFunctionKey: CFString! let kCFPlugInUnloadFunctionKey: CFString! let kCFPlugInFactoriesKey: CFString! let kCFPlugInTypesKey: CFString!

    Objective-C

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

    Constants

    • kCFPlugInDynamicRegistrationKey

      kCFPlugInDynamicRegistrationKey

      Indicates whether a plug-in requires dynamic registration.

      Available in iOS 2.0 and later.

    • kCFPlugInDynamicRegisterFunctionKey

      kCFPlugInDynamicRegisterFunctionKey

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

      Available in iOS 2.0 and later.

    • kCFPlugInUnloadFunctionKey

      kCFPlugInUnloadFunctionKey

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

      Available in iOS 2.0 and later.

    • kCFPlugInFactoriesKey

      kCFPlugInFactoriesKey

      Used to statically register factory functions.

      Available in iOS 2.0 and later.

    • kCFPlugInTypesKey

      kCFPlugInTypesKey

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

      Available in iOS 2.0 and later.

    Import Statement