Управляющий код FSCTL_RECALL_FILE

Управляющий код FSCTL_RECALL_FILE возвращает обратно файл из носителей данных, управляемых Удаленным хранилищем, программным обеспечением иерархического управления хранилищами (HSM).

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

Синтаксис

BOOL DeviceIoControl(
  (HANDLE) hDevice,            // дескриптор файла или каталога
  FSCTL_RECALL_FILE,           // dwIoControlCode
  NULL,                        // lpInBuffer
  0,                           // nInBufferSize
  NULL,                        // lpOutBuffer
  0,                           // nOutBufferSize
  (LPDWORD) lpBytesReturned,   // возвращаемое число байтов
  (LPOVERLAPPED) lpOverlapped  // структура OVERLAPPED
);

Параметры

hDevice

[in] Дескриптор файла, данные которого должны быть возвращены из носителя данных удаленного хранилища. Чтобы извлечь дескриптор устройства, вызовите функцию CreateFile. Дескриптор должен быть открыт с доступом для чтения, для записи, или с тем и другим. Для получения дополнительной информации, см. статью Защита файла и права доступа.

dwIoControlCode

[in] Управляющий код для операции. Для этой операции используйте FSCTL_RECALL_FILE.

lpInBuffer

Не используется с этой операцией; устанавливается в ПУСТО (NULL).

nInBufferSize

Не используется с этой операцией; устанавливается в нуль.

lpOutBuffer

Не используется с этой операцией; устанавливается в ПУСТО ( NULL).

nOutBufferSize

Не используется с этой операцией; устанавливается в нуль.

lpBytesReturned

[out] Указатель на переменную, которая получает размер данных, сохраненных в буфере вывода данных, в байтах.

Если параметр lpOverlapped - ПУСТО (NULL), lpBytesReturned не может быть ПУСТО (NULL). Даже тогда, когда операция не возвращает никакого вывода данных, а параметр lpOutBuffer - ПУСТО (NULL), функция DeviceIoControl использует lpBytesReturned. После такой операции, значение параметра lpBytesReturned становится бессмысленным.

Если параметр lpOverlapped - не ПУСТО (NULL), то - lpBytesReturned может быть ПУСТО (NULL). Если этот параметр - не ПУСТО (NULL) и операция возвращает данные, lpBytesReturned не имеет смысла до тех пор, пока не завершиться асинхронная операция. Чтобы получить данные о числе возвращаемых данных, вызовите функцию GetOverlappedResult. Если параметр hDevice связан с портом завершения ввода-вывода данных (I/O), Вы можете извлечь число возвращаемых данных при помощи вызова функции GetQueuedCompletionStatus.

lpOverlapped

[in] Указатель на структуру OVERLAPPED.

Если параметр hDevice открывался без установки флажка FILE_FLAG_OVERLAPPED, параметр lpOverlapped игнорируется.

Если параметр hDevice открывался с флажком FILE_FLAG_OVERLAPPED, операция выполняется как перекрывающая (асинхронная) операция. В этом случае, параметр lpOverlapped должен указать на допустимую структуру OVERLAPPED, которая содержит дескриптор объекта события. Иначе, функция завершается ошибкой непредсказуемыми способами.

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

Возвращаемые значения

Если операция завершается успешно, функция DeviceIoControl возвращает не нулевое значение.

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

Замечания

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

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

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

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

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

Как включают асинхронные операции ввода-вывода в этой операции, см. в разделе Замечаний описания функции DeviceIoControl.

Код примера

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

#include <windows.h>
#include <malloc.h>
#include <stdio.h>
#include <winioctl.h>

DWORD
RecallFile(PUCHAR FileName);

int _cdecl
main(int argc, char *argv[])
{
  HANDLE file;
  LONG   i;
  DWORD  nbytes;

  if (argc < 2) {
    printf("Используйте: recall <имя-файла1> <имя-файла2> ...\n");
    return 1;
  }

  for (i = 1; i < argc; i++) {
    (void) RecallFile(argv[i]);
  }
  return 0;
}

DWORD
RecallFile(IN PUCHAR FileName)
  /*++
Описание процедуры
    Повторный вызов файла по предопределенному пути.
Аргументы
    FileName - Путь возвращаемого файла
Возвращаемые значения
    0                     - Повторный вызов завершился успешно.
    Любое другое значение - Код ошибки для этой операции.

--*/

{
  HANDLE fileHandle;
  DWORD  nbytes;
  DWORD  errorCode = 0;

  fileHandle = CreateFile(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;
}

Смотри также

Управляющие коды, используемые в управлении файлами, CreateFile, DeviceIoControl, GetFileAttributes, OVERLAPPED

Размещение и совместимость FSCTL_RECALL_FILE
К	Windows XP	Да
л	Windows 2000 Professional	Да
и	Windows NT	Нет
е	Windows Me	Нет
н	Windows 98	Нет
т	Windows 95	Нет

С	Windows Server 2003	Да
е	Windows 2000 Server	Да
р	Windows NT Server	Нет
в
е
р
Используемая библиотека		-
Используемая DLL		-
Заголовочный файл
- объявлено в		Winioctl.h
- включено в		-
Unicode		Нет
Замечания по платформе		Не имеется

Назад в оглавление

На главную страницу

На оглавление справки