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 仅在安装了远程存储的系统上运行。 如果未安装远程存储，则操作将失败， GetLastErrorERROR_INVALID_FUNCTION返回错误代码。

无法将目录移动到远程存储。 调用 目录FSCTL_RECALL_FILE 失败， GetLastErrorERROR_INVALID_HANDLE返回错误代码。

通常，当应用程序尝试首次访问数据时，将召回存储在远程存储管理的媒体上的文件。 在不立即访问数据的情况下打开文件的应用程序可以在打开文件后立即使用 FSCTL_RECALL_FILE 来加快首次访问速度。 但是，请避免不分青红皂白地召回应用程序不接触的文件。

在调用 FSCTL_RECALL_FILE不需要使用函数 GetFileAttributes 测试标志FILE_ATTRIBUTE_OFFLINE的文件属性。 不需要测试，因为联机文件不受此操作的影响。 但是，任何操作系统调用都需要处理器时间。 若要节省处理器时间，请调用 GetFileAttributes 以检查文件属性，以确定是否需要FSCTL_RECALL_FILE。

有关重叠 I/O 对此操作的影响，请参阅 DeviceIoControl 主题的“备注”部分。

在 Windows 8 和 Windows Server 2012 中，以下技术支持此代码。

技术 支持
服务器消息块 (SMB) 3.0 协议 否
SMB 3.0 透明故障转移 (TFO) 否
具有横向扩展文件共享的 SMB 3.0 (SO) 否
群集共享卷文件系统 (CSV) 否
弹性文件系统 (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)

另请参阅