ICEnroll::enumContainers [C++]

CEnroll.enumContainers [Visual Basic]

The enumContainers method enumerates all the containers for the provider specified in the ProviderName property. If that property has not been changed, then the default value of ProviderName (usually Microsoft Base Cryptographic Provider) as set in the registry, is used for the enumeration.

[Visual Basic]
objEnroll.enumContainers( _
            dwIndex As Long ) As String
[C++]
HRESULT enumContainers (
  DWORD dwIndex,   // in
  BSTR *pbstrContainerName      // out
);

Parameters

[Visual Basic] objEnroll

Object expression that resolves to a CEnroll object.

[Visual Basic,C++] dwIndex

Specifying zero for dwIndex gets the first container. Increment dwIndex for successive containers. When there are no more containers, ERROR_NO_MORE_ITEMS is returned for C++, and it is triggered for Visual Basic.

[C++] pbstrContainerName

Pointer to BSTR variable to receive the name of the container being enumerated. It is the responsibility of the caller to free this variable (via SysFreeString).

Return Values

[Visual Basic] The return value is a String variable representing the name of the container being enumerated. An exception is raised if an error is encountered or when there are no more items remaining in the enumeration sequence.

[C++] The return value is an HRESULT. A value of S_OK indicates success. Upon successful completion of this function, pbstrContainerName will contain the name of the enumerated container. When there are no more containers, the value ERROR_NO_MORE_ITEMS is returned.

Example Code [C++]

BSTR       bstrProvName = NULL;
BSTR       bstrCon = NULL;
DWORD      nCon;
HRESULT    hr;

// Let the control know which provider to query.
bstrProvName = SysAllocString(TEXT("Microsoft Base")
                              TEXT(" Cryptographic Pr")
                              TEXT("ovider v1.0"));
hr = pEnroll->put_ProviderName( bstrProvName );
if (FAILED(hr))
{
    printf("Failed put_ProviderName - %x\n", hr);
    goto error;
}

// enumerate the containers for this provider
nCon = 0;
printf("Containers for %ws:\n", bstrProvName );
// pEnroll is previously instantiated ICEnroll interface pointer
while ( S_OK == pEnroll->enumContainers(nCon, &bstrCon) )
{
    printf("\t%d) %ws\n", nCon++, bstrCon );
    // Free this string, so it can be re-used.
    if ( NULL != bstrCon )
    {
        SysFreeString( bstrCon );
        bstrCon = NULL;
    }
}

error:

//clean up resources, etc.
if ( NULL != pEnroll )
       pEnroll->Release();

if ( NULL != bstrProvName )
    SysFreeString( bstrProvName );

if ( NULL != bstrCon )
    SysFreeString( bstrCon );

CoUninitialize();

Example Code [Visual Basic]

Dim strOut As String
Dim i As Integer
Dim NoMoreRecs As Boolean

    ' enumerate the containers
    i = 0
    NoMoreRecs = False

    On Error GoTo ErrorHandler
    Do
        strOut = objEnroll.enumContainers(i)
        If NoMoreRecs Then
            Exit Do
        End If
        ' display the index and Container value
        MsgBox (i & " " & strOut)
        i = i + 1
    Loop

    Exit Sub

ErrorHandler:

    NoMoreRecs = True
    Resume Next

    End Sub

Requirements

  Windows NT/2000: Requires Windows 2000 (or Windows NT 4.0 with the Windows NT 4.0 Option Pack).
  Header: Declared in Xenroll.h.
  Library: Use Uuid.lib.

See Also

ProviderName