ホーム › System.Ole › OleCreateLinkFromDataEx

OleCreateLinkFromDataEx

関数

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

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

シグネチャ

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

HRESULT OleCreateLinkFromDataEx(
    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	リンクオブジェクトの作成元となるデータオブジェクトへのポインター。
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*	inout	IDataObject::DAdvise を使用して各アドバイザリ接続に pAdviseSink インターフェイスが登録されたときに返される dwConnection 値の配列を返す場所。返されるアドバイザリ接続が不要な場合は NULL を指定します。pAdviseSink が NULL の場合、このパラメーターは NULL でなければなりません。
pClientSite	IOleClientSite*	in	オブジェクトがコンテナーにサービスを要求する際に使用する主要なインターフェイスへのポインター。このパラメーターには NULL を指定できます。その場合、呼び出し元は IOleObject::SetClientSite を使用してできるだけ早くクライアントサイトを確立する責任があります。
pStg	IStorage*	in	オブジェクト、およびそのオブジェクトに対して確立された既定のデータキャッシュや表示キャッシュに使用するストレージへのポインター。
ppvObj	void**	out	riid で要求されたインターフェイスポインターを受け取る出力ポインター変数のアドレス。正常に復帰すると、*ppvObj には新しく作成されたオブジェクト上の要求されたインターフェイスポインターが格納されます。

戻り値の型: HRESULT

公式ドキュメント

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

戻り値

この関数は成功時に S_OK を返します。その他に返される可能性のある値には次のものがあります。

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

解説(Remarks)

次の OleCreateLinkFromData の呼び出し:

OleCreateLinkFromData(pSrcDataObj, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

は、次の OleCreateLinkFromDataEx の呼び出しと同等です:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateLinkFromDataEx(pSrcDataObj, riid, renderopt, 1, &advf, pFormatEtc, NULL, 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 OleCreateLinkFromDataEx(
    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 OleCreateLinkFromDataEx(
    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*
    ref uint rgdwConnection,   // DWORD* in/out
    IntPtr pClientSite,   // IOleClientSite*
    IntPtr pStg,   // IStorage*
    IntPtr ppvObj   // void** out
);

<DllImport("OLE32.dll", ExactSpelling:=True)>
Public Shared Function OleCreateLinkFromDataEx(
    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*
    ByRef rgdwConnection As UInteger,   ' DWORD* in/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* in/out
' pClientSite : IOleClientSite*
' pStg : IStorage*
' ppvObj : void** out
Declare PtrSafe Function OleCreateLinkFromDataEx 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

OleCreateLinkFromDataEx = ctypes.windll.ole32.OleCreateLinkFromDataEx
OleCreateLinkFromDataEx.restype = ctypes.c_int
OleCreateLinkFromDataEx.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* in/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')
OleCreateLinkFromDataEx = Fiddle::Function.new(
  lib['OleCreateLinkFromDataEx'],
  [
    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* in/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 OleCreateLinkFromDataEx(
        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* in/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 OleCreateLinkFromDataEx(IntPtr pSrcDataObj, ref Guid riid, uint dwFlags, uint renderopt, uint cFormats, ref uint rgAdvf, IntPtr rgFormatEtc, IntPtr lpAdviseSink, ref uint rgdwConnection, IntPtr pClientSite, IntPtr pStg, IntPtr ppvObj);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLE32_OleCreateLinkFromDataEx' -Namespace Win32 -PassThru
# $api::OleCreateLinkFromDataEx(pSrcDataObj, riid, dwFlags, renderopt, cFormats, rgAdvf, rgFormatEtc, lpAdviseSink, rgdwConnection, pClientSite, pStg, ppvObj)

#uselib "OLE32.dll"
#func global OleCreateLinkFromDataEx "OleCreateLinkFromDataEx" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; OleCreateLinkFromDataEx 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* in/out -> "sptr"
; pClientSite : IOleClientSite* -> "sptr"
; pStg : IStorage* -> "sptr"
; ppvObj : void** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

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