OleLoad

関数

ストレージから既存のOLEオブジェクトを読み込む。

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

シグネチャ

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

HRESULT OleLoad(
    IStorage* pStg,
    const GUID* riid,
    IOleClientSite* pClientSite,
    void** ppvObj
);

パラメーター

名前	型	方向	説明
pStg	IStorage*	in	指定されたオブジェクトの読み込み元となるストレージオブジェクト上の IStorage インターフェイスへのポインター。
riid	GUID*	in	オブジェクトの読み込み後に、呼び出し側がオブジェクトとの通信に使用したいインターフェイスの識別子への参照。
pClientSite	IOleClientSite*	in	読み込まれるクライアントサイトオブジェクト上の IOleClientSite インターフェイスへのポインター。
ppvObj	void**	out	riid で要求されたインターフェイスポインターを受け取るポインター変数のアドレス。正常に返された場合、*ppvObj には新しく読み込まれたオブジェクト上の要求されたインターフェイスポインターが格納されます。

戻り値の型: HRESULT

公式ドキュメント

指定されたストレージオブジェクト内に入れ子になったオブジェクトをメモリに読み込みます。

戻り値

この関数は成功時に S_OK を返します。その他に取り得る値には次のものがあります。

戻り値	説明
E_NOINTERFACE	オブジェクトが指定されたインターフェイスをサポートしていません。

さらに、この関数は IPersistStorage::Load メソッドが返すエラー値のいずれかを返すことがあります。

解説(Remarks)

OLE コンテナーは、この関数を呼び出すことでオブジェクトをメモリに読み込みます。OleLoad 関数を呼び出す際、コンテナーアプリケーションは、入れ子になったオブジェクトが格納されている開いた状態のストレージオブジェクトへのポインターを渡します。通常、読み込まれる入れ子のオブジェクトは、コンテナーのルートストレージオブジェクトの子ストレージオブジェクトです。オブジェクトと共に格納されている OLE 情報を使用して、オブジェクトハンドラー (通常は既定のハンドラー) がオブジェクトの読み込みを試みます。OleLoad 関数の完了時には、オブジェクトは読み込み済みの状態となり、そのオブジェクトアプリケーションは実行されていません。

一部のアプリケーションは、オブジェクトのネイティブデータをすべて読み込みます。コンテナーは多くの場合、必要になるまで格納されたオブジェクトの読み込みを遅延させます。たとえば、オブジェクトがスクロールされて表示範囲に入り、描画が必要になるまでは、そのオブジェクトを読み込む必要はありません。

OleLoad 関数は次の手順を実行します。

必要に応じて、オブジェクトの自動変換を実行します (OleDoAutoConvert 関数を参照)。
IStorage::Stat メソッドを呼び出して、開いた状態のストレージオブジェクトから CLSID を取得します。
CoCreateInstance 関数を呼び出して、ハンドラーのインスタンスを作成します。ハンドラーのコードが利用できない場合は、既定のハンドラーが使用されます (OleCreateDefaultHandler 関数を参照)。
pClientSite パラメーターを指定して IOleObject::SetClientSite メソッドを呼び出し、オブジェクトにそのクライアントサイトを通知します。
IPersistStorage インターフェイスに対して QueryInterface メソッドを呼び出します。成功した場合、オブジェクトに対して IPersistStorage::Load メソッドが呼び出されます。
riid パラメーターで識別されるインターフェイスを照会して返します。

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

各言語での呼び出し定義

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

HRESULT OleLoad(
    IStorage* pStg,
    const GUID* riid,
    IOleClientSite* pClientSite,
    void** ppvObj
);

[DllImport("OLE32.dll", ExactSpelling = true)]
static extern int OleLoad(
    IntPtr pStg,   // IStorage*
    ref Guid riid,   // GUID*
    IntPtr pClientSite,   // IOleClientSite*
    IntPtr ppvObj   // void** out
);

<DllImport("OLE32.dll", ExactSpelling:=True)>
Public Shared Function OleLoad(
    pStg As IntPtr,   ' IStorage*
    ByRef riid As Guid,   ' GUID*
    pClientSite As IntPtr,   ' IOleClientSite*
    ppvObj As IntPtr   ' void** out
) As Integer
End Function

' pStg : IStorage*
' riid : GUID*
' pClientSite : IOleClientSite*
' ppvObj : void** out
Declare PtrSafe Function OleLoad Lib "ole32" ( _
    ByVal pStg As LongPtr, _
    ByVal riid As LongPtr, _
    ByVal pClientSite As LongPtr, _
    ByVal ppvObj As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

OleLoad = ctypes.windll.ole32.OleLoad
OleLoad.restype = ctypes.c_int
OleLoad.argtypes = [
    ctypes.c_void_p,  # pStg : IStorage*
    ctypes.c_void_p,  # riid : GUID*
    ctypes.c_void_p,  # pClientSite : IOleClientSite*
    ctypes.c_void_p,  # ppvObj : void** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLE32.dll')
OleLoad = Fiddle::Function.new(
  lib['OleLoad'],
  [
    Fiddle::TYPE_VOIDP,  # pStg : IStorage*
    Fiddle::TYPE_VOIDP,  # riid : GUID*
    Fiddle::TYPE_VOIDP,  # pClientSite : IOleClientSite*
    Fiddle::TYPE_VOIDP,  # ppvObj : void** out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ole32")]
extern "system" {
    fn OleLoad(
        pStg: *mut core::ffi::c_void,  // IStorage*
        riid: *const GUID,  // GUID*
        pClientSite: *mut core::ffi::c_void,  // IOleClientSite*
        ppvObj: *mut *mut ()  // void** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLE32.dll")]
public static extern int OleLoad(IntPtr pStg, ref Guid riid, IntPtr pClientSite, IntPtr ppvObj);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLE32_OleLoad' -Namespace Win32 -PassThru
# $api::OleLoad(pStg, riid, pClientSite, ppvObj)

#uselib "OLE32.dll"
#func global OleLoad "OleLoad" sptr, sptr, sptr, sptr
; OleLoad pStg, varptr(riid), pClientSite, ppvObj   ; 戻り値は stat
; pStg : IStorage* -> "sptr"
; riid : GUID* -> "sptr"
; pClientSite : IOleClientSite* -> "sptr"
; ppvObj : void** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLE32.dll"
#cfunc global OleLoad "OleLoad" sptr, var, sptr, sptr
; res = OleLoad(pStg, riid, pClientSite, ppvObj)
; pStg : IStorage* -> "sptr"
; riid : GUID* -> "var"
; pClientSite : IOleClientSite* -> "sptr"
; ppvObj : void** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLE32.dll"
#cfunc global OleLoad "OleLoad" sptr, sptr, sptr, sptr
; res = OleLoad(pStg, varptr(riid), pClientSite, ppvObj)
; pStg : IStorage* -> "sptr"
; riid : GUID* -> "sptr"
; pClientSite : IOleClientSite* -> "sptr"
; ppvObj : void** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。