Función JetOpenFileInstance

Se aplica a: Windows | Windows Server

Función JetOpenFileInstance

La función JetOpenFileInstance 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 JetReadFileInstance. El controlador devuelto debe cerrarse mediante JetCloseFileInstance. Se debe haber iniciado previamente una copia de seguridad externa de la instancia mediante JetBeginExternalBackupInstance.

Windows XP:JetOpenFileInstance se presenta en Windows XP.

    JET_ERR JET_API JetOpenFileInstance(
      __in          JET_INSTANCE instance,
      __in          JET_PCSTR szFileName,
      __out         JET_HANDLE* phfFile,
      __out         unsigned long* pulFileSizeLow,
      __out         unsigned long* pulFileSizeHigh
    );

Parámetros

instance

Instancia que se va a usar para esta llamada.

Para Windows 2000, la variante de API que acepta este parámetro no está disponible porque solo se admite una instancia. El uso de esta instancia global está implícito en este caso.

Para Windows XP y versiones posteriores, la variante de API que no acepta este parámetro solo se puede llamar cuando el motor está en modo heredado (modo de compatibilidad de Windows 2000) donde solo se admite una instancia. De lo contrario, se producirá un error en la operación con JET_errRunningInMultiInstanceMode.

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 lee para la copia de seguridad.

phfFile

Puntero al búfer de salida que recibe un identificador del archivo que se va a leer.

pulFileSizeLow

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

pulFileSizeHigh

Puntero al 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 JetStopBackupInstance. 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 cesado como resultado de una llamada a JetStopServiceInstance.
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_errInvalidBackupSequence	Error en la operación de copia de seguridad porque se ha llamado fuera de secuencia.
JET_errInvalidPath	Error en la operación porque no se encontró la ruta de acceso especificada.
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_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 JetOpenFileInstance 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_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. JetOpenFileInstance devolverá JET_errOutOfMemory si se intenta abrir otro archivo antes de que se abra el archivo anterior mediante JetOpenFileInstance ha sido cerrado por JetCloseFileInstance. Actualmente solo se admite un identificador de archivo pendiente.
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.
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.

Si se ejecuta correctamente, se devuelve un identificador del archivo solicitado. Si el identificador es para un archivo de base de datos, ese archivo de base de datos se preparará para una copia de seguridad de streaming 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 con . 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 JetOpenFileInstance no comprueba que la ruta de acceso del archivo solicitada esté asociada con el conjunto de archivos de los que se realiza una copia de seguridad de 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.

JetOpenFileInstance 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 JetOpenFileInstance o en el número real de bytes de datos devueltos por JetReadFileInstance.

Requisitos

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

Consulte también

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance