Estrutura SHFILEOPSTRUCTA (shellapi.h)
Contém informações que a função SHFileOperation usa para executar operações de arquivo.
Sintaxe
typedef struct _SHFILEOPSTRUCTA {
HWND hwnd;
UINT wFunc;
PCZZSTR pFrom;
PCZZSTR pTo;
FILEOP_FLAGS fFlags;
BOOL fAnyOperationsAborted;
LPVOID hNameMappings;
PCSTR lpszProgressTitle;
} SHFILEOPSTRUCTA, *LPSHFILEOPSTRUCTA;
Membros
hwnd
Digite: HWND
Um identificador de janela para a caixa de diálogo para exibir informações sobre o status da operação de arquivo.
wFunc
Tipo: UINT
Um valor que indica qual operação executar. Um dos seguintes valores:
FO_COPY
Copie os arquivos especificados no membro pFrom para o local especificado no membro pTo .
FO_DELETE
Exclua os arquivos especificados em pFrom.
FO_MOVE
Mova os arquivos especificados em pFrom para o local especificado em pTo.
FO_RENAME
Renomeie o arquivo especificado em pFrom. Não é possível usar esse sinalizador para renomear vários arquivos com uma única chamada de função. Em vez disso , use FO_MOVE .
pFrom
Tipo: PCZZTSTR
Caracteres curinga MS-DOS padrão, como "*", são permitidos apenas na posição nome do arquivo. O uso de um caractere curinga em outro lugar na cadeia de caracteres levará a resultados imprevisíveis.
Embora esse membro seja declarado como uma única cadeia de caracteres terminada em nulo, na verdade, é um buffer que pode conter vários nomes de arquivo delimitados por nulo. Cada nome de arquivo é encerrado por um único caractere NULL . O sobrenome do arquivo é encerrado com um caractere NULL duplo ("\0\0") para indicar o final do buffer.
pTo
Tipo: PCZZTSTR
Assim como pFrom, o membro pTo também é uma cadeia de caracteres terminada em nulo duplo e é tratado da mesma maneira. No entanto, o pTo deve atender às seguintes especificações:
- Não há suporte para caracteres curinga.
- As operações Copiar e Mover podem especificar diretórios de destino que não existem. Nesses casos, o sistema tenta criá-los e normalmente exibe uma caixa de diálogo para perguntar ao usuário se ele deseja criar o novo diretório. Para suprimir essa caixa de diálogo e criar os diretórios silenciosamente, defina o sinalizador FOF_NOCONFIRMMKDIR em fFlags.
- Para operações de Cópia e Movimentação, o buffer poderá conter vários nomes de arquivo de destino se o membro fFlagsespecificar FOF_MULTIDESTFILES.
- Empacote vários nomes na cadeia de caracteres pTo da mesma forma que para pFrom.
- Use caminhos totalmente qualificados. O uso de caminhos relativos não é proibido, mas pode ter resultados imprevisíveis.
fFlags
Tipo: FILEOP_FLAGS
Sinalizadores que controlam a operação de arquivo. Esse membro pode obter uma combinação dos sinalizadores a seguir.
FOF_ALLOWUNDO
Preservar informações de desfazer, se possível.
Antes do Windows Vista, as operações podiam ser desfeitas somente do mesmo processo que executava a operação original.
No Windows Vista e em sistemas posteriores, o escopo da desfazer é uma sessão de usuário. Qualquer processo em execução na sessão do usuário pode desfazer outra operação. O estado de desfazer é mantido no processo de Explorer.exe e, enquanto esse processo estiver em execução, ele poderá coordenar as funções de desfazer.
Se o parâmetro de arquivo de origem não contiver nomes de arquivo e caminho totalmente qualificados, esse sinalizador será ignorado.
FOF_CONFIRMMOUSE
Não usado.
FOF_FILESONLY
Execute a operação somente em arquivos (não em pastas) se um nome de arquivo curinga (.) for especificado.
FOF_MULTIDESTFILES
O membro pTo especifica vários arquivos de destino (um para cada arquivo de origem no pFrom) em vez de um diretório em que todos os arquivos de origem devem ser depositados.
FOF_NOCONFIRMATION
Responda com Sim a Todos para qualquer caixa de diálogo exibida.
FOF_NOCONFIRMMKDIR
Não peça ao usuário para confirmar a criação de um novo diretório se a operação exigir que um seja criado.
FOF_NO_CONNECTED_ELEMENTS
Versão 5.0. Não mova arquivos conectados como um grupo. Mova apenas os arquivos especificados.
FOF_NOCOPYSECURITYATTRIBS
Versão 4.71. Não copie os atributos de segurança do arquivo. O arquivo de destino recebe os atributos de segurança de sua nova pasta.
FOF_NOERRORUI
Não exiba uma caixa de diálogo para o usuário se ocorrer um erro.
FOF_NORECURSEREPARSE
Não usado.
FOF_NORECURSION
Execute apenas a operação no diretório local. Não opere recursivamente em subdiretórios, que é o comportamento padrão.
FOF_NO_UI
Windows Vista. Execute a operação silenciosamente, não apresentando nenhuma interface do usuário para o usuário. Isso é equivalente a FOF_SILENT | FOF_NOCONFIRMATION | FOF_NOERRORUI | FOF_NOCONFIRMMKDIR.
FOF_RENAMEONCOLLISION
Dê ao arquivo que está sendo operado um novo nome em uma operação de movimentação, cópia ou renomeação se um arquivo com o nome de destino já existir no destino.
FOF_SILENT
Não exiba uma caixa de diálogo de progresso.
FOF_SIMPLEPROGRESS
Exibir uma caixa de diálogo de progresso, mas não mostrar nomes de arquivo individuais conforme eles são operados.
FOF_WANTMAPPINGHANDLE
Se FOF_RENAMEONCOLLISION for especificado e todos os arquivos forem renomeados, atribua um objeto de mapeamento de nome que contenha seus nomes antigos e novos ao membro hNameMappings . Esse objeto deve ser liberado usando SHFreeNameMappings quando não for mais necessário.
FOF_WANTNUKEWARNING
Versão 5.0. Envie um aviso se um arquivo estiver sendo destruído permanentemente durante uma operação de exclusão em vez de reciclado. Esse sinalizador substitui parcialmente FOF_NOCONFIRMATION.
fAnyOperationsAborted
Tipo: BOOL
Quando a função retornar, esse membro conterá TRUE se alguma operação de arquivo tiver sido anulada antes de serem concluídas; caso contrário, FALSE. Uma operação pode ser anulada manualmente pelo usuário por meio da interface do usuário ou pode ser anulada silenciosamente pelo sistema se os sinalizadores FOF_NOERRORUI ou FOF_NOCONFIRMATION foram definidos.
hNameMappings
Tipo: LPVOID
Quando a função retorna, esse membro contém um identificador para um objeto de mapeamento de nome que contém os nomes antigos e novos dos arquivos renomeados. Esse membro será usado somente se o membro fFlags incluir o sinalizador FOF_WANTMAPPINGHANDLE . Consulte Comentários para obter mais detalhes.
lpszProgressTitle
Tipo: PCTSTR
Um ponteiro para o título de uma caixa de diálogo de progresso. Essa é uma cadeia de caracteres terminada em nulo. Esse membro será usado somente se fFlags incluir o sinalizador FOF_SIMPLEPROGRESS .
Comentários
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";
// RIGHT
LPTSTR pszSource = L"C:\\Windows\\*\0";
Para considerar os dois caracteres nulos de terminação, crie buffers grandes o suficiente para manter MAX_PATH (que normalmente inclui o caractere nulo de terminação única) mais 1.
Não é possível exagerar que seus caminhos sempre devem ser caminhos completos. Se os membros pFrom ou pTo forem nomes não qualificados, os diretórios atuais serão retirados das configurações de unidade e diretório atuais globais, conforme gerenciado pelas funções GetCurrentDirectory e SetCurrentDirectory .
Se você não fornecer um caminho completo, os seguintes fatos se tornarão pertinentes:
- A falta de um caminho antes de um nome de arquivo não indica a SHFileOperation que esse arquivo reside na raiz do diretório atual.
- A variável de ambiente PATH não é usada por SHFileOperation para determinar um caminho válido.
- SHFileOperation não pode ser usado para usar o diretório que é o diretório atual quando ele começa a ser executado. O diretório visto como o diretório atual é em todo o processo e pode ser alterado de outro thread enquanto a operação está em execução. Se isso acontecesse, os resultados de SHFileOperation seriam imprevisíveis.
Se pFrom for definido como um nome de arquivo sem um caminho completo, excluir o arquivo com FO_DELETE não o moverá para a Lixeira, mesmo que o sinalizador FOF_ALLOWUNDO esteja definido. Você deve fornecer um caminho completo para excluir o arquivo para a Lixeira.
SHFileOperation falha em qualquer caminho prefixado com "\?".
Há duas versões dessa estrutura, uma versão ANSI (SHFILEOPSTRUCTA) e uma versão Unicode (SHFILEOPSTRUCTW). A versão Unicode é idêntica à versão ANSI, exceto que as cadeias de caracteres largos (LPCWSTR) são usadas no lugar de cadeias de caracteres ANSI (LPCSTR). No Windows 98 e anteriores, há suporte apenas para a versão ANSI. No Microsoft Windows NT 4.0 e posterior, há suporte para as versões ANSI e Unicode dessa estrutura. SHFILEOPSTRUCTW e SHFILEOPTSTRUCTA nunca devem ser usados diretamente; a estrutura apropriada é redefinida como SHFILEOPSTRUCT pelo pré-compilador, dependendo se o aplicativo é compilado para ANSI ou Unicode.
SHNAMEMAPPING tem versões ANSI e Unicode semelhantes. Para aplicativos ANSI, hNameMappings aponta para um int seguido por uma matriz de estruturas ANSI SHNAMEMAPPING . Para aplicativos Unicode, hNameMappings aponta para um int seguido por uma matriz de estruturas SHNAMEMAPPING Unicode. No entanto, no Microsoft Windows NT 4.0 e posterior, SHFileOperationsempre retorna um identificador para um conjunto Unicode de estruturas SHNAMEMAPPING . Se você quiser que os aplicativos sejam funcionais com todas as versões do Windows, o aplicativo deverá empregar código condicional para lidar com mapeamentos de nomes. Por exemplo:
x = SHFileOperation(&shop);
if (fWin9x)
HandleAnsiNameMappings(shop.hNameMappings);
else
HandleUnicodeNameMappings(shop.hNameMappings);
Trate hNameMappings como um ponteiro para uma estrutura cujos membros são um valor UINT seguido por um ponteiro para uma matriz de estruturas SHNAMEMAPPING , como visto em sua declaração:
struct HANDLETOMAPPINGS
{
UINT uNumberOfMappings; // Number of mappings in the array.
LPSHNAMEMAPPING lpSHNameMapping; // Pointer to the array of mappings.
};
O valor UINT indica o número de estruturas SHNAMEMAPPING na matriz. Cada estrutura SHNAMEMAPPING contém o caminho antigo e novo para um dos arquivos renomeados.
Observação
O cabeçalho shellapi.h define SHFILEOPSTRUCT como um alias que seleciona automaticamente a versão ANSI ou Unicode dessa função com base na definição da constante de pré-processador UNICODE. Misturar o uso do alias neutro de codificação com código que não seja neutro em codificação pode levar a incompatibilidades que resultam em erros de compilação ou de runtime. Para obter mais informações, consulte Convenções para protótipos de função.
Requisitos
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows 2000 Server [somente aplicativos da área de trabalho] |
| Cabeçalho | shellapi.h |
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de