FSCTL_RECALL_FILE IOCTL (winioctl.h)

  • Artikel

Ruft eine Datei von Speichermedien ab, die von Remotespeicher verwaltet werden. Hierbei handelt es sich um die hierarchische Speicherverwaltungssoftware.

Um eine Datei abzurufen, rufen Sie die DeviceIoControl-Funktion mit den folgenden Parametern auf.

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

Hinweise

FSCTL_RECALL_FILE stellt eine Datei aus dem Speicher wieder her, z. B. ein Band, das von Remotespeicher verwaltet wird. Wenn die Datei bereits lokal zwischengespeichert ist, führt dieser Vorgang nichts aus. Wenn die Datei nicht in den Remotespeicher verschoben wurde, führt dieser Vorgang ebenfalls nichts aus.

FSCTL_RECALL_FILE funktioniert nur auf Systemen, auf denen Remotespeicher installiert ist. Wenn Der Remotespeicher nicht installiert ist, schlägt der Vorgang fehl, und GetLastError gibt den Fehlercode ERROR_INVALID_FUNCTION zurück.

Verzeichnisse können nicht in den Remotespeicher verschoben werden. Beim Aufrufen FSCTL_RECALL_FILE für ein Verzeichnis tritt ein Fehler auf, und GetLastError gibt den Fehlercode ERROR_INVALID_HANDLE zurück.

In der Regel werden Dateien, die auf Medien gespeichert sind, die von Remotespeicher verwaltet werden, abgerufen, wenn eine Anwendung versucht, den ersten Zugriff auf Daten zu gewähren. Eine Anwendung, die eine Datei öffnet, ohne sofort auf die Daten zuzugreifen, kann den ersten Zugriff beschleunigen, indem FSCTL_RECALL_FILE unmittelbar nach dem Öffnen der Datei verwendet wird. Vermeiden Sie jedoch das wahllose Abrufen von Dateien, die von einer Anwendung nicht berührt werden.

Bevor Sie FSCTL_RECALL_FILE müssen Sie die Attribute einer Datei für das Flag FILE_ATTRIBUTE_OFFLINE mit der Funktion GetFileAttributes nicht testen. Der Test ist unnötig, da eine Onlinedatei von diesem Vorgang nicht betroffen ist. Jeder Betriebssystemaufruf benötigt jedoch Prozessorzeit. Um Prozessorzeit zu sparen, rufen Sie GetFileAttributes auf, um Dateiattribute zu überprüfen, um festzustellen, ob FSCTL_RECALL_FILE erforderlich ist.

Die Auswirkungen von überlappenden E/A-Vorgängen auf diesen Vorgang finden Sie im Abschnitt Hinweise des Themas DeviceIoControl .

In Windows 8 und Windows Server 2012 wird dieser Code von den folgenden Technologien unterstützt.

Technologie Unterstützt
SMB 3.0-Protokoll (Server Message Block) No
SMB 3.0 Transparent Failover (TFO) No
SMB 3.0 mit Dateifreigaben mit horizontaler Skalierung (SO) No
Dateisystem mit freigegebenen Clustervolumes (CsvFS) No
Robustes Dateisystem (Resilient File System, ReFS) Ja

Beispiele

Das folgende Codebeispiel ist ein Befehlszeilenprogramm, das eine oder mehrere Dateien, die in der Befehlszeile angegeben sind, aus dem Remotespeicher abruft.

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

Anforderungen

Anforderung Wert
Unterstützte Mindestversion (Client) Windows XP [nur Desktop-Apps]
Unterstützte Mindestversion (Server) Windows Server 2003 [nur Desktop-Apps]
Kopfzeile winioctl.h (windows.h einschließen)

Weitere Informationen