FSCTL_RECALL_FILE IOCTL (winioctl.h)

  • Artikel

Memanggil kembali file dari media penyimpanan yang dikelola Penyimpanan Jarak Jauh, yang merupakan perangkat lunak manajemen penyimpanan hierarkis.

Untuk memanggil kembali file, panggil fungsi DeviceIoControl dengan parameter berikut.

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

Keterangan

FSCTL_RECALL_FILE memulihkan file dari penyimpanan, misalnya, pita yang dikelola oleh Penyimpanan Jarak Jauh. Jika file sudah di-cache secara lokal, operasi ini tidak melakukan apa pun. Demikian pula, jika file belum dipindahkan ke penyimpanan jarak jauh, operasi ini tidak melakukan apa pun.

FSCTL_RECALL_FILE hanya beroperasi pada sistem tempat Penyimpanan Jarak Jauh diinstal. Jika Penyimpanan Jarak Jauh tidak diinstal, operasi gagal dan GetLastError mengembalikan kode kesalahan ERROR_INVALID_FUNCTION.

Direktori tidak dapat dipindahkan ke penyimpanan jarak jauh. Memanggil FSCTL_RECALL_FILE untuk direktori gagal, dan GetLastError mengembalikan kode kesalahan ERROR_INVALID_HANDLE.

Biasanya, file yang disimpan di media yang dikelola oleh Penyimpanan Jarak Jauh dipanggil kembali ketika aplikasi mencoba membuat akses pertama ke data. Aplikasi yang membuka file tanpa segera mengakses data dapat mempercepat akses pertama dengan menggunakan FSCTL_RECALL_FILE segera setelah membuka file. Namun, hindari pengenalan file yang tidak dapat disentuh oleh aplikasi.

Sebelum memanggil FSCTL_RECALL_FILE Anda tidak perlu menguji atribut file untuk bendera FILE_ATTRIBUTE_OFFLINE dengan fungsi GetFileAttributes. Pengujian ini tidak perlu karena file online tidak terpengaruh oleh operasi ini. Namun, setiap panggilan sistem operasi membutuhkan waktu prosesor. Untuk menghemat waktu prosesor, panggil GetFileAttributes untuk memeriksa atribut file untuk menentukan apakah FSCTL_RECALL_FILE diperlukan.

Untuk implikasi I/O yang tumpang tindih pada operasi ini, lihat bagian Keterangan dari topik DeviceIoControl .

Di Windows 8 dan Windows Server 2012, kode ini didukung oleh teknologi berikut.

Teknologi Didukung
Protokol Server Message Block (SMB) 3.0 Tidak
SMB 3.0 Transparent Failover (TFO) Tidak
SMB 3.0 dengan Scale-out File Shares (SO) Tidak
Sistem File Volume Bersama Kluster (CsvFS) Tidak
Sistem File Tangguh (ReFS) Ya

Contoh

Contoh kode berikut adalah utilitas baris perintah yang mengingat satu atau beberapa file yang ditunjukkan pada baris perintah dari penyimpanan jarak jauh.

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

Persyaratan

Persyaratan Nilai
Klien minimum yang didukung Windows XP [hanya aplikasi desktop]
Server minimum yang didukung Windows Server 2003 [hanya aplikasi desktop]
Header winioctl.h (termasuk Windows.h)

Lihat juga