Function SecItemCopyMatching 

pub unsafe extern "C-unwind" fn SecItemCopyMatching(
    query: &CFDictionary,
    result: *mut *const CFType,
) -> i32

Available on crate feature SecItem only.

Returns one or more items which match a search query.

Parameter query: A dictionary containing an item class specification and optional attributes for controlling the search. See the “Keychain Search Attributes” section for a description of currently defined search attributes.

Parameter result: On return, a CFTypeRef reference to the found item(s). The exact type of the result is based on the search attributes supplied in the query, as discussed below.

Returns: A result code. See “Security Error Codes” (SecBase.h).

Attributes defining a search are specified by adding key/value pairs to the query dictionary.

A typical query consists of:

a kSecClass key, whose value is a constant from the Class Constants section that specifies the class of item(s) to be searched one or more keys from the “Attribute Key Constants” section, whose value is the attribute data to be matched one or more keys from the “Search Constants” section, whose value is used to further refine the search a key from the “Return Type Key Constants” section, specifying the type of results desired

Result types are specified as follows:

To obtain the data of a matching item (CFDataRef), specify kSecReturnData with a value of kCFBooleanTrue. To obtain the attributes of a matching item (CFDictionaryRef), specify kSecReturnAttributes with a value of kCFBooleanTrue. To obtain a reference to a matching item (SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef), specify kSecReturnRef with a value of kCFBooleanTrue. Note that returning references is supported only for Certificate, Key or Identity items on iOS, watchOS and tvOS. Similarly, returning references is supported only for Certificate, Key or Identity items on macOS when either kSecUseDataProtectionKeychain is set to true or kSecAttrSynchronizable is set to true. To obtain a persistent reference to a matching item (CFDataRef), specify kSecReturnPersistentRef with a value of kCFBooleanTrue. Note that unlike normal references, a persistent reference may be stored on disk or passed between processes. If more than one of these result types is specified, the result is returned as a CFDictionaryRef containing all the requested data. If a result type is not specified, no results are returned.

By default, this function returns only the first match found. To obtain more than one matching item at a time, specify kSecMatchLimit with a value greater than 1. The result will be a CFArrayRef containing up to that number of matching items; the items’ types are described above.

To filter a provided list of items down to those matching the query, specify a kSecMatchItemList whose value is a CFArray of SecKeychainItemRef, SecKeyRef, SecCertificateRef, or SecIdentityRef items. The objects in the provided array must be of the same type.

On iOS, to convert from a persistent item reference to a normal item reference, specify a kSecValuePersistentRef whose value a CFDataRef (the persistent reference), and a kSecReturnRef whose value is kCFBooleanTrue.

On macOS, to convert from persistent item references to normal item references, specify a kSecMatchItemList whose value is a CFArray containing one or more CFDataRef elements (the persistent reference), and a kSecReturnRef whose value is kCFBooleanTrue. The objects in the provided array must be of the same type.

Safety

• query generics must be of the correct type.
• result must be a valid pointer or null.