Função ConvertSecurityDescriptorToStringSecurityDescriptorA (sddl.h)

Artigo
03/08/2023

A função ConvertSecurityDescriptorToStringSecurityDescriptor converte um descritor de segurança em um formato de cadeia de caracteres. Você pode usar o formato de cadeia de caracteres para armazenar ou transmitir o descritor de segurança.

Para converter o descritor de segurança de formato de cadeia de caracteres de volta em um descritor de segurança funcional válido, chame a função ConvertStringSecurityDescriptorToSecurityDescriptor .

Sintaxe

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

Parâmetros

[in] SecurityDescriptor

Um ponteiro para o descritor de segurança a ser convertido. O descritor de segurança pode estar em formato absoluto ou auto-relativo.

[in] RequestedStringSDRevision

Especifica o nível de revisão da cadeia de caracteres StringSecurityDescriptor de saída. Atualmente, esse valor deve ser SDDL_REVISION_1.

[in] SecurityInformation

Especifica uma combinação dos sinalizadores de SECURITY_INFORMATION bits para indicar os componentes do descritor de segurança a serem incluídos na cadeia de caracteres de saída.

O sinalizador BACKUP_SECURITY_INFORMATION não é aplicável a essa função. Se o sinalizador BACKUP_SECURITY_INFORMATION for passado, o parâmetro SecurityInformation retornará TRUE com saída de cadeia de caracteres nula .

[out] StringSecurityDescriptor

Um ponteiro para uma variável que recebe um ponteiro para uma cadeia de caracteres de descritor de segurança terminada em nulo. Para obter uma descrição do formato de cadeia de caracteres, consulte Formato de cadeia de caracteres do descritor de segurança. Para liberar o buffer retornado, chame a função LocalFree .

[out] StringSecurityDescriptorLen

Um ponteiro para uma variável que recebe o tamanho, em TCHARs, da cadeia de caracteres do descritor de segurança retornada no buffer StringSecurityDescriptor . Esse parâmetro poderá ser NULL se você não precisar recuperar o tamanho. O tamanho representa o tamanho do buffer em WCHARs, não o número de WCHARs na cadeia de caracteres.

Valor retornado

Se a função for bem-sucedida, o valor retornado será diferente de zero.

Se a função falhar, o valor retornado será zero. Para obter informações de erro estendidas, chame GetLastError. A função GetLastError pode retornar um dos seguintes códigos de erro.

Código de retorno	Descrição
ERROR_INVALID_PARAMETER	Um parâmetro não é válido.
ERROR_UNKNOWN_REVISION	O nível de revisão não é válido.
ERROR_NONE_MAPPED	Não foi possível encontrar um SID ( identificador de segurança ) no descritor de segurança de entrada em uma operação de pesquisa de conta.
ERROR_INVALID_ACL	A ACL ( lista de controle de acesso ) não é válida. Esse erro será retornado se o sinalizador SE_DACL_PRESENT estiver definido no descritor de segurança de entrada e a DACL for NULL.

Comentários

Se a DACL for NULL e o bit de controle SE_DACL_PRESENT for definido no descritor de segurança de entrada, a função falhará.

Se a DACL for NULL e o bit de controle SE_DACL_PRESENT não estiver definido no descritor de segurança de entrada, a cadeia de caracteres do descritor de segurança resultante não terá um componente D:. Para obter mais informações, consulte Formato de cadeia de caracteres do descritor de segurança.

Observação

O cabeçalho sddl.h define ConvertSecurityDescriptorToStringSecurityDescriptor como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.

Requisitos

Requisito	Valor
Cliente mínimo com suporte	Windows XP [aplicativos da área de trabalho \| aplicativos UWP]
Servidor mínimo com suporte	Windows Server 2003 [aplicativos da área de trabalho \| Aplicativos UWP]
Plataforma de Destino	Windows
Cabeçalho	sddl.h
Biblioteca	Advapi32.lib
DLL	Advapi32.dll