Funzione QueryActCtxW (winbase.h)

Articolo
08/27/2023

La funzione QueryActCtxW esegue una query sul contesto di attivazione.

Sintassi

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

Parametri

[in] dwFlags

Questo parametro deve essere impostato su uno dei bit di flag seguenti.

Contrassegno	Significato
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX	QueryActCtxW esegue una query sul contesto di attivazione attivo nel thread anziché sul contesto specificato da hActCtx. Questo è in genere l'ultimo contesto di attivazione passato a ActivateActCtx. Se ActivateActCtx non è stato chiamato, il contesto di attivazione attiva può essere il contesto di attivazione usato dall'eseguibile del processo corrente. In altri casi, il sistema operativo determina il contesto di attivazione attiva. Ad esempio, quando viene chiamata la funzione di callback a un nuovo thread, il contesto di attivazione attiva può essere il contesto attivo quando è stato creato il thread chiamando CreateThread.
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE	QueryActCtxW interpreta hActCtx come tipo di dati HMODULE e esegue query su un contesto di attivazione associato a una DLL o EXE. Quando viene caricata una DLL o un file EXE, il caricatore verifica la presenza di un manifesto archiviato in una risorsa. Se il caricatore trova una risorsa RT_MANIFEST con un identificatore di risorsa impostato su ISOLATIONAWARE_MANIFEST_ RESOURCE_ID, il caricatore associa il contesto di attivazione risultante alla DLL o all'EXE. Si tratta del contesto di attivazione che query QueryActCtxW quando è stato impostato il flag di QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.
QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS	QueryActCtxW interpreta hActCtx come indirizzo all'interno di una DLL o EXE e esegue query su un contesto di attivazione associato alla DLL o all'EXE. Questo può essere qualsiasi indirizzo all'interno della DLL o dell'EXE. Ad esempio, l'indirizzo di qualsiasi funzione all'interno di una DLL o exe o dell'indirizzo di qualsiasi dato statico, ad esempio una stringa costante. Quando viene caricata una DLL o un file EXE, il caricatore verifica la presenza di un manifesto archiviato in una risorsa nello stesso modo di QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.

[in] hActCtx

Gestire il contesto di attivazione sottoposto a query.

[in, optional] pvSubInstance

Indice dell'assembly o dell'assembly e della combinazione di file nel contesto di attivazione. Il significato del valore pvSubInstance dipende dall'opzione specificata dal valore del parametro ulInfoClass .

Questo parametro può essere null.

Opzione ulInfoClass	Significato
AssemblyDetailedInformationInActivationContext	Puntatore a un DWORD che specifica l'indice dell'assembly all'interno del contesto di attivazione. Si tratta del contesto di attivazione che QueryActCtxW esegue query.
FileInformationInAssemblyOfAssemblyInActivationContext	Puntatore a una struttura ACTIVATION_CONTEXT_QUERY_INDEX . Se QueryActCtxW viene chiamato con questa opzione e la funzione ha esito positivo, il buffer restituito contiene informazioni per un file nell'assembly. Queste informazioni sono sotto forma di struttura ASSEMBLY_FILE_DETAILED_INFORMATION .

[in] ulInfoClass

Questo parametro può avere solo i valori visualizzati nella tabella seguente.

Opzione	Significato
ActivationContextBasicInformation 1	Non disponibile.
ActivationContextDetailedInformation 2	Se QueryActCtxW viene chiamato con questa opzione e la funzione ha esito positivo, il buffer restituito contiene informazioni dettagliate sul contesto di attivazione. Queste informazioni sono sotto forma di struttura ACTIVATION_CONTEXT_DETAILED_INFORMATION .
AssemblyDetailedInformationInActivationContext 3	Se QueryActCtxW viene chiamato con questa opzione e la funzione ha esito positivo, il buffer contiene informazioni sull'assembly con l'indice specificato in pvSubInstance. Queste informazioni sono sotto forma di struttura ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION .
FileInformationInAssemblyOfAssemblyInActivationContext 4	Informazioni su un file in uno degli assembly nel contesto di attivazione. Il parametro pvSubInstance deve puntare a una struttura ACTIVATION_CONTEXT_QUERY_INDEX . Se QueryActCtxW viene chiamato con questa opzione e la funzione ha esito positivo, il buffer restituito contiene informazioni per un file nell'assembly. Queste informazioni sono sotto forma di struttura ASSEMBLY_FILE_DETAILED_INFORMATION .
RunlevelInformationInActivationContext 5	Se QueryActCtxW viene chiamato con questa opzione e la funzione ha esito positivo, il buffer contiene informazioni sul livello di esecuzione richiesto del contesto di attivazione. Queste informazioni sono sotto forma di struttura ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION . Windows Server 2003 e Windows XP: Questo valore non è disponibile.
CompatibilityInformationInActivationContext 6	Se QueryActCtxW viene chiamato con questa opzione e la funzione ha esito positivo, il buffer contiene informazioni sul contesto di compatibilità richiesto. Queste informazioni sono sotto forma di struttura ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION . Windows Server 2008 e versioni precedenti e Windows Vista e versioni precedenti: Questo valore non è disponibile. Questa opzione è disponibile a partire da Windows Server 2008 R2 e Windows 7.

[out] pvBuffer

Puntatore a un buffer che contiene le informazioni restituite. Questo parametro è facoltativo e, Se pvBuffer è Null, cbBuffer deve essere zero. Se le dimensioni del buffer puntate da pvBuffer sono troppo piccole, QueryActCtxW restituisce ERROR_INSUFFICIENT_BUFFER e non vengono scritti dati nel buffer. Vedere la sezione Osservazioni per il metodo che è possibile usare per determinare le dimensioni necessarie del buffer.

[in, optional] cbBuffer

Dimensioni del buffer in byte puntate da pvBuffer. Questo parametro è facoltativo e,

[out, optional] pcbWrittenOrRequired

Numero di byte scritti o obbligatori. Il parametro pcbWrittenOrRequired può essere NULL solo quando pvBuffer è NULL. Se pcbWrittenOrRequired non è NULL, viene riempito con il numero di byte necessari per archiviare il buffer restituito.

Valore restituito

Se la funzione ha esito positivo, restituisce TRUE. In caso contrario, restituisce FALSE.

Questa funzione imposta errori che possono essere recuperati chiamando GetLastError. Per un esempio, vedere Recupero del codice Last-Error. Per un elenco completo dei codici di errore, vedere Codici di errore di sistema.

Commenti

Il parametro cbBuffer specifica le dimensioni in byte del buffer a cui punta pvBuffer. Se pvBuffer è NULL, cbBuffer deve essere 0. Il parametro pcbWrittenOrRequired può essere NULL solo se pvBuffer è NULL. Se pcbWrittenOrRequired è non NULL in caso di restituzione, viene riempito con il numero di byte necessari per archiviare le informazioni restituite. Quando i dati delle informazioni restituiti sono maggiori del buffer fornito, QueryActCtxW restituisce ERROR_INSUFFICIENT_BUFFER e non vengono scritti dati nel buffer a cui punta pvBuffer.

Nell'esempio seguente viene illustrato il metodo di chiamata prima con un buffer di piccole dimensioni e quindi viene richiamato se il buffer è troppo piccolo.

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

Requisiti

Requisito	Valore
Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows Server 2003 [solo app desktop]
Piattaforma di destinazione	Windows
Intestazione	winbase.h (include Windows.h)
Libreria	Kernel32.lib
DLL	Kernel32.dll

Share via