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

JetGetAttachInfoA

関数
外部バックアップでアタッチ済みデータベース一覧を取得する(ANSI版)。
DLLESENT.dll文字セットANSI (-A)呼出規約winapi

シグネチャ

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

INT JetGetAttachInfoA(
    CHAR* szzDatabases,   // optional
    DWORD cbMax,
    DWORD* pcbActual   // optional
);

パラメーター

名前型方向説明
szzDatabasesCHAR*outoptionalアタッチ中データベースのパス一覧を受け取る出力ANSI文字列バッファポインタ。NUL区切りの多重文字列となる。
cbMaxDWORDinszzDatabasesバッファのサイズをバイト単位で指定する値。
pcbActualDWORD*outoptional実際に必要/書き込まれたバイト数を受け取る出力ポインタ。

戻り値の型: INT

公式ドキュメント

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

戻り値

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

リターン コード

説明

JET_errSuccess

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

JET_errBackupAbortByServer

現在の外部バックアップが JetStopBackup の呼び出しによって中止されたため、操作は失敗しました。このエラーは Windows XP 以降のリリースでのみ返されます。

JET_errClientRequestToStopJetService

JetStopService の呼び出しの結果、セッションに関連付けられたインスタンス上のすべての処理が停止しているため、操作を完了できません。

JET_errInstanceUnavailable

セッションに関連付けられたインスタンスで、データの整合性を保護するためにすべてのデータへのアクセスを取り消す必要がある致命的なエラーが発生したため、操作を完了できません。このエラーは Windows XP 以降のリリースでのみ返されます。

JET_errInvalidBackupSequence

呼び出しの順序が正しくなかったため、バックアップ操作は失敗しました。現在のバックアップがフル バックアップでない場合、JetGetAttachInfo はこのエラーを返します。

JET_errInvalidParameter

指定されたパラメーターのいずれかに予期しない値が含まれているか、別のパラメーターの値と組み合わせたときに意味をなさない値が含まれています。JetGetAttachInfo では、指定されたインスタンス ハンドルが無効な場合にこれが発生することがあります (Windows XP 以降のリリース)。

JET_errNoBackup

外部バックアップが進行中でないため、操作は失敗しました。

JET_errNotInitialized

セッションに関連付けられたインスタンスがまだ初期化されていないため、操作を完了できません。

JET_errRestoreInProgress

セッションに関連付けられたインスタンスで復元操作が進行中であるため、操作を完了できません。

JET_errRunningInMultiInstanceMode

実際には複数のインスタンスが既に存在しているにもかかわらず、サポートされるインスタンスが 1 つだけであるレガシー モード (Windows 2000 互換モード) でエンジンを使用しようとしたため、操作は失敗しました。

JET_errTermInProgress

セッションに関連付けられたインスタンスがシャットダウン中であるため、操作を完了できません。

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

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

解説

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

要件

要件 値

Client

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

Server

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

Header

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

Library

ESENT.lib を使用します。

DLL

ESENT.dll が必要です。

Unicode

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

関連項目

JET_ERR
JET_INSTANCE
JetAttachDatabase
JetBeginExternalBackup
JetOpenFile
JetReadFile
JetStopBackup
JetStopService

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

各言語での呼び出し定義

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

INT JetGetAttachInfoA(
    CHAR* szzDatabases,   // optional
    DWORD cbMax,
    DWORD* pcbActual   // optional
);
[DllImport("ESENT.dll", CharSet = CharSet.Ansi, ExactSpelling = true)]
static extern int JetGetAttachInfoA(
    IntPtr szzDatabases,   // CHAR* optional, out
    uint cbMax,   // DWORD
    IntPtr pcbActual   // DWORD* optional, out
);
<DllImport("ESENT.dll", CharSet:=CharSet.Ansi, ExactSpelling:=True)>
Public Shared Function JetGetAttachInfoA(
    szzDatabases As IntPtr,   ' CHAR* optional, out
    cbMax As UInteger,   ' DWORD
    pcbActual As IntPtr   ' DWORD* optional, out
) As Integer
End Function
' szzDatabases : CHAR* optional, out
' cbMax : DWORD
' pcbActual : DWORD* optional, out
Declare PtrSafe Function JetGetAttachInfoA Lib "esent" ( _
    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

JetGetAttachInfoA = ctypes.windll.esent.JetGetAttachInfoA
JetGetAttachInfoA.restype = ctypes.c_int
JetGetAttachInfoA.argtypes = [
    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')
JetGetAttachInfoA = Fiddle::Function.new(
  lib['JetGetAttachInfoA'],
  [
    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 JetGetAttachInfoA(
        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 JetGetAttachInfoA(IntPtr szzDatabases, uint cbMax, IntPtr pcbActual);
"@
$api = Add-Type -MemberDefinition $sig -Name 'ESENT_JetGetAttachInfoA' -Namespace Win32 -PassThru
# $api::JetGetAttachInfoA(szzDatabases, cbMax, pcbActual)
#uselib "ESENT.dll"
#func global JetGetAttachInfoA "JetGetAttachInfoA" sptr, sptr, sptr
; JetGetAttachInfoA varptr(szzDatabases), cbMax, varptr(pcbActual)   ; 戻り値は stat
; szzDatabases : CHAR* optional, out -> "sptr"
; cbMax : DWORD -> "sptr"
; pcbActual : DWORD* optional, out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。
出力引数:
#uselib "ESENT.dll"
#cfunc global JetGetAttachInfoA "JetGetAttachInfoA" var, int, var
; res = JetGetAttachInfoA(szzDatabases, cbMax, pcbActual)
; szzDatabases : CHAR* optional, out -> "var"
; cbMax : DWORD -> "int"
; pcbActual : DWORD* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
出力引数:
; INT JetGetAttachInfoA(CHAR* szzDatabases, DWORD cbMax, DWORD* pcbActual)
#uselib "ESENT.dll"
#cfunc global JetGetAttachInfoA "JetGetAttachInfoA" var, int, var
; res = JetGetAttachInfoA(szzDatabases, cbMax, pcbActual)
; szzDatabases : CHAR* optional, out -> "var"
; cbMax : DWORD -> "int"
; pcbActual : DWORD* optional, out -> "var"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。
import (
	"golang.org/x/sys/windows"
	"unsafe"
)

var (
	esent = windows.NewLazySystemDLL("ESENT.dll")
	procJetGetAttachInfoA = esent.NewProc("JetGetAttachInfoA")
)

// szzDatabases (CHAR* optional, out), cbMax (DWORD), pcbActual (DWORD* optional, out)
r1, _, err := procJetGetAttachInfoA.Call(
	uintptr(szzDatabases),
	uintptr(cbMax),
	uintptr(pcbActual),
)
_ = err  // syscall.Errno (valid when the call sets last-error)
_ = r1   // INT
function JetGetAttachInfoA(
  szzDatabases: Pointer;   // CHAR* optional, out
  cbMax: DWORD;   // DWORD
  pcbActual: Pointer   // DWORD* optional, out
): Integer; stdcall;
  external 'ESENT.dll' name 'JetGetAttachInfoA';
result := DllCall("ESENT\JetGetAttachInfoA"
    , "Ptr", szzDatabases   ; CHAR* optional, out
    , "UInt", cbMax   ; DWORD
    , "Ptr", pcbActual   ; DWORD* optional, out
    , "Int")   ; return: INT
●JetGetAttachInfoA(szzDatabases, cbMax, pcbActual) = DLL("ESENT.dll", "int JetGetAttachInfoA(void*, dword, void*)")
# 呼び出し: JetGetAttachInfoA(szzDatabases, cbMax, pcbActual)
# szzDatabases : CHAR* optional, out -> "void*"
# cbMax : DWORD -> "dword"
# pcbActual : DWORD* optional, out -> "void*"
# なでしこ1は32bit・ANSI(Shift_JIS)。文字列=char*(ANSI)、ポインタ/ハンドル=void*(4byte)。
const std = @import("std");

extern "esent" fn JetGetAttachInfoA(
    szzDatabases: [*c]i8, // CHAR* optional, out
    cbMax: u32, // DWORD
    pcbActual: [*c]u32 // DWORD* optional, out
) callconv(std.os.windows.WINAPI) i32;
proc JetGetAttachInfoA(
    szzDatabases: ptr int8,  # CHAR* optional, out
    cbMax: uint32,  # DWORD
    pcbActual: ptr uint32  # DWORD* optional, out
): int32 {.importc: "JetGetAttachInfoA", stdcall, dynlib: "ESENT.dll".}
pragma(lib, "esent");
extern(Windows)
int JetGetAttachInfoA(
    byte* szzDatabases,   // CHAR* optional, out
    uint cbMax,   // DWORD
    uint* pcbActual   // DWORD* optional, out
);
ccall((:JetGetAttachInfoA, "ESENT.dll"), stdcall, Int32,
      (Ptr{Int8}, UInt32, Ptr{UInt32}),
      szzDatabases, cbMax, pcbActual)
# szzDatabases : CHAR* optional, out -> Ptr{Int8}
# cbMax : DWORD -> UInt32
# pcbActual : DWORD* optional, out -> Ptr{UInt32}
# stdcall は 32bit のみ意味を持つ(x64 では無視)。
local ffi = require("ffi")
ffi.cdef[[
int32_t JetGetAttachInfoA(
    int8_t* szzDatabases,
    uint32_t cbMax,
    uint32_t* pcbActual);
]]
local esent = ffi.load("esent")
-- esent.JetGetAttachInfoA(szzDatabases, cbMax, pcbActual)
-- szzDatabases : CHAR* optional, out
-- cbMax : DWORD
-- pcbActual : DWORD* optional, out
-- 構造体/GUIDへのポインタは cdef が通るよう void* で表記(実型は各引数コメント参照)。値渡し構造体・enum は対応する typedef を cdef に追加すること。
const koffi = require('koffi');
const lib = koffi.load('ESENT.dll');
const JetGetAttachInfoA = lib.func('__stdcall', 'JetGetAttachInfoA', 'int32_t', ['int8_t *', 'uint32_t', 'uint32_t *']);
// JetGetAttachInfoA(szzDatabases, cbMax, pcbActual)
// szzDatabases : CHAR* optional, out -> 'int8_t *'
// cbMax : DWORD -> 'uint32_t'
// pcbActual : DWORD* optional, out -> 'uint32_t *'
// 出力ポインタは koffi.out(...) で包む。構造体は koffi.struct で定義。
const lib = Deno.dlopen("ESENT.dll", {
  JetGetAttachInfoA: { parameters: ["pointer", "u32", "pointer"], result: "i32" },
});
// lib.symbols.JetGetAttachInfoA(szzDatabases, cbMax, pcbActual)
// szzDatabases : CHAR* optional, out -> "pointer"
// cbMax : DWORD -> "u32"
// pcbActual : DWORD* optional, out -> "pointer"
// 文字列は "buffer"。ANSI(-A) は new TextEncoder() で UTF-8/ANSI バイト列(末尾に \x00)を渡す。
// 値渡し構造体は { struct: [ ...field types... ] } を使用。
<?php
$ffi = FFI::cdef(<<<C
int32_t JetGetAttachInfoA(
    int8_t* szzDatabases,
    uint32_t cbMax,
    uint32_t* pcbActual);
C, "ESENT.dll");
// $ffi->JetGetAttachInfoA(szzDatabases, cbMax, pcbActual);
// szzDatabases : CHAR* optional, out
// cbMax : DWORD
// pcbActual : DWORD* optional, out
// 構造体/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.ASCII_OPTIONS);
    int JetGetAttachInfoA(
        byte[] szzDatabases,   // CHAR* optional, out
        int cbMax,   // DWORD
        IntByReference pcbActual   // DWORD* optional, out
    );
}
@[Link("esent")]
lib LibESENT
  fun JetGetAttachInfoA = JetGetAttachInfoA(
    szzDatabases : Int8*,   # CHAR* optional, out
    cbMax : UInt32,   # DWORD
    pcbActual : UInt32*   # DWORD* optional, out
  ) : Int32
end
# 構造体/GUID/enum は lib 内に対応する型定義が必要。
# 呼出規約: x64 は規約統一のため OK。x86(32bit)は WINAPI=stdcall だが Crystal の fun に stdcall 付与構文がなく非対応。
import 'dart:ffi';
import 'package:ffi/ffi.dart';

typedef JetGetAttachInfoANative = Int32 Function(Pointer<Int8>, Uint32, Pointer<Uint32>);
typedef JetGetAttachInfoADart = int Function(Pointer<Int8>, int, Pointer<Uint32>);
final JetGetAttachInfoA = DynamicLibrary.open('ESENT.dll')
    .lookupFunction<JetGetAttachInfoANative, JetGetAttachInfoADart>('JetGetAttachInfoA');
// szzDatabases : CHAR* optional, out -> Pointer<Int8>
// cbMax : DWORD -> Uint32
// pcbActual : DWORD* optional, out -> Pointer<Uint32>
// 文字列は package:ffi の "...".toNativeUtf16()/toNativeUtf8() で変換。
{$mode objfpc}{$H+}
function JetGetAttachInfoA(
  szzDatabases: Pointer;   // CHAR* optional, out
  cbMax: DWORD;   // DWORD
  pcbActual: Pointer   // DWORD* optional, out
): Integer; stdcall;
  external 'ESENT.dll' name 'JetGetAttachInfoA';
import Foreign
import Foreign.C.Types
import Foreign.C.String

foreign import stdcall safe "JetGetAttachInfoA"
  c_JetGetAttachInfoA :: Ptr Int8 -> Word32 -> Ptr Word32 -> IO Int32
-- szzDatabases : CHAR* optional, out -> Ptr Int8
-- cbMax : DWORD -> Word32
-- pcbActual : DWORD* optional, out -> Ptr Word32
-- 要 GHC(Windows)。stdcall は x64 では ccall として扱われる。ブロックする API は safe 呼び出し推奨。
open Ctypes
open Foreign

let jetgetattachinfoa =
  foreign "JetGetAttachInfoA"
    ((ptr int8_t) @-> uint32_t @-> (ptr uint32_t) @-> returning int32_t)
(* szzDatabases : CHAR* optional, out -> (ptr int8_t) *)
(* cbMax : DWORD -> uint32_t *)
(* pcbActual : DWORD* optional, out -> (ptr uint32_t) *)
(* foreign は cdecl 前提。x64 Windows では WINAPI と一致。構造体は ctypes structure を定義のこと。 *)
(cffi:define-foreign-library esent (t "ESENT.dll"))
(cffi:use-foreign-library esent)

(cffi:defcfun ("JetGetAttachInfoA" jet-get-attach-info-a :convention :stdcall) :int32
  (szz-databases :pointer)   ; CHAR* optional, out
  (cb-max :uint32)   ; DWORD
  (pcb-actual :pointer))   ; DWORD* optional, out
; isize/usize(INT_PTR/SIZE_T)は x64 前提で :int64/:uint64。x86 では :int32/:uint32。
use Win32::API;
my $JetGetAttachInfoA = Win32::API::More->new('ESENT',
    'int JetGetAttachInfoA(LPVOID szzDatabases, DWORD cbMax, LPVOID pcbActual)');
# my $ret = $JetGetAttachInfoA->Call($szzDatabases, $cbMax, $pcbActual);
# szzDatabases : CHAR* optional, out -> LPVOID
# cbMax : DWORD -> DWORD
# pcbActual : DWORD* optional, out -> LPVOID
# 値渡し構造体は pack() した文字列、または Win32::API::Struct を使用。

関連項目

文字セット違い