Função RtlUnicodeStringInitEx (ntstrsafe.h)

  • Artigo

A função RtlUnicodeStringInitEx inicializa uma estrutura 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 UNICODE_STRING do parâmetro DestinationString. O número máximo de caracteres na cadeia de caracteres para o qual 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 Buffer da estrutura 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 de buffer de origem NULL como cadeias de caracteres vazias (TEXT("")), que podem ser copiadas.

Retornar valor

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 ocorre um destes procedimentos:

  • O comprimento da cadeia de caracteres para a 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.

Comentários

A função RtlUnicodeStringInitEx faz o seguinte:

  • Define o membro Length da estrutura UNICODE_STRING para o comprimento, em bytes, da cadeia de caracteres para a qual o parâmetro pszSrc aponta.
  • Define o membro MaximumLength da estrutura UNICODE_STRING para o comprimento, em bytes, da cadeia de caracteres que o parâmetro pszSrc aponta para mais 2 bytes.
  • Define o membro 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
Cliente mínimo com suporte Disponível a partir do Windows XP com o Service Pack 1 (SP1).
Plataforma de Destino Área de Trabalho
Cabeçalho ntstrsafe.h (inclua Ntstrsafe.h)
Biblioteca Ntstrsafe.lib
IRQL PASSIVE_LEVEL

Confira também

RtlUnicodeStringInit

UNICODE_STRING