Bagikan melalui

Fungsi QueryActCtxW (winbase.h)

  • Artikel

Fungsi QueryActCtxW meminta konteks aktivasi.

Sintaks

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

Parameter ini harus diatur ke salah satu bit bendera berikut.

Bendera Makna
QUERY_ACTCTX_FLAG_USE_ACTIVE_ACTCTX
 QueryActCtxW mengkueri konteks aktivasi yang aktif pada utas alih-alih konteks yang ditentukan oleh hActCtx. Ini biasanya konteks aktivasi terakhir yang diteruskan ke ActivateActCtx. Jika ActivateActCtx belum dipanggil, konteks aktivasi aktif dapat menjadi konteks aktivasi yang digunakan oleh yang dapat dieksekusi dari proses saat ini. Dalam kasus lain, sistem operasi menentukan konteks aktivasi aktif. Misalnya, ketika fungsi panggilan balik ke utas baru dipanggil, konteks aktivasi aktif mungkin merupakan konteks yang aktif saat Anda membuat utas dengan memanggil CreateThread.
QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE
 QueryActCtxW menginterpretasikan hActCtx sebagai jenis data HMODULE dan mengkueri konteks aktivasi yang terkait dengan DLL atau EXE.

Saat DLL atau EXE dimuat, loader memeriksa manifes yang disimpan dalam sumber daya. Jika loader menemukan sumber daya RT_MANIFEST dengan pengidentifikasi sumber daya yang diatur ke ISOLATIONAWARE_MANIFEST_ RESOURCE_ID, loader mengaitkan konteks aktivasi yang dihasilkan dengan DLL atau EXE. Ini adalah konteks aktivasi yang dikueri QueryActCtxW saat bendera QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE telah ditetapkan.
QUERY_ACTCTX_FLAG_ACTCTX_IS_ADDRESS
 QueryActCtxW menafsirkan hActCtx sebagai alamat dalam DLL atau EXE dan mengkueri konteks aktivasi yang telah dikaitkan dengan DLL atau EXE. Ini bisa menjadi alamat apa pun dalam DLL atau EXE. Misalnya, alamat fungsi apa pun dalam DLL atau EXE atau alamat data statis apa pun, seperti string konstanta.

Saat DLL atau EXE dimuat, loader memeriksa manifes yang disimpan dalam sumber daya dengan cara yang sama seperti QUERY_ACTCTX_FLAG_ACTCTX_IS_HMODULE.

[in] hActCtx

Tangani konteks aktivasi yang sedang dikueri.

[in, optional] pvSubInstance

Indeks perakitan, atau kombinasi perakitan dan file, dalam konteks aktivasi. Arti pvSubInstance tergantung pada opsi yang ditentukan oleh nilai parameter ulInfoClass .

Parameter ini mungkin null.

Opsi ulInfoClass Makna
AssemblyDetailedInformationInActivationContext
 Penunjuk ke DWORD yang menentukan indeks perakitan dalam konteks aktivasi. Ini adalah konteks aktivasi yang dikueri QueryActCtxW .
FileInformationInAssemblyOfAssemblyInActivationContext
 Arahkan ke struktur ACTIVATION_CONTEXT_QUERY_INDEX . Jika QueryActCtxW dipanggil dengan opsi ini dan fungsi berhasil, buffer yang dikembalikan berisi informasi untuk file di rakitan. Informasi ini dalam bentuk struktur ASSEMBLY_FILE_DETAILED_INFORMATION .

[in] ulInfoClass

Parameter ini hanya dapat memiliki nilai yang diperlihatkan dalam tabel berikut.

Opsi Makna
ActivationContextBasicInformation
1
 Tidak tersedia.
ActivationContextDetailedInformation
2
 Jika QueryActCtxW dipanggil dengan opsi ini dan fungsi berhasil, buffer yang dikembalikan berisi informasi terperinci tentang konteks aktivasi. Informasi ini dalam bentuk struktur ACTIVATION_CONTEXT_DETAILED_INFORMATION .
AssemblyDetailedInformationInActivationContext
3
 Jika QueryActCtxW dipanggil dengan opsi ini dan fungsi berhasil, buffer berisi informasi tentang rakitan yang memiliki indeks yang ditentukan dalam pvSubInstance. Informasi ini dalam bentuk struktur ACTIVATION_CONTEXT_ASSEMBLY_DETAILED_INFORMATION .
FileInformationInAssemblyOfAssemblyInActivationContext
4
 Informasi tentang file di salah satu rakitan dalam Konteks Aktivasi. Parameter pvSubInstance harus menunjuk ke struktur ACTIVATION_CONTEXT_QUERY_INDEX . Jika QueryActCtxW dipanggil dengan opsi ini dan fungsi berhasil, buffer yang dikembalikan berisi informasi untuk file di rakitan. Informasi ini dalam bentuk struktur ASSEMBLY_FILE_DETAILED_INFORMATION .
RunlevelInformationInActivationContext
5
 Jika QueryActCtxW dipanggil dengan opsi ini dan fungsi berhasil, buffer berisi informasi tentang tingkat eksekusi konteks aktivasi yang diminta. Informasi ini dalam bentuk struktur ACTIVATION_CONTEXT_RUN_LEVEL_INFORMATION .

Windows Server 2003 dan Windows XP: Nilai ini tidak tersedia.
CompatibilityInformationInActivationContext
6
 Jika QueryActCtxW dipanggil dengan opsi ini dan fungsi berhasil, buffer berisi informasi tentang konteks kompatibilitas yang diminta. Informasi ini dalam bentuk struktur ACTIVATION_CONTEXT_COMPATIBILITY_INFORMATION .

Windows Server 2008 dan yang lebih lama, serta Windows Vista dan yang lebih lama: Nilai ini tidak tersedia. Opsi ini tersedia dimulai dengan Windows Server 2008 R2 dan Windows 7.

[out] pvBuffer

Penunjuk ke buffer yang menyimpan informasi yang dikembalikan. Parameter ini bersifat opsional. Jika pvBuffernull, maka cbBuffer harus nol. Jika ukuran buffer yang diarahkan oleh pvBuffer terlalu kecil, QueryActCtxW mengembalikan ERROR_INSUFFICIENT_BUFFER dan tidak ada data yang ditulis ke dalam buffer. Lihat bagian Keterangan untuk metode yang dapat Anda gunakan untuk menentukan ukuran buffer yang diperlukan.

[in, optional] cbBuffer

Ukuran buffer dalam byte yang diacu oleh pvBuffer. Parameter ini bersifat opsional.

[out, optional] pcbWrittenOrRequired

Jumlah byte yang ditulis atau diperlukan. Parameter pcbWrittenOrRequired hanya dapat null ketika pvBuffer adalah NULL. Jika pcbWrittenOrRequired bukan NULL, itu diisi dengan jumlah byte yang diperlukan untuk menyimpan buffer yang dikembalikan.

Mengembalikan nilai

Jika fungsi berhasil, fungsi akan mengembalikan TRUE. Jika tidak, ia mengembalikan FALSE.

Fungsi ini menetapkan kesalahan yang dapat diambil dengan memanggil GetLastError. Misalnya, lihat Mengambil Kode Last-Error. Untuk daftar lengkap kode kesalahan, lihat Kode Kesalahan Sistem.

Keterangan

Parameter cbBuffer menentukan ukuran dalam byte buffer yang diacu oleh pvBuffer. Jika pvBuffer adalah NULL, maka cbBuffer harus 0. Parameter pcbWrittenOrRequired hanya dapat berupa NULL jika pvBuffer adalah NULL. Jika pcbWrittenOrRequirednon-NULL saat dikembalikan, itu diisi dengan jumlah byte yang diperlukan untuk menyimpan informasi yang dikembalikan. Ketika data informasi yang dikembalikan lebih besar dari buffer yang disediakan, QueryActCtxW mengembalikan ERROR_INSUFFICIENT_BUFFER dan tidak ada data yang ditulis ke buffer yang diarahkan oleh pvBuffer.

Contoh berikut menunjukkan metode pemanggilan terlebih dahulu dengan buffer kecil dan kemudian menarik kembali jika buffer terlalu kecil.

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

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2003 [hanya aplikasi desktop]
Target Platform Windows
Header winbase.h (termasuk Windows.h)
Pustaka Kernel32.lib
DLL Kernel32.dll