CreateDesktopExA 関数 (winuser.h)

[アーティクル]
08/27/2023

指定したヒープを持つ新しいデスクトップを作成し、それを呼び出し元プロセスの現在のウィンドウステーションに関連付け、呼び出し元のスレッドに割り当てます。呼び出し元のプロセスには、プロセス作成時にシステムによって割り当てられるか、 SetProcessWindowStation 関数によって設定された、関連付けられたウィンドウステーションが必要です。

構文

HDESK CreateDesktopExA(
  [in]           LPCSTR                lpszDesktop,
                 LPCSTR                lpszDevice,
                 DEVMODEA              *pDevmode,
  [in]           DWORD                 dwFlags,
  [in]           ACCESS_MASK           dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES lpsa,
  [in]           ULONG                 ulHeapSize,
                 PVOID                 pvoid
);

パラメーター

[in] lpszDesktop

作成するデスクトップの名前。デスクトップ名では大文字と小文字が区別されず、円記号 (\) を含めないようにすることができます。

lpszDevice

このパラメーターは予約されており、NULL である必要があります。

pDevmode

このパラメーターは予約されており、NULL である必要があります。

[in] dwFlags

このパラメーターには、0 または次の値を指定できます。

値	意味
DF_ALLOWOTHERACCOUNTHOOK 0x0001	デスクトップ上の他のアカウントで実行されているプロセスで、このプロセスにフックを設定できるようにします。

[in] dwDesiredAccess

デスクトップに対して要求されたアクセス権。値の一覧については、「デスクトップセキュリティとアクセス権」を参照してください。

内部的に CreateDesktop はハンドルを使用してウィンドウを作成するため、このパラメーターにはDESKTOP_CREATEWINDOWアクセス権を含める必要があります。

[in, optional] lpsa

返されたハンドルを子プロセスによって継承できるかどうかを決定するSECURITY_ATTRIBUTES構造体へのポインター。 lpsa が NULL の場合、ハンドルを継承できません。

構造体の lpSecurityDescriptor メンバーは、新しいデスクトップのセキュリティ記述子を指定します。このパラメーターが NULL の場合、デスクトップは親ウィンドウステーションからセキュリティ記述子を継承します。

[in] ulHeapSize

デスクトップヒープのサイズ (KB 単位)。

pvoid

このパラメーターは予約されており、NULL である必要があります。

戻り値

関数が成功した場合、戻り値は新しく作成されたデスクトップへのハンドルです。指定したデスクトップが既に存在する場合、関数は成功し、既存のデスクトップへのハンドルを返します。ハンドルの使用が完了したら、 CloseDesktop 関数を呼び出して閉じます。

関数が失敗した場合は、返される値は NULL です。詳細なエラー情報を得るには、GetLastError を呼び出します。

解説

dwDesiredAccess パラメーターで標準アクセス権のREAD_CONTROL、WRITE_DAC、またはWRITE_OWNERを指定する場合は、DESKTOP_READOBJECTSとDESKTOP_WRITEOBJECTSアクセス権も要求する必要があります。

作成できるデスクトップの数は、システムデスクトップヒープのサイズによって制限されます。デスクトップオブジェクトは、ヒープを使用してリソースを格納します。作成できるデスクトップの数を増やすには、デスクトップヒープのサイズを大きくするか、対話型ウィンドウステーションの各デスクトップ用に予約されている既定のヒープを減らします。この値は、次のレジストリ値の SharedSection 部分文字列で指定されます: HKEY_LOCAL_MACHINE\SYSTEM\CurrentControlSet\Control\Session Manager\SubSystems\Windows。このレジストリ値の既定のデータは次のとおりです。

%SystemRoot%\system32\csrss.exe ObjectDirectory=\Windows SharedSection=1024,3072,512 Windows=On SubSystemType=Windows ServerDll=basesrv,1 ServerDll=winsrv:UserServerDllInitialization,3 ServerDll=winsrv:ConServerDllInitialization,2 ProfileControl=Off MaxRequestThreads=16

SharedSection 部分文字列の値を次に示します。

最初の SharedSection 値は、すべてのデスクトップに共通する共有ヒープのサイズ (KB 単位) です。
2 番目の SharedSection 値は、対話型ウィンドウステーション WinSta0 で作成された各デスクトップに必要なデスクトップヒープのサイズです (KB 単位)。
3 番目の SharedSection 値は、非対話型ウィンドウステーションで作成された各デスクトップに必要なデスクトップヒープのサイズ (KB 単位) です。

デスクトップヒープの既定のサイズは、ハードウェアアーキテクチャなどの要因によって異なります。デスクトップヒープのサイズを取得するには、UOI_HEAPSIZEを使用して GetUserObjectInformation 関数を呼び出します。

注意

winuser.h ヘッダーは、CreateDesktopEx をエイリアスとして定義し、UNICODE プリプロセッサ定数の定義に基づいて、この関数の ANSI または Unicode バージョンを自動的に選択します。エンコードに依存しないエイリアスをエンコードニュートラルでないコードと組み合わせて使用すると、コンパイルまたはランタイムエラーが発生する不一致が発生する可能性があります。詳細については、「関数プロトタイプの規則」を参照してください。

要件

要件	値
サポートされている最小のクライアント	Windows Vista [デスクトップアプリのみ]
サポートされている最小のサーバー	Windows Server 2008 [デスクトップアプリのみ]
対象プラットフォーム	Windows
ヘッダー	winuser.h (Windows.h を含む)
Library	User32.lib
[DLL]	User32.dll