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.
- Crie um arquivo chamado Test.htm no diretório C:\Files (C:\Files\Test.htm).
- Crie uma nova pasta chamada Test.files no diretório C:\Files (C:\Files\Test.files).
- Preencha a pasta com alguns arquivos. Qualquer arquivo colocado nessa pasta está conectado a Test.htm.
- Mova ou copie o arquivo Test.htm para o diretório C:\Files2.
- 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) |
Comentários
Em breve: Ao longo de 2024, eliminaremos os problemas do GitHub como o mecanismo de comentários para conteúdo e o substituiremos por um novo sistema de comentários. Para obter mais informações, consulte https://aka.ms/ContentUserFeedback.
Enviar e exibir comentários de