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您不需要使用 GetFileAttributes 函式來測試旗標的檔案屬性FILE_ATTRIBUTE_OFFLINE。 因為在線檔案不受此作業影響，所以不需要測試。 不過，任何操作系統呼叫都需要處理器時間。 若要節省處理器時間，請呼叫 GetFileAttributes 來檢查檔案屬性，以判斷 是否需要FSCTL_RECALL_FILE 。

如需此作業上重疊 I/O 的影響，請參閱 DeviceIoControl 主題的一節。

在 Windows 8 和 Windows Server 2012 中，下列技術支援此程序代碼。

技術 支援
伺服器消息塊 (SMB) 3.0 通訊協定 No
SMB 3.0 透明故障轉移 (TFO) No
具有向外延展檔案共用的SMB 3.0 (SO) No
叢集共用磁碟區文件系統 (CsvFS) No
彈性檔案系統 (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)

另請參閱