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 は、リモート ストレージがインストールされているシステムでのみ動作します。 Remote Storage がインストールされていない場合、操作は失敗し、 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 プロトコル いいえ
SMB 3.0 Transparent Failover (TFO) いいえ
スケールアウト ファイル共有 (SO) を使う SMB 3.0 いいえ
クラスターの共有ボリューム ファイル システム (CsvFS) いいえ
Resilient File System (ReFS) はい

例

次のコード例は、コマンド ラインで示されている 1 つ以上のファイルをリモート ストレージから呼び出すコマンド ライン ユーティリティです。

#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 (デスクトップ アプリのみ)
Header winioctl.h (Windows.h を含む)

こちらもご覧ください