IHttpTokenEntry::GetPrimaryToken メソッド

要求を処理するプロセスのプライマリ トークンを返します。

構文

virtual HANDLE GetPrimaryToken(  
   VOID  
) = 0;  

パラメーター

このメソッドは、パラメーターを受け取りません。

戻り値

HANDLE要求を処理するプロセスの偽装トークンを表す 。 NULL の場合もあります。

解説

プライマリ トークンは、要求を処理するプロセスに関連付けられているユーザー アカウントのセキュリティ コンテキストを定義するハンドルです。 このトークンは、プロセスのアクセス規則に基づいてシステム リソースへのアクセスを制限します。

GL_CACHE_OPERATION イベントに登録する CGlobalModule 派生クラスは、CGlobalModule::OnGlobalCacheOperationvirtual メソッドのパラメーターとして ICacheProvider ポインターを受け取ります。 ICacheProvider::GetCacheRecord メソッドを呼び出すことで IHttpCacheSpecificData ポインターを取得できます。場合によっては、このIHttpCacheSpecificDataポインターを IHttpTokenEntry ポインターにダウンキャストできます。 その後、 メソッドを呼び出して、プライマリ トークン ハンドルを GetPrimaryToken 取得できます。

ダウンキャスト ルールの詳細については、「 ICacheProvider::GetCacheRecord」を参照してください。

実装側の注意

IHttpTokenEntry 実装者は、このデータを使用したリソース管理を担当します。そのため、 IHttpTokenEntry 実装者は、ハンドルが不要になったときに CloseHandle を呼び出す必要があります。

呼び出し元に関する注意事項

IHttpTokenEntry 実装者は、このデータを使用したリソース管理を担当します。したがって、 IHttpTokenEntry このデータが不要になった場合、クライアントは返されたハンドルで を呼び出 CloseHandle す必要はありません。 さらに、アクセス違反がスローされるか、データが無効になるため、クライアントは、このハンドルが参照するメモリの状態を変更しないでください。

例

次のコード例では、イベントをリッスンGL_CACHE_OPERATIONしてGL_CACHE_CLEANUPし、その情報をイベント ビューアーに書き込むIHttpTokenEntryグローバル モジュールを作成する方法を示します。

#pragma warning( disable : 4290 )
#pragma warning( disable : 4530 )

#define _WINSOCKAPI_
#include <windows.h>
#include <sal.h>
#include <tchar.h>
#include <initguid.h>
#include <httptrace.h>
#include <httpserv.h>
#include <httpcach.h>

#include <string>
using namespace std;

// The CConvert class mirrors the Convert class that is 
// defined in the .NET Framework. It converts primitives 
// and other data types to wstring types.
class CConvert
{
public:
    // The ToString method converts a HANDLE to a wstring.
    // h: the HANDLE to convert to a wstring.
    // return: the HANDLE as a wstring.
    static wstring ToString(HANDLE h)
    {
        // If the HANDLE is NULL, return the "NULL" string.
        if (NULL == h)
        {
            return L"NULL";
        }

        // If the HANDLE is not valid, return 
        // the INVALID_HANDLE_VALUE as a string.
        if (INVALID_HANDLE_VALUE == h)
        {
            return L"INVALID_HANDLE_VALUE";
        }

        // The HANDLE is valid.
        return L"valid";
    }

    // The ToByteString converts a double-byte 
    // character string to a single-byte string.
    // str: the double-byte string to convert.
    // return: a single-byte string copied from str.
    static string ToByteString(const wstring& str)
    {
        // Get the length of the 
        // double-byte string.
        size_t length = str.length();

        // Create a temporary char pointer.
        char* byteChar = new char[length+1];
        byteChar[0] = '\0';
        // Copy the double-byte character string
        // into the single-byte string.        
        size_t charsReturned = 0;
        wcstombs_s(&charsReturned, byteChar, 
                   length+1, str.c_str(), length+1);
        // Create a string to return.
        string retString = byteChar;
        // Delete the temporary string and
        // set that string to NULL.
        delete[] byteChar;
        byteChar = NULL;

        // Return the single-byte string.
        return retString;
    }
};

// The CEventException class is 
// an exception that can be thrown 
// when writing an event fails.
class CEventException
{
public:
    // Creates the CEventException class.
    // str: the wstring that could 
    // not be written to a log.
    CEventException(const wstring& str)
        : m_string(str)
    {
        
    }

    // Creates the destructor for 
    // the CEventException class.
    virtual ~CEventException()
    {

    }

private:
    // Specify the wstring that could
    // not be written to an event viewer.
    wstring m_string;
};

// The CEventWriter class writes XML 
// documents and strings to the event log.
class CEventWriter
{
public:
    // Creates the CEventWriter class.
    // name: the name of the 
    // event log to open.
    CEventWriter(const wstring& name)
    {                
        #ifdef UNICODE
        m_eventLog = RegisterEventSource(NULL, name.c_str());
        #else
        string multiName = CConvert::ToByteString(name);
        m_eventLog = RegisterEventSource(NULL, multiName.c_str());
        #endif        
    }

    // Creates the destructor for the 
    // CEventWriter class. This destructor
    // closes the HANDLE to the event 
    // log if that HANDLE is open.
    virtual ~CEventWriter()
    {
        // If the HANDLE to the event 
        // log is open, close it.
        if (NULL != m_eventLog)
        {
            // Deregister the event log HANDLE.
            DeregisterEventSource(m_eventLog);
            // Set the HANDLE to NULL.
            m_eventLog = NULL;
        }
    }

    // The ReportInfo method writes 
    // a wstring to the event log.
    // info: the wstring to write.
    // return: true if the event log is written.
    BOOL ReportInfo(const wstring& info)
    {
        return ReportEvent(EVENTLOG_INFORMATION_TYPE, info);
    }
protected:
    // The ReportEvent method accepts an event type
    // and a wstring, and attempts to write that 
    // event to the event log.
    // type: the type of the event.
    // data: the wstring to write to the event log.
    // return: true if the event log is written;
    // otherwise, false.
    BOOL ReportEvent(WORD type, const wstring& data)
    {
        // If the m_eventLog HANDLE 
        // is NULL, return false.
        if (NULL == m_eventLog)
        {
            return FALSE;
        }

        #ifndef _DEBUG
        // If the current build is not debug,
        // return so the event log is not written.
        return TRUE;
        #endif

        #ifdef UNICODE
        // The unicode version of the ReportEvent
        // method requires double-byte strings.
        PCWSTR arr[1];
        arr[0] = data.c_str();
        return ::ReportEvent(m_eventLog,
                             type,
                             0, 0, NULL, 1, 
                             0, arr, (void*)arr);
        #else
        // The non-unicode version of the ReportEvent
        // method requires single-byte strings.
        string multiByte = 
            CConvert::ToByteString(data);
        LPCSTR arr[1];
        arr[0] = multiByte.c_str();
        return ::ReportEvent(m_eventLog,
                             type,
                             0, 0, NULL, 1,
                             0, arr, (void*)arr);
        #endif
    }
private:
    // Specify the HANDLE to the 
    // event log for writing.
    HANDLE m_eventLog;
};

// The CGlobalCacheModule class creates the CGlobalModule 
// class and registers for GL_CACHE_OPERATION and 
// GL_CACHE_CLEANUP events.
class CGlobalCacheModule : public CGlobalModule
{
public:
    // Creates the destructor for the 
    // CGlobalCacheModule class.
    virtual ~CGlobalCacheModule()
    {

    }

    // The RegisterGlobalModule method creates and registers 
    // a new CGlobalCacheModule for GL_CACHE_OPERATION and 
    // GL_CACHE_CLEANUP events.
    // dwServerVersion: the current server version.
    // pModuleInfo: the current IHttpModuleRegistrationInfo pointer.
    // pGlobalInfo: the current IHttpServer pointer.
    // return: ERROR_NOT_ENOUGH_MEMORY if the heap is out of 
    // memory; otherwise, the value from the call to the 
    // SetGlobalNotifications method on the pModuleInfo pointer.
    static HRESULT RegisterGlobalModule
    (
        DWORD dwServerVersion,
        IHttpModuleRegistrationInfo* pModuleInfo,
        IHttpServer* pGlobalInfo
    )
    {        
        // The pGlobalInfo parmeter must be non-NULL because
        // the constructor for the CGlobalCacheModule class
        // requires a non-NULL pointer to a valid IHttpServer 
        // pointer.
        if (NULL == pGlobalInfo)
        {
            return E_INVALIDARG;
        }

        // Create a new CGlobalCacheModule pointer.
        CGlobalCacheModule* traceModule = 
            new CGlobalCacheModule();

        // Return an out-of-memory error if the traceModule 
        // is NULL after the call to the new operator.
        if (NULL == traceModule)
        {            
            return HRESULT_FROM_WIN32(ERROR_NOT_ENOUGH_MEMORY);
        }        

        // Attempt to set global notification for both 
        // GL_CACHE_OPERATION and GL_CACHE_CLEANUP events 
        // by using the traceModule as a listener.
        HRESULT hr = pModuleInfo->SetGlobalNotifications
            (traceModule, GL_CACHE_OPERATION | GL_CACHE_CLEANUP);

        // If the SetGlobalNotifications method 
        // fails, return the HRESULT.
        if (FAILED(hr))
        {
            return hr;
        }

        // Set the priority to PRIORITY_ALIAS_FIRST, 
        // which will populate the data as much as possible.
        hr = pModuleInfo->SetPriorityForGlobalNotification(
            GL_CACHE_OPERATION, PRIORITY_ALIAS_FIRST);

        // Return the HRESULT from the call to 
        // the SetGlobalNotifications method.
        return hr;
    }
    // The OnGlobalCacheOperation method is called 
    // when GL_CACHE_OPERATION operations occur.
    // pProvider: the current ICacheProvider pointer.
    // return: GL_NOTIFICATION_CONTINUE if the event
    // log is written; otherwise, GL_NOTIFICATION_HANDLED.
    virtual GLOBAL_NOTIFICATION_STATUS OnGlobalCacheOperation
    (
        IN ICacheProvider* pProvider
    )
    {
        // The OnGlobalCacheOperation must return if the 
        // pProvider parameter is NULL because this pointer 
        // is needed for data to write to the event log.
        if (NULL == pProvider)
        {
            return GL_NOTIFICATION_CONTINUE;
        }

        try
        {
            // Get the IHttpCacheSpecificData pointer 
            // from the ICacheProvider element.
            IHttpCacheSpecificData* cacheSpecificData = 
                pProvider->GetCacheRecord();

            // Write the IHttpCacheSpecificData 
            // pointer information to the event log.
            Write(cacheSpecificData);
        }
        // A CEventException is thrown 
        // if any Write method cannot 
        // write to the event log.
        catch (CEventException)
        {
            return GL_NOTIFICATION_HANDLED;
        }

        // Return GL_NOTIFICATION_CONTINUE so that 
        // other listeners will receive the event.
        return GL_NOTIFICATION_CONTINUE;
    }

    // The OnGlobalCacheCleanup method is called 
    // when GL_CACHE_CLEANUP events occur.
    // return: GL_NOTIFICATION_CONTINUE.
    virtual GLOBAL_NOTIFICATION_STATUS OnGlobalCacheCleanup(VOID)
    {
        // Return GL_NOTIFICATION_CONTINUE so that 
        // other listeners will receive this event.
        return GL_NOTIFICATION_CONTINUE;
    }

    // PRE: none.
    // POST: the Terminate method calls delete on 
    // this, which releases the memory for the current 
    // CGlobalCacheModule pointer on the heap.
    virtual VOID Terminate(VOID)
    {
        delete this;
    }
protected:
    // Creates the constructor for 
    // the CGlobalCacheModule class.
    // The constructor initializes the 
    // private m_eventWriter to write 
    // to the IISADMIN event log.
    CGlobalCacheModule() : m_eventWriter(L"IISADMIN")
    {

    }

    // The ReportInfo method writes the 
    // formatted name and value of a method 
    // call to the event log.
    // name: the name of the method or property.
    // value: the value of the 
    // method or the property.
    // throws: a CEventException exception.
    void ReportInfo
    (
        const wstring& name,
        const wstring& value
    ) throw (CEventException)
    {
        // Create a formatted string to
        // write to the event log.
        wstring infoString =
            name + wstring(L":  ") + value;
        // Attempt to write the formatted 
        // string to the event log. If the 
        // ReportInfo method call fails,
        // throw a CEventException exception.
        if (!m_eventWriter.ReportInfo(infoString))
        {
            throw CEventException(infoString);
        }        
    }

    // The Write method writes IHttpTokenEntry 
    // pointer information to the event log.
    // tokenEntry: the IHttpTokenEntry 
    // pointer to write.
    // throws: a CEventException exception.
    void Write
    (
        IHttpTokenEntry* tokenEntry        
    ) throw (CEventException)
    {
        // If the tokenEntry parameter is NULL, 
        // throw a CEventException exception.
        if (NULL == tokenEntry)
        {
            CEventException ce
                (L"NULL IHttpTokenEntry pointer");
            throw ce;
        }

        // Get the primary token from the
        // IHttpTokenEntry pointer.
        HANDLE primaryTokenHANDLE =
            tokenEntry->GetPrimaryToken();

        // Convert the primary 
        // token to a wstring.
        wstring primaryToken =
            CConvert::ToString(primaryTokenHANDLE);

        // Write the primary token information
        // to the event log.
        ReportInfo(L"IHttpTokenEntry::GetPrimaryToken",
                   primaryToken);
    }

    // The Write method writes IHttpCacheSpecificData
    // pointer information to the event log.
    // cacheSpecificData: the IHttpCacheSpecificData
    // pointer to write.
    // throws: a CEventException exception.
    void Write
    (
        IHttpCacheSpecificData* cacheSpecificData        
    ) throw (CEventException)
    {
        // If the cacheSpecificData is NULL, 
        // return. IHttpCacheSpecificData 
        // pointer data is optional.
        if (NULL == cacheSpecificData)
        {
            return;
        }

        // Get the IHttpCacheKey pointer from the 
        // IHttpCacheSpecificData pointer.
        IHttpCacheKey* cacheKey = 
            cacheSpecificData->GetCacheKey();

        // If the cacheKey is non-NULL, get its name.
        // This may allow downcasting to a more specific 
        // IHttpCacheSpecificData pointer type.
        if (NULL != cacheKey)
        {
            // Get the cache name from the cacheKey.
            wstring cacheKeyName = cacheKey->GetCacheName();

            // If the cacheKeyName is TOKEN_CACHE_NAME, the
            // IHttpCacheSpecificData pointer can be 
            // downcast to an IHttpTokenEntry pointer.
            if (TOKEN_CACHE_NAME == cacheKeyName)
            {
                // Attempt to cast the IHttpCacheSpecificData 
                // pointer to an IHttpTokenEntry pointer.                
                IHttpTokenEntry* tokenEntry =
                    dynamic_cast<IHttpTokenEntry*>(cacheSpecificData);
                // Write the IHttpTokenEntry pointer
                // information to the event log.
                Write(tokenEntry);
            }
        }
    }

private:
    // Specify the event writer.
    CEventWriter m_eventWriter;
};

// The RegisterModule method is the 
// main entry point for the DLL.
// dwServerVersion: the current server version.
// pModuleInfo: the current 
// IHttpModuleRegistrationInfo pointer.
// pGlobalInfo: the current IHttpServer pointer.
// return: the value returned by calling the
// CGlobalCacheModule::RegisterGlobalModule
// method.
HRESULT
__stdcall
RegisterModule(
    DWORD dwServerVersion,
    IHttpModuleRegistrationInfo* pModuleInfo,
    IHttpServer* pGlobalInfo
)
{        
    // Call the static method for initialization.
    return CGlobalCacheModule::RegisterGlobalModule            
        (dwServerVersion, 
         pModuleInfo, 
         pGlobalInfo);             
}

上記のコードは、新しいイベントをイベント ビューアーに書き込みます。ここで、Data ボックスには次のような文字列が含まれています。

IHttpTokenEntry::GetPrimaryToken: valid  

モジュールは RegisterModule 関数をエクスポートする必要があります。 この関数をエクスポートするには、プロジェクトのモジュール定義 (.def) ファイルを作成するか、スイッチを使用してモジュールを /EXPORT:RegisterModule コンパイルします。 詳細については、「 チュートリアル: ネイティブ コードを使用したRequest-Level HTTP モジュールの作成」を参照してください。

必要に応じて、各関数の呼び出し規約を __stdcall (/Gz) 明示的に宣言するのではなく、呼び出し規約を使用してコードをコンパイルできます。

要件

参照

IHttpTokenEntry インターフェイス