Struttura SHFILEOPSTRUCTA (shellapi.h)

Articolo
03/15/2023

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

Nota A partire da Windows Vista, l'uso dell'interfaccia IFileOperation è consigliato per questa funzione.

Sintassi

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

Members

hwnd

Tipo: HWND

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

wFunc

Tipo: UINT

Valore che indica quale operazione 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

Nota Questa stringa deve essere con terminazione double-null.

Puntatore a uno o più nomi di file di origine. Questi nomi devono essere percorsi completi per evitare risultati imprevisti.

I caratteri jolly MS-DOS standard, 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 file viene terminato da un singolo carattere NULL . L'ultimo nome file viene terminato con un carattere NULL doppio ("\0\0") per indicare la fine del buffer.

pTo

Tipo: PCZZTSTR

Nota Questa stringa deve essere con terminazione double-null.

Puntatore al nome del file o della directory di destinazione. Questo parametro deve essere impostato su NULL se non viene utilizzato. I caratteri jolly non sono consentiti. Il loro uso porterà a risultati imprevedibili.

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

I caratteri jolly non sono supportati.
Le operazioni di 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 creare automaticamente le directory, impostare il flag 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 nello 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 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.

Nei sistemi Windows Vista e versioni successive 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é tale 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 usato.

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 archiviati tutti i file di origine.

FOF_NOCONFIRMATION

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

FOF_NOCONFIRMMKDIR

Non chiedere all'utente di confermare la creazione di una nuova directory se è necessario crearne uno.

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 usato.

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, presentando nessuna 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 quando 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 sostituisce parzialmente FOF_NOCONFIRMATION.

fAnyOperationsAborted

Tipo: BOOL

Al termine della funzione, questo membro contiene TRUE se le 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 sono stati impostati i flag FOF_NOERRORUI o FOF_NOCONFIRMATION.

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. Stringa con terminazione Null. Questo membro viene usato solo se fFlags include il flag FOF_SIMPLEPROGRESS .

Commenti

Importante È necessario assicurarsi che i percorsi di origine e di destinazione siano terminati a doppio valore Null. Una stringa normale termina con un solo carattere Null. Se si passa tale valore nei membri di origine o di destinazione, la funzione non si rende conto quando ha raggiunto la fine della stringa e continuerà a leggere in memoria fino a quando non si tratta di un valore Null double casuale. Ciò può comportare almeno un sovraccarico del buffer ed eventualmente l'eliminazione involontaria di dati non correlati.

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

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

Per tenere conto dei due caratteri Null di terminazione, assicurarsi di creare buffer di grandi dimensioni sufficienti per 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 dalle funzioni GetCurrentDirectory e SetCurrentDirectory .

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

La mancanza di un percorso prima di un nome file non indica a 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.
Non è possibile fare affidamento su SHFileOperation per usare la directory corrente quando inizia l'esecuzione. La directory considerata come la directory corrente è a livello di processo e può essere modificata da un altro thread durante l'esecuzione dell'operazione. In tal caso, 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 il flag FOF_ALLOWUNDO è impostato. È 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 ha versioni ANSI e Unicode simili. Per le applicazioni ANSI, hNameMappings punta a un valore int seguito da una matrice di strutture ANSI 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, SHFileOperation restituisce sempre 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. Ad 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.

Nota L'handle deve essere liberato con SHFreeNameMappings.

Nota

L'intestazione shellapi.h definisce SHFILEOPSTRUCT 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


Client minimo supportato	Windows XP [solo app desktop]
Server minimo supportato	Windows 2000 Server [solo app desktop]
Intestazione	shellapi.h