Metode IDXGIResource1::CreateSharedHandle (dxgi1_2.h)

  • Artikel

Membuat handel ke sumber daya bersama. Anda kemudian dapat menggunakan handel yang dikembalikan dengan beberapa perangkat Direct3D.

Sintaks

HRESULT CreateSharedHandle(
  [in, optional] const SECURITY_ATTRIBUTES *pAttributes,
  [in]           DWORD                     dwAccess,
  [in, optional] LPCWSTR                   lpName,
  [out]          HANDLE                    *pHandle
);

Parameter

[in, optional] pAttributes

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 NULL 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 deskriptor keamanan default.

Anggota lpSecurityDescriptor dari struktur menentukan SECURITY_DESCRIPTOR untuk sumber daya. Atur anggota ini ke NULL jika Anda ingin runtime menetapkan deskriptor keamanan default ke sumber daya yang terkait dengan handel yang dikembalikan. ACL dalam deskriptor keamanan default untuk sumber daya berasal dari token utama atau peniruan dari pembuat. Untuk informasi selengkapnya, lihat Keamanan Objek Sinkronisasi dan Hak Akses.

[in] dwAccess

Hak akses yang diminta ke sumber daya. Selain hak akses generik, DXGI mendefinisikan nilai berikut:

  • 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.

[in, optional] lpName

Nama sumber daya yang akan dibagikan. Nama ini terbatas pada karakter MAX_PATH. Perbandingan nama peka huruf besar/kecil.

Anda akan memerlukan nama sumber daya jika Anda memanggil metode ID3D11Device1::OpenSharedResourceByName untuk mengakses sumber daya bersama berdasarkan nama. Jika Anda memanggil metode ID3D11Device1::OpenSharedResource1 untuk mengakses sumber daya bersama dengan menangani, atur parameter ini ke NULL.

Jika lpName cocok dengan nama sumber daya yang ada, 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. Pengalihan pengguna cepat diimplementasikan menggunakan sesi Layanan Terminal. Nama objek kernel harus mengikuti pedoman yang diuraikan untuk Layanan Terminal sehingga aplikasi dapat mendukung beberapa pengguna.

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

[out] pHandle

Penunjuk ke variabel yang menerima nilai NT HANDLE ke sumber daya untuk dibagikan. Anda dapat menggunakan handel ini dalam panggilan untuk mengakses sumber daya.

Mengembalikan nilai

Mengembalikan S_OK jika berhasil; jika tidak, mengembalikan salah satu nilai berikut:

  • DXGI_ERROR_INVALID_CALL jika salah satu parameter tidak valid.
  • DXGI_ERROR_NAME_ALREADY_EXISTS jika nama sumber daya yang disediakan untuk dibagikan sudah dikaitkan dengan sumber daya lain.
  • E_ACCESSDENIED jika objek sedang dibuat di namespace yang dilindungi.
  • E_OUTOFMEMORY jika memori yang cukup tidak tersedia untuk membuat handel.
  • Mungkin kode kesalahan lain yang dijelaskan dalam topik DXGI_ERROR .
Pembaruan Platform untuk Windows 7: Pada Windows 7 atau Windows Server 2008 R2 dengan Pembaruan Platform untuk Windows 7 diinstal, CreateSharedHandle gagal dengan E_NOTIMPL. Untuk informasi selengkapnya tentang Pembaruan Platform untuk Windows 7, lihat Pembaruan Platform untuk Windows 7.

Keterangan

CreateSharedHandle hanya mengembalikan handel NT saat Anda membuat sumber daya sebagai bersama dan menentukan bahwa ia menggunakan handel NT (artinya, Anda mengatur bendera D3D11_RESOURCE_MISC_SHARED_NTHANDLE dan D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX ). Jika Anda membuat sumber daya sebagai bersama dan menentukan bahwa sumber daya tersebut menggunakan handel NT, Anda harus menggunakan CreateSharedHandle untuk mendapatkan handel untuk berbagi. Dalam situasi ini, Anda tidak dapat menggunakan metode IDXGIResource::GetSharedHandle karena akan gagal.

Anda dapat meneruskan handel yang dikembalikan CreateSharedHandle dalam panggilan ke metode ID3D11Device1::OpenSharedResource1 untuk memberikan akses perangkat ke sumber daya bersama yang Anda buat di perangkat lain.

Karena handel yang dikembalikan CreateSharedHandle adalah handel NT, Anda dapat menggunakan handel dengan CloseHandle, DuplicateHandle, dan sebagainya. Anda dapat memanggil CreateSharedHandle hanya sekali untuk sumber daya bersama; panggilan kemudian gagal. Jika Anda memerlukan lebih banyak handel ke sumber daya bersama yang sama, panggil DuplicateHandle. Ketika Anda tidak lagi memerlukan handel sumber daya bersama, panggil CloseHandle untuk menutup handel, untuk menghindari kebocoran memori.

Jika Anda meneruskan nama sumber daya ke lpName saat memanggil CreateSharedHandle untuk berbagi sumber daya, Anda kemudian dapat meneruskan nama ini dalam panggilan ke metode ID3D11Device1::OpenSharedResourceByName untuk memberikan akses perangkat lain ke sumber daya bersama. Jika Anda menggunakan sumber daya bernama, pengguna berbahaya dapat menggunakan sumber daya bernama ini sebelum Anda melakukannya dan mencegah aplikasi Anda dimulai. Untuk mencegah situasi ini, buat sumber daya bernama acak dan simpan nama sehingga hanya dapat diperoleh oleh pengguna yang berwenang. Atau, Anda dapat menggunakan file untuk tujuan ini. Untuk membatasi aplikasi Anda ke satu instans per pengguna, buat file terkunci di direktori profil pengguna.

Jika Anda membuat sumber daya sebagai bersama dan tidak menentukan bahwa sumber daya tersebut menggunakan handel NT, Anda tidak dapat menggunakan CreateSharedHandle untuk mendapatkan handel untuk berbagi karena CreateSharedHandle akan gagal.

Contoh

ID3D11Texture2D* pTexture2D;
ID3D11Device* pDevice;

pDevice->CreateTexture2D(…, &pTexture2D); // Create the texture as shared with NT HANDLEs.

HANDLE handle;
IDXGIResource1* pResource;
pTexture2D->QueryInterface(__uuidof(IDXGIResource1), (void**) &pResource);
pResource->CreateSharedHandle(NULL, 
         DXGI_SHARED_RESOURCE_READ | DXGI_SHARED_RESOURCE_WRITE, 
         NULL,
         &handle);

// Pass the handle to another process to share the resource.

Persyaratan

   
Klien minimum yang didukung Pembaruan Windows 8 dan Platform untuk Windows 7 [aplikasi desktop | Aplikasi UWP]
Server minimum yang didukung Windows Server 2012 dan Pembaruan Platform untuk Windows Server 2008 R2 [aplikasi desktop | Aplikasi UWP]
Target Platform Windows
Header dxgi1_2.h
Pustaka Dxgi.lib

Lihat juga

IDXGIResource1