ホーム › System.Ole › OleCreateFromDataEx

OleCreateFromDataEx

関数

拡張オプション付きでデータから埋め込みOLEオブジェクトを作成する。

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

シグネチャ

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

HRESULT OleCreateFromDataEx(
    IDataObject* pSrcDataObj,
    const GUID* riid,
    OLECREATE dwFlags,
    DWORD renderopt,
    DWORD cFormats,
    DWORD* rgAdvf,
    FORMATETC* rgFormatEtc,
    IAdviseSink* lpAdviseSink,
    DWORD* rgdwConnection,
    IOleClientSite* pClientSite,
    IStorage* pStg,
    void** ppvObj
);

パラメーター

名前	型	方向	説明
pSrcDataObj	IDataObject*	in	新しいオブジェクトの作成に使用される新しいデータを保持するデータ転送オブジェクトへのポインターです(OleCreateFromData を参照)。
riid	GUID*	in	返すオブジェクトのインターフェイスの識別子への参照です。
dwFlags	OLECREATE	in	このパラメーターには 0 または OLECREATE_LEAVERUNNING (0x00000001) を指定できます。
renderopt	DWORD	in	OLERENDER 列挙体から取得した値です。
cFormats	DWORD	in	renderopt が OLERENDER_FORMAT の場合、rgFormatEtc 配列内の FORMATETC 構造体の数を示します。この値は少なくとも 1 でなければなりません。それ以外の場合、このパラメーターは 0 でなければなりません。
rgAdvf	DWORD*	in	renderopt が OLERENDER_FORMAT の場合、DWORD 要素の配列へのポインターです。各要素は ADVF 列挙体の値の組み合わせです。この配列の各要素は、pAdviseSink が NULL か非 NULL かに応じて、IOleCache::Cache または IDataObject::DAdvise の呼び出しに advf パラメーターとして渡されます(下記参照)。それ以外の場合、このパラメーターは NULL でなければなりません。
rgFormatEtc	FORMATETC*	in	renderopt が OLERENDER_FORMAT の場合、FORMATETC 構造体の配列へのポインターです。pAdviseSink が NULL の場合、この配列の各要素はオブジェクトの IOleCache::Cache 呼び出しの pFormatEtc パラメーターとして渡されます。これにより、オブジェクトのインプロセスハンドラー(通常は既定のハンドラー)が管理するデータおよびプレゼンテーションのキャッシュに、プレゼンテーションその他のキャッシュ可能なデータが設定されます。pAdviseSink が非 NULL の場合、この配列の各要素は IDataObject::DAdvise 呼び出しの pFormatEtc パラメーターとして渡されます。これにより、呼び出し元(通常は OLE コンテナー)は、オブジェクトから受け取ったデータの独自のキャッシュや処理を行えます。
lpAdviseSink	IAdviseSink*	in	renderopt が OLERENDER_FORMAT の場合、データの通知に対するカスタムキャッシュまたは処理を示す有効な IAdviseSink ポインター、またはデータ形式の既定のキャッシュを示す NULL のいずれかを指定できます。
rgdwConnection	DWORD*	out	IDataObject::DAdvise を使用して各アドバイザリ接続に対して IAdviseSink インターフェイスが登録されたときに返される dwConnection 値の配列を返す場所です。返されるアドバイザリ接続が不要な場合は NULL を指定します。pAdviseSink が NULL の場合、このパラメーターは NULL でなければなりません。
pClientSite	IOleClientSite*	in	オブジェクトがコンテナーにサービスを要求する際に使用する主インターフェイスへのポインターです。このパラメーターには NULL を指定できます。その場合、IOleObject::SetClientSite を使用して、できるだけ早くクライアントサイトを確立するのは呼び出し元の責任となります。
pStg	IStorage*	in	オブジェクト、およびそのために確立される既定のデータまたはプレゼンテーションのキャッシュに使用するストレージへのポインターです。
ppvObj	void**	out	riid で要求したインターフェイスポインターを受け取る出力ポインター変数のアドレスです。正常に返ると、*ppvObj には、新しく作成されたオブジェクト上の要求されたインターフェイスポインターが格納されます。

戻り値の型: HRESULT

公式ドキュメント

OleCreateFromData の機能を拡張し、OleCreateFromData がサポートする単一形式の代わりに、プレゼンテーションまたはデータの複数形式のキャッシュを必要とするコンテナーにおいて、オブジェクトをより効率的にインスタンス化できるようにします。

戻り値

この関数は成功時に S_OK を返します。その他に返される可能性のある値は以下のとおりです。

戻り値	説明
E_NOINTERFACE	指定されたインターフェイス識別子が無効です。
E_INVALIDARG	1 つ以上のパラメーターが無効です。

解説(Remarks)

次の OleCreateFromData の呼び出し:

OleCreateFromData(lpszFileName, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

は、次の OleCreateFromDataEx の呼び出しと同等です。

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(rclsid, lpszFileName, riid, renderopt, 1, &advf, pFormatEtc, NULL, pClientSite, pStg, ppvObj);

既存のインスタンス化関数(OleCreate、OleCreateFromFile、OleCreateFromData、OleCreateLink、OleCreateLinkToFile、OleCreateLinkFromData)は、インスタンス化の際に既定のキャッシュ場所(渡された IStorage の '\001OlePresXXX' ストリーム内)に、単一のプレゼンテーションまたはデータ形式のキャッシュのみを作成します。さらに、これらのキャッシュは、オブジェクトが次に実行状態に入ったときに作成される必要があります。ほとんどのアプリケーションは少なくとも 2 つのプレゼンテーション(画面とプリンター)をキャッシュする必要があり、またハンドラーとは異なる形式や場所でデータをキャッシュする必要がある場合もあるため、アプリケーションは通常、オブジェクト作成時(つまり Insert Object、Insert Object from File、Paste Object)にデータキャッシュを準備するために、オブジェクトサーバーの起動とシャットダウンを複数回繰り返す必要があります。

これらの作成関数の拡張版は、この問題を解決します。OleCreateEx、OleCreateFromFileEx、OleCreateFromDataEx、OleCreateLinkEx、OleCreateLinkToFileEx、OleCreateLinkFromDataEx には、次の新しいパラメーターが含まれています。追加のオプションを示す dwFlags、キャッシュする形式の数を示す cFormats、キャッシュする各形式のアドバイズフラグを指定する ADVF 列挙体由来の rgAdvf、プレゼンテーション(既定のハンドラー)キャッシュとデータ(非既定ハンドラー)キャッシュのどちらが必要かを示す pAdviseSink、IDataObject::DAdvise のクッキーを返す rgdwConnection、そして単一の形式ではなく形式の配列である rgFormatEtc です。

オブジェクトのハンドラーによって複数のプレゼンテーションを自身に代わってキャッシュさせることを必要とするコンテナーは、単にこれらの関数を呼び出し、cFormats に形式の数、rgAdvf に各形式の ADVF フラグ、rgFormatEtc に形式のセットを指定するだけで済みます。これらのコンテナーは pAdviseSink に NULL を渡します。

データまたはプレゼンテーションのキャッシュをすべて自身で行うコンテナーは、これらと同じ手順を実行しますが、非 NULL の pAdviseSink を渡します。これらのコンテナーは、IAdviseSink::OnDataChange の処理中に、オブジェクトまたはデータの独自のキャッシュや操作を行います。通常、こうしたコンテナーは ADVF_NODATA でアドバイザリ接続を確立することはありませんが、そうすることが禁じられているわけではありません。

これらの新しい関数は OLE 複合ドキュメント向けです。これらの関数を使用することで、アプリケーションは現行の関数で必要とされる起動と初期化の手順の繰り返しを回避できます。これらは、既定のデータおよびプレゼンテーションのキャッシュを使用する OLE 複合ドキュメントのコンテナーアプリケーション、および基盤となる IDataObject::DAdvise のサポートから独自のキャッシュおよびデータ転送を行うアプリケーションを対象としています。

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

各言語での呼び出し定義

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

HRESULT OleCreateFromDataEx(
    IDataObject* pSrcDataObj,
    const GUID* riid,
    OLECREATE dwFlags,
    DWORD renderopt,
    DWORD cFormats,
    DWORD* rgAdvf,
    FORMATETC* rgFormatEtc,
    IAdviseSink* lpAdviseSink,
    DWORD* rgdwConnection,
    IOleClientSite* pClientSite,
    IStorage* pStg,
    void** ppvObj
);

[DllImport("OLE32.dll", ExactSpelling = true)]
static extern int OleCreateFromDataEx(
    IntPtr pSrcDataObj,   // IDataObject*
    ref Guid riid,   // GUID*
    uint dwFlags,   // OLECREATE
    uint renderopt,   // DWORD
    uint cFormats,   // DWORD
    ref uint rgAdvf,   // DWORD*
    IntPtr rgFormatEtc,   // FORMATETC*
    IntPtr lpAdviseSink,   // IAdviseSink*
    out uint rgdwConnection,   // DWORD* out
    IntPtr pClientSite,   // IOleClientSite*
    IntPtr pStg,   // IStorage*
    IntPtr ppvObj   // void** out
);

<DllImport("OLE32.dll", ExactSpelling:=True)>
Public Shared Function OleCreateFromDataEx(
    pSrcDataObj As IntPtr,   ' IDataObject*
    ByRef riid As Guid,   ' GUID*
    dwFlags As UInteger,   ' OLECREATE
    renderopt As UInteger,   ' DWORD
    cFormats As UInteger,   ' DWORD
    ByRef rgAdvf As UInteger,   ' DWORD*
    rgFormatEtc As IntPtr,   ' FORMATETC*
    lpAdviseSink As IntPtr,   ' IAdviseSink*
    <Out> ByRef rgdwConnection As UInteger,   ' DWORD* out
    pClientSite As IntPtr,   ' IOleClientSite*
    pStg As IntPtr,   ' IStorage*
    ppvObj As IntPtr   ' void** out
) As Integer
End Function

' pSrcDataObj : IDataObject*
' riid : GUID*
' dwFlags : OLECREATE
' renderopt : DWORD
' cFormats : DWORD
' rgAdvf : DWORD*
' rgFormatEtc : FORMATETC*
' lpAdviseSink : IAdviseSink*
' rgdwConnection : DWORD* out
' pClientSite : IOleClientSite*
' pStg : IStorage*
' ppvObj : void** out
Declare PtrSafe Function OleCreateFromDataEx Lib "ole32" ( _
    ByVal pSrcDataObj As LongPtr, _
    ByVal riid As LongPtr, _
    ByVal dwFlags As Long, _
    ByVal renderopt As Long, _
    ByVal cFormats As Long, _
    ByRef rgAdvf As Long, _
    ByVal rgFormatEtc As LongPtr, _
    ByVal lpAdviseSink As LongPtr, _
    ByRef rgdwConnection As Long, _
    ByVal pClientSite As LongPtr, _
    ByVal pStg 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

OleCreateFromDataEx = ctypes.windll.ole32.OleCreateFromDataEx
OleCreateFromDataEx.restype = ctypes.c_int
OleCreateFromDataEx.argtypes = [
    ctypes.c_void_p,  # pSrcDataObj : IDataObject*
    ctypes.c_void_p,  # riid : GUID*
    wintypes.DWORD,  # dwFlags : OLECREATE
    wintypes.DWORD,  # renderopt : DWORD
    wintypes.DWORD,  # cFormats : DWORD
    ctypes.POINTER(wintypes.DWORD),  # rgAdvf : DWORD*
    ctypes.c_void_p,  # rgFormatEtc : FORMATETC*
    ctypes.c_void_p,  # lpAdviseSink : IAdviseSink*
    ctypes.POINTER(wintypes.DWORD),  # rgdwConnection : DWORD* out
    ctypes.c_void_p,  # pClientSite : IOleClientSite*
    ctypes.c_void_p,  # pStg : IStorage*
    ctypes.c_void_p,  # ppvObj : void** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLE32.dll')
OleCreateFromDataEx = Fiddle::Function.new(
  lib['OleCreateFromDataEx'],
  [
    Fiddle::TYPE_VOIDP,  # pSrcDataObj : IDataObject*
    Fiddle::TYPE_VOIDP,  # riid : GUID*
    -Fiddle::TYPE_INT,  # dwFlags : OLECREATE
    -Fiddle::TYPE_INT,  # renderopt : DWORD
    -Fiddle::TYPE_INT,  # cFormats : DWORD
    Fiddle::TYPE_VOIDP,  # rgAdvf : DWORD*
    Fiddle::TYPE_VOIDP,  # rgFormatEtc : FORMATETC*
    Fiddle::TYPE_VOIDP,  # lpAdviseSink : IAdviseSink*
    Fiddle::TYPE_VOIDP,  # rgdwConnection : DWORD* out
    Fiddle::TYPE_VOIDP,  # pClientSite : IOleClientSite*
    Fiddle::TYPE_VOIDP,  # pStg : IStorage*
    Fiddle::TYPE_VOIDP,  # ppvObj : void** out
  ],
  Fiddle::TYPE_INT)

#[link(name = "ole32")]
extern "system" {
    fn OleCreateFromDataEx(
        pSrcDataObj: *mut core::ffi::c_void,  // IDataObject*
        riid: *const GUID,  // GUID*
        dwFlags: u32,  // OLECREATE
        renderopt: u32,  // DWORD
        cFormats: u32,  // DWORD
        rgAdvf: *mut u32,  // DWORD*
        rgFormatEtc: *mut FORMATETC,  // FORMATETC*
        lpAdviseSink: *mut core::ffi::c_void,  // IAdviseSink*
        rgdwConnection: *mut u32,  // DWORD* out
        pClientSite: *mut core::ffi::c_void,  // IOleClientSite*
        pStg: *mut core::ffi::c_void,  // IStorage*
        ppvObj: *mut *mut ()  // void** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLE32.dll")]
public static extern int OleCreateFromDataEx(IntPtr pSrcDataObj, ref Guid riid, uint dwFlags, uint renderopt, uint cFormats, ref uint rgAdvf, IntPtr rgFormatEtc, IntPtr lpAdviseSink, out uint rgdwConnection, IntPtr pClientSite, IntPtr pStg, IntPtr ppvObj);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLE32_OleCreateFromDataEx' -Namespace Win32 -PassThru
# $api::OleCreateFromDataEx(pSrcDataObj, riid, dwFlags, renderopt, cFormats, rgAdvf, rgFormatEtc, lpAdviseSink, rgdwConnection, pClientSite, pStg, ppvObj)

#uselib "OLE32.dll"
#func global OleCreateFromDataEx "OleCreateFromDataEx" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; OleCreateFromDataEx pSrcDataObj, varptr(riid), dwFlags, renderopt, cFormats, varptr(rgAdvf), varptr(rgFormatEtc), lpAdviseSink, varptr(rgdwConnection), pClientSite, pStg, ppvObj   ; 戻り値は stat
; pSrcDataObj : IDataObject* -> "sptr"
; riid : GUID* -> "sptr"
; dwFlags : OLECREATE -> "sptr"
; renderopt : DWORD -> "sptr"
; cFormats : DWORD -> "sptr"
; rgAdvf : DWORD* -> "sptr"
; rgFormatEtc : FORMATETC* -> "sptr"
; lpAdviseSink : IAdviseSink* -> "sptr"
; rgdwConnection : DWORD* out -> "sptr"
; pClientSite : IOleClientSite* -> "sptr"
; pStg : IStorage* -> "sptr"
; ppvObj : void** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLE32.dll"
#cfunc global OleCreateFromDataEx "OleCreateFromDataEx" sptr, var, int, int, int, var, var, sptr, var, sptr, sptr, sptr
; res = OleCreateFromDataEx(pSrcDataObj, riid, dwFlags, renderopt, cFormats, rgAdvf, rgFormatEtc, lpAdviseSink, rgdwConnection, pClientSite, pStg, ppvObj)
; pSrcDataObj : IDataObject* -> "sptr"
; riid : GUID* -> "var"
; dwFlags : OLECREATE -> "int"
; renderopt : DWORD -> "int"
; cFormats : DWORD -> "int"
; rgAdvf : DWORD* -> "var"
; rgFormatEtc : FORMATETC* -> "var"
; lpAdviseSink : IAdviseSink* -> "sptr"
; rgdwConnection : DWORD* out -> "var"
; pClientSite : IOleClientSite* -> "sptr"
; pStg : IStorage* -> "sptr"
; ppvObj : void** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLE32.dll"
#cfunc global OleCreateFromDataEx "OleCreateFromDataEx" sptr, sptr, int, int, int, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; res = OleCreateFromDataEx(pSrcDataObj, varptr(riid), dwFlags, renderopt, cFormats, varptr(rgAdvf), varptr(rgFormatEtc), lpAdviseSink, varptr(rgdwConnection), pClientSite, pStg, ppvObj)
; pSrcDataObj : IDataObject* -> "sptr"
; riid : GUID* -> "sptr"
; dwFlags : OLECREATE -> "int"
; renderopt : DWORD -> "int"
; cFormats : DWORD -> "int"
; rgAdvf : DWORD* -> "sptr"
; rgFormatEtc : FORMATETC* -> "sptr"
; lpAdviseSink : IAdviseSink* -> "sptr"
; rgdwConnection : DWORD* out -> "sptr"
; pClientSite : IOleClientSite* -> "sptr"
; pStg : IStorage* -> "sptr"
; ppvObj : void** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。