Metodo IDXGIResource1::CreateSharedHandle (dxgi1_2.h)
Crea un handle in una risorsa condivisa. È quindi possibile usare l'handle restituito con più dispositivi Direct3D.
Sintassi
HRESULT CreateSharedHandle(
[in, optional] const SECURITY_ATTRIBUTES *pAttributes,
[in] DWORD dwAccess,
[in, optional] LPCWSTR lpName,
[out] HANDLE *pHandle
);
Parametri
[in, optional] pAttributes
Puntatore a una struttura SECURITY_ATTRIBUTES che contiene due membri dati separati ma correlati: un descrittore di sicurezza facoltativo e un valore booleano che determina se i processi figlio possono ereditare l'handle restituito.
Impostare questo parametro su NULL se si desidera che l'applicazione crei per non ereditare l'handle restituito da CreateSharedHandle e se si vuole che la risorsa associata all'handle restituito ottenga un descrittore di sicurezza predefinito.
Il membro lpSecurityDescriptor della struttura specifica un SECURITY_DESCRIPTOR per la risorsa. Impostare questo membro su NULL se si vuole che il runtime assegna un descrittore di sicurezza predefinito alla risorsa associata all'handle restituito. Gli ACL nel descrittore di sicurezza predefinito per la risorsa provengono dal token primario o di rappresentazione del creatore. Per altre informazioni, vedere Sicurezza oggetti di sincronizzazione e diritti di accesso.
[in] dwAccess
Diritti di accesso richiesti alla risorsa. Oltre ai diritti di accesso generici, DXGI definisce i valori seguenti:
- DXGI_SHARED_RESOURCE_READ ( 0x80000000L ): specifica l'accesso in lettura alla risorsa.
- DXGI_SHARED_RESOURCE_WRITE ( 1 ) : specifica l'accesso in scrittura alla risorsa.
[in, optional] lpName
Nome della risorsa da condividere. Il nome è limitato a MAX_PATH caratteri. Il confronto tra nomi è distinzione tra maiuscole e minuscole.
È necessario il nome della risorsa se si chiama il metodo ID3D11Device1::OpenSharedResourceByName per accedere alla risorsa condivisa in base al nome. Se invece si chiama il metodo ID3D11Device1::OpenSharedResource1 per accedere alla risorsa condivisa tramite handle, impostare questo parametro su NULL.
Se lpName corrisponde al nome di una risorsa esistente, CreateSharedHandle ha esito negativo con DXGI_ERROR_NAME_ALREADY_EXISTS. Ciò si verifica perché questi oggetti condividono lo stesso spazio dei nomi.
Il nome può avere un prefisso "Global" o "Local" per creare in modo esplicito l'oggetto nello spazio dei nomi globale o sessione. Il resto del nome può contenere qualsiasi carattere, ad eccezione del carattere barra rovesciata (\). Per altre informazioni, vedere Spazi dei nomi degli oggetti kernel. Il passaggio rapido degli utenti viene implementato usando le sessioni di Servizi terminal. I nomi degli oggetti kernel devono seguire le linee guida descritte per Servizi terminal in modo che le applicazioni possano supportare più utenti.
L'oggetto può essere creato in uno spazio dei nomi privato. Per altre informazioni, vedere Spazi dei nomi degli oggetti.
[out] pHandle
Puntatore a una variabile che riceve il valore NT HANDLE nella risorsa da condividere. È possibile usare questo handle nelle chiamate per accedere alla risorsa.
Valore restituito
Restituisce S_OK se ha esito positivo; in caso contrario, restituisce uno dei valori seguenti:
- DXGI_ERROR_INVALID_CALL se uno dei parametri non è valido.
- DXGI_ERROR_NAME_ALREADY_EXISTS se il nome specificato della risorsa da condividere è già associato a un'altra risorsa.
- E_ACCESSDENIED se l'oggetto viene creato in uno spazio dei nomi protetto.
- E_OUTOFMEMORY se la memoria sufficiente non è disponibile per creare l'handle.
- Eventualmente altri codici di errore descritti nell'argomento DXGI_ERROR .
Commenti
CreateSharedHandle restituisce solo l'handle NT quando è stata creata la risorsa come condivisa e specificata che usa handle NT, ovvero si impostano i flag di D3D11_RESOURCE_MISC_SHARED_NTHANDLE e D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX . Se è stata creata la risorsa come condivisa e specificata che usa handle NT, è necessario usare CreateSharedHandle per ottenere un handle per la condivisione. In questa situazione non è possibile usare il metodo IDXGIResource::GetSharedHandle perché avrà esito negativo.
È possibile passare l'handle restituito da CreateSharedHandle in una chiamata al metodo ID3D11Device1::OpenSharedResource1 per concedere a un dispositivo l'accesso a una risorsa condivisa creata in un dispositivo diverso.
Poiché l'handle restituito da CreateSharedHandle è un handle NT, è possibile usare l'handle con CloseHandle, DuplicateHandle e così via. È possibile chiamare CreateSharedHandle una sola volta per una risorsa condivisa; le chiamate successive hanno esito negativo. Se sono necessari più handle per la stessa risorsa condivisa, chiamare DuplicateHandle. Quando non è più necessario l'handle di risorse condiviso, chiamare CloseHandle per chiudere l'handle, per evitare perdite di memoria.
Se si passa un nome per la risorsa a lpName quando si chiama CreateSharedHandle per condividere la risorsa, è successivamente possibile passare questo nome in una chiamata al metodo ID3D11Device1::OpenSharedResourceByName per concedere a un altro dispositivo l'accesso alla risorsa condivisa. Se si usa una risorsa denominata, un utente malintenzionato può usare questa risorsa denominata prima di eseguire e impedire l'avvio dell'app. Per evitare questa situazione, creare una risorsa denominata casualmente e archiviare il nome in modo che possa essere ottenuto solo da un utente autorizzato. In alternativa, è possibile usare un file per questo scopo. Per limitare l'app a un'istanza per utente, creare un file bloccato nella directory del profilo dell'utente.
Se la risorsa è stata creata come condivisa e non è stata specificata che usa handle NT, non è possibile usare CreateSharedHandle per ottenere un handle per la condivisione perché CreateSharedHandle avrà esito negativo.
Esempio
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.
Requisiti
| Client minimo supportato | Windows 8 e Platform Update per Windows 7 [app desktop | App UWP] |
| Server minimo supportato | Windows Server 2012 e Aggiornamento della piattaforma per Windows Server 2008 R2 [app desktop | App UWP] |
| Piattaforma di destinazione | Windows |
| Intestazione | dxgi1_2.h |
| Libreria | Dxgi.lib |