getNamedSecurityInfoA 函式 (aclapi.h)

發行項
02/23/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 傳回的安全性描述元中接收擁有者 SID 的指標，或 NULL。只有在您設定OWNER_SECURITY_INFORMATION旗標時，傳回的指標才有效。此外，如果您不需要擁有者 SID，此參數可以是 NULL 。

[out, optional] ppsidGroup

在傳回的安全性描述元中接收主要群組 SID 指標的變數指標，如果安全性描述元沒有群組 SID，則為 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 和可等候的定時器
檔案對應物件
目錄服務物件

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

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

如需透過使用者帳戶、組帳戶或登入會話控制物件存取權的詳細資訊，請參閱 DACL 如何控制物件的存取權。

範例

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

注意

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

規格需求

需求	值
最低支援的用戶端	Windows XP [傳統型應用程式 \|UWP 應用程式]
最低支援的伺服器	Windows Server 2003 [傳統型應用程式 \|UWP 應用程式]
目標平台	Windows
標頭	aclapi.h
程式庫	Advapi32.lib
Dll	Advapi32.dll