Metode IDisplayDeviceInterop::CreateSharedHandle (windows.devices.display.core.interop.h)

Artikel
03/09/2024

Untuk objek DisplaySurface atau DisplayFence , membuat handel bersama yang dapat digunakan untuk interop dengan Direct3D atau API grafis lainnya.

Sintaks

HRESULT CreateSharedHandle(
  IInspectable              *pObject,
  const SECURITY_ATTRIBUTES *pSecurityAttributes,
  DWORD                     Access,
  HSTRING                   Name,
  HANDLE                    *pHandle
);

Parameter

pObject

Penunjuk ke antarmuka IUnknown dari DisplaySurface atau objek DisplayFence .

pSecurityAttributes

Penunjuk ke struktur SECURITY_ATTRIBUTES yang berisi dua anggota data terpisah tetapi terkait: deskriptor keamanan opsional, dan nilai Boolean yang menentukan apakah proses anak dapat mewarisi handel yang dikembalikan.

Atur parameter ini ke nullptr jika Anda ingin proses anak yang mungkin dibuat aplikasi untuk tidak mewarisi handel yang dikembalikan oleh CreateSharedHandle, dan jika Anda ingin sumber daya yang terkait dengan handel yang dikembalikan untuk mendapatkan pendeskripsi keamanan default.

Anggota lpSecurityDescriptor dari struktur menentukan SECURITY_DESCRIPTOR untuk sumber daya. Atur anggota ini ke nullptr jika Anda ingin runtime menetapkan deskriptor keamanan default ke sumber daya yang terkait dengan handel yang dikembalikan. Daftar kontrol akses (ACL) di deskriptor keamanan default untuk sumber daya berasal dari token utama atau peniruan dari pembuat. Untuk informasi selengkapnya, lihat Keamanan objek sinkronisasi dan hak akses.

Access

Hak akses yang diminta ke sumber daya. Selain hak akses Generik, permukaan dapat menggunakan nilai-nilai ini.

DXGI_SHARED_RESOURCE_READ (0x80000000L). Menentukan akses baca ke sumber daya.
DXGI_SHARED_RESOURCE_WRITE (1). Menentukan akses tulis ke sumber daya.

Anda dapat menggabungkan nilai-nilai ini dengan menggunakan operasi OR bitwise.

Jika pObject adalah pagar, maka Anda harus menggunakan GENERIC_ALL.

Name

Jenis: LPCWSTR

String Unicode yang dihentikan null yang berisi nama untuk dikaitkan dengan tumpukan bersama. Nama ini terbatas pada MAX_PATH karakter. Perbandingan nama peka huruf besar/kecil.

Jika Nama cocok dengan nama sumber daya yang ada, maka CreateSharedHandle gagal dengan DXGI_ERROR_NAME_ALREADY_EXISTS. Ini terjadi karena objek ini memiliki namespace yang sama.

Nama dapat memiliki awalan "Global" atau "Lokal" untuk secara eksplisit membuat objek di namespace layanan global atau sesi. Sisa nama dapat berisi karakter apa pun kecuali karakter garis miring terbelakang (\). Untuk informasi selengkapnya, lihat Namespace objek Kernel. Peralihan pengguna yang cepat diimplementasikan menggunakan sesi Layanan Terminal. Nama objek kernel harus mengikuti panduan yang diuraikan untuk Layanan Terminal sehingga aplikasi dapat mendukung beberapa pengguna.

Objek dapat dibuat di namespace privat. Untuk informasi selengkapnya, lihat Namespace objek.

pHandle

Penunjuk ke HANDLE yang menerima handel bersama baru tersebut.

Mengembalikan nilai

Jenis: HRESULT

Metode ini mengembalikan S_OK jika berhasil, jika tidak, kode kegagalan yang menunjukkan mengapa gagal. Jika berhasil, maka pHandle akan selalu menunjuk ke handel yang baru dibuat.

Keterangan

Handel yang dikembalikan oleh CreateSharedHandle dapat digunakan dalam fungsi apa pun yang memerlukan "handel NT" ke permukaan atau pagar GPU (tergantung pada objek apa yang diteruskan), asalkan pemanggil telah diberikan akses. Berikut adalah beberapa contohnya.

Bagikan permukaan dan pagar dengan Direct3D 12 menggunakan ID3D12Device::OpenSharedHandle.
Bagikan permukaan dengan Direct3D 11 menggunakan ID3D11Device1::OpenSharedResource.
Bagikan pagar dengan Direct3D 11 menggunakan ID3D11Device5::OpenSharedFence.

Beberapa proses dapat memiliki handel dari objek yang sama, memungkinkan penggunaan objek untuk sinkronisasi atau berbagi antarproses. Mekanisme berbagi objek berikut tersedia.

Proses anak yang dibuat oleh fungsi CreateProcess dapat mewarisi handel ke objek permukaan atau pagar jika parameter pSecurityAttributes dari CreateSharedHandle memungkinkan pewarisan.
Proses dapat menentukan handel objek dalam panggilan ke fungsi DuplikatHandle untuk membuat handel duplikat yang dapat digunakan oleh proses lain.
Proses dapat menentukan nama objek dalam panggilan ke fungsi OpenSharedHandle atau ID3D12Device::OpenSharedHandleByName .

Gunakan fungsi CloseHandle untuk menutup handel. Sistem menutup handel secara otomatis ketika proses berakhir. Objek dihancurkan ketika handel terakhirnya telah ditutup dan referensi antarmuka terakhirnya telah dirilis.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Windows 10 Build 20348
Server minimum yang didukung	Windows 10 Build 20348
Target Platform	Windows
Header	windows.devices.display.core.interop.h
Pustaka	d3d12.lib
DLL	d3d12.dll

Bagikan melalui