ICertRequest::GetDispositionMessage method (certcli.h)

Article
10/13/2021

The GetDispositionMessage method gets a human-readable message that gives the current disposition of the certificate request.

Note that the message returned here may have more detail than the returned error code. For example, ICertRequest3::GetLastStatus may return an HRESULT, while GetDispositionMessage will return a detailed reason that specifies why the request was denied.

Syntax

HRESULT GetDispositionMessage(
  [out] BSTR *pstrDispositionMessage
);

Parameters

[out] pstrDispositionMessage

A pointer to the BSTR that contains the disposition message.

Return value

C++

If the method succeeds, the method returns S_OK.

Upon successful completion of this function, *pstrDispositionMessage is set to the BSTR that contains a human-readable message that gives the current disposition of the certificate request. To use this method, create a variable of BSTR type, set the variable equal to NULL, and pass the address of this variable as pstrDispositionMessage. 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

The return value is a string that contains a human-readable message that gives the current disposition of the certificate request.

Remarks

An application would call this method to obtain the message retrieved from the server by means of an earlier call to ICertRequest3::Submit or ICertRequest3::RetrievePending. Additionally, the message is stored in the Certificate Services database and may be viewed by the Certification Authority MMC snap-in (choose the Request Disposition Message column). If the message contains localized text, it was localized on the server (based on the server's locale).

Examples

#include <windows.h>
#include <stdio.h>
#include <Certcli.h>

    BSTR    bstrDispMsg = NULL;
    // pCertRequest is previously instantiated ICertRequest object 
    // pointer. Retrieve the disposition message for the 
    // previous request.
    hr = pCertRequest->GetDispositionMessage(&bstrDispMsg);
    if (FAILED(hr))
    {
        printf("Failed GetDispositionMessage [%x]\n", hr);
        goto error;
    }
    else
    {
        // Use the disposition message as needed...
    }

    // Done processing.

error:

    // Free BSTR values.
    if (NULL != bstrCA)
        SysFreeString(bstrCA);

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

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