QueryActCtxW 関数 (winbase.h)

  • [アーティクル]

QueryActCtxW 関数は、アクティブ化コンテキストに対してクエリを実行します。

構文

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

パラメーター

[in] dwFlags

このパラメーターは、次のいずれかのフラグ ビットに設定する必要があります。

フラグ 説明
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX
 QueryActCtxW は、 hActCtx で指定されたコンテキストではなく、スレッドでアクティブなアクティブ化コンテキストに対してクエリを実行します。 通常、これは ActivateActCtx に渡される最後のアクティブ化コンテキストです。 ActivateActCtx が呼び出されていない場合、アクティブなアクティブ化コンテキストは、現在のプロセスの実行可能ファイルによって使用されるアクティブ化コンテキストになります。 それ以外の場合は、オペレーティング システムによってアクティブなアクティブ化コンテキストが決定されます。 たとえば、新しいスレッドへのコールバック関数が呼び出されると、アクティブなアクティブ化コンテキストは 、CreateThread を呼び出してスレッドを作成したときにアクティブだったコンテキストである可能性があります。
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE
 QueryActCtxW は hActCtx を HMODULE データ型として解釈し、DLL または EXE に関連付けられているアクティブ化コンテキストに対してクエリを実行します。

DLL または EXE が読み込まれると、ローダーはリソースに格納されているマニフェストを確認します。 ローダーがISOLATIONAWARE_MANIFEST_ RESOURCE_IDに設定されたリソース識別子を持つRT_MANIFEST リソースを検出すると、ローダーは結果のアクティブ化コンテキストを DLL または EXE に関連付けます。 これは、QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE フラグが設定されている場合に QueryActCtxW が照会するアクティブ化コンテキストです。
QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS
 QueryActCtxW は、DLL または EXE 内のアドレスとして hActCtx を解釈し、DLL または EXE に関連付けられているアクティブ化コンテキストに対してクエリを実行します。 DLL または EXE 内の任意のアドレスを指定できます。 たとえば、DLL または EXE 内の任意の関数のアドレス、または定数文字列などの静的データのアドレスです。

DLL または EXE が読み込まれると、ローダーは、QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULEと同じ方法でリソースに格納されているマニフェストを確認します。

[in] hActCtx

クエリを実行するアクティブ化コンテキストを処理します。

[in, optional] pvSubInstance

アクティブ化コンテキスト内のアセンブリ、またはアセンブリとファイルの組み合わせのインデックス。 pvSubInstance の意味は、ulInfoClass パラメーターの値で指定されたオプションによって異なります。

このパラメーターは null でもかまいません。

ulInfoClass オプション 意味
AssemblyDetailedInformationInActivationContext
 アクティブ化コンテキスト内のアセンブリのインデックスを指定する DWORD へのポインター。 これは、 QueryActCtxW が 照会するアクティブ化コンテキストです。
FileInformationInAssemblyOfAssemblyInActivationContext
 ACTIVATION_CONTEXT_QUERY_INDEX構造体へのポインター。 このオプションを使用して QueryActCtxW が呼び出され、関数が成功した場合、返されるバッファーにはアセンブリ内のファイルの情報が含まれます。 この情報は、 ASSEMBLY_FILE_DETAILED_INFORMATION 構造の形式です。

[in] ulInfoClass

このパラメーターには、次の表に示す値のみを指定できます。

オプション 意味
ActivationContextBasicInformation
1
 使用できません。
ActivationContextDetailedInformation
2
 このオプションを使用 して QueryActCtxW が呼び出され、関数が成功した場合、返されるバッファーにはアクティブ化コンテキストに関する詳細情報が含まれます。 この情報は、 ACTIVATION_CONTEXT_DETAILED_INFORMATION 構造の形式です。
AssemblyDetailedInformationInActivationContext
3
 このオプションを使用して QueryActCtxW が呼び出され、関数が成功した場合、バッファーには pvSubInstance で指定されたインデックスを持つアセンブリに関する情報が含まれます。 この情報は、 ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION 構造の形式です。
FileInformationInAssemblyOfAssemblyInActivationContext
4
 アクティブ化コンテキストのアセンブリの 1 つのファイルに関する情報。 pvSubInstance パラメーターは、ACTIVATION_CONTEXT_QUERY_INDEX構造体を指している必要があります。 このオプションを使用して QueryActCtxW が呼び出され、関数が成功した場合、返されるバッファーにはアセンブリ内のファイルの情報が含まれます。 この情報は、 ASSEMBLY_FILE_DETAILED_INFORMATION 構造の形式です。
RunlevelInformationInActivationContext
5
 このオプションを使用して QueryActCtxW が呼び出され、関数が成功した場合、バッファーにはアクティブ化コンテキストの要求された実行レベルに関する情報が含まれます。 この情報は、 ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION 構造の形式です。

Windows Server 2003 および Windows XP: この値は使用できません。
CompatibilityInformationInActivationContext
6
 このオプションを使用 して QueryActCtxW が呼び出され、関数が成功した場合、バッファーには要求された互換性コンテキストに関する情報が含まれます。 この情報は、 ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION 構造の形式です。

Windows Server 2008 以前、および Windows Vista 以前: この値は使用できません。 このオプションは、Windows Server 2008 R2 および Windows 7 以降で使用できます。

[out] pvBuffer

返された情報を保持するバッファーへのポインター。 このパラメーターは省略可能です。 pvBuffer が null の場合、cbBuffer はゼロである必要があります。 pvBuffer が指すバッファーのサイズが小さすぎる場合、QueryActCtxW はERROR_INSUFFICIENT_BUFFERを返し、バッファーにデータは書き込まれなくなります。 バッファーの必要なサイズを決定するために使用できるメソッドについては、「解説」セクションを参照してください。

[in, optional] cbBuffer

pvBuffer が指すバッファーのサイズ (バイト単位)。 このパラメーターは省略可能です。

[out, optional] pcbWrittenOrRequired

書き込まれたバイト数または必須バイト数。 パラメーター pcbWrittenOrRequired は、pvBuffer が NULL の場合にのみ NULL にすることができます。 pcbWrittenOrRequired が NULL 以外の場合、返されるバッファーを格納するために必要なバイト数が入力されます。

戻り値

関数が成功すると、 TRUE が返されます。 それ以外の場合は、 FALSE を返します。

この関数は 、GetLastError を呼び出すことによって取得できるエラーを設定します。 例については、「 Last-Error コードの取得」を参照してください。 エラー コードの完全な一覧については、「 システム エラー コード」を参照してください。

注釈

パラメーター cbBuffer は、 pvBuffer が指すバッファーのサイズをバイト単位で指定します。 pvBuffer が NULL の場合、cbBuffer は 0 である必要があります。 パラメーター pcbWrittenOrRequired は、pvBuffer が NULL の場合にのみ NULL にすることができます。 pcbWrittenOrRequired が戻り値に NULL 以外の場合、返される情報を格納するために必要なバイト数が入力されます。 返される情報データが指定されたバッファーよりも大きい場合、 QueryActCtxW はERROR_INSUFFICIENT_BUFFERを返し、 pvBuffer が指すバッファーにデータは書き込まれなくなります。

次の例は、小さなバッファーで最初に を呼び出し、バッファーが小さすぎる場合に呼び出すメソッドを示しています。

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

if (!QueryActCtxW(..., pvData, cbAvailable, &cbRequired) && (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, &cbRequired))
    {
        // Use the returned data in pvData
    }
    HeapFree(GetProcessHeap(), 0, pvData);
    pvData = NULL;
}

要件

要件 値
サポートされている最小のクライアント Windows XP (デスクトップ アプリのみ)
サポートされている最小のサーバー Windows Server 2003 (デスクトップ アプリのみ)
対象プラットフォーム Windows
ヘッダー winbase.h (Windows.h を含む)
Library Kernel32.lib
[DLL] Kernel32.dll