Función JetOpenFile

Se aplica a: Windows | Windows Server

Función JetOpenFile

La función JetOpenFile abre una base de datos adjunta, un archivo de revisión de base de datos o un archivo de registro de transacciones de una instancia activa con el fin de realizar una copia de seguridad aproximada de streaming. Los datos de estos archivos se pueden leer posteriormente mediante el identificador devuelto mediante JetReadFile. El controlador devuelto debe cerrarse mediante JetCloseFile. Se debe haber iniciado previamente una copia de seguridad externa de la instancia mediante JetBeginExternalBackup.

    JET_ERR JET_API JetOpenFile(
      __in          const tchar* szFileName,
      __out         JET_HANDLE* phfFile,
      __out         unsigned long* pulFileSizeLow,
      __out         unsigned long* pulFileSizeHigh
    );

Parámetros

szFileName

Ruta de acceso relativa o absoluta a una base de datos adjunta, un archivo de revisión de base de datos o un archivo de registro de transacciones administrado por la instancia de que se leerá para la copia de seguridad.

phfFile

Búfer de salida que recibe un identificador para el archivo que se va a leer.

pulFileSizeLow

Búfer de salida que recibe los 32 bits menos significativos del tamaño del archivo.

pulFileSizeHigh

Búfer de salida que recibe los 32 bits más significativos del tamaño del archivo.

Valor devuelto

Esta función devuelve el tipo de datos JET_ERR con uno de los siguientes códigos de retorno. Para obtener más información sobre los posibles errores de ESE, vea Extensible Storage Engine Errors and Error Handling Parameters.

Código devuelto	Descripción
JET_errSuccess	La operación se ha completado correctamente.
JET_errBackupAbortByServer	Error en la operación porque la copia de seguridad externa actual se ha anulado mediante una llamada a JetStopBackup. Windows XP solo devolverá este error y versiones posteriores.
JET_errClientRequestToStopJetService	No es posible completar la operación porque toda la actividad de la instancia asociada a la sesión ha dejado de funcionar como resultado de una llamada a JetStopService.
JET_errFileAccessDenied	Error en la operación porque no pudo abrir el archivo solicitado debido a una infracción de uso compartido o privilegios insuficientes.
JET_errFileNotFound	Error en la operación porque no se pudo abrir el archivo solicitado porque no se encontró en la ruta de acceso especificada. Windows 2000 solo devolverá este error.
JET_errInstanceUnavailable	No es posible completar la operación porque la instancia asociada a la sesión ha encontrado un error irrecuperable que requiere que se revoque el acceso a todos los datos para proteger la integridad de esos datos. Windows XP solo devolverá este error y versiones posteriores.
JET_errInvalidBackupSequence	Error en la operación de copia de seguridad porque se ha llamado fuera de secuencia.
JET_errInvalidParameter	Uno de los parámetros proporcionados contenía un valor inesperado o contenía un valor que no tenía sentido cuando se combinaba con el valor de otro parámetro. Esto puede ocurrir para JetOpenFile cuando: El identificador de instancia especificado no es válido (Windows XP y versiones posteriores). El parámetro de nombre de archivo especificado es NULL o una cadena de longitud cero (Windows XP y versiones posteriores).
JET_errInvalidPath	Error en la operación porque no se encontró la ruta de acceso especificada.
JET_errMissingFileToBackup	No se pudo abrir el archivo solicitado para la copia de seguridad porque no se encontró. Windows XP solo devolverá este error y versiones posteriores.
JET_errNoBackup	Error en la operación porque no hay ninguna copia de seguridad externa en curso.
JET_errNotInitialized	No es posible completar la operación porque la instancia asociada a la sesión aún no se ha inicializado.
JET_errOutOfMemory	Error en la operación porque no se pudo asignar suficiente memoria para completarla. JetOpenFile devolverá JET_errOutOfMemory si se intenta abrir otro archivo antes de que el archivo anterior abierto mediante JetOpenFile haya sido cerrado por JetCloseFile. Actualmente solo se admite un identificador de archivo pendiente.
JET_errRunningInMultiInstanceMode	Error en la operación porque se intentó usar el motor en modo heredado (modo de compatibilidad de Windows 2000), donde solo se admite una instancia cuando ya existen varias instancias.
JET_errTermInProgress	No es posible completar la operación porque se está cerrando la instancia asociada a la sesión. JET_errRestoreInProgress No es posible completar la operación porque hay una operación de restauración en curso en la instancia asociada a la sesión.

Si se ejecuta correctamente, se devolverá un identificador al archivo solicitado. Si el identificador es para un archivo de base de datos, ese archivo de base de datos se preparará para la copia de seguridad de streaming, lo que puede dar lugar a la creación de un archivo de revisión de base de datos en la misma ubicación que el archivo de base de datos. El archivo de revisión de base de datos tiene exactamente la misma ruta de acceso y nombre de archivo que el archivo de base de datos, pero tiene . Extensión PAT. También se devolverá el tamaño del archivo.

En caso de error, el estado de los búferes de salida no estará definido. Se puede crear temporalmente un archivo de revisión de base de datos en el disco y se puede eliminar cualquier archivo existente en la ubicación del archivo de revisión. El error provocará la cancelación de todo el proceso de copia de seguridad de la instancia. En Windows XP y versiones posteriores, la copia de seguridad no se cancelará si se intentó realizar una copia de seguridad de una base de datos que no estaba asociada a la instancia en el momento de la llamada.

Advertencia Por motivos de seguridad, es importante tener en cuenta que JetOpenFile no comprueba que la ruta de acceso del archivo solicitada esté asociada con el conjunto de archivos de los que se debe realizar una copia de seguridad para la instancia. Como resultado, es posible usar esta función para tener acceso a cualquier archivo que pueda abrir el contexto de seguridad actual del subproceso. Es imperativo que la aplicación restrinja las rutas de acceso que se pasan a esta función a un conjunto conocido de rutas de acceso de archivo correctas o que se pueda hacer posible una divulgación de ataques de información.

Comentarios

Los búferes de salida de tamaño de archivo y identificador deben estar presentes. Si no están presentes, el motor se bloqueará porque los parámetros del búfer de salida no se validan.

En este momento, solo se puede abrir un archivo para la copia de seguridad en cualquier momento.

JetOpenFile no afirma el privilegio de copia de seguridad antes de abrir el archivo solicitado.

Es posible que el tamaño del archivo que se va a leer según lo notificado por esta función no coincida con el tamaño del archivo en el disco. En Windows XP y versiones posteriores, se puede anexar información adicional a un archivo de base de datos que usa el motor de base de datos durante una operación de restauración. Por lo tanto, la aplicación solo debe basarse en el tamaño de archivo devuelto por JetOpenFile o en el número real de bytes de datos devueltos por JetReadFile.

Requisitos

Requisito	Value
Cliente	Requiere Windows Vista, Windows XP o Windows 2000 Professional.
Servidor	Requiere Windows Server 2008, Windows Server 2003 o Windows 2000 Server.
Encabezado	Declarado en Esent.h.
Library	Use ESENT.lib.
Archivo DLL	Requiere ESENT.dll.
Unicode	Se implementa como JetOpenFileW (Unicode) y JetOpenFileA (ANSI).

Consulte también

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackup
JetCloseFile
JetGetAttachInfo
JetGetLogInfo
JetReadFile
JetStopBackup
JetStopService
JetTruncateLog