ModuleManager.framework

Abstract: Declarations for functions available in ModuleManager.framework.

Availability: Mac OS X 10.5 and later.

Includes: <CoreFoundation/CoreFoundation.h>, <ModuleManager/MMConstants.h>

Version: 0.5.4

Description:

ModuleManager.framework provides access to an XML property list file which describes the contents of script libraries. The idea of using a property list storage format for script libraries is that its form be codified at a basic level so users and developers can take advantage of a known format. Another requirement is that it be extensible so clients can add extra facilities while maintaining compatibility with the basic interchange format. ModuleManager subscribes to these concepts.

ModuleManager.framework uses the idea that script libraries are located in subfolders of folders named "Modules" located in the Scripts folders of the user, local, and network domains. It also entertains the notion that library descriptions don't have to be folder-based. They can describe a hierarchy of resources which may be anywhere on a disk or the internet.

ModuleManager's programming interface is divided into the following sections:

ModuleManager: Document activation control and r/o variables available prior to document activation.
MMDocument: Top level document functions.
MMLibrary: For manipulating libraries.
MMLibraryDescription: Used for creating libraries.
MMFile: Access to file information.
MMProperty: Access to library properties information.
MMSearchConfiguration: For manipulating search configurations.
MMSearchConfigurationDescription: Used for creating search configurations.
MMError: Error reporting.

ModuleManager is a layered technology.

The bottom layer (outlined below) does not make calls above the CoreFoundation framework APIs and only uses CoreFoundation types. This makes it easy to create a wrapper interface with object-oriented languages. An auxilliary file, MMUtilities.h, provides helper functions which use C-language primatives.

The next layer interfaces with CoreServices level technologies such as Aliases and AppleEvents. Its function declarations can be found in the MMServices.h file of the framework Headers folder. In order to use them, you must #include or #import the header as: <ModuleManager/MMServices.h>.

Functions

ModuleManager

extern CFStringRef ModuleManagerGetDocumentFileExtension ( void );

Description:: Returns the extension of the module document (default is 'mlix' ).

extern CFStringRef ModuleManagerGetDocumentPropertyListID ( void );

Description:: Returns the property list identifier used to access the shared property list. For beta purposes, the identifier is "info.library.module.<Version>." -- meaning that the file is located in the /Users/Shared directory. This can be changed by altering the value for the key "ModuleDocumentPropertyListID" in the framework's Info.plist. The identifier must have a length of at least 16 characters. If for any reason, retrieval of the default identifier fails, it will be hard-wired to "info.library.module".

extern CFStringRef ModuleManagerGetModulesFolderName ( void );

Description:: Returns the folder name for the module in each domain (currently "Modules"). For beta purposes, the name is "Modules.<Version>". This can be changed by altering the value for the key "ModuleDefaultFolderName" in the framework's Info.plist. The folder name must have a length of at least 1 character.

extern CFURLRef ModuleManagerGetModulesFolderURLForLocalDomain ( void );

Description:: The file URL for /Library/Scripts/${Modules}/ (i.e. whatever ModuleManagerGetModulesFolderName() returns).

extern CFURLRef ModuleManagerGetModulesFolderURLForNetworkDomain ( void );

Description:: Could be the file URL for /Network/Library/Scripts/${Modules}/ (i.e. whatever ModuleManagerGetModulesFolderName() returns), but NULL when the user is not logged in to a network.

extern CFURLRef ModuleManagerGetModulesFolderURLForUserDomain ( void );

Description:: The file URL for ~/Library/Scripts/${Modules}/ (i.e. whatever ModuleManagerGetModulesFolderName() returns). Module initialization will fail if this URL can't be created.

extern MMErrorRef ModuleManagerLoadDocument( CFAllocatorRef theAllocator, CFDictionaryRef theOptions );

Description:: Loads the document (the property list file) making it available for use by all the other functions in the framework.

extern MMErrorRef ModuleManagerSaveDocument ( CFAllocatorRef theAllocator );

Description:: Saves the current state of the document to disk.

MMDocument

extern CFMutableArrayRef MMDocumentCopyFileIDs( CFAllocatorRef theAllocator, MMErrorRef *outError );

Description:: Copy the ids of all files in the document.

extern CFMutableArrayRef MMDocumentCopyLibraryIDs( CFAllocatorRef theAllocator, MMErrorRef *outError );

Description:: Copies all library ids currently installed in the module.

extern CFMutableArrayRef MMDocumentCopyLibraryIDsWithTitle( CFAllocatorRef theAllocator, CFStringRef theLibraryTitle, MMErrorRef *outError );

Description:: Copies all library ids with the specified title.

extern CFMutableArrayRef MMDocumentCopyLibraryIDsWithTitleContainingSubstring( CFAllocatorRef theAllocator, CFStringRef theSubstring, MMErrorRef *outError );

Description:: Copies all library ids with the specified substring in the library title.

CFMutableArrayRef MMDocumentCopySearchConfigurationIDs( CFAllocatorRef theAllocator, MMErrorRef *outError );

Description:: Copies all search configuration ids currently in the document.

extern CFMutableArrayRef MMDocumentGetDisabledFolderSubstrings ( void );

Description:: Returns an array of substrings whose presence in the name of a folder determines whether or not it is enabled for searching.

MMUUIDRef MMDocumentGetSearchConfigurationLastSelected ( void );

Description:: Get the active search configuration ID.

extern CFStringRef MMDocumentGetVersion ( void );

Description:: Returns the current version of the document storage format.

extern MMErrorRef MMDocumentRegisterLibrary( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, MMUUIDRef *optOutLibraryID );

Description:

Add a library to the collection of libraries for the module. The basic items in a library are:

BaseURIString

Fixed text. The base path of the default libraries in their respective domains, but otherwise need not be present. Tilde expansion may be required for the user domain.

Children

An array of library IDs which were registered with this library's ID as their parent ID. May be empty.

Files

Array of IDs. These specify keys in the top-level Map container for the string representation values of URLs registered in the library. May be empty.

Flags

CFNumberRef. Stored as OR'd enumeration values. The utility functions MMU_NumberCreateWithCFIndex and MMU_NumberGetCFIndexValue are available for dealing with flag values.

Values:: kMMLibraryFlagsNone; kMMLibraryFlagPermitOverrides; kMMLibraryFlagSearchRecursively; kMMLibraryFlagTrackAliases; kMMLibraryFlagIsReserved

Kind

The Library type identifier.

ParentID

A unique identifier. An MMUUIDRef supplied by theParentLibraryID input parameter in MMLibraryDescriptionCreateMinimal().

PropertyID

A unique identifier. An MMUUIDRef auto-supplied by ModuleManager. It is the key to a property container in the top-level Properties container.

URLMapID

A unique identifier. Specifies a key in the top-level Map container for the string representation value of the URL directly associated with this library (most often a folder on disk). Will not be present if there is no associated URL.

Example of a library registered with a minimal description.

The supplied library description for this example was created with an MMLibraryDescriptionCreateMinimal() call. No additional values were added. The library title is stored in the top-level Properties container and accessed with the auto-generated PropertiesID value.

<key>com.example.empty.library</key>
<dict>
    <key>Children</key>
    <array/>
    <key>Files</key>
    <array/>
    <key>Flags</key>
    <integer>0</integer>
    <key>Kind</key>
    <string>Library</string>
    <key>ParentID</key>
    <string>info.module.library.id.local</string>
    <key>PropertyID</key>
    <string>21190e8bd367fea65df6dd2b3a0acd50</string>

extern MMErrorRef MMDocumentRegisterSearchConfiguration( CFAllocatorRef theAllocator, MMUUIDRef theSearchConfigurationDescriptionID );

Description:: Adds the referenced SearchConfiguration to the module replacing any existing configuration with the same id. The input parameter theSearchConfigurationDescriptionID is released during this process and no longer valid after the call completes.

extern MMErrorRef MMDocumentRemoveLibrary( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID );

Description:: Deletes the specified library.

extern MMErrorRef MMDocumentRemoveSearchConfiguration( CFAllocatorRef theAllocator, MMUUIDRef theSearchConfigurationID );

Description:: Deletes the specified SearchConfiguration.

extern void MMDocumentSetDisabledFolderSubstrings ( CFArrayRef theArray );

Description:: Sets the disabled folder substrings array.

extern MMErrorRef MMDocumentSetSearchConfigurationLastSelected( CFAllocatorRef theAllocator, MMUUIDRef theSearchConfigurationID );

Description:: Set the active search configuration. Should be called in response to a user action.

MMLibrary

extern CFMutableArrayRef MMLibraryGetFiles( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, MMErrorRef *outError );

Description:: Gets the array of file ids contained in the specified library. Returns NULL (and no error) if there are none.

static inline CFNumberRef MMLibraryGetFlags( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, MMErrorRef *outError );

Description:: Gets the value of the flags for the specified library. Do not release the returned number.

extern MMUUIDRef MMLibraryGetPropertyID( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, MMErrorRef *outError );

Description:: Gets the id of the Property container associated with the specified library.

extern MMUUIDRef MMLibraryGetURLMapID( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, MMErrorRef *outError );

Description:: Gets the id of the folder associated with the specified library (if it exists).

extern MMTypeRef MMLibraryGetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, CFStringRef theItemKey, MMErrorRef *outError );

Description:: Gets a value from the top level library container. Do not release the value obtained.

extern MMTypeRef MMLibraryPropertyGetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, CFStringRef thePropertyKey, MMErrorRef *outError );

Description:: Gets the value of the specifed item in the Property container associated with the library.

extern MMErrorRef MMLibraryPropertySetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, CFStringRef thePropertyKey, MMTypeRef theValue );

Description:: Sets an item value in the specified library Properties container.

extern MMErrorRef MMLibraryRegisterFileID( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, MMUUIDRef theUUID );

Description:: If a URL has already been assigned an id in another library, you can use that id to register the file in this library as well.

extern MMErrorRef MMLibraryRegisterSubfolders( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID );

Description:: Registers the immediate subfolders (and their files) of the specified library.

extern MMUUIDRef MMLibraryRegisterURL( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, CFURLRef theURL, MMErrorRef *outError );

Description:: Adds file information about the input file to the document's Files container and the input library's Files list. If file information for the input file already exists, the input library id is added to its Owners list.

static inline MMErrorRef MMLibrarySetFlags( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, CFNumberRef theNumber );

Description:: Sets the flags value in the specified library.

extern MMErrorRef MMLibrarySetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, CFStringRef theItemKey, MMTypeRef theValue );

Description:: Sets the value of the specified library item.

extern MMErrorRef MMLibraryUnregisterFileID( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, MMUUIDRef theFileID );

Description:: Removes the file from the library's Files list. Removes the library as an owner of the file in the top level Files container. The file is not removed from the top level Files container. If file represents an existing file on disk, is not touched.

extern MMErrorRef MMLibraryUnregisterURL( CFAllocatorRef theAllocator, MMUUIDRef theLibraryID, CFURLRef theURL );

Description:: Removes the URL's associated ID from the library's Files list. Removes the library as an owner of the file in the top level Files container. The file is not removed from the top level Files container. If file represents an existing file on disk, is not touched.

MMLibraryDescription

extern MMTypeRef MMLibraryDescriptionContainerGetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef theContainerKey, CFStringRef theItemKey, MMErrorRef *outError );

Description:: Gets an item value in the specified library description container.

extern MMErrorRef MMLibraryDescriptionContainerSetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef theContainerKey, CFStringRef theItemKey, MMTypeRef theValue );

Description:: Sets the value of an item in specified library description container.

extern MMUUIDRef MMLibraryDescriptionCreateMinimal( CFAllocatorRef theAllocator, MMUUIDRef theParentLibraryID, MMUUIDRef thePermanentID, CFStringRef theNewLibraryTitle, MMErrorRef *outError );

Description:: Creates the minimal library description suitable as input for registering a library. Once created, you may use the assorted MMLibraryDescription functions to add additional information to be associated with the library. The MMLibraryDescriptionSetFolderInfoWithURL() function is used to associate a library with a folder.

static inline MMTypeRef MMLibraryDescriptionFileGetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef theFileInfoKey, MMErrorRef *outError );

Description:: Gets an item value from the specified library description Files container.

static inline MMErrorRef MMLibraryDescriptionFileSetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef theFileInfoKey, MMTypeRef theValue );

Description:: Sets the value of an item in specified library description Files container.

static inline MMTypeRef MMLibraryDescriptionFolderInfoGetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef theFileInfoKey, MMErrorRef *outError );

Description:: Gets an item value from the specified library description FolderInfo container.

static inline MMErrorRef MMLibraryDescriptionFolderInfoSetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef theFileInfoKey, MMTypeRef theValue );

Description:: Sets the value of an item in specified library description FolderInfo container.

static inline CFNumberRef MMLibraryDescriptionGetFlags( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, MMErrorRef *outError );

Description:: Gets the flag value from the specified library description. Do not release the returned value.

extern MMTypeRef MMLibraryDescriptionGetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef theItemKey, MMErrorRef *outError );

Description:: Gets an item value in the specified library description.

static inline MMTypeRef MMLibraryDescriptionPropertyGetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef thePropertyKey, MMErrorRef *outError );

Description:: Gets an item value from the specified library description Properties container.

static inline MMErrorRef MMLibraryDescriptionPropertySetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef thePropertyKey, MMTypeRef theValue );

Description:: Sets the value of an item in specified library description Properties container.

static inline MMErrorRef MMLibraryDescriptionSetFlags( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFNumberRef theFlags );

Description:: Sets the value of the flags in the specified library description.

extern MMErrorRef MMLibraryDescriptionSetFolderInfoWithURL( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFURLRef theURL, CFNumberRef theFlags );

Description:: Sets the value of the URLString in the FolderInfo container. Optionally, depending on the value of theFlags parameter, calculates and set the values of the POSIXPath, HFSPath, and BookmarkData keys.

extern MMErrorRef MMLibraryDescriptionSetValue( CFAllocatorRef theAllocator, MMUUIDRef theLibraryDescriptionID, CFStringRef theItemKey, MMTypeRef theValue );

Description:: Sets the value of an item in specified library description.

MMFile

extern CFStringRef MMFileGetURL ( MMUUIDRef theFileID );

Description:: Gets the URL string associated with the specified file id.

extern MMTypeRef MMFileGetValue( CFAllocatorRef theAllocator, MMUUIDRef theFileID, CFStringRef theKey, MMErrorRef *outError );

Description:: Gets the value of the item specified by 'theKey' in the file container.

extern MMErrorRef MMFileSetValue( CFAllocatorRef theAllocator, MMUUIDRef theFileID, CFStringRef theKey, MMTypeRef theValue );

Description:: Sets the value of the item specified by 'theKey' in the file container.

MMProperty

extern MMTypeRef MMPropertyGetValue( CFAllocatorRef theAllocator, MMUUIDRef thePropertyID, CFStringRef theKey, MMErrorRef *outError );

Description:: Gets the value of the item specified by 'theKey' in the property container.

extern MMErrorRef MMPropertySetValue( CFAllocatorRef theAllocator, MMUUIDRef thePropertyID, CFStringRef theKey, MMTypeRef theValue );

Description:: Sets the value of the item specified by 'theKey' in the property container.

MMSearchConfiguration

static inline CFMutableArrayRef MMSearchConfigurationGetLibraryIDs( CFAllocatorRef theAllocator, MMUUIDRef theSearchConfigurationID, MMErrorRef *outError );

Description:: Copies the array of library ids in the specified search configuration.

extern MMTypeRef MMSearchConfigurationGetValue( CFAllocatorRef theAllocator, MMUUIDRef theSearchConfigurationID, CFStringRef theItemKey, MMErrorRef *outError );

Description:: Copies the value of an item in the specified search configuration.

extern MMErrorRef MMSearchConfigurationSetValue( CFAllocatorRef theAllocator, MMUUIDRef theSearchConfigurationID, CFStringRef theItemKey, MMTypeRef theValue );

Description:: Sets the value of an item in specified search configuration.

MMSearchConfigurationDescription

extern MMErrorRef MMSearchConfigurationDescriptionCreate( CFAllocatorRef theAllocator, CFStringRef theConfigurationTitle, MMUUIDRef thePermanentID, CFArrayRef theLibraryIDs );

Description:: Creates a minimal search configuration description. The parameters theConfigurationTitle and thePermanentID are required.

extern MMTypeRef MMSearchConfigurationDescriptionGetValue( CFAllocatorRef theAllocator, MMUUIDRef theSearchConfigurationID, CFStringRef theKey, MMErrorRef *outError );

Description:: Gets the value in the search configuration description for the specified key.

extern MMErrorRef MMSearchConfigurationDescriptionSetValue( CFAllocatorRef theAllocator, MMUUIDRef theSearchConfigurationID, CFStringRef theKey, MMTypeRef theValue );

Description:: Sets the value in the search configuration description for the specified key.

MMError

extern MMErrorRef MMErrorCreate( CFAllocatorRef theAllocator, CFStringRef theDomain, CFNumberRef theErrorNumber, CFStringRef theDescriptionFormat, ... );

Description:: Creates an error description with the specified inputs. The supplied domain is one of kMMErrorDomainOSStatus or kMMErrorDomainPOSIX. The text (possibly resulting from an evaluation of theDescriptionFormat parameter and subsequent arguments) is available from MMErrorGetDescription(). Parameter theDescriptionFormat may be NULL.

extern CFNumberRef MMErrorGetCoreErr ( void );

Description:: Returns a CFNumberRef created with 'coreFoundationUnknownErr' value. Often used with MMErrorCreate().

extern CFStringRef MMErrorGetDescription ( MMErrorRef theError );

Description:: Returns the text description contained in theError or NULL if none is available.

extern CFStringRef MMErrorGetDomain ( MMErrorRef theError );

Description:: Gets the domain string contained in theError.

extern CFNumberRef MMErrorGetNumber ( MMErrorRef theError );

Description:: Gets the error number contained in theError.

extern CFNumberRef MMErrorGetParamErr ( void );

Description:: Returns a CFNumberRef created with 'paramErr' value. Often used with MMErrorCreate().

extern void MMErrorShow( MMErrorRef theError, CFStringRef theFormat, ... );

Description:: Prints the values contained in theError to standard error and optionally displays an additional message.