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.

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

Confira também

• CreateFile
• DeviceIoControl
• Códigos de controle de gerenciamento de arquivos
• GetFileAttributes
• OVERLAPPED