Struttura SHFILEOPSTRUCTA (shellapi.h)

Contiene informazioni utilizzate dalla funzione SHFileOperation per eseguire operazioni sui file.

Sintassi

typedef struct _SHFILEOPSTRUCTA {
  HWND         hwnd;
  UINT         wFunc;
  PCZZSTR      pFrom;
  PCZZSTR      pTo;
  FILEOP_FLAGS fFlags;
  BOOL         fAnyOperationsAborted;
  LPVOID       hNameMappings;
  PCSTR        lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;

Membri

hwnd

Tipo: HWND

Handle di finestra per la finestra di dialogo per visualizzare informazioni sullo stato dell'operazione file.

wFunc

Tipo: UINT

Valore che indica l'operazione da eseguire. Uno dei valori seguenti:

FO_COPY

Copiare i file specificati nel membro pFrom nel percorso specificato nel membro pTo.

FO_DELETE

Eliminare i file specificati in pFrom.

FO_MOVE

Spostare i file specificati in pFrom nel percorso specificato in pTo.

FO_RENAME

Rinominare il file specificato in pFrom. Non è possibile usare questo flag per rinominare più file con una singola chiamata di funzione. Usare invece FO_MOVE.

pFrom

Tipo: PCZZTSTR

I caratteri jolly standard MS-DOS, ad esempio "*", sono consentiti solo nella posizione del nome file. L'uso di un carattere jolly altrove nella stringa determinerà risultati imprevedibili.

Anche se questo membro viene dichiarato come una singola stringa con terminazione Null, è in realtà un buffer che può contenere più nomi di file delimitati da null. Ogni nome di file viene terminato da un singolo carattere NULL. L'ultimo nome file viene terminato con un doppio carattere NULL ("\0\0") per indicare la fine del buffer.

pTo

Tipo: PCZZTSTR

Come pFrom, il membro pTo è anche una stringa con terminazione double-null e viene gestito in modo analogo. Tuttavia, pTo deve soddisfare le specifiche seguenti:

• I caratteri jolly non sono supportati.
• Le operazioni copia e spostamento possono specificare directory di destinazione che non esistono. In questi casi, il sistema tenta di crearli e in genere visualizza una finestra di dialogo per chiedere all'utente se vuole creare la nuova directory. Per eliminare questa finestra di dialogo e impostare automaticamente le directory, impostare il flag di FOF_NOCONFIRMMKDIR in fFlags.
• Per le operazioni di copia e spostamento, il buffer può contenere più nomi di file di destinazione se il membro fFlags specifica FOF_MULTIDESTFILES.
• Comprimere più nomi nella stringa pTo allo stesso modo di pFrom.
• Usare percorsi completi. L'uso di percorsi relativi non è consentito, ma può avere risultati imprevedibili.

fFlags

Tipo: FILEOP_FLAGS

Flag che controllano l'operazione di file. Questo membro può accettare una combinazione dei flag seguenti.

FOF_ALLOWUNDO

Conservare le informazioni di annullamento, se possibile.

Prima di Windows Vista, le operazioni potrebbero essere annullate solo dallo stesso processo che ha eseguito l'operazione originale.

In Windows Vista e nei sistemi successivi l'ambito dell'annullamento è una sessione utente. Qualsiasi processo in esecuzione nella sessione utente può annullare un'altra operazione. Lo stato di annullamento viene mantenuto nel processo di Explorer.exe e, purché il processo sia in esecuzione, può coordinare le funzioni di annullamento.

Se il parametro del file di origine non contiene nomi di file e percorsi completi, questo flag viene ignorato.

FOF_CONFIRMMOUSE

Non utilizzato.

FOF_FILESONLY

Eseguire l'operazione solo sui file (non nelle cartelle) se viene specificato un nome di file con caratteri jolly (.).

FOF_MULTIDESTFILES

Il membro pTo specifica più file di destinazione (uno per ogni file di origine in pFrom) anziché una directory in cui devono essere scaricati tutti i file di origine.

FOF_NOCONFIRMATION

Rispondere con Sì a tutti i per qualsiasi finestra di dialogo visualizzata.

FOF_NOCONFIRMMKDIR

Non chiedere all'utente di confermare la creazione di una nuova directory se l'operazione ne richiede la creazione.

FOF_NO_CONNECTED_ELEMENTS

Versione 5.0. Non spostare i file connessi come gruppo. Spostare solo i file specificati.

FOF_NOCOPYSECURITYATTRIBS

Versione 4.71. Non copiare gli attributi di sicurezza del file. Il file di destinazione riceve gli attributi di sicurezza della nuova cartella.

FOF_NOERRORUI

Non visualizzare una finestra di dialogo all'utente se si verifica un errore.

FOF_NORECURSEREPARSE

Non utilizzato.

FOF_NORECURSION

Eseguire l'operazione solo nella directory locale. Non operare in modo ricorsivo in sottodirectory, ovvero il comportamento predefinito.

FOF_NO_UI

Windows Vista. Eseguire l'operazione in modo invisibile all'utente, senza presentare alcuna interfaccia utente. Equivale a FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.

FOF_RENAMEONCOLLISION

Assegnare al file un nuovo nome in un'operazione di spostamento, copia o ridenominazione se esiste già un file con il nome di destinazione nella destinazione.

FOF_SILENT

Non visualizzare una finestra di dialogo di stato.

FOF_SIMPLEPROGRESS

Visualizzare una finestra di dialogo di stato, ma non visualizzare i singoli nomi di file mentre vengono gestiti.

FOF_WANTMAPPINGHANDLE

Se viene specificato FOF_RENAMEONCOLLISION e tutti i file sono stati rinominati, assegnare un oggetto mapping dei nomi contenente i nomi precedenti e nuovi al membro hNameMappings. Questo oggetto deve essere liberato usando SHFreeNameMappings quando non è più necessario.

FOF_WANTNUKEWARNING

Versione 5.0. Inviare un avviso se un file viene eliminato definitivamente durante un'operazione di eliminazione anziché riciclato. Questo flag esegue parzialmente l'override di FOF_NOCONFIRMATION.

fAnyOperationsAborted

Tipo: bool

Quando la funzione viene restituita, questo membro contiene TRUE se eventuali operazioni sui file sono state interrotte prima del completamento; in caso contrario, FALSE. Un'operazione può essere interrotta manualmente dall'utente tramite l'interfaccia utente oppure può essere interrotta automaticamente dal sistema se i flag FOF_NOERRORUI o FOF_NOCONFIRMATION sono stati impostati.

hNameMappings

Tipo: LPVOID

Quando la funzione viene restituita, questo membro contiene un handle per un oggetto di mapping dei nomi che contiene i nomi precedenti e nuovi dei file rinominati. Questo membro viene utilizzato solo se il membro fFlags include il flag FOF_WANTMAPPINGHANDLE. Per altri dettagli, vedere La sezione Osservazioni.

lpszProgressTitle

Tipo: PCTSTR

Puntatore al titolo di una finestra di dialogo di stato. Si tratta di una stringa con terminazione Null. Questo membro viene utilizzato solo se fFlags include il flag FOF_SIMPLEPROGRESS.

Osservazioni

// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";

Per tenere conto dei due caratteri Null terminanti, assicurarsi di creare buffer sufficientemente grandi da contenere MAX_PATH (che in genere include il singolo carattere Null di terminazione) più 1.

Non è possibile notare che i percorsi devono essere sempre percorsi completi. Se i membri pFrom o pTo sono nomi non qualificati, le directory correnti vengono ricavate dall'unità corrente globale e dalle impostazioni della directory come gestite dal GetCurrentDirectory e funzioni SetCurrentDirectory.

Se non si specifica un percorso completo, i fatti seguenti diventano pertinenti:

• La mancanza di un percorso prima di un nome file non indica di SHFileOperation che questo file risiede nella radice della directory corrente.
• La variabile di ambiente PATH non viene usata da SHFileOperation per determinare un percorso valido.
• SHFileOperation non può essere utilizzato per usare la directory corrente quando inizia l'esecuzione. La directory visualizzata come la directory corrente è a livello di processo e può essere modificata da un altro thread durante l'esecuzione dell'operazione. Se ciò dovesse accadere, i risultati di SHFileOperation sarebbero imprevedibili.

Se pFrom è impostato su un nome file senza un percorso completo, l'eliminazione del file con FO_DELETE non lo sposta nel Cestino, anche se è impostato il flag FOF_ALLOWUNDO. È necessario specificare un percorso completo per eliminare il file nel Cestino.

SHFileOperation ha esito negativo in qualsiasi percorso preceduto da "\?".

Esistono due versioni di questa struttura, una versione ANSI (SHFILEOPSTRUCTA) e una versione Unicode (SHFILEOPSTRUCTW). La versione Unicode è identica alla versione ANSI, ad eccezione del fatto che le stringhe di caratteri wide (LPCWSTR) vengono usate al posto delle stringhe di caratteri ANSI (LPCSTR). In Windows 98 e versioni precedenti è supportata solo la versione ANSI. In Microsoft Windows NT 4.0 e versioni successive sono supportate sia le versioni ANSI che Unicode di questa struttura. SHFILEOPSTRUCTW e SHFILEOPTSTRUCTA non devono mai essere usati direttamente; la struttura appropriata viene ridefinita come SHFILEOPSTRUCT dal precompiler a seconda che l'applicazione sia compilata per ANSI o Unicode.

SHNAMEMAPPING include versioni ANSI e Unicode simili. Per le applicazioni ANSI, hNameMappings punta a un int seguito da una matrice di strutture SHNAMEMAPPING. Per le applicazioni Unicode, hNameMappings punta a un int seguito da una matrice di strutture unicode SHNAMEMAPPING. Tuttavia, in Microsoft Windows NT 4.0 e versioni successive, SHFileOperationsempre restituisce un handle a un set Unicode di strutture SHNAMEMAPPING. Se si vuole che le applicazioni funzionino con tutte le versioni di Windows, l'applicazione deve usare il codice condizionale per gestire i mapping dei nomi. Per esempio:

x = SHFileOperation(&shop);

if (fWin9x) 
    HandleAnsiNameMappings(shop.hNameMappings);
else 
    HandleUnicodeNameMappings(shop.hNameMappings);

Considerare hNameMappings come puntatore a una struttura i cui membri sono un valore UINT seguito da un puntatore a una matrice di strutture SHNAMEMAPPING, come illustrato nella dichiarazione:

struct HANDLETOMAPPINGS 
{
    UINT              uNumberOfMappings;  // Number of mappings in the array.
    LPSHNAMEMAPPING   lpSHNameMapping;    // Pointer to the array of mappings.
};

Il valore UINT indica il numero di strutture SHNAMEMAPPING nella matrice. Ogni struttura SHNAMEMAPPING contiene il percorso precedente e nuovo per uno dei file rinominati.

Fabbisogno