OleCreateLinkEx

関数

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

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

シグネチャ

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

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

パラメーター

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

戻り値の型: HRESULT

公式ドキュメント

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

戻り値

この関数は、成功した場合に S_OK を返します。その他に返される可能性のある値は次のとおりです。

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

解説(Remarks)

次の OleCreateLink の呼び出しは、

OleCreateLink(pmkLinkSrc, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

次の OleCreateLinkEx の呼び出しと同等です。

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateFromFileEx(pmkLinkSrc, 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 OleCreateLinkEx(
    IMoniker* pmkLinkSrc,
    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 OleCreateLinkEx(
    IntPtr pmkLinkSrc,   // IMoniker*
    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 OleCreateLinkEx(
    pmkLinkSrc As IntPtr,   ' IMoniker*
    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

' pmkLinkSrc : IMoniker*
' 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 OleCreateLinkEx Lib "ole32" ( _
    ByVal pmkLinkSrc 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

OleCreateLinkEx = ctypes.windll.ole32.OleCreateLinkEx
OleCreateLinkEx.restype = ctypes.c_int
OleCreateLinkEx.argtypes = [
    ctypes.c_void_p,  # pmkLinkSrc : IMoniker*
    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')
OleCreateLinkEx = Fiddle::Function.new(
  lib['OleCreateLinkEx'],
  [
    Fiddle::TYPE_VOIDP,  # pmkLinkSrc : IMoniker*
    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 OleCreateLinkEx(
        pmkLinkSrc: *mut core::ffi::c_void,  // IMoniker*
        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 OleCreateLinkEx(IntPtr pmkLinkSrc, 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_OleCreateLinkEx' -Namespace Win32 -PassThru
# $api::OleCreateLinkEx(pmkLinkSrc, riid, dwFlags, renderopt, cFormats, rgAdvf, rgFormatEtc, lpAdviseSink, rgdwConnection, pClientSite, pStg, ppvObj)

#uselib "OLE32.dll"
#func global OleCreateLinkEx "OleCreateLinkEx" sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; OleCreateLinkEx pmkLinkSrc, varptr(riid), dwFlags, renderopt, cFormats, varptr(rgAdvf), varptr(rgFormatEtc), lpAdviseSink, varptr(rgdwConnection), pClientSite, pStg, ppvObj   ; 戻り値は stat
; pmkLinkSrc : IMoniker* -> "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 OleCreateLinkEx "OleCreateLinkEx" sptr, var, int, int, int, var, var, sptr, var, sptr, sptr, sptr
; res = OleCreateLinkEx(pmkLinkSrc, riid, dwFlags, renderopt, cFormats, rgAdvf, rgFormatEtc, lpAdviseSink, rgdwConnection, pClientSite, pStg, ppvObj)
; pmkLinkSrc : IMoniker* -> "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 OleCreateLinkEx "OleCreateLinkEx" sptr, sptr, int, int, int, sptr, sptr, sptr, sptr, sptr, sptr, sptr
; res = OleCreateLinkEx(pmkLinkSrc, varptr(riid), dwFlags, renderopt, cFormats, varptr(rgAdvf), varptr(rgFormatEtc), lpAdviseSink, varptr(rgdwConnection), pClientSite, pStg, ppvObj)
; pmkLinkSrc : IMoniker* -> "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(変数))。