CertEnumSubjectInSortedCTL

[This is preliminary documentation and subject to change.]

The CertEnumSubjectInSortedCTL function enumerates through the TrustedSubjects in a sorted CTL context (a CTL context created with CERT_CREATE_CONTEXT_SORTED_FLAG set). A FALSE is returned for the last subject in the sorted CTL.

#include <wincrypt.h>
BOOL WINAPI CertEnumSubjectInSortedCTL(
  PCCTL_CONTEXT pCtlContext,           //  in
  void **ppvNextSubject,               //  in, out
  PCRYPT_DER_BLOB pSubjectIdentifier,  //  out, optional
  PCRYPT_DER_BLOB pEncodedAttributes   //  out, optional
);

Parameters

pCtlContext: Pointer to the CTL_CONTEXT to be searched.
ppvNextSubject: Pointer to the address of the next TrustedSubject. To start the enumeration, *ppvNextSubject must be NULL. Upon return, *ppvNextSubject is updated to point to the next TrustedSubject in the encoded sequence.
pSubjectIdentifier: Pointer to a CRYPT_DER_BLOB structure, uniquely identifying a TrustedSubject. It can be a hash or any unique byte sequence. See BLOB Structure.
pEncodedAttributes: Pointer to a CRYPT_DER_BLOB structure containing a byte count and a pointer to the TrustedSubject's encoded attributes. See BLOB Structure.

Return Values

TRUE with *ppvNextSubject updated to point to the next TrustedSubject in the encoded sequence. FALSE if there are no more subjects or there is an invalid argument.

Remarks

The returned CRYPT_DER_BLOB structures point directly into the encoded bytes. They are not allocated, and therefore must not be freed.

If the CTL is not sorted with the CERT_CREATE_CONTEXT_SORTED_FLAG flag set, an error will result.

To retrieve extended error information, use the GetLastError function.

Example

// EXAMPLE CODE FOR USING CertEnumSubjectInSortedCTL().
// Assume a pointer to the CTL_CONTEXT (pCtlContext) is initialized
// elsewhere.
// Declare and initialize
int count= 0;                       // Counter
PCCTL_CONTEXT pCtlContext;          // Initialized elsewhere
void **ppvNextSubject;              // Pointer to the address of the
                                    //  next subject. NULL to start
                                    //  the enumeration.
CRYPT_DER_BLOB SubjectIdentifier;   // Pointer to a BLOB structure
                                    //   identifiable to the subject.
CRYPT_DER_BLOB EncodedAttributes;   // Pointer to the BLOB structure
                                    //   attributes.
BOOL fResult;                       // Returns TRUE if the function
                                    //   finds a TrustedSubject. FALSE
                                    //   if the last TrustedSubject
                                    //   has been found.

// Function call to CertEnumSubjectInSortedCTL().
ppvNextSubject= NULL;               // NULL to start the enumeration.
do {
fResult= CertEnumSubjectInSortedCTL(
              pCtlContext,          // in- Pointer to the CTL_CONTEXT
                                    //   to be searched.
              ppvNextSubject,       // in, out- NULL for the first
                                    //   function call.
              &SubjectIdentifier,   // out, optional- Pointer to
                                    //   unique BLOB structure.
&EncodedAttributes);                // out, optional- Pointer to
//   attributes BLOB structure.
if(fResult)
{  // TRUE returned- The subject was found.
// Now print out and search again.
count++;                    // Increment counter.
printf("%d. Subject found in sorted CTL.\n", count);
printf("%d. ppvNextSubject is reset to %d.\n", count,
ppvNextSubject);
    }
} while (fResult);                  //   Keep looping through the CTL
                                    //   until the last TrustedSubject
                                    //   is found.

// FALSE returned- function at the end of the CTL.
printf("CertEnumSubjectInSortedCTL enumeration complete.\n");
printf("There are %d TrustedSubjects in the CTL.\n", count);
if (!count) { // Count =0- This is an empty CTL or an error occurred.
printf("No TrustedSubject found. Check for errors.\n");
}

QuickInfo