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 convalidato, si riscontreranno 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 del 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 e si potrebbe 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 loro significato. Questi valori specifici sono descritti in dettaglio qui e solo per questi valori specifici questi significati devono essere accettati sui 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 usarle, è necessario definirle manualmente o confrontarle con il valore numerico.
- Questi codici di errore sono soggetti a modifiche e hanno storicamente fatto.
- Questi valori vengono forniti solo come supporto per il debug. Non dovrebbero essere considerati definitivi.
| Codice 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 di 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 è stato 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 file system o il supporto 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. Questo è 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 | Errore non specificato nella destinazione. |
| DE_ROOTDIR | ERRORONDEST | 0x10074 | La destinazione è una directory radice e non può essere rinominata. |
Osservazioni
È consigliabile usare nomi di percorso completi con questa funzione. L'uso con nomi di percorso relativi non è thread-safe.
Con due eccezioni, non è possibile utilizzare SHFileOperation per spostare cartelle speciali da un'unità locale a un computer remoto specificando un percorso di rete. Le eccezioni sono le cartelle documenti
Se usato per eliminare un file, SHFileOperation elimina definitivamente il file a meno che non si imposti il flag di FOF_ALLOWUNDO nel fFlags membro della struttura SHFILEOPSTRUCT a cui punta lpFileOp. L'impostazione del flag invia il file al Cestino. Se si desidera eliminare semplicemente un file e assicurarsi 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 come FOF_NOCONFIRMATION nel membro della struttura a cui punta lpFileOp. Per informazioni dettagliate sull'implementazione dei gestori di callback di copia, vedere ICopyHook::CopyCallback.
L'eliminazione di file è ricorsiva a meno che non si imposti il flag di 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. Creare la connessione ai file correlati inserendo la cartella che li 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 di 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 di FOF_NO_CONNECTED_ELEMENTS nel fFlags membro 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" può essere sostituito dalla 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 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 XP [solo app desktop] |
| server minimo supportato | Windows 2000 Server [solo app desktop] |
| piattaforma di destinazione | Finestre |
| 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) |