ホーム › System.Com.StructuredStorage › StgOpenStorageOnILockBytes

StgOpenStorageOnILockBytes

関数

ILockBytes上の複合ドキュメントを開きルートストレージを取得する。

DLLOLE32.dll呼出規約winapi対応OSWindows 2000 以降

シグネチャ

// OLE32.dll
#include <windows.h>

HRESULT StgOpenStorageOnILockBytes(
    ILockBytes* plkbyt,
    IStorage* pstgPriority,   // optional
    STGM grfMode,
    WORD** snbExclude,   // optional
    DWORD reserved,   // optional
    IStorage** ppstgOpen
);

パラメーター

名前	型	方向	説明
plkbyt	ILockBytes*	in	開くストレージオブジェクトを格納している、基盤となるバイト配列オブジェクトへの ILockBytes ポインター。
pstgPriority	IStorage*	inoptional	IStorage インターフェイスへのポインター。NULL を指定してください。NULL でない場合、このパラメーターは後述の「解説」セクションで説明するように使用されます。 StgOpenStorageOnILockBytes から制御が戻った後、pStgPriority で指定したストレージオブジェクトは解放されている可能性があり、以後使用しないでください。
grfMode	STGM	in	ストレージオブジェクトを開く際に使用するアクセスモードを指定します。詳細については、STGM Constants および後述の「解説」セクションを参照してください。
snbExclude	WORD**	inoptional	NULL を指定できます。NULL でない場合、このパラメーターは、ストレージオブジェクトを開く際に除外するこのストレージ内の要素のブロックを指します。この除外は、開くときにスナップショットコピーが行われるかどうかとは無関係に発生します。
reserved	DWORD	optional	将来の使用のために予約されています。0 でなければなりません。
ppstgOpen	IStorage**	out	正常終了時に、開かれたストレージへの IStorage ポインターの格納場所を指します。

戻り値の型: HRESULT

公式ドキュメント

StgOpenStorageOnILockBytes 関数は、ディスクファイル上には存在せず、代わりに呼び出し元が提供するバイト配列を基盤として持つ既存のストレージオブジェクトを開きます。

戻り値

StgOpenStorageOnILockBytes 関数は、ファイルシステムエラー、HRESULT でラップされたシステムエラー、または ILockBytes インターフェイスのエラー戻り値を返すこともあります。 Error Handling Strategies および Handling Unknown Errors を参照してください。

解説(Remarks)

StgOpenStorageOnILockBytes は、指定されたルートストレージオブジェクトを開きます。開かれたストレージオブジェクト上の IStorage インターフェイスへのポインターは、ppstgOpen パラメーターを通じて返されます。

対象のストレージオブジェクトは、事前に StgCreateDocfileOnILockBytes 関数で作成されている必要があります。

プログラマーが提供するバイト配列オブジェクトを指定する点を除けば、 StgOpenStorageOnILockBytes は StgOpenStorage 関数と同様です。ストレージオブジェクトは grfMode パラメーターのアクセスモードに従って開かれますが、次の制限があります。

共有モードの動作とトランザクションの分離は、ILockBytes の実装が LOCK_ONLYONCE のセマンティクスによる LockRegion と UnlockRegion をサポートしているかどうかに依存します。実装は、STATSTG の grfLocksSupported メンバーに LOCK_ONLYONCE ビットを設定することで、この機能をサポートしていることを構造化ストレージに示すことができます。ILockBytes の実装がこの機能をサポートしていない場合、共有モードは強制されず、ルートレベルのトランザクションのコミットは、同じバイト配列上で開かれた他のトランザクションインスタンスと適切に協調しません。CreateStreamOnHGlobal の実装のように、領域ロックをサポートしない ILockBytes 実装を使用するアプリケーションでは、同じバイト配列上で複数のインスタンスを同時に開くことは避けてください。

StgOpenStorageOnILockBytes はシンプルモードをサポートしません。STGM_SIMPLE フラグが指定されていても無視されます。

pStgPriority パラメーターは、既存のストレージオブジェクト (多くの場合、優先モードで開かれたもの) を、同じバイト配列上で開いた新しいストレージオブジェクトで置き換える呼び出し元のための便宜として用意されています。StgOpenStorage の pStgPriority パラメーターとは異なり、このパラメーターは StgOpenStorageOnILockBytes が行う開く操作には影響せず、単に呼び出し元が解放したい既存のストレージオブジェクトを表すにすぎません。StgOpenStorageOnILockBytes は、状況によってこのオブジェクトを解放したり解放しなかったりするため、呼び出し元はこのパラメーターに常に NULL を渡してください。 pStgPriority パラメーターの用途は、次の例に示すように、StgOpenStorageOnILockBytes を呼び出す前に呼び出し元自身がオブジェクトを解放することで、より安全な方法で同等に実現できます。

// 次の呼び出しの代替:
// HRESULT hr = StgOpenStorageOnILockBytes(
//         plkbyt, pStgPriority, grfMode, NULL, 0, &pstgNew);

pStgPriority->Release();
pStgPriority = NULL;
hr = StgOpenStorage(plkbyt, NULL, grfMode, NULL, 0, &pstgNew);

詳細については、 StgOpenStorage を参照してください。

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

各言語での呼び出し定義

// OLE32.dll
#include <windows.h>

HRESULT StgOpenStorageOnILockBytes(
    ILockBytes* plkbyt,
    IStorage* pstgPriority,   // optional
    STGM grfMode,
    WORD** snbExclude,   // optional
    DWORD reserved,   // optional
    IStorage** ppstgOpen
);

[DllImport("OLE32.dll", ExactSpelling = true)]
static extern int StgOpenStorageOnILockBytes(
    IntPtr plkbyt,   // ILockBytes*
    IntPtr pstgPriority,   // IStorage* optional
    uint grfMode,   // STGM
    IntPtr snbExclude,   // WORD** optional
    uint reserved,   // DWORD optional
    IntPtr ppstgOpen   // IStorage** out
);

<DllImport("OLE32.dll", ExactSpelling:=True)>
Public Shared Function StgOpenStorageOnILockBytes(
    plkbyt As IntPtr,   ' ILockBytes*
    pstgPriority As IntPtr,   ' IStorage* optional
    grfMode As UInteger,   ' STGM
    snbExclude As IntPtr,   ' WORD** optional
    reserved As UInteger,   ' DWORD optional
    ppstgOpen As IntPtr   ' IStorage** out
) As Integer
End Function

' plkbyt : ILockBytes*
' pstgPriority : IStorage* optional
' grfMode : STGM
' snbExclude : WORD** optional
' reserved : DWORD optional
' ppstgOpen : IStorage** out
Declare PtrSafe Function StgOpenStorageOnILockBytes Lib "ole32" ( _
    ByVal plkbyt As LongPtr, _
    ByVal pstgPriority As LongPtr, _
    ByVal grfMode As Long, _
    ByVal snbExclude As LongPtr, _
    ByVal reserved As Long, _
    ByVal ppstgOpen As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

StgOpenStorageOnILockBytes = ctypes.windll.ole32.StgOpenStorageOnILockBytes
StgOpenStorageOnILockBytes.restype = ctypes.c_int
StgOpenStorageOnILockBytes.argtypes = [
    ctypes.c_void_p,  # plkbyt : ILockBytes*
    ctypes.c_void_p,  # pstgPriority : IStorage* optional
    wintypes.DWORD,  # grfMode : STGM
    ctypes.c_void_p,  # snbExclude : WORD** optional
    wintypes.DWORD,  # reserved : DWORD optional
    ctypes.c_void_p,  # ppstgOpen : IStorage** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLE32.dll')
StgOpenStorageOnILockBytes = Fiddle::Function.new(
  lib['StgOpenStorageOnILockBytes'],
  [
    Fiddle::TYPE_VOIDP,  # plkbyt : ILockBytes*
    Fiddle::TYPE_VOIDP,  # pstgPriority : IStorage* optional
    -Fiddle::TYPE_INT,  # grfMode : STGM
    Fiddle::TYPE_VOIDP,  # snbExclude : WORD** optional
    -Fiddle::TYPE_INT,  # reserved : DWORD optional
    Fiddle::TYPE_VOIDP,  # ppstgOpen : IStorage** out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ole32")]
extern "system" {
    fn StgOpenStorageOnILockBytes(
        plkbyt: *mut core::ffi::c_void,  // ILockBytes*
        pstgPriority: *mut core::ffi::c_void,  // IStorage* optional
        grfMode: u32,  // STGM
        snbExclude: *mut *mut u16,  // WORD** optional
        reserved: u32,  // DWORD optional
        ppstgOpen: *mut *mut core::ffi::c_void  // IStorage** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLE32.dll")]
public static extern int StgOpenStorageOnILockBytes(IntPtr plkbyt, IntPtr pstgPriority, uint grfMode, IntPtr snbExclude, uint reserved, IntPtr ppstgOpen);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLE32_StgOpenStorageOnILockBytes' -Namespace Win32 -PassThru
# $api::StgOpenStorageOnILockBytes(plkbyt, pstgPriority, grfMode, snbExclude, reserved, ppstgOpen)

#uselib "OLE32.dll"
#func global StgOpenStorageOnILockBytes "StgOpenStorageOnILockBytes" sptr, sptr, sptr, sptr, sptr, sptr
; StgOpenStorageOnILockBytes plkbyt, pstgPriority, grfMode, varptr(snbExclude), reserved, ppstgOpen   ; 戻り値は stat
; plkbyt : ILockBytes* -> "sptr"
; pstgPriority : IStorage* optional -> "sptr"
; grfMode : STGM -> "sptr"
; snbExclude : WORD** optional -> "sptr"
; reserved : DWORD optional -> "sptr"
; ppstgOpen : IStorage** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLE32.dll"
#cfunc global StgOpenStorageOnILockBytes "StgOpenStorageOnILockBytes" sptr, sptr, int, var, int, sptr
; res = StgOpenStorageOnILockBytes(plkbyt, pstgPriority, grfMode, snbExclude, reserved, ppstgOpen)
; plkbyt : ILockBytes* -> "sptr"
; pstgPriority : IStorage* optional -> "sptr"
; grfMode : STGM -> "int"
; snbExclude : WORD** optional -> "var"
; reserved : DWORD optional -> "int"
; ppstgOpen : IStorage** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLE32.dll"
#cfunc global StgOpenStorageOnILockBytes "StgOpenStorageOnILockBytes" sptr, sptr, int, sptr, int, sptr
; res = StgOpenStorageOnILockBytes(plkbyt, pstgPriority, grfMode, varptr(snbExclude), reserved, ppstgOpen)
; plkbyt : ILockBytes* -> "sptr"
; pstgPriority : IStorage* optional -> "sptr"
; grfMode : STGM -> "int"
; snbExclude : WORD** optional -> "sptr"
; reserved : DWORD optional -> "int"
; ppstgOpen : IStorage** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。