FSCTL_RECALL_FILE IOCTL (winioctl.h)

  • Artigo

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)

Confira também