Compartilhar via

Função SHFileOperationA (shellapi.h)

  • Artigo

Copia, move, renomeia ou exclui um objeto do sistema de arquivos. Essa função foi substituída no Windows Vista por IFileOperation.

Sintaxe

int SHFileOperationA(
  [in, out] LPSHFILEOPSTRUCTA lpFileOp
);

Parâmetros

[in, out] lpFileOp

Tipo: LPSHFILEOPSTRUCT

Um ponteiro para uma estrutura SHFILEOPSTRUCT que contém informações de que essa função precisa para realizar a operação especificada. Esse parâmetro deve conter um valor válido que não seja NULL. Você é responsável por validar o valor. Se você não validá-lo, você experimentará resultados inesperados.

Valor de retorno

Tipo: int

Retorna zero se bem-sucedido; caso contrário, não zero. Normalmente, os aplicativos devem simplesmente verificar se há zero ou diferente de zero.

É uma boa prática examinar o valor do membro fAnyOperationsAborted do SHFILEOPSTRUCT. SHFileOperation pode retornar 0 para êxito se o usuário cancelar a operação. Se você não verificar fAnyOperationsAborted, bem como o valor retornado, não poderá saber se a função realizou a tarefa completa solicitada e poderá continuar sob suposições incorretas.

Não use GetLastError com os valores retornados dessa função.

Para examinar os valores não zero para fins de solução de problemas, eles são mapeados em grande parte para aqueles definidos em Winerror.h. No entanto, vários de seus possíveis valores retornados são baseados em códigos de erro pré-Win32, que em alguns casos se sobrepõem aos valores winerror.h posteriores sem corresponder ao seu significado. Esses valores específicos são detalhados aqui e para esses valores específicos apenas esses significados devem ser aceitos nos códigos Winerror.h. No entanto, esses valores são fornecidos com estes avisos:

  • Estes são códigos de erro pré-Win32 e não têm mais suporte ou são definidos em nenhum arquivo de cabeçalho público. Para usá-las, você deve defini-las por conta própria ou comparar com o valor numérico.
  • Esses códigos de erro estão sujeitos a alterações e historicamente o fizeram.
  • Esses valores são fornecidos apenas como um auxílio na depuração. Eles não devem ser considerados definitivos.
Código de erro Valor Significado
DE_SAMEFILE 0x71 Os arquivos de origem e de destino são o mesmo arquivo.
DE_MANYSRC1DEST 0x72 Vários caminhos de arquivo foram especificados no buffer de origem, mas apenas um caminho de arquivo de destino.
DE_DIFFDIR 0x73 A operação de renomeação foi especificada, mas o caminho de destino é um diretório diferente. Em vez disso, use a operação de movimentação.
DE_ROOTDIR 0x74 A origem é um diretório raiz, que não pode ser movido ou renomeado.
DE_OPCANCELLED 0x75 A operação foi cancelada pelo usuário ou cancelada silenciosamente se os sinalizadores apropriados foram fornecidos para SHFileOperation.
DE_DESTSUBTREE 0x76 O destino é uma subárvore da origem.
DE_ACCESSDENIEDSRC 0x78 As configurações de segurança negaram acesso à origem.
DE_PATHTOODEEP 0x79 O caminho de origem ou destino excedeu ou excederia MAX_PATH.
DE_MANYDEST 0x7A A operação envolveu vários caminhos de destino, que podem falhar no caso de uma operação de movimentação.
DE_INVALIDFILES 0x7C O caminho na origem ou destino ou ambos eram inválidos.
DE_DESTSAMETREE 0x7D A origem e o destino têm a mesma pasta pai.
DE_FLDDESTISFILE 0x7E O caminho de destino é um arquivo existente.
DE_FILEDESTISFLD 0x80 O caminho de destino é uma pasta existente.
DE_FILENAMETOOLONG 0x81 O nome do arquivo excede MAX_PATH.
DE_DEST_IS_CDROM 0x82 O destino é um CD-ROM somente leitura, possivelmente não formatado.
DE_DEST_IS_DVD 0x83 O destino é um DVD somente leitura, possivelmente não formatado.
DE_DEST_IS_CDRECORD 0x84 O destino é um CD-ROM gravável, possivelmente não formatado.
DE_FILE_TOO_LARGE 0x85 O arquivo envolvido na operação é muito grande para a mídia de destino ou o sistema de arquivos.
DE_SRC_IS_CDROM 0x86 A origem é um CD-ROM somente leitura, possivelmente não formatado.
DE_SRC_IS_DVD 0x87 A origem é um DVD somente leitura, possivelmente não formatado.
DE_SRC_IS_CDRECORD 0x88 A origem é um CD-ROM gravável, possivelmente não formatado.
DE_ERROR_MAX 0xB7 MAX_PATH foi excedido durante a operação.
0x402 Ocorreu um erro desconhecido. Normalmente, isso ocorre devido a um caminho inválido na origem ou destino. Esse erro não ocorre no Windows Vista e posterior.
ERRORONDEST 0x10000 Erro não especificado no destino.
DE_ROOTDIR | ERRORONDEST 0x10074 O destino é um diretório raiz e não pode ser renomeado.

Observações

Você deve usar nomes de caminho totalmente qualificados com essa função. Usá-lo com nomes de caminho relativos não é thread-safe.

Com duas exceções, você não pode usar SHFileOperation para mover pastas especiais de uma unidade local para um computador remoto especificando um caminho de rede. As exceções são as pastas My Documents (CSIDL_PERSONAL, CSIDL_DOCUMENTS) e My Pictures (CSIDL_MYPICTURES).

Quando usado para excluir um arquivo, SHFileOperation exclui permanentemente o arquivo, a menos que você defina o sinalizador de FOF_ALLOWUNDO no membro fFlags da estrutura SHFILEOPSTRUCT apontada por lpFileOp. A configuração desse sinalizador envia o arquivo para a Lixeira. Se você quiser simplesmente excluir um arquivo e garantir que ele não seja colocado na Lixeira, use DeleteFile.

Se um manipulador de retorno de chamada de cópia for exposto e registrado, SHFileOperation chamá-lo, a menos que você defina um sinalizador como FOF_NOCONFIRMATION no membro fFlags da estrutura apontado por lpFileOp. Consulte ICopyHook::CopyCallback para obter detalhes sobre como implementar manipuladores de retorno de chamada de cópia.

A exclusão de arquivo é recursiva, a menos que você defina o sinalizador FOF_NORECURSION em lpFileOp.

arquivos de conexão

Com o Windows 2000 ou posterior, é possível conectar um arquivo HTML com uma pasta que contém arquivos relacionados, como imagens GIF (Graphics Interchange Format) ou folhas de estilo. Se a conexão de arquivo estiver habilitada, quando você mover ou copiar o arquivo HTML, a pasta conectada e todos os seus arquivos também serão movidos ou copiados. Por outro lado, se você mover a pasta com os arquivos relacionados, o arquivo HTML também será movido.

O arquivo HTML deve ter uma extensão .htm ou .html. Crie a conexão com os arquivos relacionados colocando a pasta que os contém na mesma pasta que o arquivo HTML. O nome da pasta que contém os arquivos conectados deve ser o mesmo que o nome do arquivo HTML seguido por "_files" ou ".files" (isso diferencia maiúsculas de minúsculas; por exemplo, ". Os arquivos " não funcionam). Um exemplo é dado aqui.

  1. Crie um arquivo chamado Test.htm no diretório C:\Files (C:\Files\Test.htm).
  2. Crie uma nova pasta chamada Test.files no diretório C:\Files (C:\Files\Test.files).
  3. Preencha a pasta com alguns arquivos. Qualquer arquivo colocado nessa pasta está conectado a Test.htm.
  4. Mova ou copie o arquivo Test.htm para o diretório C:\Files2.
  5. Observe que o diretório Test.files agora também é encontrado no diretório C:\Files2.

A conexão de arquivo é habilitada por padrão. Ele pode ser desabilitado adicionando uma entrada de REG_DWORD, NoFileFolderConnection, conforme mostrado aqui:

HKEY_CURRENT_USER
   Software
      Microsoft
         Windows
            CurrentVersion
               Explorer
                  NoFileFolderConnection

Definir NoFileFolderConnection como 1 desabilita a conexão de arquivo. Se o valor estiver definido como zero ou estiver ausente, a conexão de arquivo será habilitada.

Para mover apenas os arquivos especificados e nenhum dos arquivos conectados, defina o sinalizador FOF_NO_CONNECTED_ELEMENTS no fFlags membro da estrutura apontado por lpFileOp.

Observe que o uso de uma pasta com um nome como "MyFile_files" para definir uma conexão pode não ser válido para versões localizadas do Windows. O termo "arquivos" pode precisar ser substituído pela palavra equivalente no idioma local.

Nota

O cabeçalho shellapi.h define SHFileOperation 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. A combinação do uso do alias neutro de codificação com código que não é 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]
da Plataforma de Destino Windows
cabeçalho shellapi.h
biblioteca Shell32.lib
de DLL Shell32.dll (versão 4.0 ou posterior)
conjunto de API ext-ms-win-shell-shell32-l1-2-1 (introduzido no Windows 10, versão 10.0.10240)