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.

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)