ConvertSecurityDescriptorToStringSecurityDescriptorW 函式（sddl.h）

發行項
11/20/2024

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

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

語法

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

參數

[in] SecurityDescriptor

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

[in] RequestedStringSDRevision

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

[in] SecurityInformation

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

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

[out] StringSecurityDescriptor

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

[out] StringSecurityDescriptorLen

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

傳回值

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

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

傳回碼	描述
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 應用程式]
目標平臺	窗戶
標頭	sddl.h
連結庫	Advapi32.lib
DLL	Advapi32.dll