FSCTL_RECALL_FILE IOCTL (winioctl.h)

  • Articolo

Ricorda un file dal supporto di archiviazione gestito dall'archiviazione remota, ovvero il software di gestione gerarchica dell'archiviazione.

Per richiamare un file, chiamare la funzione DeviceIoControl con i parametri seguenti.

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

Commenti

FSCTL_RECALL_FILE recupera un file dall'archiviazione, ad esempio un nastro gestito da Archiviazione remota. Se il file è già memorizzato nella cache in locale, questa operazione non fa nulla. Analogamente, se il file non è stato spostato nell'archiviazione remota, questa operazione non fa nulla.

FSCTL_RECALL_FILE funziona solo nei sistemi in cui è installato l'archiviazione remota. Se l'archiviazione remota non è installata, l'operazione ha esito negativo e GetLastError restituisce il codice di errore ERROR_INVALID_FUNCTION.

Le directory non possono essere spostate nell'archiviazione remota. La chiamata FSCTL_RECALL_FILE per una directory non riesce e GetLastError restituisce il codice di errore ERROR_INVALID_HANDLE.

In genere, i file archiviati nei supporti gestiti da Archiviazione remota vengono richiamati quando un'applicazione tenta di rendere il primo accesso ai dati. Un'applicazione che apre un file senza accedere immediatamente ai dati può velocizzare il primo accesso usando FSCTL_RECALL_FILE immediatamente dopo l'apertura del file. Tuttavia, evitare il richiamo indiscriminato di file che un'applicazione non tocca.

Prima di chiamare FSCTL_RECALL_FILE non è necessario testare gli attributi di un file per il flag FILE_ATTRIBUTE_OFFLINE con la funzione GetFileAttributes. Il test non è necessario perché un file online non è interessato da questa operazione. Tuttavia, qualsiasi chiamata del sistema operativo richiede tempo per il processore. Per risparmiare tempo di processore, chiamare GetFileAttributes per controllare gli attributi dei file per determinare se è necessario FSCTL_RECALL_FILE .

Per le implicazioni dell'I/O sovrapposta in questa operazione, vedere la sezione Osservazioni dell'argomento DeviceIoControl .

In Windows 8 e Windows Server 2012 questo codice è supportato dalle tecnologie seguenti.

Tecnologia Supportato
Protocollo SMB (Server Message Block) 3.0 No
Failover trasparente SMB 3.0 (TFO) No
SMB 3.0 con condivisioni file con scalabilità orizzontale (SO) No
File system del volume condiviso del cluster (CsvFS) No
File system resiliente (ReFS) Sì

Esempi

L'esempio di codice seguente è un'utilità della riga di comando che richiama uno o più file indicati nella riga di comando dall'archiviazione remota.

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

Requisiti

Requisito Valore
Client minimo supportato Windows XP [solo app desktop]
Server minimo supportato Windows Server 2003 [solo app desktop]
Intestazione winioctl.h (include Windows.h)

Vedi anche