ICertServerExit::EnumerateExtensions method (certif.h)

Article
10/13/2021

The EnumerateExtensions method returns the object identifier (OID) string (also known as the extension name) of the next certificate extension to be enumerated, then increments the internal pointer to the following extension.

Before calling EnumerateExtensions, an application calls ICertServerExit::EnumerateExtensionsSetup. When done enumerating, an application calls ICertServerExit::EnumerateExtensionsClose.

Syntax

HRESULT EnumerateExtensions(
  [out] BSTR *pstrExtensionName
);

Parameters

[out] pstrExtensionName

A pointer to the enumerated extension name.

Return value

C++

If the method succeeds, the method returns S_OK, and *pstrExtensionName is set to the BSTR that contains the name of the enumerated extension. A value of S_FALSE is returned if the last extension was already enumerated.

To use this method, create a variable of BSTR type, set the variable equal to NULL, and pass the address of this variable as pstrExtensionName.

When you have finished using the BSTR, free it by calling the SysFreeString function.

If the method fails, it returns an HRESULT value that indicates the error. For a list of common error codes, see Common HRESULT Values.

VB

Returns a string that contains the name of the enumerated extension, or an empty string if the last extension was already enumerated.

Remarks

This method enumerates certificate extensions recorded in the database, even those that are disabled and do not appear in the certificate. To determine whether an extension is disabled, use ICertServerExit::GetCertificateExtensionFlags to test the extension's EXTENSION_DISABLE_FLAG bit.

Examples

BSTR     bstrExt = NULL;
VARIANT  varExt;
LONG     ExtFlags;
HRESULT  hr;

VariantInit(&varExt);

// Enumerate the extensions.
while (S_OK ==
      (hr = pCertServerExit->EnumerateExtensions(&bstrExt)))
{
  // Retrieve the extension data.
  if (FAILED(pCertServerExit->GetCertificateExtension(
                              bstrExt,
                              PROPTYPE_BINARY,
                              &varExt)))
      printf("Failed GetCertificateExtension\n");
  else
  {
     // Retrieve the extension flags.
    if (FAILED(pCertServerExit->GetCertificateExtensionFlags(
                                &ExtFlags)))
        printf("Failed GetCertificateExtensionFlags\n");
    else
        // This sample will display the extension OID string,
        // the extension flags (in hex) and
        // the length of the BSTR binary ASN-encode extension.
        printf("Extension: %ws\tFlags:%x\tLength:%u\n",
               bstrExt,
               ExtFlags,
               SysStringByteLen(varExt.bstrVal));
  }
}
// Determine if hr was S_FALSE, meaning the enumeration 
// was completed, or some other error.
if (S_FALSE != hr)
    printf("Failed EnumerateExtensions - %x\n", hr);
// Free BSTR resource.
if (NULL != bstrExt)
    SysFreeString(bstrExt);
// Free VARIANT resource.
    VariantClear(&varExt);

Requirements

Requirement	Value
Minimum supported client	None supported
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	certif.h (include Certsrv.h)
Library	Certidl.lib
DLL	Certcli.dll