Funzione SHFileOperationA (shellapi.h)
Copia, sposta, rinomina o elimina un oggetto file system. Questa funzione è stata sostituita in Windows Vista da IFileOperation.
Sintassi
int SHFileOperationA(
[in, out] LPSHFILEOPSTRUCTA lpFileOp
);
Parametri
[in, out] lpFileOp
Tipo: LPSHFILEOPSTRUCT
Puntatore a una struttura SHFILEOPSTRUCT che contiene informazioni necessarie per eseguire l'operazione specificata. Questo parametro deve contenere un valore valido che non è NULL. L'utente è responsabile della convalida del valore. Se non viene convalidata, verranno visualizzati risultati imprevisti.
Valore restituito
Tipo: int
Restituisce zero se ha esito positivo; in caso contrario, diverso da zero. Le applicazioni normalmente devono semplicemente verificare la presenza di zero o diverso da zero.
È consigliabile esaminare il valore del membro fAnyOperationsAborted di SHFILEOPSTRUCT. SHFileOperation può restituire 0 per esito positivo se l'utente annulla l'operazione. Se non si controlla fAnyOperationsAborted e il valore restituito, non è possibile sapere che la funzione ha eseguito l'attività completa richiesta ed è possibile procedere con presupposti non corretti.
Non usare GetLastError con i valori restituiti di questa funzione.
Per esaminare i valori diversi da zero a scopo di risoluzione dei problemi, vengono in gran parte mappati a quelli definiti in Winerror.h. Tuttavia, molti dei possibili valori restituiti si basano su codici di errore pre-Win32, che in alcuni casi si sovrappongono ai valori Winerror.h successivi senza corrispondere al significato. Questi valori specifici sono descritti in dettaglio qui e solo per questi valori specifici devono essere accettati tramite i codici Winerror.h. Tuttavia, questi valori vengono forniti con questi avvisi:
- Si tratta di codici di errore pre-Win32 e non sono più supportati o definiti in alcun file di intestazione pubblica. Per usarli, è necessario definirli manualmente o confrontarli con il valore numerico.
- Questi codici di errore sono soggetti a modifiche e hanno sempre eseguito questa operazione.
- Questi valori vengono forniti solo come aiuto per il debug. Essi non dovrebbero essere considerati definitivi.
| Codice di errore | Valore | Significato |
|---|---|---|
| DE_SAMEFILE | 0x71 | I file di origine e di destinazione sono lo stesso file. |
| DE_MANYSRC1DEST | 0x72 | Nel buffer di origine sono stati specificati più percorsi di file, ma solo un percorso del file di destinazione. |
| DE_DIFFDIR | 0x73 | L'operazione di ridenominazione è stata specificata, ma il percorso di destinazione è una directory diversa. Usare invece l'operazione di spostamento. |
| DE_ROOTDIR | 0x74 | L'origine è una directory radice, che non può essere spostata o rinominata. |
| DE_OPCANCELLED | 0x75 | L'operazione è stata annullata dall'utente o annullata automaticamente se i flag appropriati sono stati forniti a SHFileOperation. |
| DE_DESTSUBTREE | 0x76 | La destinazione è un sottoalbero dell'origine. |
| DE_ACCESSDENIEDSRC | 0x78 | Impostazioni di sicurezza negate l'accesso all'origine. |
| DE_PATHTOODEEP | 0x79 | Il percorso di origine o di destinazione ha superato o supera MAX_PATH. |
| DE_MANYDEST | 0x7A | L'operazione ha coinvolto più percorsi di destinazione, che possono avere esito negativo nel caso di un'operazione di spostamento. |
| DE_INVALIDFILES | 0x7C | Percorso nell'origine o nella destinazione oppure entrambi non validi. |
| DE_DESTSAMETREE | 0x7D | L'origine e la destinazione hanno la stessa cartella padre. |
| DE_FLDDESTISFILE | 0x7E | Il percorso di destinazione è un file esistente. |
| DE_FILEDESTISFLD | 0x80 | Il percorso di destinazione è una cartella esistente. |
| DE_FILENAMETOOLONG | 0x81 | Il nome del file supera MAX_PATH. |
| DE_DEST_IS_CDROM | 0x82 | La destinazione è un CD-ROM di sola lettura, possibilmente non formattato. |
| DE_DEST_IS_DVD | 0x83 | La destinazione è un DVD di sola lettura, possibilmente non formattato. |
| DE_DEST_IS_CDRECORD | 0x84 | La destinazione è un CD-ROM scrivibile, possibilmente non formattato. |
| DE_FILE_TOO_LARGE | 0x85 | Il file coinvolto nell'operazione è troppo grande per il supporto o il file system di destinazione. |
| DE_SRC_IS_CDROM | 0x86 | L'origine è un CD-ROM di sola lettura, possibilmente non formattato. |
| DE_SRC_IS_DVD | 0x87 | L'origine è un DVD di sola lettura, possibilmente non formattato. |
| DE_SRC_IS_CDRECORD | 0x88 | L'origine è un CD-ROM scrivibile, possibilmente non formattato. |
| DE_ERROR_MAX | 0xB7 | MAX_PATH è stato superato durante l'operazione. |
| 0x402 | Si è verificato un errore sconosciuto. Ciò è in genere dovuto a un percorso non valido nell'origine o nella destinazione. Questo errore non si verifica in Windows Vista e versioni successive. | |
| ERRORONDEST | 0x10000 | Si è verificato un errore non specificato nella destinazione. |
| DE_ROOTDIR | ERRORONDEST | 0x10074 | La destinazione è una directory radice e non può essere rinominata. |
Commenti
È consigliabile usare nomi di percorso completi con questa funzione. L'uso con nomi di percorso relativi non è thread-safe.
Con due eccezioni, non è possibile usare SHFileOperation per spostare cartelle speciali da un'unità locale a un computer remoto specificando un percorso di rete. Le eccezioni sono le cartelle Documenti (CSIDL_PERSONAL, CSIDL_DOCUMENTS) e Immagini personali (CSIDL_MYPICTURES).
Se usato per eliminare un file, SHFileOperation elimina definitivamente il file a meno che non si imposti il flag FOF_ALLOWUNDO nel membro fFlags della struttura SHFILEOPSTRUCT a cui punta lpFileOpOp. Impostazione del flag che invia il file al Cestino. Se si vuole semplicemente eliminare un file e garantire che non sia inserito nel Cestino, usare DeleteFile.
Se viene esposto e registrato un gestore di callback di copia, SHFileOperation lo chiama a meno che non si imposti un flag, ad esempio FOF_NOCONFIRMATION nel membro fFlags della struttura a cui punta lpFileOp. Per informazioni dettagliate sull'implementazione dei gestori di callback di copia, vedere ICopyHook::CopyCallback .
L'eliminazione dei file è ricorsiva a meno che non si imposti il flag FOF_NORECURSION in lpFileOp.
Connessione di file
Con Windows 2000 o versione successiva, è possibile connettere un file HTML con una cartella contenente file correlati, ad esempio immagini GIF (Graphics Interchange Format) o fogli di stile. Se la connessione file è abilitata, quando si sposta o si copia il file HTML, anche la cartella connessa e tutti i relativi file vengono spostati o copiati. Viceversa, se si sposta la cartella con i file correlati, viene spostato anche il file HTML.Il file HTML deve avere un'estensione .htm o .html. Per creare la connessione ai file correlati, inserire la cartella che le contiene nella stessa cartella del file HTML. Il nome della cartella che contiene i file connessi deve essere uguale al nome del file HTML seguito da "_files" o ".files" (in questo caso viene fatta distinzione tra maiuscole e minuscole, ad esempio ". I file" non funzionano). Di seguito è riportato un esempio.
- Creare un file denominato Test.htm nella directory C:\Files (C:\Files\Test.htm).
- Creare una nuova cartella denominata Test.files nella directory C:\Files (C:\Files\Test.files).
- Popolare la cartella con alcuni file. Qualsiasi file inserito in questa cartella è connesso a Test.htm.
- Spostare o copiare il file Test.htm nella directory C:\Files2.
- Si noti che la directory Test.files è ora disponibile anche nella directory C:\Files2.
La connessione file è abilitata per impostazione predefinita. Può essere disabilitato aggiungendo una voce REG_DWORD , NoFileFolderConnection, come illustrato di seguito:
HKEY_CURRENT_USER Software Microsoft Windows CurrentVersion Explorer NoFileFolderConnection
L'impostazione di NoFileFolderConnection su 1 disabilita la connessione file. Se il valore è impostato su zero o è mancante, la connessione file è abilitata.
Per spostare solo i file specificati e nessuno dei file connessi, impostare il flag FOF_NO_CONNECTED_ELEMENTS nel membro fFlags della struttura a cui punta lpFileOp.
Si noti che l'uso di una cartella con un nome come "MyFile_files" per definire una connessione potrebbe non essere valido per le versioni localizzate di Windows. Il termine "files" potrebbe essere necessario sostituire con la parola equivalente nella lingua locale.
Nota
L'intestazione shellapi.h definisce SHFileOperation 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 che non è indipendente dalla codifica può causare mancate corrispondenze che generano errori di compilazione o di runtime. Per altre informazioni, vedere Convenzioni per i prototipi di funzioni.
Requisiti
| Requisito | Valore |
|---|---|
| Client minimo supportato | Windows XP [solo app desktop] |
| Server minimo supportato | Windows 2000 Server [solo app desktop] |
| Piattaforma di destinazione | Windows |
| Intestazione | shellapi.h |
| Libreria | Shell32.lib |
| DLL | Shell32.dll (versione 4.0 o successiva) |
| Set di API | ext-ms-win-shell-shell32-l1-2-1 (introdotto in Windows 10, versione 10.0.10240) |