IDXGIResource1::CreateSharedHandle メソッド (dxgi1_2.h)

  • [アーティクル]

共有リソースへのハンドルを作成します。 その後、返されたハンドルを複数の Direct3D デバイスで使用できます。

構文

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

パラメーター

[in, optional] pAttributes

2 つの独立した関連データ メンバーを含む SECURITY_ATTRIBUTES 構造体へのポインター。省略可能なセキュリティ記述子と、子プロセスが返されたハンドルを継承できるかどうかを決定するブール値。

アプリケーションが作成する可能性がある子プロセスが CreateSharedHandle によって返されるハンドルを継承しないようにする場合、および返されるハンドルに関連付けられているリソースで既定のセキュリティ記述子を取得する場合は、このパラメーターを NULL に設定します。

構造体の lpSecurityDescriptor メンバーは、リソースの SECURITY_DESCRIPTOR を指定します。 返されるハンドルに関連付けられているリソースに既定のセキュリティ記述子をランタイムが割り当てる場合は、このメンバーを NULL に設定します。 リソースの既定のセキュリティ記述子の ACL は、作成者のプライマリ トークンまたは偽装トークンから取得されます。 詳細については、「 同期オブジェクトのセキュリティとアクセス権」を参照してください。

[in] dwAccess

リソースに対して要求されたアクセス権。 DXGI では、 汎用アクセス権に加えて、次の値を定義します。

  • DXGI_SHARED_RESOURCE_READ ( 0x80000000L ) - リソースへの読み取りアクセスを指定します。
  • DXGI_SHARED_RESOURCE_WRITE ( 1 ) - リソースへの書き込みアクセスを指定します。
これらの値は、ビットごとの OR 演算を使用して結合できます。

[in, optional] lpName

共有するリソースの名前。 名前はMAX_PATH文字に制限されています。 名前の比較では大文字と小文字が区別されます。

ID3D11Device1::OpenSharedResourceByName メソッドを呼び出して共有リソースに名前でアクセスする場合は、リソース名が必要です。 代わりに ID3D11Device1::OpenSharedResource1 メソッドを呼び出して、ハンドルによって共有リソースにアクセスする場合は、このパラメーターを NULL に設定 します。

lpName が既存のリソースの名前と一致する場合、CreateSharedHandle はDXGI_ERROR_NAME_ALREADY_EXISTSで失敗します。 これは、これらのオブジェクトが同じ名前空間を共有しているために発生します。

名前には、グローバル名前空間またはセッション名前空間にオブジェクトを明示的に作成するための "Global" または "Local" プレフィックスを付けることができます。 名前の残りの部分には、円記号 (\) を除く任意の文字を含めることができます。 詳細については、「 カーネル オブジェクトの名前空間」を参照してください。 ターミナル サービス セッションを使用して、高速ユーザー切り替えが実装されます。 カーネル オブジェクト名は、アプリケーションが複数のユーザーをサポートできるように、ターミナル サービスに関するガイドラインに従う必要があります。

オブジェクトは、プライベート名前空間に作成できます。 詳細については、「 オブジェクトの名前空間」を参照してください。

[out] pHandle

共有するリソースに NT HANDLE 値を受け取る変数へのポインター。 このハンドルを呼び出しで使用して、リソースにアクセスできます。

戻り値

成功した場合はS_OKを返します。それ以外の場合は、次のいずれかの値を返します。

  • パラメーター の 1 つが無効な場合にDXGI_ERROR_INVALID_CALLします。
  • 共有 するリソースの指定された名前が既に別のリソースに関連付けられている場合は、DXGI_ERROR_NAME_ALREADY_EXISTSします。
  • オブジェクトが保護された名前空間に作成されているかどうかをE_ACCESSDENIEDします。
  • ハンドルを作成するのに十分なメモリが使用できない場合は、E_OUTOFMEMORYします。
  • DXGI_ERRORトピックで説明されているその他のエラー コード。
Windows 7 のプラットフォーム更新プログラム: Windows 7 用プラットフォーム更新プログラム がインストールされている Windows 7 または Windows Server 2008 R2 では、 CreateSharedHandle はE_NOTIMPLで失敗します。 Windows 7 のプラットフォーム更新プログラムの詳細については、「Windows 7 用プラットフォーム更新プログラム」を参照してください。

解説

CreateSharedHandle は、リソースを共有として作成し、NT ハンドルを使用するように指定した場合にのみ NT ハンドルを返します (つまり、 D3D11_RESOURCE_MISC_SHARED_NTHANDLE フラグと D3D11_RESOURCE_MISC_SHARED_KEYEDMUTEX フラグを設定します)。 リソースを共有として作成し、NT ハンドルを使用するように指定した場合は、 CreateSharedHandle を 使用して共有用のハンドルを取得する必要があります。 この状況では、 IDXGIResource::GetSharedHandle メソッドは失敗するため使用できません。

CreateSharedHandle が ID3D11Device1::OpenSharedResource1 メソッドの呼び出しで返すハンドルを渡して、別のデバイスで作成した共有リソースへのデバイス アクセス権をデバイスに付与できます。

CreateSharedHandle が返すハンドルは NT ハンドルであるため、CloseHandle、DuplicateHandle などのハンドルを使用できます。 CreateSharedHandle は、共有リソースに対して 1 回だけ呼び出すことができます。それ以降の呼び出しは失敗します。 同じ共有リソースに対してさらにハンドルが必要な場合は、 DuplicateHandle を呼び出します。 共有リソース ハンドルが不要になった場合は、メモリ リークを回避するために CloseHandle を呼び出してハンドルを閉じます。

リソースを共有するために CreateSharedHandle を呼び出すときにリソースの名前を lpName に渡すと、その後、ID3D11Device1::OpenSharedResourceByName メソッドの呼び出しでこの名前を渡して、別のデバイスに共有リソースへのアクセス権を付与できます。 名前付きリソースを使用する場合、悪意のあるユーザーは、その前にこの名前付きリソースを使用して、アプリの起動を妨げる可能性があります。 このような状況を回避するには、ランダムに名前付きリソースを作成し、承認されたユーザーのみが取得できるように名前を格納します。 または、この目的でファイルを使用することもできます。 アプリをユーザーごとに 1 つのインスタンスに制限するには、ユーザーのプロファイル ディレクトリにロックされたファイルを作成します。

リソースを共有として作成し、NT ハンドルを使用するように指定しなかった場合、 CreateSharedHandle を 使用して共有用のハンドルを取得することはできません。 これは、CreateSharedHandle が失敗するためです。

例

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.

要件

   
サポートされている最小のクライアント Windows 8 および Windows 7 用プラットフォーム更新プログラム [デスクトップ アプリ |UWP アプリ]
サポートされている最小のサーバー Windows Server 2012 および Windows Server 2008 R2 用プラットフォーム更新プログラム [デスクトップ アプリ |UWP アプリ]
対象プラットフォーム Windows
ヘッダー dxgi1_2.h
Library Dxgi.lib

関連項目

IDXGIResource1