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.

  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 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)