Función BackupWrite (winbase.h)

  • Artículo

La función BackupWrite se puede usar para restaurar un archivo o directorio de copia de seguridad mediante BackupRead. Use la función ReadFile para obtener un flujo de datos del medio de copia de seguridad y, a continuación, use BackupWrite para escribir los datos en el archivo o directorio especificados.

Sintaxis

BOOL BackupWrite(
  [in]  HANDLE  hFile,
  [in]  LPBYTE  lpBuffer,
  [in]  DWORD   nNumberOfBytesToWrite,
  [out] LPDWORD lpNumberOfBytesWritten,
  [in]  BOOL    bAbort,
  [in]  BOOL    bProcessSecurity,
  [out] LPVOID  *lpContext
);

Parámetros

[in] hFile

Identificador del archivo o directorio que se va a restaurar. Para obtener el identificador, llame a la función CreateFile . Las SACL no se restauran a menos que se haya creado el identificador de archivo con el derecho de acceso ACCESS_SYSTEM_SECURITY . Para asegurarse de que las ACE de integridad se restauran correctamente, el identificador de archivo también debe haberse creado con el derecho de acceso WRITE_OWNER . 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 BackupWrite 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.

[in] lpBuffer

Puntero a un búfer desde el que la función escribe datos.

[in] nNumberOfBytesToWrite

Tamaño 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] lpNumberOfBytesWritten

Puntero a una variable que recibe el número de bytes escritos.

[in] bAbort

Indica si ha terminado de usar BackupWrite en el identificador. Mientras restaura el archivo, especifique este parámetro como FALSE. Una vez que haya terminado de usar BackupWrite, debe llamar a BackupWrite 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

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

Si bProcessSecurity es TRUE, debe especificar WRITE_OWNER y WRITE_DAC acceso al abrir el identificador de archivo o directorio. Si el identificador no tiene esos derechos de acceso, el sistema operativo deniega el acceso a los datos de ACL y no se producirá la restauración de datos de ACL.

[out] lpContext

Puntero a una variable que recibe un puntero a una estructura de datos interna utilizada por BackupWrite para mantener la información de contexto durante una operación de restauración.

Debe establecer la variable a la que apunta lpContext en NULL antes de la primera llamada a BackupWrite 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 BackupWrite.

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

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 restauración de archivos cifrados en el sistema de archivos cifrado. Use WriteEncryptedFileRaw para ese propósito.

Los datos leídos desde el medio de copia de seguridad deben estar separados por WIN32_STREAM_ID estructuras.

El tipo de secuencia BACKUP_LINK permite restaurar archivos con vínculos físicos.

Requisitos

Requisito Value
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

BackupRead

BackupSeek

CreateFile

WIN32_STREAM_ID

WriteEncryptedFileRaw