GetNamedSecurityInfoA 函式（aclapi.h）

發行項
11/20/2024

GetNamedSecurityInfo 函式會擷取名稱所指定物件的安全性描述元複本。

語法

DWORD GetNamedSecurityInfoA(
  [in]            LPCSTR               pObjectName,
  [in]            SE_OBJECT_TYPE       ObjectType,
  [in]            SECURITY_INFORMATION SecurityInfo,
  [out, optional] PSID                 *ppsidOwner,
  [out, optional] PSID                 *ppsidGroup,
  [out, optional] PACL                 *ppDacl,
  [out, optional] PACL                 *ppSacl,
  [out, optional] PSECURITY_DESCRIPTOR *ppSecurityDescriptor
);

參數

[in] pObjectName

Null 終止字串的指標，指定要從中擷取安全性資訊的物件名稱。如需不同物件類型之字串格式的描述，請參閱 SE_OBJECT_TYPE。

[in] ObjectType

指定 SE_OBJECT_TYPE 列舉中的值，這個值表示 pObjectName 參數所命名的物件類型。

[in] SecurityInfo

一組位旗標，表示要擷取的安全性信息類型。此參數可以是 SECURITY_INFORMATION 位旗標的組合。

[out, optional] ppsidOwner

變數的指標，如果安全性描述元沒有擁有者 SID，ppSecurityDescriptor 或 NULL 傳回安全性描述元中的擁有者 SID 指標。只有在您設定OWNER_SECURITY_INFORMATION旗標時，傳回的指標才有效。此外，如果您不需要擁有者 SID，則可以將此參數 NULL。

[out, optional] ppsidGroup

在傳回的安全性描述元中接收主要群組 SID 指標的變數指標，如果安全描述元沒有群組 SID，則為 NULL NULL。只有在您設定GROUP_SECURITY_INFORMATION旗標時，傳回的指標才有效。此外，如果您不需要群組 SID，則可以將此參數 NULL。

[out, optional] ppDacl

在傳回的安全性描述元中接收 DACL 指標的變數指標，如果安全性描述元沒有 DACL，則 NULL。只有在您設定DACL_SECURITY_INFORMATION旗標時，傳回的指標才有效。此外，如果您不需要 DACL，則可以將此參數 NULL。

[out, optional] ppSacl

在傳回的安全性描述元中接收 SACL 指標的變數指標，如果安全性描述元沒有 SACL，則為 NULL 。只有在您設定SACL_SECURITY_INFORMATION旗標時，傳回的指標才有效。此外，如果您不需要 SACL，則可以 NULL。

[out, optional] ppSecurityDescriptor

變數的指標，接收物件之安全性描述元的指標。當您完成使用指標時，呼叫 LocalFree 函式來釋放傳回的緩衝區。

如果其中一個 ppsidOwner、ppsidGroup、ppDacl或 ppSacl 參數不是 NULL，則需要此參數。

傳回值

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

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

言論

如果任何 ppsidOwner、ppsidGroup、ppDacl或 ppSacl 參數都是非NULL，且 SecurityInfo 參數會指定從物件擷取它們，這些參數會指向在 ppSecurityDescriptor中傳回之安全性描述元中的對應參數。如果安全性描述元不包含所要求的信息，對應的參數將會設定為 NULL。

若要從物件的安全性描述元讀取擁有者、群組或 DACL，物件的 DACL 必須授與READ_CONTROL呼叫者的存取權，或者呼叫者必須是對象的擁有者。

若要讀取對象的系統訪問控制清單，呼叫程式必須啟用SE_SECURITY_NAME許可權。如需啟用權限之安全性含意的詳細資訊，請參閱使用特殊許可權執行。

您可以使用 GetNamedSecurityInfo 函式搭配下列類型的物件：

NTFS 檔案系統上的本機或遠端檔案或目錄
本機或遠端印表機
本機或遠端 Windows 服務
網路共用
登錄機碼
旗號、事件、Mutex 和可等候的定時器
檔案對應物件
目錄服務物件

此函式不會處理競爭條件。如果您的線程在大約另一個線程變更物件的安全性描述元時呼叫此函式，則此函式可能會失敗。

此函式會以純文本傳輸資訊。除非系統已關閉簽署，但不會執行加密，否則會簽署此函式傳輸的資訊。

如需透過使用者帳戶、組帳戶或登入工作階段控制物件存取的詳細資訊，請參閱 DACLs 如何控制物件存取。

例子

如需使用 getNamedSecurityInfo的範例，請參閱修改物件的 ACL。

注意

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

要求

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