FSCTL_RECALL_FILE IOCTL (winioctl.h)

  • Article

Rappelle un fichier à partir d’un support de stockage géré par Stockage distant, qui est le logiciel de gestion du stockage hiérarchique.

Pour rappeler un fichier, appelez la fonction DeviceIoControl avec les paramètres suivants.

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

Remarques

FSCTL_RECALL_FILE récupère un fichier à partir d’un stockage, par exemple une bande gérée par le stockage à distance. Si le fichier est déjà mis en cache localement, cette opération ne fait rien. De même, si le fichier n’a pas été déplacé vers le stockage distant, cette opération ne fait rien.

FSCTL_RECALL_FILE fonctionne uniquement sur les systèmes sur lesquels le stockage à distance est installé. Si le stockage à distance n’est pas installé, l’opération échoue et GetLastError retourne le code d’erreur ERROR_INVALID_FUNCTION.

Les répertoires ne peuvent pas être déplacés vers le stockage distant. L’appel de FSCTL_RECALL_FILE pour un répertoire échoue et GetLastError retourne le code d’erreur ERROR_INVALID_HANDLE.

En règle générale, les fichiers stockés sur un média géré par le stockage à distance sont rappelés lorsqu’une application tente d’obtenir le premier accès aux données. Une application qui ouvre un fichier sans accéder immédiatement aux données peut accélérer le premier accès en utilisant FSCTL_RECALL_FILE immédiatement après l’ouverture du fichier. Toutefois, évitez de rappeler sans discrimination des fichiers qu’une application ne touche pas.

Avant d’appeler FSCTL_RECALL_FILE vous n’avez pas besoin de tester les attributs d’un fichier pour l’indicateur FILE_ATTRIBUTE_OFFLINE avec la fonction GetFileAttributes. Le test n’est pas nécessaire, car un fichier en ligne n’est pas affecté par cette opération. Toutefois, tout appel de système d’exploitation prend du temps processeur. Pour économiser le temps du processeur, appelez GetFileAttributes pour case activée attributs de fichier afin de déterminer si FSCTL_RECALL_FILE est nécessaire.

Pour connaître les implications des E/S qui se chevauchent sur cette opération, consultez la section Remarques de la rubrique DeviceIoControl .

Dans Windows 8 et Windows Server 2012, ce code est pris en charge par les technologies suivantes.

Technologie Prise en charge
Protocole Server Message Block (SMB) 3.0 No
Basculement transparent SMB 3.0 (TFO) No
SMB 3.0 avec partages de fichiers avec montée en puissance parallèle (SO) No
Système de fichiers du volume partagé de cluster (CsvFS) No
Système de fichiers résilient (ReFS) Oui

Exemples

L’exemple de code suivant est un utilitaire de ligne de commande qui rappelle un ou plusieurs fichiers indiqués sur la ligne de commande à partir du stockage distant.

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

Configuration requise

Condition requise Valeur
Client minimal pris en charge Windows XP [applications de bureau uniquement]
Serveur minimal pris en charge Windows Server 2003 [applications de bureau uniquement]
En-tête winioctl.h (inclure Windows.h)

Voir aussi