FSCTL_RECALL_FILE IOCTL (winioctl.h)

  • Artículo

Recupera un archivo de los medios de almacenamiento que administra Almacenamiento remoto, que es el software de administración de almacenamiento jerárquico.

Para recuperar un archivo, llame a la función DeviceIoControl con los parámetros siguientes.

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

Comentarios

FSCTL_RECALL_FILE recupera un archivo del almacenamiento, por ejemplo, una cinta administrada por almacenamiento remoto. Si el archivo ya está almacenado en caché localmente, esta operación no hace nada. Del mismo modo, si el archivo no se ha movido al almacenamiento remoto, esta operación no hace nada.

FSCTL_RECALL_FILE solo funciona en sistemas en los que está instalado el almacenamiento remoto. Si el almacenamiento remoto no está instalado, se produce un error en la operación y GetLastError devuelve el código de error ERROR_INVALID_FUNCTION.

Los directorios no se pueden mover al almacenamiento remoto. Se produce un error al llamar a FSCTL_RECALL_FILE para un directorio y GetLastError devuelve el código de error ERROR_INVALID_HANDLE.

Normalmente, los archivos almacenados en medios administrados por el almacenamiento remoto se recuperan cuando una aplicación intenta realizar el primer acceso a los datos. Una aplicación que abre un archivo sin acceder inmediatamente a los datos puede acelerar el primer acceso mediante FSCTL_RECALL_FILE inmediatamente después de abrir el archivo. Sin embargo, evite recuperar indiscriminadamente los archivos que una aplicación no toca.

Antes de llamar a FSCTL_RECALL_FILE no es necesario probar los atributos de un archivo para la marca FILE_ATTRIBUTE_OFFLINE con la función GetFileAttributes. La prueba no es necesaria porque esta operación no afecta a un archivo en línea. Sin embargo, cualquier llamada del sistema operativo tarda tiempo en el procesador. Para conservar el tiempo del procesador, llame a GetFileAttributes para comprobar los atributos de archivo para determinar si es necesario FSCTL_RECALL_FILE .

Para conocer las implicaciones de la E/S superpuesta en esta operación, consulte la sección Comentarios del tema DeviceIoControl .

En Windows 8 y Windows Server 2012, este código es compatible con las siguientes tecnologías.

Tecnología Compatible
Protocolo Bloque de mensajes del servidor (SMB) 3.0 No
Conmutación por error transparente (TFO) de SMB 3.0 No
SMB 3.0 con recursos compartidos de archivos de escalabilidad horizontal (SO) No
Sistema de archivos de Volumen compartido de clúster (CsvFS) No
Sistema de archivos resistente a errores (ReFS) Sí

Ejemplos

El ejemplo de código siguiente es una utilidad de línea de comandos que recupera uno o varios archivos indicados en la línea de comandos desde el almacenamiento remoto.

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

Requisitos

Requisito Value
Cliente mínimo compatible Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible Windows Server 2003 [solo aplicaciones de escritorio]
Encabezado winioctl.h (incluye Windows.h)

Consulte también