FSCTL_RECALL_FILE IOCTL (winioctl.h)

  • Статья

Возвращает файл с носителя, которым управляет удаленное хранилище, которое является программным обеспечением для управления иерархическим хранилищем.

Чтобы отозвать файл, вызовите функцию DeviceIoControl со следующими параметрами.

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
);

Комментарии

FSCTL_RECALL_FILE восстанавливает файл из хранилища, например ленту, которая управляется удаленным хранилищем. Если файл уже кэширован локально, эта операция не выполняет никаких действий. Аналогичным образом, если файл не был перемещен в удаленное хранилище, эта операция не выполняет никаких действий.

FSCTL_RECALL_FILE работает только в системах, где установлено удаленное хранилище. Если удаленное хранилище не установлено, операция завершается сбоем, и GetLastError возвращает код ошибки ERROR_INVALID_FUNCTION.

Каталоги нельзя переместить в удаленное хранилище. Вызов FSCTL_RECALL_FILE для каталога завершается сбоем, и GetLastError возвращает код ошибки ERROR_INVALID_HANDLE.

Как правило, файлы, хранящиеся на носителе, управляемом удаленным хранилищем, отзываются, когда приложение пытается сделать первый доступ к данным. Приложение, которое открывает файл без немедленного доступа к данным, может ускорить первый доступ с помощью FSCTL_RECALL_FILE сразу после открытия файла. Однако избегайте неизбирательного отзыва файлов, которые приложение не касается.

Перед вызовом FSCTL_RECALL_FILE не нужно проверять атрибуты файла для флага , FILE_ATTRIBUTE_OFFLINE с помощью функции GetFileAttributes. Тест не требуется, так как эта операция не влияет на сетевой файл. Однако любой вызов операционной системы занимает время процессора. Чтобы сэкономить время процессора, вызовите GetFileAttributes для проверка атрибутов файла, чтобы определить, требуется ли FSCTL_RECALL_FILE.

Сведения о последствиях перекрывающихся операций ввода-вывода для этой операции см. в разделе Примечания статьи DeviceIoControl .

В Windows 8 и Windows Server 2012 этот код поддерживается следующими технологиями.

Технология Поддерживается
Протокол SMB 3.0 Нет
SMB 3.0 Transparent Failover (TFO) Нет
SMB 3.0 с масштабируемыми общими папками (SO) Нет
Файловая система общего тома кластера (CSVFS) Нет
Восстанавливаемая файловая система (ReFS) Да

Примеры

В следующем примере кода используется служебная программа командной строки, которая возвращает один или несколько файлов, указанных в командной строке, из удаленного хранилища.

#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;
}

Требования

Требование Значение
Минимальная версия клиента Windows XP [только классические приложения]
Минимальная версия сервера Windows Server 2003 [только классические приложения]
Верхняя часть winioctl.h (включая Windows.h)

См. также раздел