Compartilhar via

Estrutura SHFILEOPSTRUCTA (shellapi.h)

  • Artigo

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

Observação A partir do Windows Vista, o uso da interface IFileOperation é recomendado sobre essa função.
 

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

Tipo: 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 deve ser executada. 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. Você não pode usar esse sinalizador para renomear vários arquivos com uma única chamada de função. Em vez disso, use FO_MOVE.

pFrom

Tipo: PCZZTSTR

Observação Essa cadeia de caracteres deve ser terminada em nulo duplo.
 
Um ponteiro para um ou mais nomes de arquivo de origem. Esses nomes devem ser caminhos totalmente qualificados para evitar resultados inesperados.

Caracteres curinga de MS-DOS padrão, como "*", são permitidos apenas na posição nome do arquivo. Usar um caractere curinga em outro lugar da 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 de NULL . O nome do último arquivo é encerrado com um caractere nulo de nulo duplo ("\0\0") para indicar o final do buffer.

pTo

Tipo: PCZZTSTR

Observação Essa cadeia de caracteres deve ser terminada em nulo duplo.
 
Um ponteiro para o arquivo de destino ou o nome do diretório. Esse parâmetro deve ser definido como NULL se ele não for usado. Caracteres curinga não são permitidos. Seu uso levará a resultados imprevisíveis.

Como pFrom, o membro pTo também é uma cadeia de caracteres terminada de nulo duplo e é tratado da mesma maneira. No entanto, 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 do fFlags especificar 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 ter uma combinação dos sinalizadores a seguir.

FOF_ALLOWUNDO

Preservar informações de desfazer, se possível.

Antes do Windows Vista, as operações só podiam ser desfeitas do mesmo processo que executou 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 em pFrom) em vez de um diretório em que todos os arquivos de origem devem ser depositados.

FOF_NOCONFIRMATION

Responda com Sim para Todos os 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

Forneça o arquivo que está sendo operado em um novo nome em uma operação de movimentação, cópia ou renomeação se já existir um arquivo com o nome de destino no destino.

FOF_SILENT

Não exiba uma caixa de diálogo de progresso.

FOF_SIMPLEPROGRESS

Exiba uma caixa de diálogo de progresso, mas não mostre nomes de arquivo individuais enquanto 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 hNameMappings membro. Esse objeto deve ser liberado usando SHFreeNameMappings quando ele 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 VERDADEIRO se quaisquer operações de arquivo foram anuladas 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.

Observações

Importante Você deve garantir que os caminhos de origem e de destino sejam encerrados com valor duplo nulo. Uma cadeia de caracteres normal termina em apenas um único caractere nulo. Se você passar esse valor nos membros de origem ou destino, a função não perceberá quando chegar ao final da cadeia de caracteres e continuará a ser lida na memória até chegar a um valor nulo duplo aleatório. Isso pode, pelo menos, levar a uma sobrecarga de buffer e, possivelmente, à exclusão não intencional de dados não relacionados.
 
// WRONG
LPTSTR pszSource = L"C:\\Windows\\*";

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

Para considerar os dois caracteres nulos que terminam, 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 globais de diretório e unidade atual, 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 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 confiada 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 de 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 cadeias de caracteres largas (LPCWSTR) são usadas no lugar de cadeias de caracteres ANSI (LPCSTR). No Windows 98 e anterior, 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 de SHNAMEMAPPING ANSI. Para aplicativos Unicode, hNameMappings aponta para um de int seguido por uma matriz de estruturas de SHNAMEMAPPING Unicode. No entanto, no Microsoft Windows NT 4.0 e posterior, SHFileOperationsempre retorna um identificador para um conjunto Unicode de estruturas de 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 de 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 de SHNAMEMAPPING na matriz. Cada estrutura SHNAMEMAPPING contém o caminho antigo e novo para um dos arquivos renomeados.

Observação O identificador deve ser liberado com SHFreeNameMappings.
 

Nota

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 do 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 Conventions for Function Prototypes.

Requisitos

Requisito Valor
de cliente com suporte mínimo Windows XP [somente aplicativos da área de trabalho]
servidor com suporte mínimo Windows 2000 Server [somente aplicativos da área de trabalho]
cabeçalho shellapi.h