Fungsi RtlStringCchCopyNA (ntstrsafe.h)

Artikel
05/03/2024

Fungsi RtlStringCchCopyNW dan RtlStringCchCopyNA menyalin string yang dihitung karakter ke buffer sambil membatasi ukuran string yang disalin.

Sintaks

NTSTRSAFEDDI RtlStringCchCopyNA(
  [out] NTSTRSAFE_PSTR pszDest,
  [in]  size_t         cchDest,
  [in]  STRSAFE_PCNZCH pszSrc,
        size_t         cchToCopy
);

Parameter

[out] pszDest

Penunjuk ke buffer yang disediakan penelepon yang menerima string yang disalin. String di pszSrc, hingga karakter cchSrc , disalin ke buffer di pszDest dan dihentikan dengan karakter null.

[in] cchDest

Ukuran buffer tujuan, dalam karakter. Jumlah maksimum karakter yang diizinkan adalah NTSTRSAFE_MAX_CCH.

[in] pszSrc

Penunjuk ke string yang disediakan penelepon dan dihentikan null.

cchToCopy

Jumlah maksimum karakter untuk disalin dari pszSrc ke buffer yang disediakan oleh pszDest.

Menampilkan nilai

Fungsi mengembalikan salah satu nilai NTSTATUS yang tercantum dalam tabel berikut. Untuk informasi tentang cara menguji nilai NTSTATUS, lihat Menggunakan Nilai NTSTATUS.

Menampilkan kode	Deskripsi
STATUS_SUCCESS	Status keberhasilan ini berarti data sumber ada, string disalin tanpa pemotokan, dan buffer tujuan yang dihasilkan dihentikan null.
STATUS_BUFFER_OVERFLOW	Status peringatan ini berarti operasi salin tidak selesai karena ruang yang tidak mencukupi di buffer tujuan. Buffer tujuan berisi versi untai (karakter) yang disalin yang disalin.
STATUS_INVALID_PARAMETER	Status kesalahan ini berarti fungsi menerima parameter input yang tidak valid. Untuk informasi selengkapnya, lihat paragraf berikut ini. Fungsi mengembalikan nilai STATUS_INVALID_PARAMETER saat: Nilai dalam cchDest lebih besar dari ukuran buffer maksimum. Buffer tujuan sudah penuh. Penunjuk NULL ada. Panjang buffer tujuan adalah nol, tetapi string sumber panjang bukan nol ada.

Menampilkan kode

Deskripsi

STATUS_SUCCESS

Status keberhasilan ini berarti data sumber ada, string disalin tanpa pemotokan, dan buffer tujuan yang dihasilkan dihentikan null.

STATUS_BUFFER_OVERFLOW

Status peringatan ini berarti operasi salin tidak selesai karena ruang yang tidak mencukupi di buffer tujuan. Buffer tujuan berisi versi untai (karakter) yang disalin yang disalin.

STATUS_INVALID_PARAMETER

Status kesalahan ini berarti fungsi menerima parameter input yang tidak valid. Untuk informasi selengkapnya, lihat paragraf berikut ini.

Fungsi mengembalikan nilai STATUS_INVALID_PARAMETER saat:

Nilai dalam cchDest lebih besar dari ukuran buffer maksimum.
Buffer tujuan sudah penuh.
Penunjuk NULL ada.
Panjang buffer tujuan adalah nol, tetapi string sumber panjang bukan nol ada.

Keterangan

RtlStringCchCopyNW dan RtlStringCchCopyNA harus digunakan alih-alih strncpy.

Fungsi menyalin sejumlah karakter tertentu dari string sumber. RtlStringCchCopyNW dan RtlStringCchCopyNA menerima ukuran, dalam karakter, dari buffer tujuan untuk memastikan bahwa fungsi tidak menulis melewati akhir buffer.

Perhatikan bahwa fungsi-fungsi ini bereaksi berbeda dari strncpy dalam satu hal. Jika cchSrc lebih besar dari jumlah karakter dalam pszSrc, RtlStringCchCopyNW dan RtlStringCchCopyNA—tidak seperti strncpy—jangan lanjutkan ke pad pszDest dengan karakter null hingga karakter cchSrc disalin.

Gunakan RtlStringCchCopyNW untuk menangani string Unicode dan RtlStringCchCopyNA untuk menangani string ANSI. Formulir yang Anda gunakan bergantung pada data Anda, seperti yang diperlihatkan dalam tabel berikut ini.

Jenis data string	String literal	Fungsi
WCHAR	L"string"	RtlStringCchCopyNW
char	"string"	RtlStringCchCopyNA

Jika pszSrc dan pszDest menunjuk ke string yang tumpang tindih, perilaku fungsi tidak terdefinisi.

Baik pszSrc maupun pszDest tidak boleh NULL. Jika Anda perlu menangani nilai penunjuk string NULL , gunakan RtlStringCchCopyNEx.

Untuk informasi selengkapnya tentang fungsi string aman, lihat Menggunakan Fungsi String Aman.

Persyaratan

Persyaratan	Nilai
Klien minimum yang didukung	Tersedia di Windows XP dengan Paket Layanan 1 (SP1) dan versi Windows yang lebih baru.
Target Platform	Desktop
Header	ntstrsafe.h (termasuk Ntstrsafe.h)
Pustaka	Ntstrsafe.lib
IRQL	Bagaimanapun, jika string yang dimanipulasi selalu berada dalam memori, jika tidak, PASSIVE_LEVEL

Lihat juga

RtlStringCbCopyN

RtlStringCchCopy

RtlStringCchCopyNEx