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 |
---|---|
|
Request did not complete |
|
Request failed |
|
Request denied |
|
Certificate issued |
|
Certificate issued separately |
|
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 |