BuildSecurityDescriptorA 函式（aclapi.h）

發行項
11/20/2024

BuildSecurityDescriptor 函式會設定並初始化新的安全性描述元。此函式可以藉由將指定的安全性資訊與現有安全性描述元中的資訊合併，來初始化新的安全性描述元。如果您未指定現有的安全性描述元，函式會根據指定的安全性資訊，初始化新的安全性描述元。

BuildSecurityDescriptor 函式會建立自我相對安全性描述元。自我相對格式會讓安全性描述元適合儲存在數據流中。

語法

DWORD BuildSecurityDescriptorA(
  [in, optional] PTRUSTEE_A           pOwner,
  [in, optional] PTRUSTEE_A           pGroup,
  [in]           ULONG                cCountOfAccessEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAccessEntries,
  [in]           ULONG                cCountOfAuditEntries,
  [in, optional] PEXPLICIT_ACCESS_A   pListOfAuditEntries,
  [in, optional] PSECURITY_DESCRIPTOR pOldSD,
  [out]          PULONG               pSizeNewSD,
  [out]          PSECURITY_DESCRIPTOR *pNewSD
);

參數

[in, optional] pOwner

識別新安全性描述元擁有者之信任結構的指標。如果結構使用TRUSTEE_IS_NAME窗體，BuildSecurityDescriptor 會查閱與指定信任者名稱相關聯的安全性標識符（SID）。

如果此參數 NULL，則函式會使用由 pOldSD 所指向的原始安全性描述元的擁有者 SID。如果 pOldSDNULL，或 pOldSD 中的擁有者 SID NULL，則擁有者 SID 在新的安全性描述元中 NULL。

[in, optional] pGroup

識別新安全性描述元之主要群組 SID 之 TRUSTEE 的指標結構。如果結構使用TRUSTEE_IS_NAME窗體，BuildSecurityDescriptor 查閱與指定信任項名稱相關聯的 SID。

如果此參數 NULL，則函式會使用由 pOldSD 所指向之原始安全性描述元的群組 SID。如果 pOldSD NULL，或如果 pOldSD 中的群組 SID NULL，則群組 SID 會新的安全性描述元中的 NULL。

[in] cCountOfAccessEntries

pListOfAccessEntries 陣列中的 EXPLICIT_ACCESS 結構數目。

[in, optional] pListOfAccessEntries

EXPLICIT_ACCESS 結構的陣列指標，描述新安全性描述元之任意存取控制清單（DACL）的存取控制資訊。函式會藉由將數位中的資訊與 pOldSD 中的 DACL 合併為 pOldSD，以建立新的 DACL。如果 pOldSDNULL，或如果 pOldSD 中的 DACL NULL，則函式會根據數位中的資訊建立新的 DACL。如需從 EXPLICIT_ACCESS 結構數位建立 ACL 的規則描述，請參閱 setEntriesInAcl 函式。

如果 pListOfAccessEntriesNULL，則新的安全性描述元會從 pOldSD 取得 DACL。在此情況下，如果 pOldSDNULL，或如果 pOldSD 中的 DACL NULL，則新的 DACL 會 NULL。

[in] cCountOfAuditEntries

pListOfAuditEntries 陣列中的 EXPLICIT_ACCESS 結構數目。

[in, optional] pListOfAuditEntries

EXPLICIT_ACCESS 結構的陣列指標，描述新安全性描述元之 SACL 的稽核控制資訊。函式會藉由將數位資訊與 pOldSD 中的 SACL 合併 pOldSD，以建立新的 SACL。如果 pOldSDNULL，或 pOldSD 中的 SACL NULL，則函式會根據數位中的資訊建立新的 SACL。

如果 pListOfAuditEntriesNULL，則新的安全性描述項會從 pOldSD 取得 SACL。在此情況下，如果 pOldSD NULL，或 pOldSD 中的 SACL NULL，則新的 SACL 會 NULL。

[in, optional] pOldSD

現有自我相對 SECURITY_DESCRIPTOR 結構的指標及其相關聯的安全性資訊。函式會將指定的擁有者、群組、訪問控制和稽核控制資訊與這個安全性描述元中的資訊合併，以建置新的安全性描述元。此參數可以是 NULL。

[out] pSizeNewSD

接收安全性描述元大小之變數的指標，以位元組為單位。

[out] pNewSD

接收新安全性描述元指標之變數的指標。函式會配置新安全性描述元的記憶體。您必須呼叫 LocalFree 函式，以釋放傳回的緩衝區。

傳回值

如果函式成功，函式會傳回ERROR_SUCCESS。

如果函式失敗，它會傳回 WinError.h 中定義的非零錯誤碼。

言論

BuildSecurityDescriptor 函式適用於在其本身對象上實作或公開安全性的信任伺服器。函式會使用適合串行化為數據流並儲存至磁碟的自我相對安全性描述元，因為信任的伺服器可能需要。

注意

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

要求

要求	價值
最低支援的用戶端	Windows XP [僅限傳統型應用程式]
支援的最低伺服器	Windows Server 2003 [僅限傳統型應用程式]
目標平臺	窗戶
標頭	aclapi.h
連結庫	Advapi32.lib
DLL	Advapi32.dll