Метод IHttpTokenEntry::GetImpersonationToken
Возвращает токен олицетворения для пользователя.
Синтаксис
virtual HANDLE GetImpersonationToken(
VOID
) = 0;
Параметры
Этот метод не принимает параметров.
Возвращаемое значение
Объект , HANDLE представляющий токен олицетворения для пользователя. Может иметь значение "NULL".
Комментарии
Маркер олицетворения — это дескриптор, который определяет контекст безопасности пользователя, выполняющего запрос. Этот маркер позволяет серверу олицетворять пользователя во время запроса, чтобы доступ к системным ресурсам был основан на правилах доступа для этого пользователя.
Во время олицетворения используются как основной маркер, возвращенный методом GetPrimaryToken , так и токен олицетворения, возвращенный методом GetImpersonationToken . Это может либо расширить, либо заключить права пользователя на основе правил безопасности для этого пользователя.
Производные классы CGlobalModule, которые регистрируются для событий GL_CACHE_OPERATION, получают указатель ICacheProvider в качестве параметра метода CGlobalModule::OnGlobalCacheOperationvirtual. Вы можете получить указатель IHttpCacheSpecificData , вызвав метод ICacheProvider::GetCacheRecord , и в некоторых случаях можно понизить этот IHttpCacheSpecificData указатель на указатель IHttpTokenEntry . Затем можно получить дескриптор токена олицетворения, вызвав GetImpersonationToken метод .
Дополнительные сведения о правилах нисходяшей передачи см. в разделе ICacheProvider::GetCacheRecord.
Примечания для разработчиков
IHttpTokenEntry разработчики отвечают за управление ресурсами с помощью этих данных; IHttpTokenEntry Поэтому разработчики должны вызывать функцию CloseHandle для дескриптора, когда она больше не нужна.
Примечания для абонентов
IHttpTokenEntryразработчики отвечают за управление ресурсами с помощью этих данных; Поэтому клиенты не должны вызывать CloseHandle возвращенный дескриптор, IHttpTokenEntry если эти данные больше не нужны. Кроме того, клиенты не должны изменять состояние памяти, на которую ссылается этот дескриптор, так как будет вызвано нарушение доступа или данные станут недействительными.
Пример
В следующем примере кода показано, как создать глобальный модуль, который прослушивает GL_CACHE_OPERATION и GL_CACHE_CLEANUP события, а затем записывает IHttpTokenEntry сведения в Просмотр событий.
Внимание!
IIS 7 создает большое количество событий в Просмотр событий. Чтобы избежать ошибки переполнения журнала в рабочей среде, обычно следует избегать записи сведений кэша в журнал событий. В целях демонстрации этот пример кода записывает запись в Просмотр событий только в режиме отладки.
#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 impersonation token from
// the IHttpTokenEntry pointer.
HANDLE impersonationTokenHANDLE =
tokenEntry->GetImpersonationToken();
// Convert the token to a wstring.
wstring impersonationToken =
CConvert::ToString(impersonationTokenHANDLE);
// Write the impersonation token
// information to the event log.
ReportInfo(L"IHttpTokenEntry::GetImpersonationToken",
impersonationToken);
}
// 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);
}
Приведенный выше код записывает новое событие в Просмотр событий, где поле "Данные" содержит строку, аналогичную приведенной ниже.
IHttpTokenEntry::GetImpersonationToken: valid
Модуль должен экспортировать функцию RegisterModule . Эту функцию можно экспортировать, создав файл определения модуля (DEF- файл) для проекта, или скомпилировать модуль с помощью /EXPORT:RegisterModule параметра . Дополнительные сведения см. в разделе Пошаговое руководство. Создание модуля HTTP Request-Level с помощью машинного кода.
При необходимости можно скомпилировать код с помощью __stdcall (/Gz) соглашения о вызовах вместо явного объявления соглашения о вызовах для каждой функции.
Требования
| Тип | Описание |
|---|---|
| клиент | — IIS 7.0 в Windows Vista — IIS 7.5 в Windows 7 — IIS 8.0 в Windows 8 — IIS 10.0 в Windows 10 |
| Сервер | — IIS 7.0 в Windows Server 2008 — IIS 7.5 в Windows Server 2008 R2 — IIS 8.0 в Windows Server 2012 — IIS 8.5 в Windows Server 2012 R2 — IIS 10.0 в Windows Server 2016 |
| Продукт | — IIS 7.0, IIS 7.5, IIS 8.0, IIS 8.5, IIS 10.0 - IIS Express 7.5, IIS Express 8.0, IIS Express 10.0 |
| Заголовок | Httpserv.h |
См. также:
Интерфейс IHttpTokenEntry
Метод IHttpTokenEntry::GetPrimaryToken
Метод IHttpTokenEntry::GetSid
Обратная связь
Ожидается в ближайшее время: в течение 2024 года мы постепенно откажемся от GitHub Issues как механизма обратной связи для контента и заменим его новой системой обратной связи. Дополнительные сведения см. в разделе https://aka.ms/ContentUserFeedback.
Отправить и просмотреть отзыв по