Fungsi JetOpenFileInstance

Berlaku untuk: Windows | Windows Server

Fungsi JetOpenFileInstance

Fungsi JetOpenFileInstance membuka database terlampir, file patch database, atau file log transaksi instans aktif untuk tujuan melakukan pencadangan fuzzy streaming. Data dari file-file ini kemudian dapat dibaca melalui handel yang dikembalikan menggunakan JetReadFileInstance. Handel yang dikembalikan harus ditutup menggunakan JetCloseFileInstance. Cadangan eksternal instans harus telah dimulai sebelumnya menggunakan JetBeginExternalBackupInstance.

Windows XP:JetOpenFileInstance diperkenalkan di 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
    );

Parameter

Sebagai contoh

Instans yang digunakan untuk panggilan ini.

Untuk Windows 2000, varian API yang menerima parameter ini tidak tersedia karena hanya satu instans yang didukung. Penggunaan instans global yang satu ini tersirat dalam kasus ini.

Untuk rilis Windows XP dan yang lebih baru, varian API yang tidak menerima parameter ini hanya dapat dipanggil ketika mesin berada dalam mode warisan (mode kompatibilitas Windows 2000) di mana hanya satu instans yang didukung. Jika tidak, operasi akan gagal dengan JET_errRunningInMultiInstanceMode.

szFileName

Jalur relatif atau absolut ke database terlampir, file patch database, atau file log transaksi yang dikelola oleh instans yang dibaca untuk cadangan.

phfFile

Arahkan ke buffer output yang menerima handel ke file yang akan dibaca.

pulFileSizeLow

Arahkan ke buffer output yang menerima 32 bit yang paling tidak signifikan dari ukuran file.

pulFileSizeHigh

Arahkan ke buffer output yang menerima 32 bit paling signifikan dari ukuran file.

Tampilkan Nilai

Fungsi ini mengembalikan jenis data JET_ERR dengan salah satu kode pengembalian berikut. Untuk informasi selengkapnya tentang kemungkinan kesalahan ESE, lihat Kesalahan Mesin Penyimpanan yang Dapat Diperluas dan Parameter Penanganan Kesalahan.

Menampilkan kode	Deskripsi
JET_errSuccess	Operasi berhasil diselesaikan.
JET_errBackupAbortByServer	Operasi gagal karena cadangan eksternal saat ini telah dibatalkan oleh panggilan ke JetStopBackupInstance. Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.
JET_errClientRequestToStopJetService	Tidak dimungkinkan untuk menyelesaikan operasi karena semua aktivitas pada instans yang terkait dengan sesi telah berhenti sebagai akibat dari panggilan ke JetStopServiceInstance.
JET_errFileAccessDenied	Operasi gagal karena tidak dapat membuka file yang diminta karena pelanggaran berbagi atau hak istimewa yang tidak memadai.
JET_errFileNotFound	Operasi gagal karena tidak dapat membuka file yang diminta karena tidak dapat ditemukan pada jalur yang ditentukan. Kesalahan ini hanya akan dikembalikan oleh Windows 2000.
JET_errInvalidBackupSequence	Operasi pencadangan gagal karena dipanggil secara berurutan.
JET_errInvalidPath	Operasi gagal karena jalur yang ditentukan tidak dapat ditemukan.
JET_errInstanceUnavailable	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi telah mengalami kesalahan fatal yang mengharuskan akses ke semua data dicabut untuk melindungi integritas data tersebut. Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.
JET_errInvalidParameter	Salah satu parameter yang disediakan berisi nilai yang tidak terduga atau berisi nilai yang tidak masuk akal ketika dikombinasikan dengan nilai parameter lain. Ini dapat terjadi untuk JetOpenFileInstance ketika: Handel instans yang ditentukan tidak valid (Windows XP dan rilis yang lebih baru). Parameter nama file yang ditentukan adalah NULL atau string panjang nol (Windows XP dan rilis yang lebih baru).
JET_errMissingFileToBackup	File yang diminta tidak dapat dibuka untuk pencadangan karena tidak dapat ditemukan. Kesalahan ini hanya akan dikembalikan oleh Windows XP dan rilis yang lebih baru.
JET_errNoBackup	Operasi gagal karena tidak ada pencadangan eksternal yang sedang berlangsung.
JET_errNotInitialized	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi belum diinisialisasi.
JET_errOutOfMemory	Operasi gagal karena memori tidak cukup dapat dialokasikan untuk menyelesaikannya. JetOpenFileInstance akan mengembalikan JET_errOutOfMemory jika upaya dilakukan untuk membuka file lain sebelum file sebelumnya dibuka menggunakan JetOpenFileInstance telah ditutup oleh JetCloseFileInstance. Hanya satu handel file terutang yang saat ini didukung.
JET_errRestoreInProgress	Tidak dimungkinkan untuk menyelesaikan operasi karena operasi pemulihan sedang berlangsung pada instans yang terkait dengan sesi.
JET_errRunningInMultiInstanceMode	Operasi gagal karena upaya dilakukan untuk menggunakan mesin dalam mode warisan (mode kompatibilitas Windows 2000) di mana hanya satu instans yang didukung ketika sebenarnya beberapa instans sudah ada.
JET_errTermInProgress	Tidak dimungkinkan untuk menyelesaikan operasi karena instans yang terkait dengan sesi sedang dimatikan.

Jika berhasil, handel ke file yang diminta dikembalikan. Jika handel adalah untuk file database, file database tersebut akan disiapkan untuk pencadangan streaming yang dapat mengakibatkan pembuatan file patch database di lokasi yang sama dengan file database. File patch database memiliki jalur dan nama file yang sama persis dengan file database tetapi dengan . Ekstensi PAT. Ukuran file juga akan dikembalikan.

Jika gagal, status buffer output tidak akan terdefinisi. File patch database dapat dibuat sementara pada disk dan file yang ada di lokasi file patch dapat dihapus. Kegagalan akan mengakibatkan pembatalan seluruh proses pencadangan untuk instans. Pada Windows XP dan rilis yang lebih baru, cadangan tidak akan dibatalkan jika upaya dilakukan untuk mencadangkan database yang tidak dilampirkan ke instans pada saat panggilan.

Peringatan Untuk alasan keamanan, penting untuk dicatat bahwa JetOpenFileInstance tidak memverifikasi bahwa jalur file yang diminta dikaitkan dengan kumpulan file yang dicadangkan untuk instans. Akibatnya, dimungkinkan untuk menggunakan fungsi ini untuk mengakses file apa pun yang dapat dibuka oleh konteks keamanan utas saat ini. Sangat penting bahwa aplikasi membatasi jalur yang diteruskan ke fungsi ini ke serangkaian jalur file yang baik yang diketahui atau pengungkapan serangan informasi dapat dimungkinkan.

Keterangan

Penyangga output handel dan ukuran file harus ada. Jika tidak ada maka mesin akan crash karena parameter buffer output tidak divalidasi.

Saat ini, hanya satu file yang dapat dibuka untuk pencadangan pada satu waktu.

JetOpenFileInstance tidak menegaskan hak istimewa cadangan sebelum membuka file yang diminta.

Ukuran file yang akan dibaca seperti yang dilaporkan oleh fungsi ini mungkin tidak cocok dengan ukuran file pada disk. Pada Windows XP dan rilis yang lebih baru, informasi tambahan dapat ditambahkan ke file database yang digunakan oleh mesin database selama operasi pemulihan. Dengan demikian, aplikasi hanya boleh mengandalkan ukuran file yang dikembalikan oleh JetOpenFileInstance atau pada jumlah byte data aktual yang dikembalikan oleh JetReadFileInstance.

Persyaratan

Persyaratan	Nilai
Klien	Memerlukan Windows Vista atau Windows XP.
Server	Memerlukan Windows Server 2008 atau Windows Server 2003.
Header	Dinyatakan dalam Esent.h.
Pustaka	Gunakan ESENT.lib.
DLL	Membutuhkan ESENT.dll.
Unicode	Diimplementasikan sebagai JetOpenFileInstanceW (Unicode) dan JetOpenFileInstanceA (ANSI).

Lihat juga

JET_ERR
JET_HANDLE
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackupInstance
JetCloseFileInstance
JetGetAttachInfoInstance
JetGetLogInfoInstance
JetReadFileInstance
JetStopBackupInstance
JetTruncateLogInstance