Funzione lstrcpynW (winbase.h)

Articolo
11/20/2024

Copia un numero specificato di caratteri da una stringa di origine in un buffer.

Avviso Non usare. È consigliabile usare StringCchCopy. Vedere la sezione Osservazioni.

Sintassi

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

Parametri

[out] lpString1

Tipo: LPTSTR

Buffer di destinazione, che riceve i caratteri copiati. Il buffer deve essere sufficientemente grande da contenere il numero di valori TCHAR specificati da iMaxLength, inclusa la stanza per un carattere Null di terminazione.

[in] lpString2

Tipo: LPCTSTR

Stringa di origine da cui la funzione deve copiare i caratteri.

[in] iMaxLength

Tipo: int

Numero di valori TCHAR da copiare dalla stringa a cui punta lpString2 nel buffer a cui punta lpString1, incluso un carattere Null di terminazione.

Valore restituito

Tipo: LPTSTR

Se la funzione ha esito positivo, il valore restituito è un puntatore al buffer. La funzione può avere esito positivo anche se la stringa di origine è maggiore di caratteri iMaxLength.

Se la funzione ha esito negativo, il valore restituito viene NULL e lpString1 potrebbe non essere terminato null.

Osservazioni

Il buffer a cui punta lpString1 deve essere sufficientemente grande da includere un carattere Null di terminazione e il valore di lunghezza della stringa specificato da iMaxLength include spazio per un carattere Null di terminazione.

La funzione lstrcpyn ha un comportamento non definito se i buffer di origine e di destinazione si sovrappongono.

avviso di sicurezza

L'uso di questa funzione in modo errato può compromettere la sicurezza dell'applicazione. Questa funzione usa la gestione delle eccezioni strutturata (SEH) per intercettare le violazioni di accesso e altri errori. Quando questa funzione rileva errori SEH, restituisce NULL senza terminazione null della stringa e senza notificare al chiamante l'errore. Il chiamante non è sicuro presupporre che lo spazio insufficiente sia la condizione di errore.

Se il buffer a cui punta lpString1 non è sufficiente per contenere la stringa copiata, può verificarsi un sovraccarico del buffer. Quando si copia un'intera stringa, si noti che sizeof restituisce il numero di byte. Ad esempio, se lpString1 punta a un buffer szString1 che viene dichiarato come TCHAR szString[100], sizeof(szString1) restituisce le dimensioni del buffer in byte anziché WCHAR, che potrebbe causare un overflow del buffer per la versione Unicode della funzione.

Le situazioni di overflow del buffer sono la causa di molti problemi di sicurezza nelle applicazioni e possono causare un attacco Denial of Service all'applicazione se si verifica una violazione di accesso. Nel peggiore dei casi, un sovraccarico del buffer può consentire a un utente malintenzionato di inserire codice eseguibile nel processo, soprattutto se lpString1 è un buffer basato su stack.

L'uso di sizeof(szString1)/sizeof(szString1[0]) fornisce le dimensioni appropriate del buffer.

È consigliabile usare StringCchCopy; usare StringCchCopy(buffer, sizeof(buffer)/sizeof(buffer[0]), src);, sapendo che buffer non deve essere un puntatore o usare StringCchCopy(buffer, ARRAYSIZE(buffer), src);, sapendo che, durante la copia in un puntatore, il chiamante è responsabile del passaggio delle dimensioni della memoria puntata in caratteri.

Rivedere Considerazioni sulla sicurezza: interfaccia utente di Windows prima di continuare.

Nota

L'intestazione winbase.h definisce lstrcpyn come alias che seleziona automaticamente la versione ANSI o Unicode di questa funzione in base alla definizione della costante del preprocessore UNICODE. La combinazione dell'utilizzo dell'alias indipendente dalla codifica con il codice non indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere convenzioni di per i prototipi di funzioni.

Fabbisogno

Requisito	Valore
client minimo supportato	Windows 2000 Professional [solo app desktop]
server minimo supportato	Windows 2000 Server [solo app desktop]
piattaforma di destinazione	Finestre
intestazione	winbase.h (include Windows.h)
libreria	Kernel32.lib
dll	Kernel32.dll