CreateDesktopA 函式 (winuser.h)

發行項
03/04/2024

建立新的桌面，將它與呼叫進程的目前視窗月臺產生關聯，並將它指派給呼叫線程。呼叫進程必須有相關聯的視窗月臺，由系統在進程建立期間指派，或由 SetProcessWindowStation 函式設定。

若要指定桌面的堆積大小，請使用 CreateDesktopEx 函式。

語法

HDESK CreateDesktopA(
  [in]           LPCSTR                lpszDesktop,
                 LPCSTR                lpszDevice,
                 DEVMODEA              *pDevmode,
  [in]           DWORD                 dwFlags,
  [in]           ACCESS_MASK           dwDesiredAccess,
  [in, optional] LPSECURITY_ATTRIBUTES lpsa
);

參數

[in] lpszDesktop

要建立的桌面名稱。桌面名稱不區分大小寫，且可能不會包含反斜杠字元 (\) 。

lpszDevice

保留;必須是 NULL。

pDevmode

保留;必須是 NULL。

[in] dwFlags

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

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

[in] dwDesiredAccess

桌面的存取權。如需值清單，請參閱桌面安全性與訪問許可權。

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

[in, optional] lpsa

SECURITY_ATTRIBUTES 結構的指標，決定子進程是否可以繼承傳回的句柄。如果 lpsa 是 NULL，則無法繼承句柄。

結構的 lpSecurityDescriptor 成員會指定新桌面的安全性描述元。如果此參數為NULL，桌面會從父視窗月臺繼承其安全性描述元。

傳回值

如果函式成功，則傳回值是新建立桌面的句柄。如果指定的桌面已經存在，函式會成功，並將句柄傳回給現有的桌面。當您完成使用句柄時，請呼叫 CloseDesktop 函式將其關閉。

如果函式失敗，則傳回值為 NULL。若要取得擴充的錯誤資訊，請呼叫 GetLastError。

備註

如果 dwDesiredAccess 參數指定 READ_CONTROL、 WRITE_DAC或 WRITE_OWNER 標準訪問許可權，您也必須要求 DESKTOP_READOBJECTS 和 DESKTOP_WRITEOBJECTS 訪問許可權。

可建立的桌面數目受限於系統桌面堆積的大小，也就是 48 MB。桌面物件會使用堆積來儲存資源。您可以藉由減少互動式視窗站臺中每個桌面保留的預設堆積，來增加可建立的桌面數目。此值是在下列登入值的「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 為單位。

注意

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

規格需求

需求	值
最低支援的用戶端	Windows 2000 專業版 [僅限傳統型應用程式]
最低支援的伺服器	Windows 2000 Server [僅限傳統型應用程式]
目標平台	Windows
標頭	winuser.h (包括 Windows.h)
程式庫	User32.lib
Dll	User32.dll
API 集合	ext-ms-win-ntuser-windowstation-l1-1-0 (於 Windows 8)