Função RtlUnicodeStringInitEx (ntstrsafe.h)

Artigo
02/07/2025

A função rtlUnicodeStringInitEx inicializa uma estrutura de UNICODE_STRING.

Sintaxe

NTSTRSAFEDDI RtlUnicodeStringInitEx(
  [out]          PUNICODE_STRING  DestinationString,
  [in, optional] NTSTRSAFE_PCWSTR pszSrc,
  [in]           DWORD            dwFlags
);

Parâmetros

[out] DestinationString

Opcional. Um ponteiro para uma estrutura UNICODE_STRING a ser inicializada. O ponteiro pszSrc é copiado para a estrutura de UNICODE_STRING do parâmetro DestinationString. O número máximo de caracteres na cadeia de caracteres que pszSrc aponta é NTSTRSAFE_UNICODE_STRING_MAX_CCH. DestinationString pode ser NULL, mas somente se STRSAFE_IGNORE_NULLS estiver definido em dwFlags.

[in, optional] pszSrc

Opcional. Um ponteiro para uma constante de cadeia de caracteres terminada em nulo. Esse ponteiro de cadeia de caracteres será copiado para o membro do buffer da estrutura de UNICODE_STRING apontada pelo parâmetro DestinationString. Esse ponteiro de cadeia de caracteres pode ser NULL.

[in] dwFlags

O seguinte sinalizador é definido:

STRSAFE_IGNORE_NULLS

Se esse sinalizador estiver definido, o ponteiro de origem poderá ser NULL. RtlUnicodeStringInitEx trata ponteiros nulos buffer de origem, como cadeias de caracteres vazias (TEXT(")), que podem ser copiadas.

Valor de retorno

RtlUnicodeStringInitEx retorna um dos seguintes valores NTSTATUS.

Código de retorno	Descrição
STATUS_SUCCESS	Esse êxito status significa que os dados de origem estavam presentes, a cadeia de caracteres foi copiada sem truncamento e o buffer de destino resultante foi encerrado em nulo.
STATUS_INVALID_PARAMETER	Esse erro status significa que a função recebeu um parâmetro de entrada inválido. Para obter mais informações, consulte a lista a seguir.

RtlUnicodeStringInitEx retorna o valor STATUS_INVALID_PARAMETER quando um dos seguintes ocorre:

O comprimento da cadeia de caracteres à qual o parâmetro pszSrc aponta é maior que NTSTRSAFE_UNICODE_STRING_MAX_CCH caracteres.
O ponteiro DestinationString é NULL, mas o ponteiro pszSrc não é NULL.

Para obter informações sobre como testar valores NTSTATUS, consulte Usando valores NTSTATUS.

Observações

A função RtlUnicodeStringInitEx faz o seguinte:

Define o Length membro da estrutura UNICODE_STRING para o comprimento, em bytes, da cadeia de caracteres à qual o parâmetro pszSrc aponta.
Define o membro MaximumLength da estrutura UNICODE_STRING ao comprimento, em bytes, da cadeia de caracteres que o parâmetro pszSrc aponta para mais 2 bytes.
Define o membro do buffer da estrutura UNICODE_STRING para o endereço especificado pelo parâmetro pszSrc.

O ponteiro DestinationString não pode ser NULL, a menos que o sinalizador STRSAFE_IGNORE_NULLS esteja definido.

Para obter mais informações sobre as funções de cadeia de caracteres seguras, consulte Usando funções de cadeia de caracteres seguras.

Requisitos

Requisito	Valor
de cliente com suporte mínimo	Disponível a partir do Windows XP com Service Pack 1 (SP1).
da Plataforma de Destino	Área de trabalho
cabeçalho	ntstrsafe.h (inclua Ntstrsafe.h)
biblioteca	Ntstrsafe.lib
IRQL	Se as cadeias de caracteres que estão sendo manipuladas estiverem sempre residentes na memória, caso contrário, PASSIVE_LEVEL

Consulte também

rtlUnicodeStringInit

UNICODE_STRING

Compartilhar via