objc2_core_services/generated/Metadata/

MDQuery.rs

//! This file has been automatically generated by `objc2`'s `header-translator`.
//! DO NOT EDIT
use core::cell::UnsafeCell;
use core::ffi::*;
use core::marker::{PhantomData, PhantomPinned};
use core::ptr::NonNull;
#[cfg(feature = "dispatch2")]
use dispatch2::*;
#[cfg(feature = "objc2")]
use objc2::__framework_prelude::*;
use objc2_core_foundation::*;

use crate::*;

/// This is the type of a reference to MDQuerys.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/mdquery?language=objc)
#[doc(alias = "MDQueryRef")]
#[repr(C)]
pub struct MDQuery {
    inner: [u8; 0],
    _p: UnsafeCell<PhantomData<(*const UnsafeCell<()>, PhantomPinned)>>,
}

cf_type!(
    unsafe impl MDQuery {}
);
#[cfg(feature = "objc2")]
cf_objc2_type!(
    unsafe impl RefEncode<"__MDQuery"> for MDQuery {}
);

/// [Apple's documentation](https://developer.apple.com/documentation/coreservices/mdqueryoptionflags?language=objc)
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MDQueryOptionFlags(pub c_uint);
impl MDQueryOptionFlags {
    #[doc(alias = "kMDQuerySynchronous")]
    pub const Synchronous: Self = Self(1);
    #[doc(alias = "kMDQueryWantsUpdates")]
    pub const WantsUpdates: Self = Self(4);
    #[doc(alias = "kMDQueryAllowFSTranslation")]
    pub const AllowFSTranslation: Self = Self(8);
}

#[cfg(feature = "objc2")]
unsafe impl Encode for MDQueryOptionFlags {
    const ENCODING: Encoding = c_uint::ENCODING;
}

#[cfg(feature = "objc2")]
unsafe impl RefEncode for MDQueryOptionFlags {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

unsafe impl ConcreteType for MDQuery {
    /// Returns the type identifier of all MDQuery instances.
    #[doc(alias = "MDQueryGetTypeID")]
    #[inline]
    fn type_id() -> CFTypeID {
        extern "C-unwind" {
            fn MDQueryGetTypeID() -> CFTypeID;
        }
        unsafe { MDQueryGetTypeID() }
    }
}

impl MDQuery {
    /// Creates a new query with the given query expression.
    ///
    /// Parameter `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.
    ///
    /// Parameter `queryString`: The query expression string for this query. The
    /// syntax for query expressions is explained above in the
    /// header overview documentation.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// Returns: An MDQueryRef, or NULL on failure. If the query string
    /// is empty or malformed (invalid syntax), returns NULL.
    ///
    /// # Safety
    ///
    /// - `allocator` might not allow `None`.
    /// - `query_string` might not allow `None`.
    /// - `value_list_attrs` generic must be of the correct type.
    /// - `value_list_attrs` might not allow `None`.
    /// - `sorting_attrs` generic must be of the correct type.
    /// - `sorting_attrs` might not allow `None`.
    #[doc(alias = "MDQueryCreate")]
    #[inline]
    pub unsafe fn new(
        allocator: Option<&CFAllocator>,
        query_string: Option<&CFString>,
        value_list_attrs: Option<&CFArray>,
        sorting_attrs: Option<&CFArray>,
    ) -> Option<CFRetained<MDQuery>> {
        extern "C-unwind" {
            fn MDQueryCreate(
                allocator: Option<&CFAllocator>,
                query_string: Option<&CFString>,
                value_list_attrs: Option<&CFArray>,
                sorting_attrs: Option<&CFArray>,
            ) -> Option<NonNull<MDQuery>>;
        }
        let ret =
            unsafe { MDQueryCreate(allocator, query_string, value_list_attrs, sorting_attrs) };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }

    /// 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.
    ///
    /// Parameter `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.
    ///
    /// Parameter `query`: The parent query of the new query.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// Parameter `sortingAttrs`: An optional array of attribute names. The
    /// query will sort 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.
    ///
    /// Returns: An MDQueryRef, or NULL on failure. If the query string
    /// is empty or malformed (invalid syntax), returns NULL.
    ///
    /// # Safety
    ///
    /// - `allocator` might not allow `None`.
    /// - `query` might not allow `None`.
    /// - `query_string` might not allow `None`.
    /// - `value_list_attrs` generic must be of the correct type.
    /// - `value_list_attrs` might not allow `None`.
    /// - `sorting_attrs` generic must be of the correct type.
    /// - `sorting_attrs` might not allow `None`.
    #[doc(alias = "MDQueryCreateSubset")]
    #[inline]
    pub unsafe fn new_subset(
        allocator: Option<&CFAllocator>,
        query: Option<&MDQuery>,
        query_string: Option<&CFString>,
        value_list_attrs: Option<&CFArray>,
        sorting_attrs: Option<&CFArray>,
    ) -> Option<CFRetained<MDQuery>> {
        extern "C-unwind" {
            fn MDQueryCreateSubset(
                allocator: Option<&CFAllocator>,
                query: Option<&MDQuery>,
                query_string: Option<&CFString>,
                value_list_attrs: Option<&CFArray>,
                sorting_attrs: Option<&CFArray>,
            ) -> Option<NonNull<MDQuery>>;
        }
        let ret = unsafe {
            MDQueryCreateSubset(
                allocator,
                query,
                query_string,
                value_list_attrs,
                sorting_attrs,
            )
        };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }

    /// Creates a new query with the given query expression.
    ///
    /// Parameter `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.
    ///
    /// Parameter `queryString`: The query expression string for this query. The
    /// syntax for query expressions is explained above in the
    /// header overview documentation.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// Parameter `items`: An array of items. The query will only return results
    /// in this set.
    ///
    /// Returns: An MDQueryRef, or NULL on failure. If the query string
    /// is empty or malformed (invalid syntax), returns NULL.
    ///
    /// # Safety
    ///
    /// - `allocator` might not allow `None`.
    /// - `query_string` might not allow `None`.
    /// - `value_list_attrs` generic must be of the correct type.
    /// - `value_list_attrs` might not allow `None`.
    /// - `sorting_attrs` generic must be of the correct type.
    /// - `sorting_attrs` might not allow `None`.
    /// - `items` generic must be of the correct type.
    /// - `items` might not allow `None`.
    #[doc(alias = "MDQueryCreateForItems")]
    #[inline]
    pub unsafe fn new_for_items(
        allocator: Option<&CFAllocator>,
        query_string: Option<&CFString>,
        value_list_attrs: Option<&CFArray>,
        sorting_attrs: Option<&CFArray>,
        items: Option<&CFArray>,
    ) -> Option<CFRetained<MDQuery>> {
        extern "C-unwind" {
            fn MDQueryCreateForItems(
                allocator: Option<&CFAllocator>,
                query_string: Option<&CFString>,
                value_list_attrs: Option<&CFArray>,
                sorting_attrs: Option<&CFArray>,
                items: Option<&CFArray>,
            ) -> Option<NonNull<MDQuery>>;
        }
        let ret = unsafe {
            MDQueryCreateForItems(
                allocator,
                query_string,
                value_list_attrs,
                sorting_attrs,
                items,
            )
        };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }

    /// Returns the query string of the query.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Returns: The query string of the query.
    #[doc(alias = "MDQueryCopyQueryString")]
    #[inline]
    pub unsafe fn query_string(&self) -> Option<CFRetained<CFString>> {
        extern "C-unwind" {
            fn MDQueryCopyQueryString(query: &MDQuery) -> Option<NonNull<CFString>>;
        }
        let ret = unsafe { MDQueryCopyQueryString(self) };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }

    /// Returns the list of attribute names for which the query is
    /// collecting the lists of values.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Returns: The list of value list attribute names of the query.
    #[doc(alias = "MDQueryCopyValueListAttributes")]
    #[inline]
    pub unsafe fn value_list_attributes(&self) -> Option<CFRetained<CFArray>> {
        extern "C-unwind" {
            fn MDQueryCopyValueListAttributes(query: &MDQuery) -> Option<NonNull<CFArray>>;
        }
        let ret = unsafe { MDQueryCopyValueListAttributes(self) };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }

    /// Returns the list of attribute names the query is using to sort
    /// the results.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Returns: The list of sorting attribute names of the query.
    #[doc(alias = "MDQueryCopySortingAttributes")]
    #[inline]
    pub unsafe fn sorting_attributes(&self) -> Option<CFRetained<CFArray>> {
        extern "C-unwind" {
            fn MDQueryCopySortingAttributes(query: &MDQuery) -> Option<NonNull<CFArray>>;
        }
        let ret = unsafe { MDQueryCopySortingAttributes(self) };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }
}

/// 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.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/mdquerybatchingparams?language=objc)
#[repr(C)]
#[derive(Clone, Copy, Debug, PartialEq)]
pub struct MDQueryBatchingParams {
    pub first_max_num: usize,
    pub first_max_ms: usize,
    pub progress_max_num: usize,
    pub progress_max_ms: usize,
    pub update_max_num: usize,
    pub update_max_ms: usize,
}

#[cfg(feature = "objc2")]
unsafe impl Encode for MDQueryBatchingParams {
    const ENCODING: Encoding = Encoding::Struct(
        "?",
        &[
            <usize>::ENCODING,
            <usize>::ENCODING,
            <usize>::ENCODING,
            <usize>::ENCODING,
            <usize>::ENCODING,
            <usize>::ENCODING,
        ],
    );
}

#[cfg(feature = "objc2")]
unsafe impl RefEncode for MDQueryBatchingParams {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

impl MDQuery {
    /// Returns the current parameters that control batching of progress
    /// notifications.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Returns: An MDQueryBatchingParams structure with the current
    /// batching parameters.
    #[doc(alias = "MDQueryGetBatchingParameters")]
    #[inline]
    pub unsafe fn batching_parameters(&self) -> MDQueryBatchingParams {
        extern "C-unwind" {
            fn MDQueryGetBatchingParameters(query: &MDQuery) -> MDQueryBatchingParams;
        }
        unsafe { MDQueryGetBatchingParameters(self) }
    }

    /// Parameter `query`: The query whose batching parameters are to be set.
    ///
    /// Parameter `params`: An MDQueryBatchingParams structure with the batching
    /// parameters to set.
    #[doc(alias = "MDQuerySetBatchingParameters")]
    #[inline]
    pub unsafe fn set_batching_parameters(&self, params: MDQueryBatchingParams) {
        extern "C-unwind" {
            fn MDQuerySetBatchingParameters(query: &MDQuery, params: MDQueryBatchingParams);
        }
        unsafe { MDQuerySetBatchingParameters(self, params) }
    }
}

/// 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.
///
/// Parameter `query`: The MDQuery instance.
///
/// Parameter `item`: The default MDItemRef for the result.
///
/// Parameter `context`: The user-defined context parameter given to
/// MDQuerySetCreateResultFunction().
///
/// Returns: 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.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/mdquerycreateresultfunction?language=objc)
#[cfg(feature = "MDItem")]
pub type MDQueryCreateResultFunction =
    Option<unsafe extern "C-unwind" fn(*mut MDQuery, *mut MDItem, *mut c_void) -> *const c_void>;

impl MDQuery {
    /// 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.
    ///
    /// Parameter `query`: The query to whose result create function is to be set.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// # Safety
    ///
    /// - `func` must be implemented correctly.
    /// - `context` must be a valid pointer.
    /// - `cb` must be a valid pointer.
    #[doc(alias = "MDQuerySetCreateResultFunction")]
    #[cfg(feature = "MDItem")]
    #[inline]
    pub unsafe fn set_create_result_function(
        &self,
        func: MDQueryCreateResultFunction,
        context: *mut c_void,
        cb: *const CFArrayCallBacks,
    ) {
        extern "C-unwind" {
            fn MDQuerySetCreateResultFunction(
                query: &MDQuery,
                func: MDQueryCreateResultFunction,
                context: *mut c_void,
                cb: *const CFArrayCallBacks,
            );
        }
        unsafe { MDQuerySetCreateResultFunction(self, func, context, cb) }
    }
}

/// 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.
///
/// Parameter `query`: The MDQuery instance.
///
/// Parameter `attrName`: The attribute name of the value.
///
/// Parameter `attrValue`: The default value of the value.
///
/// Parameter `context`: The user-defined context parameter given to
/// MDQuerySetCreateValueFunction().
///
/// Returns: 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.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/mdquerycreatevaluefunction?language=objc)
pub type MDQueryCreateValueFunction = Option<
    unsafe extern "C-unwind" fn(
        *mut MDQuery,
        *const CFString,
        *const CFType,
        *mut c_void,
    ) -> *const c_void,
>;

impl MDQuery {
    /// 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.
    ///
    /// Parameter `query`: The query to whose value create function is to be set.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// # Safety
    ///
    /// - `func` must be implemented correctly.
    /// - `context` must be a valid pointer.
    /// - `cb` must be a valid pointer.
    #[doc(alias = "MDQuerySetCreateValueFunction")]
    #[inline]
    pub unsafe fn set_create_value_function(
        &self,
        func: MDQueryCreateValueFunction,
        context: *mut c_void,
        cb: *const CFArrayCallBacks,
    ) {
        extern "C-unwind" {
            fn MDQuerySetCreateValueFunction(
                query: &MDQuery,
                func: MDQueryCreateValueFunction,
                context: *mut c_void,
                cb: *const CFArrayCallBacks,
            );
        }
        unsafe { MDQuerySetCreateValueFunction(self, func, context, cb) }
    }

    /// Set the dispatch queue on which query results will be delivered
    /// by MDQueryExecute. 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.
    ///
    /// Parameter `query`: The query for which the dispatch queue should be set.
    ///
    /// Parameter `queue`: The dispatch queue on which results should be delivered.
    ///
    /// # Safety
    ///
    /// - `queue` possibly has additional threading requirements.
    /// - `queue` might not allow `None`.
    #[doc(alias = "MDQuerySetDispatchQueue")]
    #[cfg(feature = "dispatch2")]
    #[inline]
    pub unsafe fn set_dispatch_queue(&self, queue: Option<&DispatchQueue>) {
        extern "C-unwind" {
            fn MDQuerySetDispatchQueue(query: &MDQuery, queue: Option<&DispatchQueue>);
        }
        unsafe { MDQuerySetDispatchQueue(self, queue) }
    }

    /// 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.]]
    ///
    /// Parameter `query`: The query to execute.
    ///
    /// Parameter `optionFlags`: Bitwise or of MDQueryOptionFlags
    ///
    /// Returns: Returns true if the query was started (executed in the case
    /// of a synchronous query), false otherwise. Queries cannot be
    /// executed more than once.
    #[doc(alias = "MDQueryExecute")]
    #[inline]
    pub unsafe fn execute(&self, option_flags: CFOptionFlags) -> bool {
        extern "C-unwind" {
            fn MDQueryExecute(query: &MDQuery, option_flags: CFOptionFlags) -> Boolean;
        }
        let ret = unsafe { MDQueryExecute(self, option_flags) };
        ret != 0
    }

    /// 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.
    ///
    /// Parameter `query`: The query to stop.
    #[doc(alias = "MDQueryStop")]
    #[inline]
    pub unsafe fn stop(&self) {
        extern "C-unwind" {
            fn MDQueryStop(query: &MDQuery);
        }
        unsafe { MDQueryStop(self) }
    }

    /// 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.
    ///
    /// Parameter `query`: The query for which updates are to be disabled.
    ///
    /// Returns: The generation number of the query. This changes each time the query's
    /// result set has changed.
    #[doc(alias = "MDQueryDisableUpdates")]
    #[inline]
    pub unsafe fn disable_updates(&self) {
        extern "C-unwind" {
            fn MDQueryDisableUpdates(query: &MDQuery);
        }
        unsafe { MDQueryDisableUpdates(self) }
    }

    /// 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.
    ///
    /// Parameter `query`: The query for which updates are to be enabled.
    #[doc(alias = "MDQueryEnableUpdates")]
    #[inline]
    pub unsafe fn enable_updates(&self) {
        extern "C-unwind" {
            fn MDQueryEnableUpdates(query: &MDQuery);
        }
        unsafe { MDQueryEnableUpdates(self) }
    }

    /// Returns true if the first phase of a query, the initial result
    /// gathering, has finished.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Returns: A boolean indicating whether or not the first phase
    /// of a query has completed.
    #[doc(alias = "MDQueryIsGatheringComplete")]
    #[inline]
    pub unsafe fn is_gathering_complete(&self) -> bool {
        extern "C-unwind" {
            fn MDQueryIsGatheringComplete(query: &MDQuery) -> Boolean;
        }
        let ret = unsafe { MDQueryIsGatheringComplete(self) };
        ret != 0
    }

    /// 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.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Returns: The number of results in the query.
    #[doc(alias = "MDQueryGetResultCount")]
    #[inline]
    pub unsafe fn result_count(&self) -> CFIndex {
        extern "C-unwind" {
            fn MDQueryGetResultCount(query: &MDQuery) -> CFIndex;
        }
        unsafe { MDQueryGetResultCount(self) }
    }

    /// 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.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Parameter `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.
    ///
    /// Returns: Returns the MDItemRef currently at the given index, or
    /// if a result-create function has been set, returns the
    /// result returned by that function.
    #[doc(alias = "MDQueryGetResultAtIndex")]
    #[inline]
    pub unsafe fn result_at_index(&self, idx: CFIndex) -> *const c_void {
        extern "C-unwind" {
            fn MDQueryGetResultAtIndex(query: &MDQuery, idx: CFIndex) -> *const c_void;
        }
        unsafe { MDQueryGetResultAtIndex(self, idx) }
    }

    /// 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.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Parameter `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.
    ///
    /// Returns: 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.
    ///
    /// # Safety
    ///
    /// `result` must be a valid pointer.
    #[doc(alias = "MDQueryGetIndexOfResult")]
    #[inline]
    pub unsafe fn index_of_result(&self, result: *const c_void) -> CFIndex {
        extern "C-unwind" {
            fn MDQueryGetIndexOfResult(query: &MDQuery, result: *const c_void) -> CFIndex;
        }
        unsafe { MDQueryGetIndexOfResult(self, result) }
    }

    /// Returns the value of the named attribute for the result at
    /// the given index.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// Returns: The value of the attribute, or NULL if the attribute
    /// doesn't exist in the query on that result.
    ///
    /// # Safety
    ///
    /// `name` might not allow `None`.
    #[doc(alias = "MDQueryGetAttributeValueOfResultAtIndex")]
    #[inline]
    pub unsafe fn attribute_value_of_result_at_index(
        &self,
        name: Option<&CFString>,
        idx: CFIndex,
    ) -> *mut c_void {
        extern "C-unwind" {
            fn MDQueryGetAttributeValueOfResultAtIndex(
                query: &MDQuery,
                name: Option<&CFString>,
                idx: CFIndex,
            ) -> *mut c_void;
        }
        unsafe { MDQueryGetAttributeValueOfResultAtIndex(self, name, idx) }
    }

    /// 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.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Parameter `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.
    ///
    /// Returns: A CFArray holding the value objects for that attribute.
    ///
    /// # Safety
    ///
    /// `name` might not allow `None`.
    #[doc(alias = "MDQueryCopyValuesOfAttribute")]
    #[inline]
    pub unsafe fn values_of_attribute(
        &self,
        name: Option<&CFString>,
    ) -> Option<CFRetained<CFArray>> {
        extern "C-unwind" {
            fn MDQueryCopyValuesOfAttribute(
                query: &MDQuery,
                name: Option<&CFString>,
            ) -> Option<NonNull<CFArray>>;
        }
        let ret = unsafe { MDQueryCopyValuesOfAttribute(self, name) };
        ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
    }

    /// 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.
    ///
    /// Parameter `query`: The query to be interrogated.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// Returns: The number of results with that attribute and value.
    ///
    /// # Safety
    ///
    /// - `name` might not allow `None`.
    /// - `value` should be of the correct type.
    /// - `value` might not allow `None`.
    #[doc(alias = "MDQueryGetCountOfResultsWithAttributeValue")]
    #[inline]
    pub unsafe fn count_of_results_with_attribute_value(
        &self,
        name: Option<&CFString>,
        value: Option<&CFType>,
    ) -> CFIndex {
        extern "C-unwind" {
            fn MDQueryGetCountOfResultsWithAttributeValue(
                query: &MDQuery,
                name: Option<&CFString>,
                value: Option<&CFType>,
            ) -> CFIndex;
        }
        unsafe { MDQueryGetCountOfResultsWithAttributeValue(self, name, value) }
    }

    /// Sets the sort order for a query.
    ///
    /// Parameter `query`: The query for which the sort order is to be set.
    ///
    /// Parameter `sortingAttrs`: An array of attribute names, as in MDQueryCreate.
    /// The query's result set will be sorted according to the order of
    /// these attributes. All names in the array have to have been passed
    /// as sortingAttrs when the query was created. The attribute names
    /// are CFStrings
    ///
    /// Returns: A boolean, true on success, false on failure.
    ///
    /// # Safety
    ///
    /// - `sorting_attrs` generic must be of the correct type.
    /// - `sorting_attrs` might not allow `None`.
    #[doc(alias = "MDQuerySetSortOrder")]
    #[inline]
    pub unsafe fn set_sort_order(&self, sorting_attrs: Option<&CFArray>) -> bool {
        extern "C-unwind" {
            fn MDQuerySetSortOrder(query: &MDQuery, sorting_attrs: Option<&CFArray>) -> Boolean;
        }
        let ret = unsafe { MDQuerySetSortOrder(self, sorting_attrs) };
        ret != 0
    }
}

/// [Apple's documentation](https://developer.apple.com/documentation/coreservices/mdquerysortoptionflags?language=objc)
#[repr(transparent)]
#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash, PartialOrd, Ord)]
pub struct MDQuerySortOptionFlags(pub c_uint);
impl MDQuerySortOptionFlags {
    #[doc(alias = "kMDQueryReverseSortOrderFlag")]
    pub const ReverseSortOrderFlag: Self = Self(1 << 0);
}

#[cfg(feature = "objc2")]
unsafe impl Encode for MDQuerySortOptionFlags {
    const ENCODING: Encoding = c_uint::ENCODING;
}

#[cfg(feature = "objc2")]
unsafe impl RefEncode for MDQuerySortOptionFlags {
    const ENCODING_REF: Encoding = Encoding::Pointer(&Self::ENCODING);
}

impl MDQuery {
    /// Sets the sort flags for a query.
    ///
    /// Parameter `query`: The query for which the sort flags is to be set.
    ///
    /// Parameter `fieldName`: The attribute name for which sort option flags are to be set.
    /// The attribute name must have been part of the sortingFlags when the query was created.
    ///
    /// Parameter `flags`: A uint32_t containing MDQuerySortOptionFlags to be applied to the attibute
    ///
    /// Returns: A boolean, true on success, false on failure.
    ///
    /// # Safety
    ///
    /// `field_name` might not allow `None`.
    #[doc(alias = "MDQuerySetSortOptionFlagsForAttribute")]
    #[inline]
    pub unsafe fn set_sort_option_flags_for_attribute(
        &self,
        field_name: Option<&CFString>,
        flags: u32,
    ) -> bool {
        extern "C-unwind" {
            fn MDQuerySetSortOptionFlagsForAttribute(
                query: &MDQuery,
                field_name: Option<&CFString>,
                flags: u32,
            ) -> Boolean;
        }
        let ret = unsafe { MDQuerySetSortOptionFlagsForAttribute(self, field_name, flags) };
        ret != 0
    }

    /// Gets the sort option flags for a sorting attribute.
    ///
    /// Parameter `query`: The query for which fetch sort option flags.
    ///
    /// Parameter `fieldName`: The attribute name for which sort option flags are to be fetched.
    ///
    /// Returns: A uint32_t, with MDQuerySortOptionFlags set for the attribute.
    ///
    /// # Safety
    ///
    /// `field_name` might not allow `None`.
    #[doc(alias = "MDQueryGetSortOptionFlagsForAttribute")]
    #[inline]
    pub unsafe fn sort_option_flags_for_attribute(&self, field_name: Option<&CFString>) -> u32 {
        extern "C-unwind" {
            fn MDQueryGetSortOptionFlagsForAttribute(
                query: &MDQuery,
                field_name: Option<&CFString>,
            ) -> u32;
        }
        unsafe { MDQueryGetSortOptionFlagsForAttribute(self, field_name) }
    }
}

/// Type of the callback function used to sort the results of an
/// MDQuery.
///
/// Parameter `query`: The MDQuery instance.
///
/// Parameter `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.
///
/// Parameter `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.
///
/// Parameter `context`: The user-defined context parameter given to
/// MDQuerySetSortComparator().
///
/// Returns: 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.
///
/// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/mdquerysortcomparatorfunction?language=objc)
pub type MDQuerySortComparatorFunction = Option<
    unsafe extern "C-unwind" fn(
        *mut *const CFType,
        *mut *const CFType,
        *mut c_void,
    ) -> CFComparisonResult,
>;

impl MDQuery {
    /// 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.
    ///
    /// Parameter `query`: The query to whose result sort function is to be set.
    ///
    /// Parameter `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.
    ///
    /// Parameter `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.
    ///
    /// # Safety
    ///
    /// - `comparator` must be implemented correctly.
    /// - `context` must be a valid pointer.
    #[doc(alias = "MDQuerySetSortComparator")]
    #[inline]
    pub unsafe fn set_sort_comparator(
        &self,
        comparator: MDQuerySortComparatorFunction,
        context: *mut c_void,
    ) {
        extern "C-unwind" {
            fn MDQuerySetSortComparator(
                query: &MDQuery,
                comparator: MDQuerySortComparatorFunction,
                context: *mut c_void,
            );
        }
        unsafe { MDQuerySetSortComparator(self, comparator, context) }
    }

    /// # Safety
    ///
    /// `comparator` might not allow `None`.
    #[doc(alias = "MDQuerySetSortComparatorBlock")]
    #[cfg(feature = "block2")]
    #[inline]
    pub unsafe fn set_sort_comparator_block(
        &self,
        comparator: Option<
            &block2::DynBlock<dyn Fn(*mut *const CFType, *mut *const CFType) -> CFComparisonResult>,
        >,
    ) {
        extern "C-unwind" {
            fn MDQuerySetSortComparatorBlock(
                query: &MDQuery,
                comparator: Option<
                    &block2::DynBlock<
                        dyn Fn(*mut *const CFType, *mut *const CFType) -> CFComparisonResult,
                    >,
                >,
            );
        }
        unsafe { MDQuerySetSortComparatorBlock(self, comparator) }
    }
}

extern "C" {
    /// 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.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryprogressnotification?language=objc)
    pub static kMDQueryProgressNotification: Option<&'static CFString>;
}

extern "C" {
    /// 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.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdquerydidfinishnotification?language=objc)
    pub static kMDQueryDidFinishNotification: Option<&'static CFString>;
}

extern "C" {
    /// 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.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdquerydidupdatenotification?language=objc)
    pub static kMDQueryDidUpdateNotification: Option<&'static CFString>;
}

extern "C" {
    /// 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.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryupdateaddeditems?language=objc)
    pub static kMDQueryUpdateAddedItems: Option<&'static CFString>;
}

extern "C" {
    /// 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.]]
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryupdatechangeditems?language=objc)
    pub static kMDQueryUpdateChangedItems: Option<&'static CFString>;
}

extern "C" {
    /// 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.]]
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryupdateremoveditems?language=objc)
    pub static kMDQueryUpdateRemovedItems: Option<&'static CFString>;
}

extern "C" {
    /// 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).
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryresultcontentrelevance?language=objc)
    pub static kMDQueryResultContentRelevance: Option<&'static CFString>;
}

impl MDQuery {
    /// 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.
    ///
    /// Parameter `query`: The query object to modify.
    ///
    /// Parameter `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.
    ///
    /// Parameter `scopeOptions`: additional options for modifying the search.
    /// Currently, pass 0 (zero).
    ///
    /// # Safety
    ///
    /// - `scope_directories` generic must be of the correct type.
    /// - `scope_directories` might not allow `None`.
    #[doc(alias = "MDQuerySetSearchScope")]
    #[inline]
    pub unsafe fn set_search_scope(
        &self,
        scope_directories: Option<&CFArray>,
        scope_options: OptionBits,
    ) {
        extern "C-unwind" {
            fn MDQuerySetSearchScope(
                query: &MDQuery,
                scope_directories: Option<&CFArray>,
                scope_options: OptionBits,
            );
        }
        unsafe { MDQuerySetSearchScope(self, scope_directories, scope_options) }
    }
}

extern "C" {
    /// 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
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryscopehome?language=objc)
    pub static kMDQueryScopeHome: Option<&'static CFString>;
}

extern "C" {
    /// 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).
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryscopecomputer?language=objc)
    pub static kMDQueryScopeComputer: Option<&'static CFString>;
}

extern "C" {
    /// A constant, which can be passed in the scopeDirectories array, to specify
    /// that the search should include all user mounted remote volumes.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryscopenetwork?language=objc)
    pub static kMDQueryScopeNetwork: Option<&'static CFString>;
}

extern "C" {
    /// A constant, which can be passed in the scopeDirectories array, to specify
    /// that the search should be restricted to indexed, locally mounted volumes and
    /// indexed user mounted remote volumes, plus the user's home directory.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryscopeallindexed?language=objc)
    pub static kMDQueryScopeAllIndexed: Option<&'static CFString>;
}

extern "C" {
    /// A constant, which can be passed in the scopeDirectories array, to specify
    /// that the search should be restricted to indexed, locally mounted volumes, plus the user's
    /// home directory (which may be on a remote volume).
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryscopecomputerindexed?language=objc)
    pub static kMDQueryScopeComputerIndexed: Option<&'static CFString>;
}

extern "C" {
    /// A constant, which can be passed in the scopeDirectories array, to specify
    /// that the search should include indexed user mounted remote volumes.
    ///
    /// See also [Apple's documentation](https://developer.apple.com/documentation/coreservices/kmdqueryscopenetworkindexed?language=objc)
    pub static kMDQueryScopeNetworkIndexed: Option<&'static CFString>;
}

impl MDQuery {
    /// Use MDQuerySetMaxCount to limit the number of results
    /// returned by the query engine.  This must be called before the query is executed.
    ///
    /// Parameter `query`: The query object to modify.
    ///
    /// Parameter `size`: The maximum number of results desired.
    #[doc(alias = "MDQuerySetMaxCount")]
    #[inline]
    pub unsafe fn set_max_count(&self, size: CFIndex) {
        extern "C-unwind" {
            fn MDQuerySetMaxCount(query: &MDQuery, size: CFIndex);
        }
        unsafe { MDQuerySetMaxCount(self, size) }
    }
}

#[deprecated = "renamed to `MDQuery::new`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryCreate(
    allocator: Option<&CFAllocator>,
    query_string: Option<&CFString>,
    value_list_attrs: Option<&CFArray>,
    sorting_attrs: Option<&CFArray>,
) -> Option<CFRetained<MDQuery>> {
    extern "C-unwind" {
        fn MDQueryCreate(
            allocator: Option<&CFAllocator>,
            query_string: Option<&CFString>,
            value_list_attrs: Option<&CFArray>,
            sorting_attrs: Option<&CFArray>,
        ) -> Option<NonNull<MDQuery>>;
    }
    let ret = unsafe { MDQueryCreate(allocator, query_string, value_list_attrs, sorting_attrs) };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

#[deprecated = "renamed to `MDQuery::new_subset`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryCreateSubset(
    allocator: Option<&CFAllocator>,
    query: Option<&MDQuery>,
    query_string: Option<&CFString>,
    value_list_attrs: Option<&CFArray>,
    sorting_attrs: Option<&CFArray>,
) -> Option<CFRetained<MDQuery>> {
    extern "C-unwind" {
        fn MDQueryCreateSubset(
            allocator: Option<&CFAllocator>,
            query: Option<&MDQuery>,
            query_string: Option<&CFString>,
            value_list_attrs: Option<&CFArray>,
            sorting_attrs: Option<&CFArray>,
        ) -> Option<NonNull<MDQuery>>;
    }
    let ret = unsafe {
        MDQueryCreateSubset(
            allocator,
            query,
            query_string,
            value_list_attrs,
            sorting_attrs,
        )
    };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

#[deprecated = "renamed to `MDQuery::new_for_items`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryCreateForItems(
    allocator: Option<&CFAllocator>,
    query_string: Option<&CFString>,
    value_list_attrs: Option<&CFArray>,
    sorting_attrs: Option<&CFArray>,
    items: Option<&CFArray>,
) -> Option<CFRetained<MDQuery>> {
    extern "C-unwind" {
        fn MDQueryCreateForItems(
            allocator: Option<&CFAllocator>,
            query_string: Option<&CFString>,
            value_list_attrs: Option<&CFArray>,
            sorting_attrs: Option<&CFArray>,
            items: Option<&CFArray>,
        ) -> Option<NonNull<MDQuery>>;
    }
    let ret = unsafe {
        MDQueryCreateForItems(
            allocator,
            query_string,
            value_list_attrs,
            sorting_attrs,
            items,
        )
    };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

#[deprecated = "renamed to `MDQuery::query_string`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryCopyQueryString(
    query: &MDQuery,
) -> Option<CFRetained<CFString>> {
    extern "C-unwind" {
        fn MDQueryCopyQueryString(query: &MDQuery) -> Option<NonNull<CFString>>;
    }
    let ret = unsafe { MDQueryCopyQueryString(query) };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

#[deprecated = "renamed to `MDQuery::value_list_attributes`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryCopyValueListAttributes(
    query: &MDQuery,
) -> Option<CFRetained<CFArray>> {
    extern "C-unwind" {
        fn MDQueryCopyValueListAttributes(query: &MDQuery) -> Option<NonNull<CFArray>>;
    }
    let ret = unsafe { MDQueryCopyValueListAttributes(query) };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

#[deprecated = "renamed to `MDQuery::sorting_attributes`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryCopySortingAttributes(
    query: &MDQuery,
) -> Option<CFRetained<CFArray>> {
    extern "C-unwind" {
        fn MDQueryCopySortingAttributes(query: &MDQuery) -> Option<NonNull<CFArray>>;
    }
    let ret = unsafe { MDQueryCopySortingAttributes(query) };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::batching_parameters`"]
    pub fn MDQueryGetBatchingParameters(query: &MDQuery) -> MDQueryBatchingParams;
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::set_batching_parameters`"]
    pub fn MDQuerySetBatchingParameters(query: &MDQuery, params: MDQueryBatchingParams);
}

extern "C-unwind" {
    #[cfg(feature = "MDItem")]
    #[deprecated = "renamed to `MDQuery::set_create_result_function`"]
    pub fn MDQuerySetCreateResultFunction(
        query: &MDQuery,
        func: MDQueryCreateResultFunction,
        context: *mut c_void,
        cb: *const CFArrayCallBacks,
    );
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::set_create_value_function`"]
    pub fn MDQuerySetCreateValueFunction(
        query: &MDQuery,
        func: MDQueryCreateValueFunction,
        context: *mut c_void,
        cb: *const CFArrayCallBacks,
    );
}

extern "C-unwind" {
    #[cfg(feature = "dispatch2")]
    #[deprecated = "renamed to `MDQuery::set_dispatch_queue`"]
    pub fn MDQuerySetDispatchQueue(query: &MDQuery, queue: Option<&DispatchQueue>);
}

#[deprecated = "renamed to `MDQuery::execute`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryExecute(
    query: &MDQuery,
    option_flags: CFOptionFlags,
) -> bool {
    extern "C-unwind" {
        fn MDQueryExecute(query: &MDQuery, option_flags: CFOptionFlags) -> Boolean;
    }
    let ret = unsafe { MDQueryExecute(query, option_flags) };
    ret != 0
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::stop`"]
    pub fn MDQueryStop(query: &MDQuery);
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::disable_updates`"]
    pub fn MDQueryDisableUpdates(query: &MDQuery);
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::enable_updates`"]
    pub fn MDQueryEnableUpdates(query: &MDQuery);
}

#[deprecated = "renamed to `MDQuery::is_gathering_complete`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryIsGatheringComplete(query: &MDQuery) -> bool {
    extern "C-unwind" {
        fn MDQueryIsGatheringComplete(query: &MDQuery) -> Boolean;
    }
    let ret = unsafe { MDQueryIsGatheringComplete(query) };
    ret != 0
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::result_count`"]
    pub fn MDQueryGetResultCount(query: &MDQuery) -> CFIndex;
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::result_at_index`"]
    pub fn MDQueryGetResultAtIndex(query: &MDQuery, idx: CFIndex) -> *const c_void;
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::index_of_result`"]
    pub fn MDQueryGetIndexOfResult(query: &MDQuery, result: *const c_void) -> CFIndex;
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::attribute_value_of_result_at_index`"]
    pub fn MDQueryGetAttributeValueOfResultAtIndex(
        query: &MDQuery,
        name: Option<&CFString>,
        idx: CFIndex,
    ) -> *mut c_void;
}

#[deprecated = "renamed to `MDQuery::values_of_attribute`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQueryCopyValuesOfAttribute(
    query: &MDQuery,
    name: Option<&CFString>,
) -> Option<CFRetained<CFArray>> {
    extern "C-unwind" {
        fn MDQueryCopyValuesOfAttribute(
            query: &MDQuery,
            name: Option<&CFString>,
        ) -> Option<NonNull<CFArray>>;
    }
    let ret = unsafe { MDQueryCopyValuesOfAttribute(query, name) };
    ret.map(|ret| unsafe { CFRetained::from_raw(ret) })
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::count_of_results_with_attribute_value`"]
    pub fn MDQueryGetCountOfResultsWithAttributeValue(
        query: &MDQuery,
        name: Option<&CFString>,
        value: Option<&CFType>,
    ) -> CFIndex;
}

#[deprecated = "renamed to `MDQuery::set_sort_order`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQuerySetSortOrder(
    query: &MDQuery,
    sorting_attrs: Option<&CFArray>,
) -> bool {
    extern "C-unwind" {
        fn MDQuerySetSortOrder(query: &MDQuery, sorting_attrs: Option<&CFArray>) -> Boolean;
    }
    let ret = unsafe { MDQuerySetSortOrder(query, sorting_attrs) };
    ret != 0
}

#[deprecated = "renamed to `MDQuery::set_sort_option_flags_for_attribute`"]
#[inline]
pub unsafe extern "C-unwind" fn MDQuerySetSortOptionFlagsForAttribute(
    query: &MDQuery,
    field_name: Option<&CFString>,
    flags: u32,
) -> bool {
    extern "C-unwind" {
        fn MDQuerySetSortOptionFlagsForAttribute(
            query: &MDQuery,
            field_name: Option<&CFString>,
            flags: u32,
        ) -> Boolean;
    }
    let ret = unsafe { MDQuerySetSortOptionFlagsForAttribute(query, field_name, flags) };
    ret != 0
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::sort_option_flags_for_attribute`"]
    pub fn MDQueryGetSortOptionFlagsForAttribute(
        query: &MDQuery,
        field_name: Option<&CFString>,
    ) -> u32;
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::set_sort_comparator`"]
    pub fn MDQuerySetSortComparator(
        query: &MDQuery,
        comparator: MDQuerySortComparatorFunction,
        context: *mut c_void,
    );
}

extern "C-unwind" {
    #[cfg(feature = "block2")]
    #[deprecated = "renamed to `MDQuery::set_sort_comparator_block`"]
    pub fn MDQuerySetSortComparatorBlock(
        query: &MDQuery,
        comparator: Option<
            &block2::DynBlock<dyn Fn(*mut *const CFType, *mut *const CFType) -> CFComparisonResult>,
        >,
    );
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::set_search_scope`"]
    pub fn MDQuerySetSearchScope(
        query: &MDQuery,
        scope_directories: Option<&CFArray>,
        scope_options: OptionBits,
    );
}

extern "C-unwind" {
    #[deprecated = "renamed to `MDQuery::set_max_count`"]
    pub fn MDQuerySetMaxCount(query: &MDQuery, size: CFIndex);
}