Función BackupRead (winbase.h)

La función BackupRead se puede usar para realizar una copia de seguridad de un archivo o directorio, incluida la información de seguridad. La función lee los datos asociados a un archivo o directorio especificados en un búfer, que luego se puede escribir en el medio de copia de seguridad mediante la función WriteFile .

Sintaxis

BOOL BackupRead(
  [in]  HANDLE  hFile,
  [out] LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToRead,
  [out] LPDWORD lpNumberOfBytesRead,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Parámetros

[in] hFile

Identificador del archivo o directorio del que se va a realizar una copia de seguridad. Para obtener el identificador, llame a la función CreateFile . Las SACL no se leen a menos que se haya creado el identificador de archivo con el derecho de acceso ACCESS_SYSTEM_SECURITY . Para obtener más información, vea Derechos de acceso y seguridad de archivos.

El identificador debe ser sincrónico (no superpuesto). Esto significa que la marca FILE_FLAG_OVERLAPPED no debe establecerse cuando se llama a CreateFile . Esta función no valida que el identificador que recibe sea sincrónico, por lo que no devuelve un código de error para un identificador sincrónico, pero llamarlo con un identificador asincrónico (superpuesto) puede dar lugar a errores sutiles que son muy difíciles de depurar.

La función BackupRead puede producir un error si se llamó a CreateFile con la marca FILE_FLAG_NO_BUFFERING. En este caso, la función GetLastError devuelve el valor ERROR_INVALID_PARAMETER.

[out] lpBuffer

Puntero a un búfer que recibe los datos.

[in] nNumberOfBytesToRead

Longitud del búfer, en bytes. El tamaño del búfer debe ser mayor que el tamaño de una estructura de WIN32_STREAM_ID .

[out] lpNumberOfBytesRead

Puntero a una variable que recibe el número de bytes leídos.

Si la función devuelve un valor distinto de cero y la variable a la que apunta lpNumberOfBytesRead es cero, se han leído todos los datos asociados al identificador de archivo.

[in] bAbort

Indica si ha terminado de usar BackupRead en el identificador. Mientras realiza una copia de seguridad del archivo, especifique este parámetro como FALSE. Una vez que haya terminado de usar BackupRead, debe llamar a BackupRead una vez más especificando TRUE para este parámetro y pasando el lpContext adecuado. lpContext debe pasarse cuando bAbort es TRUE; se omiten todos los demás parámetros.

[in] bProcessSecurity

Indica si la función restaurará los datos de la lista de control de acceso (ACL) para el archivo o directorio.

Si bProcessSecurity es TRUE, se realizará una copia de seguridad de los datos de ACL.

[out] lpContext

Puntero a una variable que recibe un puntero a una estructura de datos interna usada por BackupRead para mantener la información de contexto durante una operación de copia de seguridad.

Debe establecer la variable a la que apunta lpContext en NULL antes de la primera llamada a BackupRead para el archivo o directorio especificados. La función asigna memoria para la estructura de datos y, a continuación, establece la variable para que apunte a esa estructura. No debe cambiar lpContext ni la variable a la que apunta entre llamadas a BackupRead.

Para liberar la memoria usada por la estructura de datos, llame a BackupRead con el parámetro bAbort establecido en TRUE cuando se complete la operación de copia de seguridad.

Valor devuelto

Si la función se realiza correctamente, el valor devuelto es distinto de cero.

Si se produce un error en la función, el valor devuelto es cero, lo que indica que se ha producido un error de E/S. Para obtener información de error extendida, llame a GetLastError.

Comentarios

Esta función no está pensada para usarse en la copia de seguridad de archivos cifrados en el sistema de archivos cifrado. Use ReadEncryptedFileRaw para ese propósito.

Si se produce un error mientras BackupRead lee datos, el proceso de llamada puede omitir los datos incorrectos llamando a la función BackupSeek .

El archivo o directorio se debe restaurar mediante la función BackupWrite .

Requisitos

Cliente mínimo compatible	Windows XP [solo aplicaciones de escritorio]
Servidor mínimo compatible	Windows Server 2003 [solo aplicaciones de escritorio]
Plataforma de destino	Windows
Encabezado	winbase.h (incluye Windows.h)
Library	Kernel32.lib
Archivo DLL	Kernel32.dll

Vea también

BackupSeek

BackupWrite

Creación de una aplicación de copia de seguridad

ReadEncryptedFileRaw

WIN32_STREAM_ID