Win32 API 日本語リファレンス
ホーム › Storage.Jet › JetRestoreW

JetRestoreW

関数
バックアップからデータベースを復元する(Unicode版)。
DLLESENT.dll文字セットUnicode (-W)呼出規約winapi

シグネチャ

// ESENT.dll  (Unicode / -W)
#include <windows.h>

INT JetRestoreW(
    WORD* szSource,
    JET_PFNSTATUS pfn   // optional
);

パラメーター

名前型方向説明
szSourceWORD*in復元元バックアップファイルが格納されたディレクトリのパスを指す終端付きUnicode文字列ポインタ。
pfnJET_PFNSTATUSinoptional進捗通知を受け取るステータスコールバック関数(JET_PFNSTATUS)。NULL可。

戻り値の型: INT

公式ドキュメント

JetRestore 関数は、インスタンスのストリーミング バックアップを、アタッチされているすべてのデータベースを含めて復元および回復します。この関数は主に、データベースのインスタンスを 1 つしか許可しない Windows 2000 以前のデータベース エンジンとの下位互換性のために用意されています。この場合、復元されるのはアクティブなインスタンスです。JetRestore では、復元先のデータベースの場所を指定できません。

戻り値

この関数は JET_ERR データ型を返し、その値は次の戻り値コードのいずれかになります。発生する可能性のある ESE エラーの詳細については、Extensible Storage Engine Errors および Error Handling Parameters を参照してください。

戻り値コード

説明

JET_errSuccess

操作は正常に完了しました。

JET_errAlreadyInitialized

このインスタンスに対してエンジンが既に初期化されているため、操作は失敗しました。

JET_errInvalidLogSequence

バックアップ セットのログ ファイルのセットと、現在のログ パスのログ ファイルのセットが一致しません。

JET_errInvalidParameter

指定されたパラメーターのいずれかに、予期しない値、または他のパラメーターの値と組み合わせたときに意味をなさない値が含まれていました。

JET_errInvalidPath

指定されたパスの一部 (バックアップ パス、コピー先のパス、インスタンスのログ パスまたはシステム パス) が無効なため、操作は失敗しました。

JET_errPageSizeMismatch

エンジンに構成されているデータベース ページ サイズ (JetSetSystemParameter で JET_paramDatabasePageSize を設定) が、トランザクション ログ ファイル、またはそのトランザクション ログ ファイルに関連付けられたデータベースの作成に使用されたデータベース ページ サイズと一致しないため、操作は失敗しました。

JET_errRunningInMultiInstanceMode

パラメーターがシングル インスタンス モード (Windows 2000 互換モード) を意味しているにもかかわらず、エンジンが既にマルチ インスタンス モードになっているため、操作は失敗しました。

成功した場合、バックアップ セットのデータベース ファイルが元の場所に復元され、データベースがトランザクション整合性の取れたクリーンな状態になるように回復処理が実行されます。回復処理では、バックアップ セットのログ ファイルと、ログ パスにログ ファイルが存在する場合はそれらのログ ファイルが再生されます。この回復処理により、チェックポイント ファイル、トランザクション ログ ファイル、およびそれらのトランザクション ログ ファイルから参照されるすべてのデータベースが変更されます。

失敗した場合、インスタンスは初期化されていない状態のままになります。復元の開始とデータベースの回復を試みた過程で、トランザクション ログ ファイルおよびそれらのトランザクション ログ ファイルから参照されるデータベースの状態は、変更されている可能性が高くなります。

解説

回復処理では、バックアップ時にインスタンスにアタッチされていたデータベースが再構築され、変更内容がデータベース ファイルに書き戻されます。その結果、データベースはトランザクション整合性の取れた状態になります。可能であれば、バックアップの取得後からトランザクション ログに記録された最新の変更までに行われた変更も、データベースに保存されます。これは、バックアップの取得後に生成されたトランザクション ログがトランザクション ログ ディレクトリにまだ存在する場合に可能です。なお、インスタンスで循環ログが有効になっている場合、生成されたトランザクション ログは再利用されるため、回復処理で保存できるのはバックアップ時点までに行われた変更となります。いずれの場合も、データベースに対して再生するトランザクション ログ ファイルの数が多いと、この処理にかなりの時間がかかることがあります。

JetRestore 関数は、対象のインスタンスに対して JetInit を呼び出す前に呼び出す必要があります。

回復処理では多数のデータベース ページとトランザクション ログが使用されるため、これらの関数からは一連のさまざまなエラーが返される可能性があります。そうしたエラーには、Jet_errOutOfMemory のような一時的なリソース割り当ての失敗から、JET_errReadVerifyFailure、JET_errLogFileCorrupt、JET_errBadPageLink のような物理的な破損を表すものまであります。これらのエラーはほとんどの場合ハードウェアの問題が原因であり、回避することはできません。ファイルの管理ミスは、JET_errMissingLogFile、JET_errAttachedDatabaseMismatch、JET_errDatabaseSharingViolation、JET_errInvalidLogSequence として現れることが最も多くなります。これらのエラーはアプリケーション側で防止できます。アプリケーションは、これらのファイルの格納場所が、ユーザーや他のアプリケーションといった外部の要因によって操作されないよう、慎重に保護する必要があります。インスタンスを完全に破棄する場合は、そのインスタンスに関連付けられたすべてのファイルを削除する必要があります。これには、チェックポイント ファイル、トランザクション ログ ファイル、およびインスタンスにアタッチされているすべてのデータベース ファイルが含まれます。

回復処理の各段階では、トランザクション ログの再生の進行状況や復元の最終結果を含むイベント ログのエントリが生成されます。

要件

要件 値

クライアント

Windows Vista、Windows XP、または Windows 2000 Professional が必要です。

サーバー

Windows Server 2008、Windows Server 2003、または Windows 2000 Server が必要です。

ヘッダー

Esent.h で宣言されています。

ライブラリ

ESENT.lib を使用します。

DLL

ESENT.dll が必要です。

Unicode

JetRestoreW (Unicode) および JetRestoreA (ANSI) として実装されています。

関連項目

JET_ERR
JET_GRBIT
JET_INSTANCE
JetBackup
JetBackupInstance
JetCreateInstance
JetSetSystemParameter

出典・ライセンス: 上記「公式ドキュメント」の内容は Microsoft の Win32 API ドキュメント(MicrosoftDocs/sdk-api)を日本語に翻訳・改変したものです。© Microsoft Corporation. CC BY 4.0 で提供。
Microsoft 公式リファレンス: 英語 (en-us) · 日本語 (ja-jp)

各言語での呼び出し定義

// ESENT.dll  (Unicode / -W)
#include <windows.h>

INT JetRestoreW(
    WORD* szSource,
    JET_PFNSTATUS pfn   // optional
);
[DllImport("ESENT.dll", CharSet = CharSet.Unicode, ExactSpelling = true)]
static extern int JetRestoreW(
    ref ushort szSource,   // WORD*
    IntPtr pfn   // JET_PFNSTATUS optional
);
<DllImport("ESENT.dll", CharSet:=CharSet.Unicode, ExactSpelling:=True)>
Public Shared Function JetRestoreW(
    ByRef szSource As UShort,   ' WORD*
    pfn As IntPtr   ' JET_PFNSTATUS optional
) As Integer
End Function
' szSource : WORD*
' pfn : JET_PFNSTATUS optional
Declare PtrSafe Function JetRestoreW Lib "esent" ( _
    ByRef szSource As Integer, _
    ByVal pfn As LongPtr) As Long
' Unicode(W): 文字列は ByVal As LongPtr とし StrPtr(unicodeStr) を渡す
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。
import ctypes
from ctypes import wintypes

JetRestoreW = ctypes.windll.esent.JetRestoreW
JetRestoreW.restype = ctypes.c_int
JetRestoreW.argtypes = [
    ctypes.POINTER(ctypes.c_ushort),  # szSource : WORD*
    ctypes.c_void_p,  # pfn : JET_PFNSTATUS optional
]
require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetRestoreW = Fiddle::Function.new(
  lib['JetRestoreW'],
  [
    Fiddle::TYPE_VOIDP,  # szSource : WORD*
    Fiddle::TYPE_VOIDP,  # pfn : JET_PFNSTATUS optional
  ],
  Fiddle::TYPE_INT)
# Wide strings: pass str.encode("UTF-16LE") + "\x00\x00"
#[link(name = "esent")]
extern "system" {
    fn JetRestoreW(
        szSource: *mut u16,  // WORD*
        pfn: *const core::ffi::c_void  // JET_PFNSTATUS optional
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.
$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Unicode)]
public static extern int JetRestoreW(ref ushort szSource, IntPtr pfn);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetRestoreW' -Namespace Win32 -PassThru
# $api::JetRestoreW(szSource, pfn)
#uselib "ESENT.dll"
#func global JetRestoreW "JetRestoreW" wptr, wptr
; JetRestoreW varptr(szSource), pfn   ; 戻り値は stat
; szSource : WORD* -> "wptr"
; pfn : JET_PFNSTATUS optional -> "wptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "ESENT.dll"
#cfunc global JetRestoreW "JetRestoreW" var, sptr
; res = JetRestoreW(szSource, pfn)
; szSource : WORD* -> "var"
; pfn : JET_PFNSTATUS optional -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; INT JetRestoreW(WORD* szSource, JET_PFNSTATUS pfn)
#uselib "ESENT.dll"
#cfunc global JetRestoreW "JetRestoreW" var, intptr
; res = JetRestoreW(szSource, pfn)
; szSource : WORD* -> "var"
; pfn : JET_PFNSTATUS optional -> "intptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	esent = windows.NewLazySystemDLL("ESENT.dll")
	procJetRestoreW = esent.NewProc("JetRestoreW")
)

// szSource (WORD*), pfn (JET_PFNSTATUS optional)
r1, _, err := procJetRestoreW.Call(
	uintptr(szSource),
	uintptr(pfn),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // INT
function JetRestoreW(
  szSource: Pointer;   // WORD*
  pfn: Pointer   // JET_PFNSTATUS optional
): Integer; stdcall;
  external 'ESENT.dll' name 'JetRestoreW';
result := DllCall("ESENT\JetRestoreW"
    , "Ptr", szSource   ; WORD*
    , "Ptr", pfn   ; JET_PFNSTATUS optional
    , "Int")   ; return: INT
●JetRestoreW(szSource, pfn) = DLL("ESENT.dll", "int JetRestoreW(void*, void*)")
# 呼び出し: JetRestoreW(szSource, pfn)
# szSource : WORD* -> "void*"
# pfn : JET_PFNSTATUS optional -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
# ※-W(Unicode)関数。なでしこ1はANSIのため -A 版の利用を推奨。
const std = @import("std");

extern "esent" fn JetRestoreW(
    szSource: [*c]u16, // WORD*
    pfn: ?*anyopaque // JET_PFNSTATUS optional
) callconv(std.os.windows.WINAPI) i32;
// Unicode(-W): UTF-16LE のヌル終端バッファ([*c]const u16)を渡す。
proc JetRestoreW(
    szSource: ptr uint16,  # WORD*
    pfn: pointer  # JET_PFNSTATUS optional
): int32 {.importc: "JetRestoreW", stdcall, dynlib: "ESENT.dll".}
# Unicode(-W): WideCString は newWideCString("...") で生成。
pragma(lib, "esent");
extern(Windows)
int JetRestoreW(
    ushort* szSource,   // WORD*
    void* pfn   // JET_PFNSTATUS optional
);
ccall((:JetRestoreW, "ESENT.dll"), stdcall, Int32,
      (Ptr{UInt16}, Ptr{Cvoid}),
      szSource, pfn)
# szSource : WORD* -> Ptr{UInt16}
# pfn : JET_PFNSTATUS optional -> Ptr{Cvoid}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
# Unicode(-W): Cwstring には transcode(UInt16, "...") 等で UTF-16 を渡す。
local ffi = require("ffi")
ffi.cdef[[
int32_t JetRestoreW(
    uint16_t* szSource,
    void* pfn);
]]
local esent = ffi.load("esent")
-- esent.JetRestoreW(szSource, pfn)
-- szSource : WORD*
-- pfn : JET_PFNSTATUS optional
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
-- Unicode(-W): uint16_t* には UTF-16LE のバッファ(ffi.new("uint16_t[?]", ...))を渡す。
const koffi = require('koffi');
const lib = koffi.load('ESENT.dll');
const JetRestoreW = lib.func('__stdcall', 'JetRestoreW', 'int32_t', ['uint16_t *', 'void *']);
// JetRestoreW(szSource, pfn)
// szSource : WORD* -> 'uint16_t *'
// pfn : JET_PFNSTATUS optional -> 'void *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
// コールバック(関数ポインタ)は koffi.proto/koffi.register で型を定義して渡す(素の void* では JS 関数を渡せない)。
const lib = Deno.dlopen("ESENT.dll", {
  JetRestoreW: { parameters: ["pointer", "pointer"], result: "i32" },
});
// lib.symbols.JetRestoreW(szSource, pfn)
// szSource : WORD* -> "pointer"
// pfn : JET_PFNSTATUS optional -> "pointer"
// 文字列は "buffer"。Unicode(-W) は new TextEncoder() ではなく UTF-16LE のバイト列(末尾に \x00\x00)を Uint8Array で渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t JetRestoreW(
    uint16_t* szSource,
    void* pfn);
C, "ESENT.dll");
// $ffi->JetRestoreW(szSource, pfn);
// szSource : WORD*
// pfn : JET_PFNSTATUS optional
// 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
// WINAPI(stdcall): x64 では呼出規約が統一されるため問題なし。x86 では __stdcall 対応のラッパが必要な場合あり。
import com.sun.jna.*;
import com.sun.jna.ptr.*;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;

public interface Esent extends StdCallLibrary {
    Esent INSTANCE = Native.load("esent", Esent.class, W32APIOptions.UNICODE_OPTIONS);
    int JetRestoreW(
        ShortByReference szSource,   // WORD*
        Callback pfn   // JET_PFNSTATUS optional
    );
}
// Unicode(-W): WString(入力)/char[](出力)で UTF-16 をマーシャリング。
@[Link("esent")]
lib LibESENT
  fun JetRestoreW = JetRestoreW(
    szSource : UInt16*,   # WORD*
    pfn : Void*   # JET_PFNSTATUS optional
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef JetRestoreWNative = Int32 Function(Pointer<Uint16>, Pointer<Void>);
typedef JetRestoreWDart = int Function(Pointer<Uint16>, Pointer<Void>);
final JetRestoreW = DynamicLibrary.open('ESENT.dll')
    .lookupFunction<JetRestoreWNative, JetRestoreWDart>('JetRestoreW');
// szSource : WORD* -> Pointer<Uint16>
// pfn : JET_PFNSTATUS optional -> Pointer<Void>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function JetRestoreW(
  szSource: Pointer;   // WORD*
  pfn: Pointer   // JET_PFNSTATUS optional
): Integer; stdcall;
  external 'ESENT.dll' name 'JetRestoreW';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "JetRestoreW"
  c_JetRestoreW :: Ptr Word16 -> Ptr () -> IO Int32
-- szSource : WORD* -> Ptr Word16
-- pfn : JET_PFNSTATUS optional -> Ptr ()
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let jetrestorew =
  foreign "JetRestoreW"
    ((ptr uint16_t) @-> (ptr void) @-> returning int32_t)
(* szSource : WORD* -> (ptr uint16_t) *)
(* pfn : JET_PFNSTATUS optional -> (ptr void) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library esent (t "ESENT.dll"))
(cffi:use-foreign-library esent)

(cffi:defcfun ("JetRestoreW" jet-restore-w :convention :stdcall) :int32
  (sz-source :pointer)   ; WORD*
  (pfn :pointer))   ; JET_PFNSTATUS optional
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $JetRestoreW = Win32::API::More->new('ESENT',
    'int JetRestoreW(LPVOID szSource, LPVOID pfn)');
# my $ret = $JetRestoreW->Call($szSource, $pfn);
# szSource : WORD* -> LPVOID
# pfn : JET_PFNSTATUS optional -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。
# コールバック(関数ポインタ)は Perl sub を直接渡せません。Win32::API::Callback を使用してください。
# Unicode(-W): LPCWSTR/LPWSTR は Win32::API が UTF-16 変換を行う。

関連項目

文字セット違い
類似 API
使用する型