ICertRequest::RetrievePending method (certcli.h)

The RetrievePending method retrieves a certificate's disposition status from an earlier request that may have previously returned CR_DISP_INCOMPLETE or CR_DISP_UNDER_SUBMISSION.

If the resulting disposition status is CR_DISP_ISSUED, you can retrieve the issued certificate by calling ICertRequest3::GetCertificate. If a disposition other than CR_DISP_ISSUED is returned, call ICertRequest3::GetLastStatus, ICertRequest3::GetDispositionMessage, or both methods for more information.

Syntax

HRESULT RetrievePending(
  [in]          LONG       RequestId,
  [in]          const BSTR strConfig,
  [out, retval] LONG       *pDisposition
);

Parameters

[in] RequestId

The ID of the request that had previously returned CR_DISP_INCOMPLETE or CR_DISP_UNDER_SUBMISSION.

[in] strConfig

Represents a valid configuration string for the Certificate Services server. The string can be either an HTTPS URL for an enrollment server or in the form ComputerName\CAName, where ComputerName is the network name of the server, and CAName is the common name of the certification authority, as entered during Certificate Services setup. For information about the configuration string name, see ICertConfig.

Windows Server 2008, Windows Vista, Windows Server 2003 and Windows XP:  An HTTPS URL is not supported as an input.

[out, retval] pDisposition

A pointer to the request's disposition value.

Return value

C++

If the method succeeds, the method returns S_OK.

Upon successful completion of this function, *pDisposition is set to one of the values in the following table.

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

The return value specifies the disposition of the request. The disposition is one of the following values.
Return code Description
CR_DISP_INCOMPLETE
Request did not complete
CR_DISP_ERROR
Request failed
CR_DISP_DENIED
Request denied
CR_DISP_ISSUED
Certificate issued
CR_DISP_ISSUED_OUT_OF_BAND
Certificate issued separately
CR_DISP_UNDER_SUBMISSION
Request taken under submission

Remarks

A successful call to this method generates an EXITEVENT_CERTRETRIEVEPENDING event. An active exit module will receive notification of this event (by means of a call to ICertExit3::Notify) if the exit module specified this event when calling ICertExit3::Initialize.

Examples

BSTR    bstrCA = NULL;
long    nReqID, nDisp;

// In this example, the request ID is hard-coded.
nReqID = 1234;

// Note use of two '\' in C++ to produce one '\'.
bstrCA = SysAllocString(L"server01\\myCAName");

// pCertRequest is previously instantiated ICertRequest
// object pointer. Retrieve the status for the specified request.
hr = pCertRequest->RetrievePending( nReqID, bstrCA, &nDisp );
if (FAILED(hr))
{
    printf("Failed RetrievePending [%x]\n", hr);
    goto error;
}
else
{
    // Use the disposition value as needed...
}
// Free BSTR resource.
if ( NULL != bstrCA )
    SysFreeString( bstrCA );

Requirements

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

See also

CCertRequest

ICertConfig

ICertRequest

ICertRequest2

ICertRequest3