ConvertSecurityDescriptorToStringSecurityDescriptorA 函式 (sddl.h)

發行項
03/01/2024

ConvertSecurityDescriptorToStringSecurityDescriptor 函式會將安全性描述元轉換成字串格式。您可以使用字串格式來儲存或傳輸安全性描述元。

若要將字串格式安全性描述元轉換成有效的功能安全性描述元，請呼叫 ConvertStringSecurityDescriptorToSecurityDescriptor 函式。

語法

BOOL ConvertSecurityDescriptorToStringSecurityDescriptorA(
  [in]  PSECURITY_DESCRIPTOR SecurityDescriptor,
  [in]  DWORD                RequestedStringSDRevision,
  [in]  SECURITY_INFORMATION SecurityInformation,
  [out] LPSTR                *StringSecurityDescriptor,
  [out] PULONG               StringSecurityDescriptorLen
);

參數

[in] SecurityDescriptor

要轉換之安全性描述元的指標。安全性描述元可以是絕對或自我相對格式。

[in] RequestedStringSDRevision

指定輸出 StringSecurityDescriptor 字串串的修訂層級。此值目前必須SDDL_REVISION_1。

[in] SecurityInformation

指定 SECURITY_INFORMATION 位旗標的組合，以指出要包含在輸出字串中之安全性描述元的元件。

BACKUP_SECURITY_INFORMATION旗標不適用於此函式。如果傳入BACKUP_SECURITY_INFORMATION旗標， SecurityInformation 參數會以 null 字串輸出傳回 TRUE。

[out] StringSecurityDescriptor

變數的指標，可接收 以 Null 終止之安全性描述元字串的指標。如需字串格式的描述，請參閱安全性描述元字串格式。若要釋放傳回的緩衝區，請呼叫 LocalFree 函式。

[out] StringSecurityDescriptorLen

接收 StringSecurityDescriptor 緩衝區中傳回之安全性描述元字串大小之變數的指標。如果您不需要擷取大小，此參數可以是 NULL 。大小代表 WCHARs 中的緩衝區大小，而不是字串中的 WCHAR 數目。

傳回值

如果函式成功，則傳回非零的值。

如果此函式失敗，則傳回值為零。若要取得擴充的錯誤資訊，請呼叫 GetLastError。 GetLastError 函式可能會傳回下列其中一個錯誤碼。

傳回碼	Description
ERROR_INVALID_PARAMETER	參數無效。
ERROR_UNKNOWN_REVISION	修訂層級無效。
ERROR_NONE_MAPPED	在帳戶查閱作業中找不到輸入安全性描述元中 (SID) 的安全性識別碼。
ERROR_INVALID_ACL	(ACL) 的訪問控制清單無效。如果在輸入安全性描述元中設定SE_DACL_PRESENT旗標，且 DACL 為 NULL，則會傳回此錯誤。

備註

如果 DACL 為 NULL，且在輸入安全性描述元中設定SE_DACL_PRESENT控制位，則函式會失敗。

如果 DACL 為 NULL，且輸入安全性描述元中未設定SE_DACL_PRESENT控制位，則產生的安全性描述元字串沒有 D：元件。如需詳細資訊，請參閱安全性描述元字串格式。

注意

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

規格需求

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