Fungsi lstrcpynW (winbase.h)

Artikel
11/20/2024

Menyalin jumlah karakter tertentu dari string sumber ke dalam buffer.

Peringatan Jangan gunakan. Pertimbangkan untuk menggunakan StringCchCopy. Lihat Komentar.

Sintaksis

LPWSTR lstrcpynW(
  [out] LPWSTR  lpString1,
  [in]  LPCWSTR lpString2,
  [in]  int     iMaxLength
);

Parameter

[out] lpString1

Jenis: LPTSTR

Buffer tujuan, yang menerima karakter yang disalin. Buffer harus cukup besar untuk berisi jumlah nilai TCHAR yang ditentukan olehiMaxLength , termasuk ruang untuk karakter null yang dihentikan.

[in] lpString2

Jenis: LPCTSTR

String sumber tempat fungsi akan menyalin karakter.

[in] iMaxLength

Jenis: int

Jumlah nilai TCHAR yang akan disalin dari string yang ditunjukkan oleh lpString2 ke dalam buffer yang ditunjukkan oleh lpString1, termasuk karakter null yang mengakhiri.

Mengembalikan nilai

Jenis: LPTSTR

Jika fungsi berhasil, nilai yang dikembalikan adalah penunjuk ke buffer. Fungsi ini dapat berhasil meskipun string sumber lebih besar dari karakter iMaxLength.

Jika fungsi gagal, nilai pengembalian NULL dan lpString1 mungkin tidak dihentikan null.

Komentar

Buffer yang ditunjukkan oleh lpString1 harus cukup besar untuk menyertakan karakter null yang mengakhiri, dan nilai panjang string yang ditentukan oleh iMaxLength menyertakan ruang untuk karakter null yang mengakhiri.

Fungsi lstrcpyn memiliki perilaku yang tidak ditentukan jika buffer sumber dan tujuan tumpang tindih.

Peringatan Keamanan

Menggunakan fungsi ini salah dapat membahayakan keamanan aplikasi Anda. Fungsi ini menggunakan penanganan pengecualian terstruktur (SEH) untuk menangkap pelanggaran akses dan kesalahan lainnya. Ketika fungsi ini menangkap kesalahan SEH, fungsi ini mengembalikan NULL tanpa menghentikan string null dan tanpa memberi tahu pemanggil kesalahan. Pemanggil tidak aman untuk mengasumsikan bahwa ruang yang tidak mencukup adalah kondisi kesalahan.

Jika buffer yang ditunjukkan oleh lpString1 tidak cukup besar untuk berisi string yang disalin, dapat terjadi overrun buffer. Saat menyalin seluruh string, perhatikan bahwa ukuran dari mengembalikan jumlah byte. Misalnya, jika lpString1 menunjuk ke buffer szString1 yang dinyatakan sebagai TCHAR szString[100], maka sizeof(szString1) memberikan ukuran buffer dalam byte daripada WCHAR, yang dapat menyebabkan luapan buffer untuk versi Fungsi Unicode.

Situasi luapan buffer adalah penyebab banyak masalah keamanan dalam aplikasi dan dapat menyebabkan penolakan serangan layanan terhadap aplikasi jika terjadi pelanggaran akses. Dalam kasus terburuk, overrun buffer dapat memungkinkan penyerang untuk menyuntikkan kode yang dapat dieksekusi ke dalam proses Anda, terutama jika lpString1 adalah buffer berbasis tumpukan.

Menggunakan sizeof(szString1)/sizeof(szString1[0]) memberikan ukuran buffer yang tepat.

Pertimbangkan untuk menggunakan StringCchCopy; gunakan , menyadari bahwa tidak boleh menjadi penunjuk atau menggunakan , menyadari bahwa, saat menyalin ke penunjuk, pemanggil bertanggung jawab untuk meneruskan ukuran memori yang ditujukan ke dalam karakter.

Tinjau Pertimbangan Keamanan: Antarmuka Pengguna Windows sebelum melanjutkan.

Nota

Header winbase.h mendefinisikan lstrcpyn sebagai alias yang secara otomatis memilih versi ANSI atau Unicode dari fungsi ini berdasarkan definisi konstanta preprosedur UNICODE. Mencampur penggunaan alias encoding-netral dengan kode yang tidak mengodekan-netral dapat menyebabkan ketidakcocokan yang mengakibatkan kesalahan kompilasi atau runtime. Untuk informasi selengkapnya, lihat Konvensi untuk Prototipe Fungsi.

Persyaratan

Syarat	Nilai
klien minimum yang didukung	Windows 2000 Professional [hanya aplikasi desktop]
server minimum yang didukung	Windows 2000 Server [hanya aplikasi desktop]
Platform Target	Windows
Header	winbase.h (termasuk Windows.h)
Pustaka	Kernel32.lib
DLL	Kernel32.dll