Compartilhar via


Função SHFileOperationA (shellapi.h)

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 executar 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, terá resultados inesperados.

Retornar valor

Tipo: int

Retorna zero se tiver êxito; caso contrário, diferente de zero. Os aplicativos normalmente devem simplesmente marcar para zero ou diferente de zero.

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

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

Para examinar os valores diferentes de 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 valores retornados possíveis 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:

  • Esses 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 do 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 ao SHFileOperation.
DE_DESTSUBTREE 0x76 O destino é uma subárvore da origem.
DE_ACCESSDENIEDSRC 0x78 As configurações de segurança negaram o 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 era inválido.
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 no destino. Esse erro não ocorre no Windows Vista e posterior.
ERRORONDEST 0x10000 Ocorreu um erro não especificado no destino.
DE_ROOTDIR | ERRORONDEST 0x10074 O destino é um diretório raiz e não pode ser renomeado.

Comentários

Você deve usar nomes de caminho totalmente qualificados com essa função. Usá-lo com nomes de caminho relativo 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 Meus Documentos (CSIDL_PERSONAL, CSIDL_DOCUMENTS) e Minhas Imagens (CSIDL_MYPICTURES).

Quando usado para excluir um arquivo, SHFileOperation exclui permanentemente o arquivo, a menos que você defina o sinalizador FOF_ALLOWUNDO no membro fFlags da estrutura SHFILEOPSTRUCT apontada por lpFileOp. Definir esse 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 o chamará, a menos que você defina um sinalizador como FOF_NOCONFIRMATION no membro fFlags da estrutura apontada 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.

Conectando arquivos

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. Você cria 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, ". Arquivos" não funciona). 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 está 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 for 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 membro fFlags da estrutura apontada 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.

Observação

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

Requisito Valor
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]
Plataforma de Destino Windows
Cabeçalho shellapi.h
Biblioteca Shell32.lib
DLL Shell32.dll (versão 4.0 ou posterior)
Conjunto de APIs ext-ms-win-shell-shell32-l1-2-1 (introduzido no Windows 10, versão 10.0.10240)