path: root/fpcsrc/packages/univint/src/MDQuery.pas

{      MDQuery.h
        Copyright (c) 2003-2005, Apple Computer, Inc. All rights reserved.
}

 { Pascal Translation: Gorazd Krosl <gorazd_1957@yahoo.ca>, October 2009 }

{
    Modified for use with Free Pascal
    Version 308
    Please report any bugs to <gpc@microbizz.nl>
}

{$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}
{$mode macpas}
{$packenum 1}
{$macro on}
{$inline on}
{$calling mwpascal}

unit MDQuery;
interface
{$setc UNIVERSAL_INTERFACES_VERSION := $0400}
{$setc GAP_INTERFACES_VERSION := $0308}

{$ifc not defined USE_CFSTR_CONSTANT_MACROS}
    {$setc USE_CFSTR_CONSTANT_MACROS := TRUE}
{$endc}

{$ifc defined CPUPOWERPC and defined CPUI386}
	{$error Conflicting initial definitions for CPUPOWERPC and CPUI386}
{$endc}
{$ifc defined FPC_BIG_ENDIAN and defined FPC_LITTLE_ENDIAN}
	{$error Conflicting initial definitions for FPC_BIG_ENDIAN and FPC_LITTLE_ENDIAN}
{$endc}

{$ifc not defined __ppc__ and defined CPUPOWERPC32}
	{$setc __ppc__ := 1}
{$elsec}
	{$setc __ppc__ := 0}
{$endc}
{$ifc not defined __ppc64__ and defined CPUPOWERPC64}
	{$setc __ppc64__ := 1}
{$elsec}
	{$setc __ppc64__ := 0}
{$endc}
{$ifc not defined __i386__ and defined CPUI386}
	{$setc __i386__ := 1}
{$elsec}
	{$setc __i386__ := 0}
{$endc}
{$ifc not defined __x86_64__ and defined CPUX86_64}
	{$setc __x86_64__ := 1}
{$elsec}
	{$setc __x86_64__ := 0}
{$endc}
{$ifc not defined __arm__ and defined CPUARM}
	{$setc __arm__ := 1}
{$elsec}
	{$setc __arm__ := 0}
{$endc}

{$ifc defined cpu64}
  {$setc __LP64__ := 1}
{$elsec}
  {$setc __LP64__ := 0}
{$endc}


{$ifc defined __ppc__ and __ppc__ and defined __i386__ and __i386__}
	{$error Conflicting definitions for __ppc__ and __i386__}
{$endc}

{$ifc defined __ppc__ and __ppc__}
	{$setc TARGET_CPU_PPC := TRUE}
	{$setc TARGET_CPU_PPC64 := FALSE}
	{$setc TARGET_CPU_X86 := FALSE}
	{$setc TARGET_CPU_X86_64 := FALSE}
	{$setc TARGET_CPU_ARM := FALSE}
	{$setc TARGET_OS_MAC := TRUE}
	{$setc TARGET_OS_IPHONE := FALSE}
	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
{$elifc defined __ppc64__ and __ppc64__}
	{$setc TARGET_CPU_PPC := FALSE}
	{$setc TARGET_CPU_PPC64 := TRUE}
	{$setc TARGET_CPU_X86 := FALSE}
	{$setc TARGET_CPU_X86_64 := FALSE}
	{$setc TARGET_CPU_ARM := FALSE}
	{$setc TARGET_OS_MAC := TRUE}
	{$setc TARGET_OS_IPHONE := FALSE}
	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
{$elifc defined __i386__ and __i386__}
	{$setc TARGET_CPU_PPC := FALSE}
	{$setc TARGET_CPU_PPC64 := FALSE}
	{$setc TARGET_CPU_X86 := TRUE}
	{$setc TARGET_CPU_X86_64 := FALSE}
	{$setc TARGET_CPU_ARM := FALSE}
{$ifc defined(iphonesim)}
 	{$setc TARGET_OS_MAC := FALSE}
	{$setc TARGET_OS_IPHONE := TRUE}
	{$setc TARGET_IPHONE_SIMULATOR := TRUE}
{$elsec}
	{$setc TARGET_OS_MAC := TRUE}
	{$setc TARGET_OS_IPHONE := FALSE}
	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
{$endc}
{$elifc defined __x86_64__ and __x86_64__}
	{$setc TARGET_CPU_PPC := FALSE}
	{$setc TARGET_CPU_PPC64 := FALSE}
	{$setc TARGET_CPU_X86 := FALSE}
	{$setc TARGET_CPU_X86_64 := TRUE}
	{$setc TARGET_CPU_ARM := FALSE}
	{$setc TARGET_OS_MAC := TRUE}
	{$setc TARGET_OS_IPHONE := FALSE}
	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
{$elifc defined __arm__ and __arm__}
	{$setc TARGET_CPU_PPC := FALSE}
	{$setc TARGET_CPU_PPC64 := FALSE}
	{$setc TARGET_CPU_X86 := FALSE}
	{$setc TARGET_CPU_X86_64 := FALSE}
	{$setc TARGET_CPU_ARM := TRUE}
	{ will require compiler define when/if other Apple devices with ARM cpus ship }
	{$setc TARGET_OS_MAC := FALSE}
	{$setc TARGET_OS_IPHONE := TRUE}
	{$setc TARGET_IPHONE_SIMULATOR := FALSE}
{$elsec}
	{$error __ppc__ nor __ppc64__ nor __i386__ nor __x86_64__ nor __arm__ is defined.}
{$endc}

{$ifc defined __LP64__ and __LP64__ }
  {$setc TARGET_CPU_64 := TRUE}
{$elsec}
  {$setc TARGET_CPU_64 := FALSE}
{$endc}

{$ifc defined FPC_BIG_ENDIAN}
	{$setc TARGET_RT_BIG_ENDIAN := TRUE}
	{$setc TARGET_RT_LITTLE_ENDIAN := FALSE}
{$elifc defined FPC_LITTLE_ENDIAN}
	{$setc TARGET_RT_BIG_ENDIAN := FALSE}
	{$setc TARGET_RT_LITTLE_ENDIAN := TRUE}
{$elsec}
	{$error Neither FPC_BIG_ENDIAN nor FPC_LITTLE_ENDIAN are defined.}
{$endc}
{$setc ACCESSOR_CALLS_ARE_FUNCTIONS := TRUE}
{$setc CALL_NOT_IN_CARBON := FALSE}
{$setc OLDROUTINENAMES := FALSE}
{$setc OPAQUE_TOOLBOX_STRUCTS := TRUE}
{$setc OPAQUE_UPP_TYPES := TRUE}
{$setc OTCARBONAPPLICATION := TRUE}
{$setc OTKERNEL := FALSE}
{$setc PM_USE_SESSION_APIS := TRUE}
{$setc TARGET_API_MAC_CARBON := TRUE}
{$setc TARGET_API_MAC_OS8 := FALSE}
{$setc TARGET_API_MAC_OSX := TRUE}
{$setc TARGET_CARBON := TRUE}
{$setc TARGET_CPU_68K := FALSE}
{$setc TARGET_CPU_MIPS := FALSE}
{$setc TARGET_CPU_SPARC := FALSE}
{$setc TARGET_OS_UNIX := FALSE}
{$setc TARGET_OS_WIN32 := FALSE}
{$setc TARGET_RT_MAC_68881 := FALSE}
{$setc TARGET_RT_MAC_CFM := FALSE}
{$setc TARGET_RT_MAC_MACHO := TRUE}
{$setc TYPED_FUNCTION_POINTERS := TRUE}
{$setc TYPE_BOOL := FALSE}
{$setc TYPE_EXTENDED := FALSE}
{$setc TYPE_LONGLONG := TRUE}
uses MacTypes,CFBase,CFString,CFDictionary,CFArray,MDItem;
{$endc} {not MACOSALLINCLUDE}


{$ifc TARGET_OS_MAC}

{$ALIGN POWER}


{!
        @header MDQuery

        MDQuery is a CF-compliant object, and follows the CF conventions,
        and can be used with the CF polymorphic functions, like CFRetain().

        MDQuery encapsulates all queries against the MetaData
        database. Queries gather results or process updates only while
        the current thread's run loop is running. Queries normally
        operate asynchronously, and only send out progress
        notificiations as the list is being collected. The query list
        is kept up to date with respect to value lists and sorting as
        the progress notifications are sent out, so the query is in a
        good state during those events.

        Result Retreval
                An MDQueryRef presents its results as if it were a simple
                array object.  The results can either be MDItemRefs (the
                default) or custom structs, CFTypeRefs, or Objective C
                objects.  For example if the result objects are represented
                as 'FSNodes' (a type defined in the client application) a
                call to MDQueryGetResultAtIndex() will return an FSNode
                object. This is useful, because it allows the Metadata
                library to maintain the results in a form that is directly
                useable in the application.

        Query Sorting
                Sorting the results from a query can be performed in one  of
                two ways. First is to let the library sort the results for you
                by passing an array of attributes to sort on to
                MDQueryCreate(). The default sort provided by MDQueryCreate()
                is a assending sort strings are compared using
                CFStringCompare() with the options kCFCompareNonliteral |
                kCFCompareLocalized | kCFCompareNumerically. CFDataRefs are
                compared by using memcmp() of the data pointers. If an Item
                does not have the attribute, it compares less than the
                attribute that is there.

                If you need to do a more complex sort (like a case insensitive
                sort on CFStringRefs) then you will need to also provide a
                comparitor function and call MDQuerySetSortComparator(), and
                also provide which attributes to sort on to MDQueryCreate().

        Undefined Behavior
                For functions which take an MDQueryRef parameter, if this
                parameter is not a valid MDQueryRef, the behavior is
                undefined. NULL is not a valid MDQueryRef.

                For functions which take CF*Ref parameters, such as
                CFStringRef and CFArrayRef, if this parameter is not a
                valid CF object of the correct type, the behavior is
                undefined. NULL is not a valid CF*Ref.

                Additional constraints or allowed values on parameters
                are noted with the specific functions.

}



{!
        @typedef MDQueryRef
        This is the type of a reference to MDQuerys.
}
type
	MDQueryRef = ^SInt32; { an opaque type }

const
	kMDQuerySynchronous = 1;
	kMDQueryWantsUpdates = 4;
	
type
	MDQueryOptionFlags = SIGNEDLONG;


{!
        @enum MDQueryOptionFlags
        @constant kMDQuerySynchronous Block during the gathering phase.
                If this parameter is true, the function will not return
                until the query has finished gathering the initial
                results. The run loop will run in the default mode, which
                will allow anything registered in that mode with this run
                loop to execute as well. If this parameter is false, the
                function returns immediately after starting the query
                asychronously.
        @constant kMDQueryWantsUpdates When set, after gathering the initial results
                the query will watch for changes in the system which should
                update the list of results. This can be changes which cause
                new files to now match the query, or changes which cause
                files in the result list to continue to match, or no longer
                match, the query. Files which begin to match the query are
                added to the result list, and files which no longer match
                the query expression are removed from the result list.
                Currently, this parameter is ignored if the synchronous
                parameter is true. This is subject to change, and you
                should always pass in the value you want here.
}

{!
        @function MDQueryGetTypeID
        Returns the type identifier of all MDQuery instances.
}
function MDQueryGetTypeID: CFTypeID; external name '_MDQueryGetTypeID';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryCreate
        Creates a new query with the given query expression.
        @param allocator The CFAllocator which should be used to allocate
                memory for the query and its sub-storage. This
                parameter may be NULL in which case the current default
                CFAllocator is used.
        @param queryString The query expression string for this query. The
                syntax for query expressions is explained above in the
                header overview documentation.
        @param valueListAttrs An optional array of attribute names. The
                query will collect the values of these attributes into
                uniqued lists, which can be used or displayed to summarize
                the results of the query, or allow a user to further
                qualify the items for which they are searching. This
                parameter may be NULL if no value lists are desired. Value
                list collection increases CPU usage and significantly
                increases the memory usage of an MDQuery. The attribute
                names are CFStrings.
        @param sortingAttrs An optional array of attribute names. The
                query will results of the query based on the values of
                these attributes. The first name in the array is used as
                the primary sort key, the second as the secondary key, and
                so on. The comparison of like-typed values is a simple,
                literal comparison. This parameter may be NULL if no
                sorting is desired. Sorting increases memory usage and
                significantly increases the CPU usage of an MDQuery.
                However, when possible, it is almost always cheaper to have
                the MDQuery do the sorting, rather than you fetching all
                the results and attributes from each of them and doing the
                sorting yourself. The attribute names are CFStrings.
        @result An MDQueryRef, or NULL on failure. If the query string
                is empty or malformed (invalid syntax), returns NULL.
}
function MDQueryCreate( allocator: CFAllocatorRef; queryString: CFStringRef; valueListAttrs: CFArrayRef; sortingAttrs: CFArrayRef ): MDQueryRef; external name '_MDQueryCreate';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryCreateSubset
        Creates a new query, which is a subset of the given query. Only
                results matched by the given query can be matched by the
                query expression of this query.
        @param allocator The CFAllocator which should be used to allocate
                memory for the query and its sub-storage. This
                parameter may be NULL in which case the current default
                CFAllocator is used.
        @param query The parent query of the new query.
        @param queryString The query expression string for this query.
                This expression in effect may further restrict the matches
                found by the parent query. If the string is empty the
                behavior is undefined.
        @param valueListAttrs An optional array of attribute names. The
                query will collect the values of these attributes into
                uniqued lists, which can be used or displayed to summarize
                the results of the query, or allow a user to further
                qualify the items for which they are searching. This
                parameter may be NULL if no value lists are desired. Value
                list collection increases CPU usage and significantly
                increases the memory usage of an MDQuery. The attribute
                names are CFStrings.
        @param sortingAttrs An optional array of attribute names. The
                query will results of the query based on the values of
                these attributes. The first name in the array is used as
                the primary sort key, the second as the secondary key, and
                so on. The comparison of like-typed values is a simple,
                literal comparison. This parameter may be NULL if no
                sorting is desired. Sorting increases memory usage and
                significantly increases the CPU usage of an MDQuery.
                However, when possible, it is almost always cheaper to have
                the MDQuery do the sorting, rather than you fetching all
                the results and attributes from each of them and doing the
                sorting yourself. The attribute names are CFStrings.
        @result An MDQueryRef, or NULL on failure. If the query string
                is empty or malformed (invalid syntax), returns NULL.
}
function MDQueryCreateSubset( allocator: CFAllocatorRef; query: MDQueryRef; queryString: CFStringRef; valueListAttrs: CFArrayRef; sortingAttrs: CFArrayRef ): MDQueryRef; external name '_MDQueryCreateSubset';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryCopyQueryString
        Returns the query string of the query.
        @param query The query to be interrogated.
        @result The query string of the query.
}
function MDQueryCopyQueryString( query: MDQueryRef ): CFStringRef; external name '_MDQueryCopyQueryString';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryCopyValueListAttributes
        Returns the list of attribute names for which the query is
                collecting the lists of values.
        @param query The query to be interrogated.
        @result The list of value list attribute names of the query.
}
function MDQueryCopyValueListAttributes( query: MDQueryRef ): CFArrayRef; external name '_MDQueryCopyValueListAttributes';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryCopySortingAttributes
        Returns the list of attribute names the query is using to sort
                the results.
        @param query The query to be interrogated.
        @result The list of sorting attribute names of the query.
}
function MDQueryCopySortingAttributes( query: MDQueryRef ): CFArrayRef; external name '_MDQueryCopySortingAttributes';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @typedef MDQueryBatchingParams
        Structure containing the progress notification batching
                parameters of an MDQuery. The first notification can be
                triggered by the either first_max_num or first_max_ms limit
                being exceeded. Subsequent notifications are triggered by
                either the progress_max_num or progress_max_ms limit. The
                default batching parameters are undefined and subject to
                change.
        @field first_max_num The maximum number of results that can
                accumulate before a progress notification is sent out
                by the MDQuery, for the first notification.
        @field first_max_ms The maximum number of milliseconds that can
                pass before a progress notification is sent out. This
                value is advisory, in that the notification will be
                triggered "at some point after first_max_ms milliseconds
                have passed since the query began accumulating results",
                but generally not very long after, for the first
                progress notification.
        @field progress_max_num The maximum number of results that can
                accumulate before a progress notification is sent out
                by the MDQuery, for notifications after the first,
                during the initial gathering phase of the query.
        @field progress_max_ms The maximum number of milliseconds that can
                pass before a progress notification is sent out. This
                value is advisory, in that the notification will be
                triggered "at some point after first_max_ms milliseconds
                have passed since the query began accumulating results",
                but generally not very long after, for progress
                notifications after the first, during the initial
                gathering phase of the query.
        @field update_max_num The maximum number of results that can
                accumulate before an update notification is sent out
                by the MDQuery, for notifications after the gathering
                phase of the query has finished.
        @field update_max_ms The maximum number of milliseconds that can
                pass before a progress notification is sent out. This
                value is advisory, in that the notification will be
                triggered "at some point after first_max_ms milliseconds
                have passed since the query began accumulating results",
                but generally not very long after, for update notifications
                after the gathering phase of the query has finished.
}
type
	MDQueryBatchingParams = record
		first_max_num: size_t;
		first_max_ms: size_t;
		progress_max_num: size_t;
		progress_max_ms: size_t;
		update_max_num: size_t;
		update_max_ms: size_t;
	end;

{!
        @function MDQueryGetBatchingParameters
        Returns the current parameters that control batching of progress
                notifications.
        @param query The query to be interrogated.
        @result An MDQueryBatchingParams structure with the current
                batching parameters.
}
function MDQueryGetBatchingParameters( query: MDQueryRef ): MDQueryBatchingParams; external name '_MDQueryGetBatchingParameters';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQuerySetBatchingParameters
        @param query The query whose batching parameters are to be set.
        @param params An MDQueryBatchingParams structure with the batching
                parameters to set.
}
procedure MDQuerySetBatchingParameters( query: MDQueryRef; params: MDQueryBatchingParams ); external name '_MDQuerySetBatchingParameters';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @typedef MDQueryCreateResultFunction
        Type of the callback function used to create the result objects
                stored and returned by an MDQuery. The function may
                hold onto the given MDItemRef in some other data
                structure, but must retain it for it to remain valid.
                The create-result function is called lazily as results
                are requested from a query, so it will not generally
                be called on all results, if in fact any. This avoids
                the cost of creating potentially hundreds of thousands
                of what might be temporary objects.
        @param query The MDQuery instance.
        @param item The default MDItemRef for the result.
        @param context The user-defined context parameter given to
                MDQuerySetCreateResultFunction().
        @result The function must return a pointer-sized value that can
                be managed with the callbacks which were set at the same
                time the create function was given to the query. The
                value must be returned with a reference (such as if the
                retain callback had been called on it), as implied by the
                Create name. If this function doesn't wish to create a
                new object, it can return the given MDItemRef, but must
                also return it with a new retain, and the callbacks must
                be able to handle an MDItemRef as an input value. If
                this function returns NULL, NULL will be stored for the
                moment in the query, MDQueryGetResultAtIndex() may return
                NULL for that result, and the next time the query wants
                the result, it will call this function again.
}
type
	MDQueryCreateResultFunction = function( query: MDQueryRef; item: MDItemRef; context: UnivPtr ): UnivPtr;

{!
        @function MDQuerySetCreateResultFunction
        Sets the function used to create the result objects of the
                MDQuery. If no create function is set on an MDQuery,
                the default result objects are MDItemRefs. Results
                created after a create function is set will be created
                through the given create function, but values created
                before the function was set (or after it is unset) are
                not modified. Therefore it is not advisable to change
                this function after MDQueryExecute() has been called
                with the query. The create-result function is called
                lazily as results are requested from a query, so it will
                not generally be called on all results, if in fact any.
                This avoids the cost of creating potentially hundreds
                of thousands of what might be temporary objects.
        @param query The query to whose result create function is to be set.
        @param func The callback function the MDQuery will use to
                create its results, such as those returned from
                MDQueryGetResultAtIndex(). This parameter
                may be NULL, in which case any previous result creation
                settings are cancelled, and the MDQuery will subsequently
                produce MDItemRefs. If the function (when the parameter is
                not NULL) is not of type MDQueryCreateResultFunction or
                does not behave as a MDQueryCreateResultFunction must,
                the behavior is undefined.
        @param context A pointer-sized user-defined value, which is
                passed as the third parameter to the create function,
                but is otherwise unused by MDQuery. The MDQuery does
                not retain the context in any way, so it must remain
                valid for at least the lifetime of the query. If the
                context is not what is expected by the create function,
                the behavior is undefined.
        @param cb A pointer to a CFArrayCallBacks structure
                initialized with the callbacks for the query to use to
                manage the created result objects. A copy of the
                contents of the callbacks structure is made, so that a
                pointer to a structure on the stack can be passed in, or
                can be reused for multiple query creations. Only version
                0 of the CFArrayCallBacks is supported. The retain field
                may be NULL, in which case the MDQuery will do nothing to
                add a retain to the created results for the query. The
                release field may be NULL, in which case the MDQuery will
                do nothing to remove the query's retain (such as the one
                it gets from the create function) on the result objects
                when the query is destroyed. If the copyDescription field
                is NULL, the query will create a simple description for
                the result objects. If the equal field is NULL, the query
                will use pointer equality to test for equality of results.
                This callbacks parameter itself may be NULL, which is
                treated as if a valid structure of version 0 with all
                fields NULL had been passed in. Otherwise, if any of the
                fields are not valid pointers to functions of the correct
                type, or this parameter is not a valid pointer to a
                CFArrayCallBacks callbacks structure, the behavior is
                undefined. If any of the value values returned from the
                create function is not one understood by one or more of
                the callback functions, the behavior when those callback
                functions are used is undefined. For example, if the create
                function can return NULL, then NULL must be understood by
                the callback functions as a possible parameter. The retain
                and release callbacks must be a matched set -- do not
                assume that the retain function will be unused or that
                additional reference counts will not be taken on the
                created results.
}
procedure MDQuerySetCreateResultFunction( query: MDQueryRef; func: MDQueryCreateResultFunction; context: UnivPtr; {const} cb: CFArrayCallBacksPtr ); external name '_MDQuerySetCreateResultFunction';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @typedef MDQueryCreateValueFunction
        Type of the callback function used to create the value objects
                stored and returned by an MDQuery. The function may
                hold onto the given attribute name and/or value in some
                other data structure, but must retain them for them to
                remain valid.
        @param query The MDQuery instance.
        @param attrName The attribute name of the value.
        @param attrValue The default value of the value.
        @param context The user-defined context parameter given to
                MDQuerySetCreateValueFunction().
        @result The function must return a pointer-sized value that can
                be managed with the callbacks which were set at the same
                time the create function was given to the query. The
                value must be returned with a reference (such as if the
                retain callback had been called on it), as implied by the
                Create name. If this function doesn't wish to create a
                new object, it can return the given CFTypeRef, but must
                also return it with a new retain, and the callbacks must
                be able to handle a CFTypeRef as an input value.
}
type
	MDQueryCreateValueFunction = function( query: MDQueryRef; attrName: CFStringRef; attrValue: CFTypeRef; context: UnivPtr ): UnivPtr;

{!
        @function MDQuerySetCreateValueFunction
        Sets the function used to create the value objects of the
                MDQuery. These are the values of the value lists that
                were requested when the query was created. If no create
                function is set on an MDQuery, the default value objects
                are the CFTypeRef values of the attributes. Values
                created after a create function is set will be created
                through the given create function, but values created
                before the function was set (or after it is unset)
                are not modified. Therefore it is not advisable to
                change this function after MDQueryExecute() has been
                called with the query.
        @param query The query to whose value create function is to be set.
        @param func The callback function the MDQuery will use to
                create the value list values, such as those returned from
                MDQueryCopyValuesOfAttribute(). This parameter
                may be NULL, in which case any previous value creation
                settings are cancelled, and the MDQuery will subsequently
                produce the default CFTypeRefs. If the function (when the
                parameter is not NULL) is not of type
                MDQueryCreateValueFunction or does not behave as a
                MDQueryCreateValueFunction must, the behavior is undefined.
        @param context A pointer-sized user-defined value, which is
                passed as the fourth parameter to the create function,
                but is otherwise unused by MDQuery. The MDQuery does
                not retain the context in any way, so it must remain
                valid for at least the lifetime of the query. If the
                context is not what is expected by the create function,
                the behavior is undefined.
        @param cb A pointer to a CFArrayCallBacks structure
                initialized with the callbacks for the query to use to
                manage the created value objects. A copy of the
                contents of the callbacks structure is made, so that a
                pointer to a structure on the stack can be passed in, or
                can be reused for multiple query creations. Only version
                0 of the CFArrayCallBacks is supported. The retain field
                may be NULL, in which case the MDQuery will do nothing to
                add a retain to the created values for the query. The
                release field may be NULL, in which case the MDQuery will
                do nothing to remove the query's retain (such as the one
                it gets from the create function) on the value objects
                when the query is destroyed. If the copyDescription field
                is NULL, the query will create a simple description for
                the value objects. If the equal field is NULL, the query
                will use pointer equality to test for equality of values.
                This callbacks parameter itself may be NULL, which is
                treated as if a valid structure of version 0 with all
                fields NULL had been passed in. Otherwise, if any of the
                fields are not valid pointers to functions of the correct
                type, or this parameter is not a valid pointer to a
                CFArrayCallBacks callbacks structure, the behavior is
                undefined. If any of the value values returned from the
                create function is not one understood by one or more of
                the callback functions, the behavior when those callback
                functions are used is undefined. For example, if the
                create function can return NULL, then NULL must be
                understood by the callback functions as a possible
                parameter. The retain and release callbacks must be a
                matched set -- do not assume that the retain function will
                be unused or that additional reference counts will not be
                taken on the created values.
}
procedure MDQuerySetCreateValueFunction( query: MDQueryRef; func: MDQueryCreateValueFunction; context: UnivPtr; {const} cb: CFArrayCallBacksPtr ); external name '_MDQuerySetCreateValueFunction';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryExecute
        Run the query, and populate the query with the results. Queries
                only gather results or process updates while the current
                thread's run loop is running. Queries normally operate
                asynchronously, and send out progress and update
                notifications to report changes to the list of results
                that has been collected. Queries have two phases: the
                initial gathering of all currently matching results, and
                a second live-update phase where queries monitor the
                state of the system and update themselves to external
                changes in files or the operating environment (for example,
                as time advances, files which did not match the query
                when it was started may later match the query). Query
                notifications are posted within the context of the same
                thread which executes the query.
                [[There are three operational modes: (1) synchronous static
                queries, which collect the list of current results and then
                do not watch for updates to the results, (2) asynchronous
                static queries, which collect the results asychronously
                after this function returns, and then do not watch for
                updates to the results, and (3) asynchronous live queries
                which collect the initial results asychronously after this
                function returns, and then do watch for updates to the
                results, until the query is destroyed. There is little
                reason not to allow the fourth case, synchronous collection
                of initial results, followed by asynchronous monitoring
                for updates, so this may change in the future.]]
        @param query The query to execute.
        @param optionFlags Bitwise or of MDQueryOptionFlags
        @result Returns true if the query was started (executed in the case
                of a synchronous query), false otherwise. Queries cannot be
                executed more than once.
}
function MDQueryExecute( query: MDQueryRef; optionFlags: CFOptionFlags ): Boolean; external name '_MDQueryExecute';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryStop
        Stops the query from ever generating more results. Queries may be
                executed only once, so a stopped query cannot be
                restarted. The query will also not generate any result
                updates. The query is static after this function returns.
                The query will do final processing of results that have
                come in but not yet been processed (because, say, the
                batching parameters hasn't triggered that yet). That may
                trigger a progress notification, so be aware of that if
                you are stopping a query from within your progress note
                handler; that is, during this function, a recursive
                progress and/or finished notification might occur, which
                might recursively call your notification handler. It is
                safe to call this function recursively. You would call
                this function to stop a query that is generating way too
                many results to be useful, but still want to access the
                results that have come in so far. If a query is stopped
                before the gathering phase finishes, it will not report
                itself as finished, nor will it send out a finished
                notification.
        @param query The query to stop.
}
procedure MDQueryStop( query: MDQueryRef ); external name '_MDQueryStop';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryDisableUpdates
        Disables updates to the query result list. This should be called
                before iterating through the list of results to prevent
                the result list from changing during the iteration. The
                disabled state is a counter, and disabling can be done
                recursively and from different threads.
        @param query The query for which updates are to be disabled.
}
procedure MDQueryDisableUpdates( query: MDQueryRef ); external name '_MDQueryDisableUpdates';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryEnableUpdates
        Re-enables updates to the query result list. This should be called
                when finished iterating through the list of results, to
                allow changes to the result list to occur. Changes will
                be allowed when all the disables have been matched by a
                corresponding enable.
        @param query The query for which updates are to be enabled.
}
procedure MDQueryEnableUpdates( query: MDQueryRef ); external name '_MDQueryEnableUpdates';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryIsGatheringComplete
        Returns true if the first phase of a query, the initial result
                gathering, has finished.
        @param query The query to be interrogated.
        @result A boolean indicating whether or not the first phase
                of a query has completed.
 }
function MDQueryIsGatheringComplete( query: MDQueryRef ): Boolean; external name '_MDQueryIsGatheringComplete';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryGetResultCount
        Returns the number of results currently collected by the query.
                Note that the number of results in a query will change
                over time as the query's result list is updated.
        @param query The query to be interrogated.
        @result The number of results in the query.
}
function MDQueryGetResultCount( query: MDQueryRef ): CFIndex; external name '_MDQueryGetResultCount';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryGetResultAtIndex
        Returns the current result at the given index. This function
                causes the result object to be created if it hasn't
                been created already. For performance reasons, it is
                not advisable to ask for results that you don't need,
                to avoid the cost of creating them. If possible, call
                this function to fetch only the results you need to
                display or otherwise process. Note that the index of
                a particular result will change over time, as the
                query's result list is updated.
        @param query The query to be interrogated.
        @param idx The index into the query's result list. If the index is
                negative, or is equal to or larger than the current
                number of results in the query, the behavior is undefined.
        @result Returns the MDItemRef currently at the given index, or
                if a result-create function has been set, returns the
                result returned by that function.
}
function MDQueryGetResultAtIndex( query: MDQueryRef; idx: CFIndex ): UnivPtr; external name '_MDQueryGetResultAtIndex';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryGetIndexOfResult
        Returns the current index of the given result. If a result-create
                function has been set, and the equal callback is non-NULL,
                it will be used to test the query's results against the
                candidate result. Note that the index of a result will
                change over time, as the query's result list is updated.
        @param query The query to be interrogated.
        @param result The candidate result object for which to search.
                If a custom create-result function has been set, and this
                parameter is not a valid result object that the provided
                callbacks can handle, the behavior is undefined. If a custom
                create-result function has not been set, this parameter
                must be a valid MDItemRef.
        @result The index of the given result, or kCFNotFound if the
                value is not one of the query's existing results. If
                you provided a custom result creation function, 
                as well as a custom object comparator function,
                result will be objects created by that function.
}
function MDQueryGetIndexOfResult( query: MDQueryRef; result: {const} UnivPtr ): CFIndex; external name '_MDQueryGetIndexOfResult';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryGetAttributeValueOfResultAtIndex
        Returns the value of the named attribute for the result at
                the given index.
        @param query The query to be interrogated.
        @param name The attribute name for which to return the values.
                If the attribute is not one of those requested in the
                valueListAttrs or sortingAttrs parameters to one of
                the query creation functions, the result will be NULL.
        @param idx The index into the query's result list. If the index is
                negative, or is equal to or larger than the current
                number of results in the query, the behavior is undefined.
        @result The value of the attribute, or NULL if the attribute
                doesn't exist in the query on that result.
}
function MDQueryGetAttributeValueOfResultAtIndex( query: MDQueryRef; name: CFStringRef; idx: CFIndex ): UnivPtr; external name '_MDQueryGetAttributeValueOfResultAtIndex';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryCopyValuesOfAttribute
        Returns the list of values, from the results of the query, of the
                named attribute. The list is not ordered in any way. The
                list contains only one occurrence of each value. Note that
                this list may change over time, as the query's result list
                is updated.
        @param query The query to be interrogated.
        @param name The attribute name for which to return the values.
                If the attribute is not one of those requested in the
                valueListAttrs parameter to one of the query creation
                functions, the behavior is undefined.
        @result A CFArray holding the value objects for that attribute.
}
function MDQueryCopyValuesOfAttribute( query: MDQueryRef; name: CFStringRef ): CFArrayRef; external name '_MDQueryCopyValuesOfAttribute';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @function MDQueryGetCountOfResultsWithAttributeValue
        Returns the number of results which have the given attribute and
                attribute value. Note that this count may change over time,
                as the query's result list is updated.
        @param query The query to be interrogated.
        @param name The attribute name for which to return the number
                of results with the given value. If the attribute is not
                one of those requested in the valueListAttrs parameter to
                one of the query creation functions, the behavior is
                undefined.
        @param value The attribute value for which to return the number
                of results with that value. This parameter may be NULL,
                in which case the number of results that do not contain
                the named attribute is returned.
        @result The number of results with that attribute and value.
}
function MDQueryGetCountOfResultsWithAttributeValue( query: MDQueryRef; name: CFStringRef; value: CFTypeRef ): CFIndex; external name '_MDQueryGetCountOfResultsWithAttributeValue';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @typedef MDQuerySortComparatorFunction
        Type of the callback function used to sort the results of an
                MDQuery.
        @param query The MDQuery instance.
        @param attrs1 A C array of attribute values for a result. The
                values occur in the array in the same order and position
                that the attribute names were passed in the sortingAttrs
                array when the query was created. The values of the
                attributes might be NULL, if the attribute doesn't exist
                on a result or if read access to that attribute is not
                allowed.
        @param attrs2 A C array of attribute values for a result. The
                values occur in the array in the same order and position
                that the attribute names were passed in the sortingAttrs
                array when the query was created. The values of the
                attributes might be NULL, if the attribute doesn't exist
                on a result or if read access to that attribute is not
                allowed.
        @param context The user-defined context parameter given to
                MDQuerySetSortComparator().
        @result The function must return one of the CFComparisonResults
                kCFCompareLessThan, kCFCompareEqualTo, or
                kCFCompareGreaterThan. There is no provision for unordered
                results. The comparison must be a total order relation,
                and additionally produce temporally identical results (that
                is, produce the same results for the same inputs in the
                future as now), for the sort results to be predictable.
}
type
	MDQuerySortComparatorFunction = function( {const} attrs1: {variable-size-array} CFTypeRefPtr; {const} attrs2: {variable-size-array} CFTypeRefPtr; context: UnivPtr ): CFComparisonResult;

{!
        @function MDQuerySetSortComparator
        Sets the function used to sort the results of an MDQuery. You
                may set the comparator function as many times as you
                like, even while the query is executing. Whenever the
                comparator function is set, all results are re-sorted
                using the new comparator function before the function
                returns. The function pointer can be NULL to cancel
                custom sorting and revert to the default sorting.
                The default sort provided by MDQueryCreate()
                is a assending sort strings are compared using
                CFStringCompare() with the options kCFCompareNonliteral |
                kCFCompareLocalized | kCFCompareNumerically. CFDataRefs are
                compared by using memcmp() of the data pointers.
        @param query The query to whose result sort function is to be set.
        @param func The callback function the MDQuery will use to
                sort its results. If the function (when the parameter is
                not NULL) is not of type MDQuerySortComparatorFunction or
                does not behave as a MDQuerySortComparatorFunction must,
                the behavior is undefined. The function pointer may
                be NULL to cancel any custom comparator.
        @param context A pointer-sized user-defined value, which is
                passed as the third parameter to the sort function,
                but is otherwise unused by MDQuery. The MDQuery does
                not retain the context in any way, so it must remain
                valid for the lifetime of the query or until the sort
                function is set again. If the context is not what is
                expected by the comparator, the behavior is undefined.
}
procedure MDQuerySetSortComparator( query: MDQueryRef; comparator: MDQuerySortComparatorFunction; context: UnivPtr ); external name '_MDQuerySetSortComparator';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)


{!
        @constant kMDQueryProgressNotification
        The name of the notification sent to indicate changes to the
                query's results list during the initial gathering phase
                of a query's execution. Mostly adds will occur during
                this phase, but removals and changes can also occur, as
                in any update. This info dictionary parameter of the
                notification can carry the kMDQueryUpdateChangedItems
                and kMDQueryUpdateRemovedItems keys. Note that these
                keys may be have empty arrays for values, or be missing,
                if there are no changes of that particular type. For
                performance reasons, added results are not indicated in
                progress notifications (to avoid the cost of creating
                the result objects). These notifications are sent out
                by a query before the kMDQueryDidFinishNotification.
}
var kMDQueryProgressNotification: CFStringRef; external name '_kMDQueryProgressNotification'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @constant kMDQueryDidFinishNotification
        The name of the notification sent to indicate that the query has
                finished with the initial result-gathering phase, and may
                now proceed into the live-update phase (if that option
                was chosen when the query was executed). This notification
                often shortly follows after the last progress notification.
                It is usually not necessary to update any displayed UI in
                response to this notification, since it doesn't indicate
                any change in the result list of a query.
}
var kMDQueryDidFinishNotification: CFStringRef; external name '_kMDQueryDidFinishNotification'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @constant kMDQueryDidUpdateNotification
        The name of the notification sent to indicate changes to the
                query's results list during the second, live-update, phase
                of a query's execution. This notification can carry the
                kMDQueryUpdateAddedItems, kMDQueryUpdateChangedItems,
                and kMDQueryUpdateRemovedItems keys in the info
                dictionary parameter of the notification. Note that these
                keys may be have empty arrays for values, or be missing,
                if there are no changes of that particular type. These
                notifications are sent out by a query after the
                kMDQueryDidUpdateNotification.
}
var kMDQueryDidUpdateNotification: CFStringRef; external name '_kMDQueryDidUpdateNotification'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @constant kMDQueryUpdateAddedItems
        The name of the key in a query notification's info dictionary
                which identifies the list of added results. A result is
                added if the file contents or some metadata attribute
                of it is changed, and it now matches the query. Result
                objects are created for the newly added results, to be
                put in the list.
}
var kMDQueryUpdateAddedItems: CFStringRef; external name '_kMDQueryUpdateAddedItems'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @constant kMDQueryUpdateChangedItems
        The name of the key in a query notification's info dictionary
                which identifies the list of changed results. A result
                is changed if the file contents or some metadata
                attribute of it is changed, but it still matches the
                query. The list only contains result objects which have
                previously been created, and does not indicate results
                which have been changed for which result objects have
                not been created.
                [[This is for performance reasons, to avoid creating
                result objects just to represent a change of a result
                which has not been looked at, but this semantic may
                change.]]
}
var kMDQueryUpdateChangedItems: CFStringRef; external name '_kMDQueryUpdateChangedItems'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @constant kMDQueryUpdateRemovedItems
        The name of the key in a query notification's info dictionary
                which identifies the list of removed results. A result
                can be removed if it no longer matches the query. The
                list only contains result objects which have previously
                been created, and does not indicate results which have
                been removed for which result objects have not been
                created.
                [[This is for performance reasons, to avoid creating
                temporary result objects just to represent the deletion
                of the result, but this semantic may change.]]
}
var kMDQueryUpdateRemovedItems: CFStringRef; external name '_kMDQueryUpdateRemovedItems'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
        @constant kMDQueryResultContentRelevance
        The name of a query-specific attribute for use in sorting.
                The relevance of an item is a CFNumberRef with a
                floating point value. This is the relevance for
                content searches.
                The maximum and minimum values for a particular
                search cannot be determined until all of the results
                have been returned.  If there are multiple
                kMDItemTextContent predicates in the query, no
                relevance is returned.
                This is an attribute of a result item that is
                specific to the item in the context of the query.
                Also, the relevance does not compare the result
                relative to the other results of a query, but is
                computed just on the result item itself. Finally,
                this is only the relevance value for content,
                not a relevance for the item as a whole. The
                relevance attribute may not even be computed for
                an item if the item is found to match the query
                through evaluation of other attributes of the
                item than its contents. If the value is not
                computed, it is treated as an attribute on the
                item which does not exist (for sorting purposes,
                for example).
}
var kMDQueryResultContentRelevance: CFStringRef; external name '_kMDQueryResultContentRelevance'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
    @function MDQuerySetSearchScope
    @discussion Use MDQuerySetSearchScope to limit the results
             returned by the query engine to those MDItemRefs that
             appear  within the specified directories.  This may be
             used to limit searching to particular volumes. Tilde
			 paths, or environment variables are not expanded.
			 Calling this multiple times will replace the previous
			 options. This must be called before the query is executed.
    @param query The query object to modify.
    @param scopeDirectories a CFArray of CFStringRef or CFURLRef objects which
           specify where to search.  For conveinience, the kMDQueryScopeHome,
			kMDQueryScopeComputer and kMDQueryScopeNetwork constants may also
			be present in this array.
    @param scopeOptions additional options for modifying the search.
           Currently, pass 0 (zero).
 }

procedure MDQuerySetSearchScope( query: MDQueryRef; scopeDirectories: CFArrayRef; scopeOptions: OptionBits ); external name '_MDQuerySetSearchScope';
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
@constant kMDQueryScopeHome
	A constant, which can be passed in the scopeDirectories array, to specify
	that the search should be restricted to the volume and directory that contains
	the current user's home directory
 }
var kMDQueryScopeHome: CFStringRef; external name '_kMDQueryScopeHome'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
@constant kMDQueryScopeComputer
	A constant, which can be passed in the scopeDirectories array, to specify
	that the search should be restricted to all locally mounted volumes, plus the user's
	home directory (which may be on a remote volume).
 }
var kMDQueryScopeComputer: CFStringRef; external name '_kMDQueryScopeComputer'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
@constant kMDQueryScopeNetwork
	A constant, which can be passed in the scopeDirectories array, to specify
	that the search should include all user mounted remote volumes.
 }
var kMDQueryScopeNetwork: CFStringRef; external name '_kMDQueryScopeNetwork'; (* attribute const *)
(* AVAILABLE_MAC_OS_X_VERSION_10_4_AND_LATER *)

{!
 @function MDQuerySetMaxCount
 @discussion Use MDQuerySetMaxCount to limit the number of results
 returned by the query engine.  This must be called before the query is executed.
 @param query The query object to modify.
 @param size The maximum number of results desired.
 }
procedure MDQuerySetMaxCount( query: MDQueryRef; size: CFIndex ); external name '_MDQuerySetMaxCount';
(* AVAILABLE_MAC_OS_X_VERSION_10_5_AND_LATER *)

{$endc} {TARGET_OS_MAC}
{$ifc not defined MACOSALLINCLUDE or not MACOSALLINCLUDE}

end.
{$endc} {not MACOSALLINCLUDE}