FSCTL_RECALL_FILE IOCTL (winioctl.h)
Recupera um arquivo da mídia de armazenamento gerenciado pelo Armazenamento Remoto, que é o software de gerenciamento de armazenamento hierárquico.
Para recuperar um arquivo, chame a função DeviceIoControl com os parâmetros a seguir.
BOOL DeviceIoControl(
(HANDLE) hDevice, // handle to file or directory
FSCTL_RECALL_FILE, // dwIoControlCode
NULL, // lpInBuffer
0, // nInBufferSize
NULL, // lpOutBuffer
0, // nOutBufferSize
(LPDWORD) lpBytesReturned, // number of bytes returned
(LPOVERLAPPED) lpOverlapped // OVERLAPPED structure
);
Comentários
FSCTL_RECALL_FILE recupera um arquivo do armazenamento, por exemplo, uma fita gerenciada pelo Armazenamento Remoto. Se o arquivo já estiver armazenado em cache localmente, essa operação não fará nada. Da mesma forma, se o arquivo não tiver sido movido para o armazenamento remoto, essa operação não fará nada.
FSCTL_RECALL_FILE opera somente em sistemas em que o Armazenamento Remoto está instalado. Se o Armazenamento Remoto não estiver instalado, a operação falhará e GetLastError retornará o código de erro ERROR_INVALID_FUNCTION.
Os diretórios não podem ser movidos para o armazenamento remoto. A chamada FSCTL_RECALL_FILE para um diretório falha e GetLastError retorna o código de erro ERROR_INVALID_HANDLE.
Normalmente, os arquivos armazenados em mídia gerenciada pelo Armazenamento Remoto são recuperados quando um aplicativo tenta fazer o primeiro acesso aos dados. Um aplicativo que abre um arquivo sem acessar imediatamente os dados pode acelerar o primeiro acesso usando FSCTL_RECALL_FILE imediatamente após abrir o arquivo. No entanto, evite o recall indiscriminado de arquivos que um aplicativo não toque.
Antes de chamar FSCTL_RECALL_FILE não é necessário testar os atributos de um arquivo para o sinalizador FILE_ATTRIBUTE_OFFLINE com a função GetFileAttributes. O teste é desnecessário porque um arquivo online não é afetado por essa operação. No entanto, qualquer chamada do sistema operacional leva tempo do processador. Para conservar o tempo do processador, chame GetFileAttributes para marcar atributos de arquivo para determinar se FSCTL_RECALL_FILE é necessário.
Para obter as implicações de E/S sobreposta nesta operação, consulte a seção Comentários do tópico DeviceIoControl .
Em Windows 8 e Windows Server 2012, esse código é compatível com as tecnologias a seguir.
| Tecnologia | Com suporte |
|---|---|
| Protocolo SMB (SMB) 3.0 | No |
| TFO (Failover transparente) do SMB 3.0 | No |
| SMB 3.0 com compartilhamentos de arquivos de expansão (SO) | No |
| Sistema de arquivos de Volume Compartilhado Clusterizado (CsvFS) | No |
| ReFS (Sistema de Arquivos Resiliente) | Sim |
Exemplos
O exemplo de código a seguir é um utilitário de linha de comando que lembra um ou mais arquivos indicados na linha de comando do armazenamento remoto.
#include <Windows.h>
#include <malloc.h>
#include <stdio.h>
#include <WinIoCtl.h>
DWORD RecallFile(PTCHAR FileName);
int _cdecl _tmain(int argc, TCHAR *argv[])
{
LONG i;
if (argc < 2) {
printf("Usage: recall <file-name1> <file-name2> ...\n");
return 1;
}
for (i = 1; i < argc; i++) {
(void) RecallFile((PTCHAR) argv[i]);
}
return 0;
}
DWORD RecallFile(IN PTCHAR FileName)
/*++
Routine Description
Recalls the file with the supplied path.
Arguments
FileName - Path of the file to be recalled
Return Value
0 - Recall is successful.
Any other value - Error code for the operation.
--*/
{
HANDLE fileHandle;
DWORD nbytes;
DWORD errorCode = 0;
fileHandle = CreateFile((LPCTSTR) FileName,
GENERIC_READ,
FILE_SHARE_READ,
NULL,
OPEN_EXISTING,
FILE_ATTRIBUTE_NORMAL,
NULL);
if (fileHandle == INVALID_HANDLE_VALUE)
{
errorCode = GetLastError();
printf("Couldn't open file %s: error %x\n", FileName,
errorCode);
return errorCode;
}
if (!DeviceIoControl(fileHandle,
FSCTL_RECALL_FILE,
NULL,
0,
NULL,
0,
&nbytes,
NULL))
{
errorCode = GetLastError();
printf("Couldn't recall file %s: error %x\n",
FileName, errorCode);
}
CloseHandle(fileHandle);
return errorCode;
}
Requisitos
| Requisito | Valor |
|---|---|
| Cliente mínimo com suporte | Windows XP [somente aplicativos da área de trabalho] |
| Servidor mínimo com suporte | Windows Server 2003 [somente aplicativos da área de trabalho] |
| Cabeçalho | winioctl.h (inclua Windows.h) |