OSX/libsecurity_keychain/Security/SecIdentitySearch.h

   1 /*
   2  * Copyright (c) 2002-2011 Apple Inc. All Rights Reserved.
   3  *
   4  * @APPLE_LICENSE_HEADER_START@
   5  *
   6  * This file contains Original Code and/or Modifications of Original Code
   7  * as defined in and that are subject to the Apple Public Source License
   8  * Version 2.0 (the 'License'). You may not use this file except in
   9  * compliance with the License. Please obtain a copy of the License at
  10  * http://www.opensource.apple.com/apsl/ and read it before using this
  11  * file.
  12  *
  13  * The Original Code and all software distributed under the License are
  14  * distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  15  * EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  16  * INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  17  * FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  18  * Please see the License for the specific language governing rights and
  19  * limitations under the License.
  20  *
  21  * @APPLE_LICENSE_HEADER_END@
  22  */
  23
  24 /*!
  25         @header SecIdentitySearch
  26         The functions provided in SecIdentitySearch implement a query for SecIdentity objects.
  27 */
  28
  29 #ifndef _SECURITY_SECIDENTITYSEARCH_H_
  30 #define _SECURITY_SECIDENTITYSEARCH_H_
  31
  32 #include <Security/SecBase.h>
  33 #include <Security/cssmtype.h>
  34 #include <CoreFoundation/CFArray.h>
  35 #include <CoreFoundation/CFDictionary.h>
  36 #include <CoreFoundation/CFString.h>
  37 #include <AvailabilityMacros.h>
  38
  39
  40 #if defined(__cplusplus)
  41 extern "C" {
  42 #endif
  43
  44 CF_ASSUME_NONNULL_BEGIN
  45
  46 /*!
  47     @typedef SecIdentitySearchRef
  48     @abstract Contains information about an identity search.
  49 */
  50 typedef struct CF_BRIDGED_TYPE(id) OpaqueSecIdentitySearchRef *SecIdentitySearchRef;
  51
  52 /*!
  53         @function SecIdentitySearchGetTypeID
  54         @abstract Returns the type identifier of SecIdentitySearch instances.
  55         @result The CFTypeID of SecIdentitySearch instances.
  56         @discussion This API is deprecated in 10.7. The SecIdentitySearchRef type is no longer used.
  57 */
  58 CFTypeID SecIdentitySearchGetTypeID(void)
  59                 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
  60
  61 /*!
  62         @function SecIdentitySearchCreate
  63         @abstract Creates a search reference for finding identities.
  64     @param keychainOrArray An reference to an array of keychains to search, a single keychain, or NULL to search the user's default keychain search list.
  65         @param keyUsage A CSSM_KEYUSE value, as defined in cssmtype.h. This value narrows the search to return only those identities which match the specified key usage. Pass a value of 0 to ignore key usage and return all available identities. Note that passing CSSM_KEYUSE_ANY limits the results to only those identities that can be used for every operation.
  66     @param searchRef On return, an identity search reference. You must release the identity search reference by calling the CFRelease function.
  67     @result A result code.  See "Security Error Codes" (SecBase.h).
  68         @discussion You can set values for key usage, and one or more keychains, to control the search for identities. You can use the returned search reference to obtain the remaining identities in subsequent calls to the SecIentitySearchCopyNext function. You must release the identity search reference by calling the CFRelease function.
  69         This function is deprecated in Mac OS X 10.7 and later; to find identities which match a given key usage or other attributes, please use the SecItemCopyMatching API (see SecItem.h).
  70 */
  71 OSStatus SecIdentitySearchCreate(CFTypeRef __nullable keychainOrArray, CSSM_KEYUSE keyUsage, SecIdentitySearchRef * __nullable CF_RETURNS_RETAINED searchRef)
  72                 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
  73
  74 /*!
  75         @function SecIdentitySearchCopyNext
  76     @abstract Finds the next identity matching the given search criteria, as previously specified by a call to SecIdentitySearchCreate or SecIdentitySearchCreateWithAttributes.
  77         @param searchRef A reference to the current identity search. You create the identity search reference by calling either SecIdentitySearchCreate or SecIdentitySearchCreateWithAttributes.
  78         @param identity On return, an identity reference for the next found identity, if any. You must call the CFRelease function when finished with the identity reference.
  79         @result A result code. When there are no more identities found that match the search criteria, errSecItemNotFound is returned. See "Security Error Codes" (SecBase.h).
  80         @discussion This function is deprecated in Mac OS X 10.7 and later; to find identities which match specified attributes, please use the SecItemCopyMatching API (see SecItem.h).
  81 */
  82 OSStatus SecIdentitySearchCopyNext(SecIdentitySearchRef searchRef, SecIdentityRef * __nullable CF_RETURNS_RETAINED identity)
  83                 DEPRECATED_IN_MAC_OS_X_VERSION_10_7_AND_LATER;
  84
  85 CF_ASSUME_NONNULL_END
  86
  87 #if defined(__cplusplus)
  88 }
  89 #endif
  90
  91 #endif /* !_SECURITY_SECIDENTITYSEARCH_H_ */