ホーム › Storage.Jet › JetGetAttachInfoInstanceA

JetGetAttachInfoInstanceA

関数

指定インスタンスのアタッチ済みデータベース一覧を取得する(ANSI版)。

DLLESENT.dll文字セットANSI (-A)呼出規約winapi

シグネチャ

// ESENT.dll  (ANSI / -A)
#include <windows.h>

INT JetGetAttachInfoInstanceA(
    JET_INSTANCE instance,
    CHAR* szzDatabases,   // optional
    DWORD cbMax,
    DWORD* pcbActual   // optional
);

パラメーター

名前	型	方向	説明
instance	JET_INSTANCE	in	情報取得対象のインスタンスを識別するJET_INSTANCEハンドル。
szzDatabases	CHAR*	outoptional	アタッチ中データベースのパス一覧を受け取る出力ANSI文字列バッファポインタ。NUL区切りの多重文字列となる。
cbMax	DWORD	in	szzDatabasesバッファのサイズをバイト単位で指定する値。
pcbActual	DWORD*	outoptional	実際に必要/書き込まれたバイト数を受け取る出力ポインタ。

戻り値の型: INT

公式ドキュメント

JetGetAttachInfoInstance 関数は、JetBeginExternalBackupInstance によって開始されたバックアップ中に、バックアップファイルセットに含めるべきデータベースファイルの名前をインスタンスに問い合わせるために使用します。対象となるのは、JetAttachDatabase を使用して現在インスタンスにアタッチされているデータベースのみです。これらのファイルは、その後 JetOpenFileInstance を使用して開き、JetReadFileInstance を使用して読み取ることができます。

戻り値

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

戻り値コード	説明
JET_errSuccess	操作は正常に完了しました。
JET_errBackupAbortByServer	現在の外部バックアップが JetStopBackupInstance の呼び出しによって中止されたため、操作は失敗しました。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errClientRequestToStopJetService	JetStopServiceInstance の呼び出しの結果、セッションに関連付けられたインスタンス上のすべての活動が停止したため、操作を完了できません。
JET_errInstanceUnavailable	セッションに関連付けられたインスタンスで致命的なエラーが発生し、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要があるため、操作を完了できません。このエラーは Windows XP 以降のリリースでのみ返されます。
JET_errInvalidBackupSequence	バックアップ操作は、正しい順序以外で呼び出されたため失敗しました。現在のバックアップが完全バックアップでない場合、JetGetAttachInfoInstance はこのエラーを返します。
JET_errInvalidParameter	指定されたパラメーターのいずれかに予期しない値が含まれていたか、別のパラメーターの値と組み合わせると意味をなさない値が含まれていました。JetGetAttachInfoInstance では、指定されたインスタンスハンドルが無効な場合にこのエラーが発生することがあります (Windows XP 以降のリリース)。
JET_errNoBackup	外部バックアップが実行中でないため、操作は失敗しました。
JET_errNotInitialized	セッションに関連付けられたインスタンスがまだ初期化されていないため、操作を完了できません。
JET_errRestoreInProgress	セッションに関連付けられたインスタンスで復元操作が進行中であるため、操作を完了できません。
JET_errRunningInMultiInstanceMode	実際には既に複数のインスタンスが存在しているにもかかわらず、1 つのインスタンスのみがサポートされるレガシモード (Windows 2000 互換モード) でエンジンを使用しようとしたため、操作は失敗しました。
JET_errTermInProgress	セッションに関連付けられたインスタンスがシャットダウン中であるため、操作を完了できません。

成功した場合、バックアップファイルセットに含めるべきデータベースファイルのセットに関する要求された情報が、指定された出力バッファーに格納されます。

失敗した場合、出力バッファーの状態は未定義です。この失敗により、そのインスタンスのバックアップ処理全体がキャンセルされます。

解説

この API は、バックアップファイルセットに含めるべきファイルの完全な一覧を受け取るには出力バッファーが小さすぎる場合でも、エラーや警告を返さないことに注意することが重要です。アプリケーションは、この一覧の実際のサイズを受け取るバッファーを常に用意し、その情報を使用して一覧が切り詰められたかどうかを判断する必要があります。

要件

要件	値
クライアント	Windows Vista または Windows XP が必要です。
サーバー	Windows Server 2008 または Windows Server 2003 が必要です。
ヘッダー	Esent.h で宣言されています。
ライブラリ	ESENT.lib を使用します。
DLL	ESENT.dll が必要です。
Unicode	JetGetAttachInfoInstanceW (Unicode) および JetGetAttachInfoInstanceA (ANSI) として実装されています。

各言語での呼び出し定義

// ESENT.dll  (ANSI / -A)
#include <windows.h>

INT JetGetAttachInfoInstanceA(
    JET_INSTANCE instance,
    CHAR* szzDatabases,   // optional
    DWORD cbMax,
    DWORD* pcbActual   // optional
);

[DllImport("ESENT.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int JetGetAttachInfoInstanceA(
    UIntPtr instance,   // JET_INSTANCE
    IntPtr szzDatabases,   // CHAR* optional, out
    uint cbMax,   // DWORD
    IntPtr pcbActual   // DWORD* optional, out
);

<DllImport("ESENT.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function JetGetAttachInfoInstanceA(
    instance As UIntPtr,   ' JET_INSTANCE
    szzDatabases As IntPtr,   ' CHAR* optional, out
    cbMax As UInteger,   ' DWORD
    pcbActual As IntPtr   ' DWORD* optional, out
) As Integer
End Function

' instance : JET_INSTANCE
' szzDatabases : CHAR* optional, out
' cbMax : DWORD
' pcbActual : DWORD* optional, out
Declare PtrSafe Function JetGetAttachInfoInstanceA Lib "esent" ( _
    ByVal instance As LongPtr, _
    ByVal szzDatabases As LongPtr, _
    ByVal cbMax As Long, _
    ByVal pcbActual As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

JetGetAttachInfoInstanceA = ctypes.windll.esent.JetGetAttachInfoInstanceA
JetGetAttachInfoInstanceA.restype = ctypes.c_int
JetGetAttachInfoInstanceA.argtypes = [
    ctypes.c_size_t,  # instance : JET_INSTANCE
    ctypes.POINTER(ctypes.c_byte),  # szzDatabases : CHAR* optional, out
    wintypes.DWORD,  # cbMax : DWORD
    ctypes.POINTER(wintypes.DWORD),  # pcbActual : DWORD* optional, out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('ESENT.dll')
JetGetAttachInfoInstanceA = Fiddle::Function.new(
  lib['JetGetAttachInfoInstanceA'],
  [
    Fiddle::TYPE_UINTPTR_T,  # instance : JET_INSTANCE
    Fiddle::TYPE_VOIDP,  # szzDatabases : CHAR* optional, out
    -Fiddle::TYPE_INT,  # cbMax : DWORD
    Fiddle::TYPE_VOIDP,  # pcbActual : DWORD* optional, out
  ],
  Fiddle::TYPE_INT)

#[link(name = "esent")]
extern "system" {
    fn JetGetAttachInfoInstanceA(
        instance: usize,  // JET_INSTANCE
        szzDatabases: *mut i8,  // CHAR* optional, out
        cbMax: u32,  // DWORD
        pcbActual: *mut u32  // DWORD* optional, out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("ESENT.dll", CharSet = CharSet.Ansi)]
public static extern int JetGetAttachInfoInstanceA(UIntPtr instance, IntPtr szzDatabases, uint cbMax, IntPtr pcbActual);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetGetAttachInfoInstanceA' -Namespace Win32 -PassThru
# $api::JetGetAttachInfoInstanceA(instance, szzDatabases, cbMax, pcbActual)

#uselib "ESENT.dll"
#func global JetGetAttachInfoInstanceA "JetGetAttachInfoInstanceA" sptr, sptr, sptr, sptr
; JetGetAttachInfoInstanceA instance, varptr(szzDatabases), cbMax, varptr(pcbActual)   ; 戻り値は stat
; instance : JET_INSTANCE -> "sptr"
; szzDatabases : CHAR* optional, out -> "sptr"
; cbMax : DWORD -> "sptr"
; pcbActual : DWORD* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "ESENT.dll"
#cfunc global JetGetAttachInfoInstanceA "JetGetAttachInfoInstanceA" sptr, var, int, var
; res = JetGetAttachInfoInstanceA(instance, szzDatabases, cbMax, pcbActual)
; instance : JET_INSTANCE -> "sptr"
; szzDatabases : CHAR* optional, out -> "var"
; cbMax : DWORD -> "int"
; pcbActual : DWORD* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "ESENT.dll"
#cfunc global JetGetAttachInfoInstanceA "JetGetAttachInfoInstanceA" sptr, sptr, int, sptr
; res = JetGetAttachInfoInstanceA(instance, varptr(szzDatabases), cbMax, varptr(pcbActual))
; instance : JET_INSTANCE -> "sptr"
; szzDatabases : CHAR* optional, out -> "sptr"
; cbMax : DWORD -> "int"
; pcbActual : DWORD* optional, out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。