QueryActCtxW-Funktion (winbase.h)

Artikel
08/27/2023

Die QueryActCtxW-Funktion fragt den Aktivierungskontext ab.

Syntax

BOOL QueryActCtxW(
  [in]            DWORD  dwFlags,
  [in]            HANDLE hActCtx,
  [in, optional]  PVOID  pvSubInstance,
  [in]            ULONG  ulInfoClass,
  [out]           PVOID  pvBuffer,
  [in, optional]  SIZE_T cbBuffer,
  [out, optional] SIZE_T *pcbWrittenOrRequired
);

Parameter

[in] dwFlags

Dieser Parameter sollte auf eines der folgenden Flagbits festgelegt werden.

Flag	Bedeutung
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX	QueryActCtxW fragt den Aktivierungskontext ab, der im Thread aktiv ist, anstatt den durch hActCtx angegebenen Kontext. Dies ist normalerweise der letzte Aktivierungskontext, der an ActivateActCtx übergeben wurde. Wenn ActivateActCtx nicht aufgerufen wurde, kann der aktive Aktivierungskontext der Aktivierungskontext sein, der von der ausführbaren Datei des aktuellen Prozesses verwendet wird. In anderen Fällen bestimmt das Betriebssystem den aktiven Aktivierungskontext. Wenn beispielsweise die Rückruffunktion für einen neuen Thread aufgerufen wird, kann der aktive Aktivierungskontext der Kontext sein, der beim Erstellen des Threads durch Aufrufen von CreateThread aktiv war.
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE	QueryActCtxW interpretiert hActCtx als HMODULE-Datentyp und fragt einen Aktivierungskontext ab, der einer DLL oder EXE zugeordnet ist. Wenn eine DLL oder EXE geladen wird, sucht das Ladeprogramm nach einem Manifest, das in einer Ressource gespeichert ist. Wenn der Ladevorgang eine RT_MANIFEST Ressource mit einem Ressourcenbezeichner findet, der auf ISOLATIONAWARE_MANIFEST_ RESOURCE_ID festgelegt ist, ordnet das Ladeprogramm den resultierenden Aktivierungskontext der DLL oder EXE zu. Dies ist der Aktivierungskontext, den QueryActCtxW abfragt, wenn das QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE-Flag festgelegt wurde.
QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS	QueryActCtxW interpretiert hActCtx als Adresse innerhalb einer DLL oder EXE und fragt einen Aktivierungskontext ab, der der DLL oder EXE zugeordnet wurde. Dies kann eine beliebige Adresse innerhalb der DLL oder EXE sein. Beispielsweise die Adresse einer beliebigen Funktion in einer DLL oder EXE oder die Adresse statischer Daten, z. B. einer konstanten Zeichenfolge. Wenn eine DLL oder EXE geladen wird, sucht das Ladeprogramm auf ein in einer Ressource gespeichertes Manifest auf die gleiche Weise wie QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.

[in] hActCtx

Behandeln Sie den aktivierungskontext, der abgefragt wird.

[in, optional] pvSubInstance

Index der Assembly oder Assembly- und Dateikombination im Aktivierungskontext. Die Bedeutung von pvSubInstance hängt von der Option ab, die durch den Wert des ulInfoClass-Parameters angegeben wird.

Dieser Parameter kann NULL sein.

ulInfoClass-Option	Bedeutung
AssemblyDetailedInformationInActivationContext	Zeiger auf ein DWORD , das den Index der Assembly im Aktivierungskontext angibt. Dies ist der Aktivierungskontext, den QueryActCtxW abfragt.
FileInformationInAssemblyOfAssemblyInActivationContext	Zeiger auf eine ACTIVATION_CONTEXT_QUERY_INDEX-Struktur . Wenn QueryActCtxW mit dieser Option aufgerufen wird und die Funktion erfolgreich ist, enthält der zurückgegebene Puffer Informationen für eine Datei in der Assembly. Diese Informationen befinden sich in Form der ASSEMBLY_FILE_DETAILED_INFORMATION-Struktur .

[in] ulInfoClass

Dieser Parameter darf nur die Werte enthalten, die in der folgenden Tabelle angezeigt werden.

Option	Bedeutung
ActivationContextBasicInformation 1	Nicht verfügbar.
ActivationContextDetailedInformation 2	Wenn QueryActCtxW mit dieser Option aufgerufen wird und die Funktion erfolgreich ist, enthält der zurückgegebene Puffer ausführliche Informationen zum Aktivierungskontext. Diese Informationen befinden sich in Form der ACTIVATION_CONTEXT_DETAILED_INFORMATION-Struktur .
AssemblyDetailedInformationInActivationContext 3	Wenn QueryActCtxW mit dieser Option aufgerufen wird und die Funktion erfolgreich ist, enthält der Puffer Informationen zu der Assembly, deren Index in pvSubInstance angegeben ist. Diese Informationen sind in Form der ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION-Struktur .
FileInformationInAssemblyOfAssemblyInActivationContext 4	Informationen zu einer Datei in einer der Assemblys im Aktivierungskontext. Der parameter pvSubInstance muss auf eine ACTIVATION_CONTEXT_QUERY_INDEX Struktur verweisen. Wenn QueryActCtxW mit dieser Option aufgerufen wird und die Funktion erfolgreich ist, enthält der zurückgegebene Puffer Informationen für eine Datei in der Assembly. Diese Informationen befinden sich in Form der ASSEMBLY_FILE_DETAILED_INFORMATION-Struktur .
RunlevelInformationInActivationContext 5	Wenn QueryActCtxW mit dieser Option aufgerufen wird und die Funktion erfolgreich ist, enthält der Puffer Informationen zur angeforderten Ausführungsebene des Aktivierungskontexts. Diese Informationen sind in Form der ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION-Struktur . Windows Server 2003 und Windows XP: Dieser Wert ist nicht verfügbar.
CompatibilityInformationInActivationContext 6	Wenn QueryActCtxW mit dieser Option aufgerufen wird und die Funktion erfolgreich ist, enthält der Puffer Informationen zum angeforderten Kompatibilitätskontext. Diese Informationen sind in Form der ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION-Struktur . Windows Server 2008 und früher sowie Windows Vista und früher: Dieser Wert ist nicht verfügbar. Diese Option ist ab Windows Server 2008 R2 und Windows 7 verfügbar.

[out] pvBuffer

Zeiger auf einen Puffer, der die zurückgegebenen Informationen enthält. Dieser Parameter ist optional. Wenn pvBufferNULL ist, muss cbBuffer null sein. Wenn die Größe des Puffers, auf den von pvBuffer verwiesen wird, zu klein ist, gibt QueryActCtxW ERROR_INSUFFICIENT_BUFFER zurück, und es werden keine Daten in den Puffer geschrieben. Die Methode, mit der Sie die erforderliche Größe des Puffers ermitteln können, finden Sie im Abschnitt Hinweise.

[in, optional] cbBuffer

Größe des Puffers in Bytes, auf die von pvBuffer verwiesen wird. Dieser Parameter ist optional.

[out, optional] pcbWrittenOrRequired

Anzahl der geschriebenen oder erforderlichen Bytes. Der Parameter pcbWrittenOrRequired kann nur NULL sein, wenn pvBufferNULL ist. Wenn pcbWrittenOrRequired nicht NULL ist, wird es mit der Anzahl von Bytes gefüllt, die zum Speichern des zurückgegebenen Puffers erforderlich sind.

Rückgabewert

Wenn die Funktion erfolgreich ist, gibt sie TRUE zurück. Andernfalls wird FALSE zurückgegeben.

Diese Funktion legt Fehler fest, die durch Aufrufen von GetLastError abgerufen werden können. Ein Beispiel finden Sie unter Abrufen des Last-Error Codes. Eine vollständige Liste der Fehlercodes finden Sie unter Systemfehlercodes.

Hinweise

Der Parameter cbBuffer gibt die Größe des Puffers in Bytes an, auf den von pvBuffer verwiesen wird. Wenn pvBufferNULL ist, muss cbBuffer 0 sein. Der Parameter pcbWrittenOrRequired kann nur NULL sein, wenn pvBufferNULL ist. Wenn pcbWrittenOrRequired bei der Rückgabe nicht NULL ist, wird es mit der Anzahl von Bytes gefüllt, die zum Speichern der zurückgegebenen Informationen erforderlich sind. Wenn die zurückgegebenen Informationsdaten größer als der bereitgestellte Puffer sind, gibt QueryActCtxW ERROR_INSUFFICIENT_BUFFER zurück, und es werden keine Daten in den Puffer geschrieben, auf den von pvBuffer verwiesen wird.

Das folgende Beispiel zeigt die Methode zum Aufrufen zuerst mit einem kleinen Puffer und dann zum Abrufen, wenn der Puffer zu klein ist.

SIZE_T cbRequired;
PVOID pvData = NULL;
SIZE_T cbAvailable = 0;

if (!QueryActCtxW(..., pvData, cbAvailable, &amp;cbRequired) &amp;&amp; (GetLastError()== ERROR_INSUFFICIENT_BUFFER))
{
    // Allocate enough space to store the returned buffer, fail if too small
    if (NULL == (pvData = HeapAlloc(GetProcessHeap(), 0, cbRequired)))
    {
        SetLastError(ERROR_NOT_ENOUGH_MEMORY);
        return FALSE;
    }
    cbAvailable = cbRequired;
    // Try again, this should succeed.
    if (QueryActCtxW(..., pvData, cbAvailable, &amp;cbRequired))
    {
        // Use the returned data in pvData
    }
    HeapFree(GetProcessHeap(), 0, pvData);
    pvData = NULL;
}

Anforderungen

Anforderung	Wert
Unterstützte Mindestversion (Client)	Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server)	Windows Server 2003 [nur Desktop-Apps]
Zielplattform	Windows
Kopfzeile	winbase.h (Windows.h einschließen)
Bibliothek	Kernel32.lib
DLL	Kernel32.dll

Freigeben über