ICertExit

Certificate Services サーバーと終了モジュール(exit module)との間の通信を提供します。

ICertExit の実装者は、ICertManageModule も実装する必要があります。さらに、ICertExit を実装するクラスの ProgID は、命名規則に従う必要があります。具体的には、ProgID は次の形式でなければなりません。

"MyApp.Exit"

ここで MyApp は、アプリケーションを識別する指定子です。たとえば C++ では、ICertExit を実装するクラス(CMyCertExitModule)の DECLARE_REGISTRY マクロで次のコードを使用できます。

DECLARE_REGISTRY(
    CMyCertExitModule,
    L"MyCode.Exit.1",
    L"MyCode.Exit",
    IDS_CERTEXITMODULE_DESC,
    THREADFLAGS_BOTH)

上記のサンプルでは、IDS_CERTEXITMODULE_DESC 値は、クラスを説明する文字列に対応する、リソースファイル(.rc)内のアプリケーション固有の識別子です。

Certmod.h で定義されている文字列定数を使用すると、命名規則への準拠が容易になります。

定数	値
wszCERTEXITMODULE_POSTFIX	TEXT(".Exit")

 

Certificate Services サーバーに同時に登録できる Visual Basic Scripting Edition 終了モジュールは、1 つだけです。複数の Visual Basic Scripting Edition 終了モジュールが登録されている場合、証明機関(CA)MMC スナップイン、Certificate Services アプリケーション、または certutil コマンドラインプログラムでエラーが発生することがあります。Visual Basic Scripting Edition の開発環境では、DLL のビルドが成功すると、その DLL が自動的に登録される点に注意してください。そのため、ある Visual Basic Scripting Edition 終了モジュールが既に登録されている状態で別の Visual Basic Scripting Edition 終了モジュールを作成すると、この状況が発生することがあります。この状況を回避するには、コマンドライン命令 regsvr32 /u FileName.dll を使用して、いずれかの Visual Basic Scripting Edition 終了モジュールの登録を解除する必要があります。ここで FileName.dll は、アクティブにする予定のない Visual Basic Scripting Edition 終了モジュールの名前です。

Visual Basic Scripting Edition で ICertExit を実装する場合は、プロジェクトに次の形式の名前を付ける必要があります。

"MyApp"

ここで MyApp は、アプリケーションを識別する指定子です。さらに、ICertExit を実装するクラスには "Exit" という名前を付ける必要があります。

サーバーエンジンが自身を初期化するときに、サーバーエンジンによって呼び出されます。

C++

メソッドが成功した場合、S_OK を返し、*pEventMask には下記の表のフラグの組み合わせが設定されます(終了モジュールがどのイベントの通知も必要としない場合は EXITEVENT_INVALID が設定されます)。

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

終了モジュールがどのイベントの通知も必要としない場合は、フラグ EXITEVENT_INVALID を設定してください。

VB

戻り値は、終了モジュールが通知を要求するイベントを示すフラグを含むマスクです。呼び出し後、それらの種類のすべてのイベントは、Notify の呼び出しを通じて、サーバーエンジンから終了モジュールへ通知されます。次のフラグは、いずれか、またはすべてを設定できます。

戻り値コード/値	説明
EXITEVENT_CERTDENIED &H4	証明書が拒否されました。
EXITEVENT_CERTISSUED &H1	証明書が発行されました。
EXITEVENT_CERTPENDING &H2	証明書が保留中です。
EXITEVENT_CERTRETRIEVEPENDING &H10	RetrievePending の呼び出しに成功しました。
EXITEVENT_CERTREVOKED &H8	証明書が失効しました。
EXITEVENT_CRLISSUED &H20	証明書失効リストが発行されました。
EXITEVENT_INVALID 0	現在、そのイベントは有効ではありません。
EXITEVENT_SHUTDOWN &H40	Certificate Services のシャットダウン。

カスタム終了モジュールを作成する場合は、このメソッドを実装してください。

例

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

STDMETHODIMP CCertExit::Initialize(
    /* [in] */ BSTR const strConfig,
    /* [retval][out] */ LONG __RPC_FAR *pEventMask)
{
    // Verify valid pointer passed in.
    if (NULL == pEventMask)
        return ( E_POINTER );  // Bad pointer

    // strConfig can be used by the Exit module.
    // Here, it is stored in a BSTR member variable.
    // Remember to call SysFreeString to free m_strConfig when done.
    m_strConfig = SysAllocString( strConfig );
    // Check to determine whether there was enough memory.
    if (NULL == m_strConfig)
        return ( E_OUTOFMEMORY );  // Not enough memory

    // Inform server engine (CA) that we're interested in
    // the following events.
    *pEventMask = EXITEVENT_CERTISSUED |
                  EXITEVENT_CERTPENDING |
                  EXITEVENT_CERTDENIED |
                  EXITEVENT_CERTREVOKED |
                  EXITEVENT_CERTRETRIEVEPENDING |
                  EXITEVENT_CRLISSUED |
                  EXITEVENT_SHUTDOWN;

    if ( fDebug )
    {
        printf("Exit's Initialize member called\n");
        printf("\tstrConfig = %ws\n", strConfig );
    }

    return( S_OK );
}

イベントが発生したことを終了モジュールに通知するために、サーバーエンジンによって呼び出されます。

VB

メソッドが成功した場合は、S_OK を返します。

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

証明機関(CA)が複数の終了モジュールを使用している場合、Certificate Services は各終了モジュールにそのイベントを通知します(その終了モジュールが Initialize によって通知を要求していることが前提です)。終了モジュールが通知される順序を想定してはならず、また、ある終了モジュールが別の終了モジュールの処理に依存してもなりません。通知された各終了モジュールが Notify から復帰するまでは、次の終了モジュールには通知されません。

例

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

STDMETHODIMP CCertExit::Notify(
    /* [in] */ LONG ExitEvent,
    /* [in] */ LONG Context)
{
    char *pszEvent;
    HRESULT hr = S_OK;

    switch (ExitEvent)
    {
    case EXITEVENT_CERTISSUED:
        //  Call application-specific function for issued certs.
        hr = MyEventCertIssued(Context);
        pszEvent = "certissued";
        break;

    case EXITEVENT_CERTPENDING:
        pszEvent = "certpending";
        break;

    case EXITEVENT_CERTDENIED:
        pszEvent = "certdenied";
        break;

    case EXITEVENT_CERTREVOKED:
        pszEvent = "certrevoked";
        break;

    case EXITEVENT_CERTRETRIEVEPENDING:
        pszEvent = "retrievepending";
        break;

    case EXITEVENT_CRLISSUED:
        pszEvent = "crlissued";
        break;

    case EXITEVENT_SHUTDOWN:
        //  Call application-specific function for shutdown.
        hr = MyEventShutdown();
        pszEvent = "shutdown";
        break;

    default:
        pszEvent = "Unexpected event";
        break;
    }

    if ( fDebug )
    {
        //  Display what took place.
        printf("Exit::Notify(%s=%x, context=%u) return=%x\n",
                      pszEvent,
                      ExitEvent,
                      Context,
                      hr);
    }

    return(hr);
}

終了モジュールとその機能に関する、人が読める形式の説明を返します。

C++

メソッドが成功した場合は、S_OK を返します。

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

VB

終了モジュールとその機能を説明する文字列を返します。

カスタム終了モジュールを作成する場合は、このメソッドを実装してください。

例

STDMETHODIMP
CCertExit::GetDescription(
    /* [out, retval] */ BSTR __RPC_FAR *pstrDescription)
{
    if (NULL == pstrDescription)
    {
        // Bad pointer address.
        return (E_POINTER);
    }
    if (NULL != *pstrDescription)
    {
        SysFreeString(*pstrDescription);
        *pstrDescription=NULL;
    }
    // wszMyExitModuleDesc defined elsewhere, for example:
    // #define wszMyExitModuleDesc L"My Exit Module"
    *pstrDescription = SysAllocString(wszMyExitModuleDesc);
    if (NULL == *pstrDescription)
    {
        // Not enough memory
        return ( E_OUTOFMEMORY );
    }
    // Success
    return( S_OK );
}

#define global IID_ICertExit "{E19AE1A0-7364-11D0-8816-00A0C903B83C}"
#usecom global ICertExit IID_ICertExit "{}"
#comfunc global ICertExit_Initialize      7 wstr,var
#comfunc global ICertExit_Notify          8 int,int
#comfunc global ICertExit_GetDescription  9 var
; ※数字は vtbl インデックス(0始まり)。0/1/2 は IUnknown(QueryInterface/AddRef/Release)。
; ※このインターフェースは直接 CoCreateInstance するクラスIDが無いため "{}"(他メソッド/アクティベーションで取得)。
; ※出力/バッファ引数は var(変数直渡し)。varptr 方式にも切替可。
; ※IDispatch 実装。HSP では comobj 経由でメソッド名による呼び出しも可能(vtbl 不要)。