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 (CSIDL_PERSONAL, CSIDL_DOCUMENTS) e cartelle immagini personali (CSIDL_MYPICTURES).

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.

1. Creare un file denominato Test.htm nella directory C:\Files (C:\Files\Test.htm).
2. Creare una nuova cartella denominata Test.files nella directory C:\Files (C:\Files\Test.files).
3. Popolare la cartella con alcuni file. Qualsiasi file inserito in questa cartella è connesso a Test.htm.
4. Spostare o copiare il file Test.htm nella directory C:\Files2.
5. 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.

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)