CreateDesktopExA 函式（winuser.h）

發行項
11/20/2024

建立具有指定堆積的新桌面、將它與呼叫進程的目前視窗月臺產生關聯，並將它指派給呼叫線程。呼叫進程必須有相關聯的視窗月臺，由系統在進程建立期間指派，或由 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

此參數可以是零或下列值。

價值	意義
DF_ALLOWOTHERACCOUNTHOOK 0x0001	啟用在桌面上其他帳戶中執行的進程，以設定此程式中的勾點。

[in] dwDesiredAccess

要求的桌面存取權。如需值清單，請參閱 Desktop Security and Access Rights。

此參數必須包含DESKTOP_CREATEWINDOW訪問許可權，因為內部 CreateDesktop 使用句柄來建立視窗。

[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 為單位。
第二個 SharedSection 值是互動式視窗站 WinSta0 中建立的每個桌面所需的桌面堆積大小，以 KB 為單位。
第三個 SharedSection 值是每一個在非互動式視窗站台中建立之桌面堆積的大小，以 KB 為單位。

桌面堆積的預設大小取決於硬體架構等因素。若要擷取桌面堆積的大小，請使用 UOI_HEAPSIZE 呼叫 getUserObjectInformation 函式。

注意

winuser.h 標頭會將 CreateDesktopEx 定義為別名，根據 UNICODE 預處理器常數的定義，自動選取此函式的 ANSI 或 Unicode 版本。混合使用編碼中性別名與非編碼中性的程序代碼，可能會導致編譯或運行時間錯誤不符。如需詳細資訊，請參閱函式原型的慣例。

要求

要求	價值
最低支援的用戶端	Windows Vista [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2008 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	winuser.h （包括 Windows.h）
連結庫	User32.lib
DLL	User32.dll