Estrutura SHFILEOPSTRUCTW (shellapi.h)

Contém informações que a função SHFileOperation usa para executar operações de arquivo.

Sintaxe

typedef struct _SHFILEOPSTRUCTW {
  HWND         hwnd;
  UINT         wFunc;
  PCZZWSTR     pFrom;
  PCZZWSTR     pTo;
  FILEOP_FLAGS fFlags;
  BOOL         fAnyOperationsAborted;
  LPVOID       hNameMappings;
  PCWSTR       lpszProgressTitle;
} SHFILEOPSTRUCTW, *LPSHFILEOPSTRUCTW;

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 retorna, esse membro contém TRUE se alguma operação de arquivo foi 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 diretório e unidade atual global, 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 para 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 confiado 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 é de 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 estiver 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 LPCSTR (cadeias de caracteres ANSI). 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.

Requisitos