Mac Developer Library

Developer

CoreServices Framework Reference MDQuery Reference

Options
Deployment Target:

On This Page
Language:

MDQuery Reference

MDQuery is a CF-compliant object, follows the CF conventions, and can be used with the CF polymorphic functions, such as CFRetain. MDQuery encapsulates queries against the System store of the file metadata.

An MDQuery normally executes asynchronously and posts progress notifications as the results are collected. During the gathering phase the query results conform to the specified value lists and sorting.

MDQuery gathers results and processes updates only while the current thread's run loop is running.

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

For functions that 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.

Functions

  • Creates a new query instance.

    Declaration

    Swift

    func MDQueryCreate(_ allocator: CFAllocator!, _ queryString: CFString!, _ valueListAttrs: CFArray!, _ sortingAttrs: CFArray!) -> MDQuery!

    Objective-C

    MDQueryRef MDQueryCreate ( CFAllocatorRef allocator, CFStringRef queryString, CFArrayRef valueListAttrs, CFArrayRef sortingAttrs );

    Parameters

    allocator

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

    queryString

    The query expression string for this query.

    valueListAttrs

    An optional array of attribute names. The query will collect the values of these attributes into uniqued lists that can be used to summarize the results of the query and allow the user to further qualify the search. This parameter may be NULL if no value lists are required. Value list collection increases CPU usage and significantly increases the memory usage of an MDQuery. The attribute names are CFStrings.

    sortingAttrs

    A n array of attribute names used to sort the results, or NULL if no sorting is required. 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. Sorting increases memory usage and significantly increases the CPU usage of an MDQuery. It is usually more efficient to allow the MDQuery to sort the results than retrieving the values and sorting the results yourself. The attribute names are CFStrings.

    Return Value

    An MDQueryRef, or NULL on failure. If the query string is empty or malformed the function returns NULL.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Creates a new query that is a subset of the specified parentquery.

    Declaration

    Swift

    func MDQueryCreateSubset(_ allocator: CFAllocator!, _ query: MDQuery!, _ queryString: CFString!, _ valueListAttrs: CFArray!, _ sortingAttrs: CFArray!) -> MDQuery!

    Objective-C

    MDQueryRef MDQueryCreateSubset ( CFAllocatorRef allocator, MDQueryRef query, CFStringRef queryString, CFArrayRef valueListAttrs, CFArrayRef sortingAttrs );

    Parameters

    allocator

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

    query

    The parent query

    queryString

    The query expression string for this query.

    valueListAttrs

    An optional array of attribute names. The query will collect the values of these attributes into uniqued lists that can be used to summarize the results of the query and allow the user to further qualify the search. This parameter may be NULL if no value lists are required. Value list collection increases CPU usage and significantly increases the memory usage of an MDQuery. The attribute names are CFStrings.

    sortingAttrs

    A n array of attribute names used to sort the results, or NULL if no sorting is required. 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. Sorting increases memory usage and significantly increases the CPU usage of an MDQuery. It is usually more efficient to allow the MDQuery to sort the results than retrieving the values and sorting the results yourself. The attribute names are CFStrings.

    Return Value

    An MDQueryRef, or NULL on failure. If the query string is empty or malformed the function returns NULL.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Sets the search scope for a query instance.

    Declaration

    Swift

    func MDQuerySetSearchScope(_ query: MDQuery!, _ scopeDirectories: CFArray!, _ scopeOptions: OptionBits)

    Objective-C

    void MDQuerySetSearchScope ( MDQueryRef query, CFArrayRef scopeDirectories, OptionBits scopeOptions );

    Parameters

    query

    The query object to modify.

    scopeDirectories

    A CFArray of CFStringRef or CFURLRef objects which specify where to search. For convenience the kMDQueryScopeHome, kMDQueryScopeComputer and kMDQueryScopeNetwork constants may also be included in the array.

    scopeOptions

    Additional options for modifying the search. Currently you must pass 0.

    Discussion

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Sets the dispatch queue on which query results will be delivered by MDQueryExecute.

    Declaration

    Swift

    func MDQuerySetDispatchQueue(_ query: MDQuery!, _ queue: dispatch_queue_t!)

    Objective-C

    void MDQuerySetDispatchQueue ( MDQueryRef query, dispatch_queue_t queue );

    Parameters

    query

    The query.

    queue

    The dispatch queue on which results should be delivered.

    Discussion

    It is not advisable to change set dispatch queue after MDQueryExecute has been called with the query.

    Setting the dispatch queue for a synchronous query (kMDQuerySynchronous) has no effect.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.6 and later.

  • Sets the maximum number of results returned.

    Declaration

    Swift

    func MDQuerySetMaxCount(_ query: MDQuery!, _ size: CFIndex)

    Objective-C

    void MDQuerySetMaxCount ( MDQueryRef query, CFIndex size );

    Parameters

    query

    The query.

    size

    The maximum number of return results.

    Discussion

    This must be called before the query is executed.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.5 and later.

  • Returns the current parameters that control the batching of progress notifications.

    Declaration

    Swift

    func MDQueryGetBatchingParameters(_ query: MDQuery!) -> MDQueryBatchingParams

    Objective-C

    MDQueryBatchingParams MDQueryGetBatchingParameters ( MDQueryRef query );

    Parameters

    query

    The query.

    Return Value

    An MDQueryBatchingParams structure with the current batching parameters.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Set the query batching parameters.

    Declaration

    Swift

    func MDQuerySetBatchingParameters(_ query: MDQuery!, _ params: MDQueryBatchingParams)

    Objective-C

    void MDQuerySetBatchingParameters ( MDQueryRef query, MDQueryBatchingParams params );

    Parameters

    query

    The query.

    params

    An MDQueryBatchingParams structure with the batching parameters to set.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the list of attribute names for which values are being collected by the query.

    Declaration

    Swift

    func MDQueryCopyValueListAttributes(_ query: MDQuery!) -> CFArray!

    Objective-C

    CFArrayRef MDQueryCopyValueListAttributes ( MDQueryRef query );

    Parameters

    query

    The query.

    Return Value

    A CFArrayRef containing the attribute names of the collected values.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the list of attribute names used to sort the results.

    Declaration

    Swift

    func MDQueryCopySortingAttributes(_ query: MDQuery!) -> CFArray!

    Objective-C

    CFArrayRef MDQueryCopySortingAttributes ( MDQueryRef query );

    Parameters

    query

    The query.

    Return Value

    A CFArrayRef containing the attribute names used to sort the query results.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the query string of the query.

    Declaration

    Swift

    func MDQueryCopyQueryString(_ query: MDQuery!) -> CFString!

    Objective-C

    CFStringRef MDQueryCopyQueryString ( MDQueryRef query );

    Parameters

    query

    The query.

    Return Value

    A CFStringRef containing the query string.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Sets the function used to create the result objects of the MDQuery.

    Declaration

    Swift

    func MDQuerySetCreateResultFunction(_ query: MDQuery!, _ `func`: MDQueryCreateResultFunction, _ context: UnsafeMutablePointer<Void>, _ cb: UnsafePointer<CFArrayCallBacks>)

    Objective-C

    void MDQuerySetCreateResultFunction ( MDQueryRef query, MDQueryCreateResultFunction func, void *context, const CFArrayCallBacks *cb );

    Parameters

    query

    The query.

    func

    The callback function the MDQuery will use to create its results, such as those returned by the function MDQueryGetResultAtIndex. This parameter may be NULL, in which case any previous result creation settings are cancelled and the MDQuery will subsequently produce MDItemRefs. If a function is specified and is not of type MDQueryCreateResultFunction or does not behave as a MDQueryCreateResultFunction must, the behavior is undefined.

    context

    A pointer-sized user-defined value, that is passed as the third parameter to the create function. MDQuery does not use this value, does not retain the context in any way, and requires that the context be valid for the lifetime of the query. If the context is not what is expected by the create function, the behavior is undefined.

    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 not add a retain to the created results for the query. The release field may be NULL, in which case the MDQuery will not 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 in which case it is treated as a valid version 0 structure with all fields NULL. 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, you should not assume that the retain function will be unused or that additional reference counts will not be taken on the created results.

    Discussion

    If no create function is specified for an MDQuery, the default result objects are MDItemRefs. Results created after the function MDQuerySetCreateResultFunction is called are created through the specified create function, but values created before the function was set, or after it is unset, are not modified. It is not advisable to change this function after the function MDQueryExecute has been called. The create-result function is called lazily as results are requested from a query, it is not called on all results, and may not be called at all. This avoids the cost of creating potentially hundreds of thousands of what might be temporary objects.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Sets the function used to sort the results of an MDQuery.

    Declaration

    Swift

    func MDQuerySetSortComparator(_ query: MDQuery!, _ comparator: MDQuerySortComparatorFunction, _ context: UnsafeMutablePointer<Void>)

    Objective-C

    void MDQuerySetSortComparator ( MDQueryRef query, MDQuerySortComparatorFunction comparator, void *context );

    Parameters

    query

    The query.

    comparator

    The callback function the MDQuery uses to sort the results list. This parameter may be NULL which cancels previous sort comparator settings. If a function is specified and is not of type MDQuerySortComparatorFunction or does not behave as a MDQuerySortComparatorFunction must, the behavior is undefined.

    context

    A pointer-sized user-defined value, that is passed as the third parameter to the create function. MDQuery does not use this value, does not retain the context in any way, and requires that the context be valid for the lifetime of the query. If the context is not what is expected by the create function, the behavior is undefined.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Sets the function used to create the value objects of the MDQuery.

    Declaration

    Swift

    func MDQuerySetCreateValueFunction(_ query: MDQuery!, _ `func`: MDQueryCreateValueFunction, _ context: UnsafeMutablePointer<Void>, _ cb: UnsafePointer<CFArrayCallBacks>)

    Objective-C

    void MDQuerySetCreateValueFunction ( MDQueryRef query, MDQueryCreateValueFunction func, void *context, const CFArrayCallBacks *cb );

    Parameters

    query

    The query.

    func

    The callback function the MDQuery should use to create the value list values, such as those returned by the function 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 a function is specified and is not of type MDQueryCreateValueFunction or does not behave as a MDQueryCreateValueFunction must, the behavior is undefined.

    context

    A pointer-sized user-defined value, that is passed as the third parameter to the create function. MDQuery does not use this value, does not retain the context in any way, and requires that the context be valid for the lifetime of the query. If the context is not what is expected by the create function, the behavior is undefined.

    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 not add a retain to the created values. 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 in which case it is treated as a valid version 0 structure with all fields NULL. 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, you should not assume that the retain function will be unused or that additional reference counts will not be taken on the created results.

    Discussion

    Values created after a create function is set will be created using the newly specified function, but existing values are not modified. It is not advisable to change this function after MDQueryExecute has been called with the query.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Run the query, and populate the query with the results.

    Declaration

    Swift

    func MDQueryExecute(_ query: MDQuery!, _ optionFlags: CFOptionFlags) -> Boolean

    Objective-C

    Boolean MDQueryExecute ( MDQueryRef query, CFOptionFlags optionFlags );

    Parameters

    query

    The query to execute.

    optionFlags

    A bitwise OR of the MDQueryOptionFlags to be used by the query.

    Return Value

    Returns TRUE if the query was started, FALSE otherwise. Queries cannot be executed more than once.

    Discussion

    Queries only gather results or process updates while the current thread's run loop is running.

    Queries have two phases: the initial gathering phase that collects all currently matching results and a second live-update phase. Updates occur during the live-update phase if a change in a file occurs such that it no longer matches the query or if it begins to 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.

    Query notifications are posted within the context of the same thread which executes the query.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Stops the query from generating more results.

    Declaration

    Swift

    func MDQueryStop(_ query: MDQuery!)

    Objective-C

    void MDQueryStop ( MDQueryRef query );

    Parameters

    query

    The query.

    Discussion

    Queries may be executed only once and cannot be restarted. The query will first complete processing any unprocessed results.do. 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.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Disables updates to the query result list.

    Declaration

    Swift

    func MDQueryDisableUpdates(_ query: MDQuery!)

    Objective-C

    void MDQueryDisableUpdates ( MDQueryRef query );

    Parameters

    query

    The query.

    Discussion

    This function should be called before iterating over query results that could change due to live-updates. The disabled state is a counter and disabling can be done recursively and from different threads.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Enables updates to the query result list.

    Declaration

    Swift

    func MDQueryEnableUpdates(_ query: MDQuery!)

    Objective-C

    void MDQueryEnableUpdates ( MDQueryRef query );

    Parameters

    query

    The query.

    Discussion

    This function should be called when finished iterating through the list of results. Live-updates to the query results will continue when all the disables have been matched by a corresponding enable.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns true if the first phase of a query, the initial result gathering, has finished.

    Declaration

    Swift

    func MDQueryIsGatheringComplete(_ query: MDQuery!) -> Boolean

    Objective-C

    Boolean MDQueryIsGatheringComplete ( MDQueryRef query );

    Parameters

    query

    The query.

    Return Value

    Returns TRUE if the first phase of a query has completed, otherwise FALSE.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the list of values from the results of the query for the specified attribute.

    Declaration

    Swift

    func MDQueryCopyValuesOfAttribute(_ query: MDQuery!, _ name: CFString!) -> CFArray!

    Objective-C

    CFArrayRef MDQueryCopyValuesOfAttribute ( MDQueryRef query, CFStringRef name );

    Parameters

    query

    The query.

    name

    The attribute name to return the value of. If the attribute is not one of those requested when the query was created the behavior is undefined

    Return Value

    A CFArrayRef containing the value objects for the specified attribute. The array contents are not ordered and contain only one occurrence of each value. The array contents may change over time if the query is configured for live-updates.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the value of the named attribute for the result at the given index.

    Declaration

    Swift

    func MDQueryGetAttributeValueOfResultAtIndex(_ query: MDQuery!, _ name: CFString!, _ idx: CFIndex) -> UnsafeMutablePointer<Void>

    Objective-C

    void * MDQueryGetAttributeValueOfResultAtIndex ( MDQueryRef query, CFStringRef name, CFIndex idx );

    Parameters

    query

    The query.

    name

    The attribute name to return the values of. 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.

    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.

    Return Value

    The value of the attribute, or NULL if the attribute doesn't exist for the specified result.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the number of results which have the given attribute and attribute value.

    Declaration

    Swift

    func MDQueryGetCountOfResultsWithAttributeValue(_ query: MDQuery!, _ name: CFString!, _ value: AnyObject!) -> CFIndex

    Objective-C

    CFIndex MDQueryGetCountOfResultsWithAttributeValue ( MDQueryRef query, CFStringRef name, CFTypeRef value );

    Parameters

    query

    The query.

    name

    The attribute name to return the result count of. If the attribute is not one of those requested in the valueListAttrs parameter, the behavior is undefined.

    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 specified attribute is returned.

    Return Value

    The number of results containing that attribute and value.

    Discussion

    This count may change over time if the query allows live-updates.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the current index of the given result.

    Declaration

    Swift

    func MDQueryGetIndexOfResult(_ query: MDQuery!, _ result: UnsafePointer<Void>) -> CFIndex

    Objective-C

    CFIndex MDQueryGetIndexOfResult ( MDQueryRef query, const void *result );

    Parameters

    query

    The query.

    result

    The result object to search for. 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.

    Return Value

    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 result, the result will be objects created by that function.

    Discussion

    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 can change over time if the query allows live-updates.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the current result at the given index.

    Declaration

    Swift

    func MDQueryGetResultAtIndex(_ query: MDQuery!, _ idx: CFIndex) -> UnsafePointer<Void>

    Objective-C

    const void * MDQueryGetResultAtIndex ( MDQueryRef query, CFIndex idx );

    Parameters

    query

    The query.

    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.

    Return Value

    Returns the MDItemRef currently at the given index, or if a result-creation function has been set, returns the result returned by that function.

    Discussion

    This function causes the result object to be created if it hasn't been created already. For performance reasons you should only request objects that you require. 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 can change over time if the query is configured to allow live-updates.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Returns the number of results currently collected by the query.

    Declaration

    Swift

    func MDQueryGetResultCount(_ query: MDQuery!) -> CFIndex

    Objective-C

    CFIndex MDQueryGetResultCount ( MDQueryRef query );

    Parameters

    query

    The query.

    Return Value

    The number of results in the query.

    Discussion

    Note that the number of results in a query will change over time as the query's result list is updated.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Sets the block used to sort the results of an MDQuery.

    Declaration

    Swift

    func MDQuerySetSortComparatorBlock(_ query: MDQuery!, _ comparator: ((UnsafePointer<Unmanaged<AnyObject>?>, UnsafePointer<Unmanaged<AnyObject>?>) -> CFComparisonResult)!)

    Objective-C

    void MDQuerySetSortComparatorBlock ( MDQueryRef query, CFComparisonResult (^comparator)(const CFTypeRef attrs1[], const CFTypeRef attrs2[]) );

    Parameters

    query

    The query.

    comparator

    The callback block the MDQuery will use to sort its results. The comparator may be called on multiple threads in parallel, and must be reentrant. To take advantage of parallel sorting, it is best to avoid any locking in the comparator.

    The block may be NULL to cancel any custom comparator.

    Discussion

    You may set the comparator block as many times as you like, even while the query is executing. Whenever the comparator block is set, all results are re-sorted using the new comparator block before the function returns. The block can be NULL to cancel custom sorting and revert to the default sorting.

    The default sort provided by MDQueryCreate is an ascending sort. Strings are compared using CFStringCompare with the options kCFCompareNonliteral | kCFCompareLocalized | kCFCompareNumerically. CFDataRefs are compared by using memcmp() of the data pointers.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.6 and later.

  • Returns the type identifier of all MDQuery instances

    Declaration

    Swift

    func MDQueryGetTypeID() -> CFTypeID

    Objective-C

    CFTypeID MDQueryGetTypeID ( void );

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

Callbacks

  • Callback function used to sort the results of a query.

    Declaration

    Objective-C

    typedef CFComparisonResult (*MDQuerySortComparatorFunction) ( const CFTypeRef attrs1[], const CFTypeRef attrs2[], void *context );

    Parameters

    query

    The query instance.

    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 will be NULL if the attribute doesn't exist for a result or if read access to that attribute is not allowed.

    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 will be NULL if the attribute doesn't exist for a result or if read access to that attribute is not allowed.

    context

    The user-defined context parameter provided in the function MDQuerySetSortComparator.

    Return Value

    The function must return one of the CFComparisonResults kCFCompareLessThan, kCFCompareEqualTo, or kCFCompareGreaterThan. There is no provision for unordered results. The comparison should be a total order relation and produce the same results for the same inputs.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Callback function used to create the result objects stored and returned by a query.

    Declaration

    Objective-C

    typedef const void * (*MDQueryCreateResultFunction) ( MDQueryRef query, MDItemRef item, void *context );

    Parameters

    query

    The query instance.

    item

    The default MDItemRef for the result.

    context

    The user-defined context parameter provided to the MDQuerySetCreateResultFunction function.

    Return Value

    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.

    Discussion

    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.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

  • Callback function used to create the value objects stored and returned by a query.

    Declaration

    Objective-C

    typedef const void * (*MDQueryCreateValueFunction) ( MDQueryRef query, CFStringRef attrName, CFTypeRef attrValue, void *context );

    Parameters

    query

    The query instance.

    attrName

    The attribute name of the value.

    attrValue

    The default value of the value.

    context

    The user-defined context parameter provided in the MDQuerySetCreateValueFunction function.

    Return Value

    The function must return a pointer-sized value that can be managed with the callback 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.

    Discussion

    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

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

Data Types

Batching Parameters

  • Structure containing the progress notification batching parameters of a MDQuery.

    Declaration

    Swift

    struct MDQueryBatchingParams { var first_max_num: UInt var first_max_ms: UInt var progress_max_num: UInt var progress_max_ms: UInt var update_max_num: UInt var update_max_ms: UInt }

    Objective-C

    typedef struct { size_t 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; } MDQueryBatchingParams;

    Fields

    first_max_num

    The maximum number of results that can accumulate before the first progress notification is sent. This value is used only during the initial result-gathering phase of a query.

    first_max_ms

    The maximum number of milliseconds that can pass before the first progress notification is sent. 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. This value is used only during the initial result-gathering phase of a query.

    progress_max_num

    The maximum number of results that can accumulate before additional progress notifications are sent. This value is used only during the initial result-gathering phase of a query.

    progress_max_ms

    The maximum number of milliseconds that can pass before additional progress notifications are sent. This value is advisory, in that the notification will be triggered at some point after progress_max_ms milliseconds have passed since the query began accumulating results. This value is used only during the initial result-gathering phase of a query.

    update_max_num

    The maximum number of results that can accumulate before an update notification is sent. This value is used only during the live-update phase of a query.

    update_max_ms

    The maximum number of milliseconds that can pass before an update notification is sent. This value is advisory, in that the notification will be triggered at some point after update_max_ms milliseconds have passed since the query began accumulating results. This value is used only during the live-update phase of a query.

    Discussion

    The default batching parameters are undefined and subject to change.

    Availability

    Available in OS X v10.4 and later.

Miscellaneous

  • A reference to a MDQuery object.

    Declaration

    Swift

    typealias MDQueryRef = MDQuery

    Objective-C

    typedef struct __MDQuery *MDQueryRef;

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

Constants

Query Option Flags

  • Specify the execution mode for a query.

    Declaration

    Swift

    struct MDQueryOptionFlags { init(_ value: UInt32) var value: UInt32 }

    Objective-C

    typedef enum { kMDQuerySynchronous = 1, kMDQueryWantsUpdates = 4, } MDQueryOptionFlags;

    Constants

    • kMDQuerySynchronous

      kMDQuerySynchronous

      Specifies that a query should block during the initial gather phase. The query’s run loop will run in the default mode. If this option is not specified the query function returns immediately after starting the query asynchronously.

      Available in OS X v10.4 and later.

    • kMDQueryWantsUpdates

      kMDQueryWantsUpdates

      Specifies that a query should provide live-updates to the result list after the initial gathering phase. Updates occur during the live-update phase if a change in a file occurs such that it no longer matches the query or if it begins to 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 option is ignored if the kMDQuerySynchronous parameter is specified. This is subject to change, and you should always pass the value appropriate to the required behavior.

      Available in OS X v10.4 and later.

    Import Statement

    import CoreServices

    Availability

    Available in OS X v10.4 and later.

Notifications

  • Indicates that a query has finished with the initial result-gathering phase.

    Declaration

    Swift

    let kMDQueryDidFinishNotification: CFString!

    Objective-C

    const CFStringRef kMDQueryDidFinishNotification;

    Constants

    • kMDQueryDidFinishNotification

      kMDQueryDidFinishNotification

      Posted to indicate that the query has finished the initial result-gathering phase.

      Available in OS X v10.4 and later.

    Discussion

    The query results list is not updated as a result of this notification.

    This notification is only sent to the application’s notification center.

    Import Statement

  • Indicates that a query’s results list has change during the live-update phase of a query.

    Declaration

    Swift

    let kMDQueryDidUpdateNotification: CFString!

    Objective-C

    const CFStringRef kMDQueryDidUpdateNotification;

    Constants

    • kMDQueryDidUpdateNotification

      kMDQueryDidUpdateNotification

      Notification posted to indicate that a change has occurred to the query’s results list during the live-update phase of a query’s execution.

      Available in OS X v10.4 and later.

    Discussion

    The info dictionary of the notification can contain kMDQueryUpdateAddedItems, kMDQueryUpdateChangedItems, and kMDQueryUpdateRemovedItems keys.

    This notification is only sent to the application’s notification center.

    Import Statement

  • Indicates that a query’s results list has change during the initial result-gathering phase of a query.

    Declaration

    Swift

    let kMDQueryProgressNotification: CFString!

    Objective-C

    const CFStringRef kMDQueryProgressNotification;

    Constants

    • kMDQueryProgressNotification

      kMDQueryProgressNotification

      Notification posted to indicate that a change has occurred to the query’s results list during the initial result-gathering phase of execution.

      Available in OS X v10.4 and later.

    Discussion

    New items are typically added during this phase, however it is possible for items to be removed or updated, if the original file is changed. The info dictionary of the notification can contain kMDQueryUpdateChangedItems and kMDQueryUpdateRemovedItems keys.

    For performance reasons added results are not indicated in progress notifications, to avoid the cost of creating the result objects.

    This notification is only sent to the application’s notification center.

    Import Statement

Notification Info Keys

  • Specify the items that have changed in the query results.

    Declaration

    Swift

    let kMDQueryUpdateAddedItems: CFString! let kMDQueryUpdateChangedItems: CFString! let kMDQueryUpdateRemovedItems: CFString!

    Objective-C

    const CFStringRef kMDQueryUpdateAddedItems; const CFStringRef kMDQueryUpdateChangedItems; const CFStringRef kMDQueryUpdateRemovedItems;

    Constants

    • kMDQueryUpdateAddedItems

      kMDQueryUpdateAddedItems

      An array that identifies the items that have been added to the query results. This list only contains result objects that have previously been created, result objects that have not been created are not included.

      Available in OS X v10.4 and later.

    • kMDQueryUpdateChangedItems

      kMDQueryUpdateChangedItems

      An array that identifies the items that have changed in the query results. This list only contains result objects that have previously been created, result objects that have not been created are not included.

      Available in OS X v10.4 and later.

    • kMDQueryUpdateRemovedItems

      kMDQueryUpdateRemovedItems

      An array that identifies the items that have been removed from the query results. This list only contains result objects that have previously been created, result objects that have not been created are not included.

      Available in OS X v10.4 and later.

    Import Statement

  • Specify the scope of a query’s search.

    Declaration

    Swift

    let kMDQueryScopeHome: CFString! let kMDQueryScopeComputer: CFString! let kMDQueryScopeNetwork: CFString! let kMDQueryScopeAllIndexed: CFString! let kMDQueryScopeComputerIndexed: CFString! let kMDQueryScopeNetworkIndexed: CFString!

    Objective-C

    const CFStringRef kMDQueryScopeHome; const CFStringRef kMDQueryScopeComputer; const CFStringRef kMDQueryScopeNetwork; const CFStringRef kMDQueryScopeAllIndexed; const CFStringRef kMDQueryScopeComputerIndexed; const CFStringRef kMDQueryScopeNetworkIndexed;

    Constants

    • kMDQueryScopeHome

      kMDQueryScopeHome

      Specifies that the query should be restricted to the volume and directory that contains the current user’s home directory.

      Available in OS X v10.4 and later.

    • kMDQueryScopeComputer

      kMDQueryScopeComputer

      Specifies that the query should be restricted to all locally mounted volumes, plus the user’s home directory (which may be on a remote volume).

      Available in OS X v10.4 and later.

    • kMDQueryScopeNetwork

      kMDQueryScopeNetwork

      Specifies that the query should include all user mounted remote volumes.

      Available in OS X v10.4 and later.

    • kMDQueryScopeAllIndexed

      kMDQueryScopeAllIndexed

      Specifies that the search should be restricted to indexed, locally mounted volumes and indexed user mounted remote volumes, plus the user's home directory.

      Available in OS X v10.6 and later.

    • kMDQueryScopeComputerIndexed

      kMDQueryScopeComputerIndexed

      Specifies that the search should be restricted to indexed, locally mounted volumes, plus the user's home directory (which may be on a remote volume).

      Available in OS X v10.6 and later.

    • kMDQueryScopeNetworkIndexed

      kMDQueryScopeNetworkIndexed

      Specifies that the search should include indexed user mounted remote volumes.

      Available in OS X v10.6 and later.

    Discussion

    These constants can be passed in the scopeDirectories array to the function MDQuerySetSearchScope.

    Import Statement

  • Key used in a user notification’s description dictionary that indicates the relevance of a result.

    Declaration

    Swift

    let kMDQueryResultContentRelevance: CFString!

    Objective-C

    const CFStringRef kMDQueryResultContentRelevance;

    Constants

    • kMDQueryResultContentRelevance

      kMDQueryResultContentRelevance

      A CFNumberRef with a floating point value between 0.0 and 1.0 inclusive.

      Available in OS X v10.4 and later.

    Discussion

    The relevance value indicates the relevance of the content of a result object. The relevance is computed based on the value of the result itself, not on its relevance to the other results returned by the query.

    The relevance value is for the content of the object only, not on the result item as a whole, and may not be computed if the item matches the query through evaluation of other attributes

    If the value is not computed it is treated as an attribute on the item that does not exist.

    Import Statement