ICertRequest

クライアントまたは仲介アプリケーションと証明書サービス (Certificate Services) との間の通信を提供します。

証明書サービス (Certificate Services) サーバーに要求を送信します。

C++

この関数が正常に完了すると、*pDisposition は次の表のいずれかの値に設定されます。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

VB

BASE64 形式の要求をファイルから読み取る場合は、ファイルが Unicode であることを確認するか、このメソッドで要求を送信する前に ASCII から Unicode に変換してください。

Examples

    //  The pointer to the interface object.
    ICertRequest * pCertRequest = NULL;

    //  The variable for the computer\CAName.
    BSTR         bstrCA = NULL;

    //  The variable for the request.
    BSTR         bstrRequest = NULL;

    //  The variable for the attributes.
    BSTR         bstrAttribs = NULL;

    //  The variable for the disposition code.
    long        nDisp;

    HRESULT     hr;

    //  Initialize COM.
    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

    //  Check status.
    if (FAILED(hr))
    {
        printf("Failed CoInitializeEx [%x]\n", hr);
        goto error;
    }

    //  Instantiate the CertConfig object.
    hr = CoCreateInstance(CLSID_CCertRequest,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_ICertRequest,
                          (void **)&pCertRequest);
    if (FAILED(hr))
    {
        printf("Failed CoCreateInstance pCertRequest [%x]\n", hr);
        goto error;
    }

    //  Specify the certification authority.
    //  Note: In C++, produce one backslash (\) by using two.
    bstrCA = SysAllocString(L"server01\\myCAName");

    //  Create the request (not shown), and assign it to bstrRequest,
    //  for example, use ICEnroll::createPKCS10.

    //  Generate the attributes. In this case, no attributes
    //  are specified.
    bstrAttribs = SysAllocString(L"");
    
    //  Submit the request.
    hr = pCertRequest->Submit(CR_IN_BASE64 | CR_IN_PKCS10, 
                              bstrRequest,
                              bstrAttribs,
                              bstrCA, 
                              &nDisp );
    if (FAILED(hr))
    {
        printf("Failed Submit [%x]\n", hr);
        goto error;
    }
    else
    {
        //  Use the disposition value as needed.
    }

    //  Done processing.

error:

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

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

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

    //  Clean up object resources.
    if (NULL != pCertRequest)
        pCertRequest->Release();

    //  Free COM resources.
    CoUninitialize();

以前に CR_DISP_INCOMPLETE または CR_DISP_UNDER_SUBMISSION を返した可能性のある以前の要求から、証明書の処理状況を取得します。

C++

この関数が正常に完了すると、*pDisposition は次の表のいずれかの値に設定されます。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

VB

このメソッドの呼び出しが成功すると、EXITEVENT_CERTRETRIEVEPENDING イベントが生成されます。アクティブな終了モジュール (exit module) は、( ICertExit3::Notify の呼び出しによって) このイベントの通知を受け取ります。ただし、終了モジュールが 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 );

この要求の最後の戻りコードを取得します。これは要求の処理状況ではなく、エラーコード情報を返します。

C++

この関数が正常に完了すると、*pStatus は ICertRequest3::Submit、ICertRequest3::RetrievePending、または ICertRequest3::GetCACertificate の最新の呼び出しの結果コードに設定されます。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

VB

GetLastStatus によって取得される値は、 ICertRequest3::Submit、 ICertRequest3::RetrievePending、または ICertRequest3::GetCACertificate の最新の呼び出しに依存します。これらのメソッドのいずれかの呼び出しがサーバー上で失敗した場合は、GetLastStatus を呼び出してエラー番号を取得します。一部のサーバー障害 (拒否された要求など) では、メソッド呼び出しから S_OK と CR_DISP_ISSUED 以外の処理状況が返されるため、GetLastStatus を使用して失敗の具体的な原因を取得できます。これらのメソッドのいずれかの呼び出しが成功した場合、その後の GetLastStatus の呼び出しは S_OK (ゼロ) を返します。

さらに、要求の処理状況は証明書サービスのデータベースに保存され、証明機関 MMC スナップインで表示できます (「要求処理状況」列を選択します)。

Examples

HRESULT    hrServer, hr;
// pCertRequest is previously instantiated
// ICertRequest object pointer.
hr = pCertRequest->GetLastStatus((LONG *) &hrServer);
if (FAILED(hr))
{
    printf("Failed GetLastStatus [%x]\n", hr);
    goto error;
}
else
{
    // Use the HRESULT value as needed...
}

要求および後続の証明書の現在の内部要求番号を取得します。

C++

この関数が正常に完了すると、*pRequestId は要求 ID の値に設定されます。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

VB

証明書要求の現在の処理状況を示す、人間が読めるメッセージを取得します。

C++

この関数が正常に完了すると、*pstrDispositionMessage は、証明書要求の現在の処理状況を示す、人間が読めるメッセージを含む BSTR に設定されます。このメソッドを使用するには、BSTR 型の変数を作成し、その変数を NULL に設定して、この変数のアドレスを pstrDispositionMessage として渡します。BSTR の使用が終わったら、SysFreeString 関数を呼び出して解放します。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

VB

アプリケーションは、以前の ICertRequest3::Submit または ICertRequest3::RetrievePending の呼び出しによってサーバーから取得されたメッセージを得るために、このメソッドを呼び出します。さらに、このメッセージは証明書サービスのデータベースに保存され、証明機関 MMC スナップインで表示できます (「要求処理状況メッセージ」列を選択します)。メッセージにローカライズされたテキストが含まれている場合、それは (サーバーのロケールに基づいて) サーバー上でローカライズされたものです。

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);

証明書サービスサーバーの証明機関 (CA) 証明書を返します。

C++

このメソッドが正常に完了すると、*pstrCertificate は CA 証明書を含む BSTR に設定されます。このメソッドを使用するには、BSTR 型の変数を作成し、その変数を NULL に設定して、この変数のアドレスを pstrCertificate として渡します。

*pstrCertificate の使用が終わったら、SysFreeString 関数を呼び出して解放します。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

VB

管理タスクは DCOM を使用します。以前のバージョンの Certadm.h で定義されているこのインターフェイスメソッドを呼び出すコードは、クライアントとサーバーの両方が同じ Windows オペレーティングシステムを実行している限り、Windows ベースのサーバー上で動作します。

要求に対して発行された証明書を、X.509 証明書として、またはオプションで Public Key Cryptography Standards (PKCS) にパッケージ化して返します。

メソッドが *pstrCertificate を要求の証明書を含む BSTR に設定した場合、S_OK を返します。

メソッドが失敗した場合は、エラーを示す HRESULT 値を返します。一般的なエラーコードの一覧については、Common HRESULT Values を参照してください。

アプリケーションは、以前の ICertRequest3::Submit または ICertRequest3::RetrievePending の呼び出しによって発行された証明書を取得するために、このメソッドを呼び出します。

Examples

次の例は、証明書の取得を示しています。

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

HRESULT main()
{
    //  Pointer to interface object.
    ICertRequest * pCertRequest = NULL;

    //  Variable for COMPUTER\CANAME.
    BSTR         bstrCA = NULL;

    //  Variable for CA Certificate.
    BSTR         bstrCACert = NULL;

    HRESULT     hr;

    //  Initialize COM.
    hr = CoInitializeEx(NULL, COINIT_APARTMENTTHREADED);

    //  Check status.
    if (FAILED(hr))
    {
        printf("Failed CoInitializeEx [%x]\n", hr);
        goto error;
    }

    //  Instantiate the CertConfig object.
    hr = CoCreateInstance(CLSID_CCertRequest,
                          NULL,
                          CLSCTX_INPROC_SERVER,
                          IID_ICertRequest,
                          (void **)&pCertRequest);
    if (FAILED(hr))
    {
        printf("Failed CoCreateInstance pCertRequest [%x]\n", hr);
        goto error;
    }

    //  Note use of two backslashes (\\) in C++ 
    //  to produce one backslash (\).
    bstrCA = SysAllocString(L"server01\\myCAName");
    
    //  Retrieve the CA certificate.
    hr = pCertRequest->GetCACertificate(FALSE,
                                        bstrCA,
                                        CR_OUT_BASE64,
                                        &bstrCACert);
    if (FAILED(hr))
    {
        printf("Failed GetCACertificate [%x]\n", hr);
        goto error;
    }
    else
    {
        //  Use CA Certificate as needed.
    }

    //  Done processing.

error:

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

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

    //  Clean up object resources.
    if (NULL != pCertRequest)
        pCertRequest->Release();

    //  Free COM resources.
    CoUninitialize();

    return hr;

}