Função RtlStringCchCopyNA (ntstrsafe.h)
As funções RtlStringCchCopyNW e RtlStringCchCopyNA copiam uma cadeia de caracteres contada para um buffer enquanto limitam o tamanho da cadeia de caracteres copiada.
Sintaxe
NTSTRSAFEDDI RtlStringCchCopyNA(
[out] NTSTRSAFE_PSTR pszDest,
[in] size_t cchDest,
[in] STRSAFE_PCNZCH pszSrc,
size_t cchToCopy
);
Parâmetros
[out] pszDest
Um ponteiro para um buffer fornecido pelo chamador que recebe a cadeia de caracteres copiada. A cadeia de caracteres em pszSrc, até caracteres cchSrc , é copiada para o buffer em pszDest e terminada com um caractere nulo.
[in] cchDest
O tamanho do buffer de destino, em caracteres. O número máximo de caracteres permitido é NTSTRSAFE_MAX_CCH.
[in] pszSrc
Um ponteiro para uma cadeia de caracteres com terminação nula fornecida pelo chamador.
cchToCopy
O número máximo de caracteres a serem copiados de pszSrc para o buffer fornecido pelo pszDest.
Retornar valor
A função retorna um dos valores NTSTATUS listados na tabela a seguir. Para obter informações sobre como testar valores NTSTATUS, consulte Usando valores NTSTATUS.
| Código de retorno | Descrição |
|---|---|
|
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. |
|
Esse aviso status significa que a operação de cópia não foi concluída devido a espaço insuficiente no buffer de destino. O buffer de destino contém uma versão truncada da cadeia de caracteres copiada. |
|
Esse erro status significa que a função recebeu um parâmetro de entrada inválido. Para obter mais informações, consulte o parágrafo a seguir.
A função retorna o valor STATUS_INVALID_PARAMETER quando:
|
Comentários
RtlStringCchCopyNW e RtlStringCchCopyNA devem ser usados em vez de strncpy.
As funções copiam um determinado número de caracteres de uma cadeia de caracteres de origem. RtlStringCchCopyNW e RtlStringCchCopyNA recebem o tamanho, em caracteres, do buffer de destino para garantir que as funções não sejam gravadas após o final do buffer.
Observe que essas funções se comportam de forma diferente de strncpy em um aspecto. Se cchSrc for maior que o número de caracteres em pszSrc, RtlStringCchCopyNW e RtlStringCchCopyNA, ao contrário de strncpy, não continue a preencher pszDest com caracteres nulos até que os caracteres cchSrc sejam copiados.
Use RtlStringCchCopyNW para manipular cadeias de caracteres Unicode e RtlStringCchCopyNA para manipular cadeias de caracteres ANSI. O formulário usado depende de seus dados, conforme mostrado na tabela a seguir.
| Tipos de dados de cadeia de caracteres | Cadeia de caracteres literal | Função |
|---|---|---|
| WCHAR | L"string" | RtlStringCchCopyNW |
| char | “cadeia de caracteres” | RtlStringCchCopyNA |
Se pszSrc e pszDest apontarem para cadeias de caracteres sobrepostas, o comportamento da função será indefinido.
Nem pszSrc nem pszDest podem ser NULL. Se você precisar manipular valores de ponteiro de cadeia de caracteres NULL , use RtlStringCchCopyNEx.
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 no Windows XP com Service Pack 1 (SP1) e versões posteriores do Windows. |
| Plataforma de Destino | Área de Trabalho |
| Cabeçalho | ntstrsafe.h (inclua Ntstrsafe.h) |
| Biblioteca | Ntstrsafe.lib |
| IRQL | Qualquer se as cadeias de caracteres que estão sendo manipuladas estiverem sempre residentes na memória, caso contrário, PASSIVE_LEVEL |