OleCreateEx

関数

複数フォーマットやアドバイズを指定して埋め込みOLEオブジェクトを作成する。

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

シグネチャ

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

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

パラメーター

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

戻り値の型: HRESULT

公式ドキュメント

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

戻り値

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

戻り値	説明
E_NOINTERFACE	指定されたインターフェイス識別子が無効です。

解説(Remarks)

次の OleCreate の呼び出しは:

OleCreate(rclsid, riid, renderopt, pFormatEtc, pClientSite, pStg, ppvObj);

次の OleCreateEx の呼び出しと等価です:

DWORD    advf = ADVF_PRIMEFIRST;
    OleCreateEx(rclsid, 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、そして単一形式ではなく形式の配列である pFormatEtc です。

複数のプレゼンテーションをオブジェクトのハンドラーによってキャッシュさせる必要のあるコンテナーは、単にこれらの関数を呼び出し、cFormats に形式の数、rgAdvf に各形式の ADVF フラグ、pFormatEtc に形式のセットを指定するだけで済みます。これらのコンテナーは 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 OleCreateEx(
    const GUID* rclsid,
    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 OleCreateEx(
    ref Guid rclsid,   // GUID*
    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 OleCreateEx(
    ByRef rclsid As Guid,   ' GUID*
    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

' rclsid : GUID*
' 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 OleCreateEx Lib "ole32" ( _
    ByVal rclsid 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

OleCreateEx = ctypes.windll.ole32.OleCreateEx
OleCreateEx.restype = ctypes.c_int
OleCreateEx.argtypes = [
    ctypes.c_void_p,  # rclsid : GUID*
    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')
OleCreateEx = Fiddle::Function.new(
  lib['OleCreateEx'],
  [
    Fiddle::TYPE_VOIDP,  # rclsid : GUID*
    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 OleCreateEx(
        rclsid: *const GUID,  // GUID*
        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 OleCreateEx(ref Guid rclsid, 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_OleCreateEx' -Namespace Win32 -PassThru
# $api::OleCreateEx(rclsid, riid, dwFlags, renderopt, cFormats, rgAdvf, rgFormatEtc, lpAdviseSink, rgdwConnection, pClientSite, pStg, ppvObj)

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