SafeArrayCreateEx

関数

追加情報を指定してSAFEARRAYを作成する。

DLLOLEAUT32.dll呼出規約winapi

シグネチャ

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

SAFEARRAY* SafeArrayCreateEx(
    VARENUM vt,
    DWORD cDims,
    SAFEARRAYBOUND* rgsabound,
    void* pvExtra
);

パラメーター

名前	型	方向	説明
vt	VARENUM	in	配列の各要素の基本型または VARTYPE。バリアント型 VT_RECORD には FADF_RECORD フラグを設定でき、VT_DISPATCH または VT_UNKNOWN には FADF_HAVEIID フラグを設定でき、その他すべての VARTYPE には FADF_HAVEVARTYPE を設定できます。
cDims	DWORD	in	配列の次元数。
rgsabound	SAFEARRAYBOUND*	in	配列に割り当てる境界のベクター(各次元に 1 つ)。
pvExtra	void*	in	ユーザー定義型のセーフ配列を作成する場合の、そのユーザー定義型の型情報。vt パラメーターが VT_RECORD の場合、pvExtra はレコードを記述する IRecordInfo へのポインターになります。vt パラメーターが VT_DISPATCH または VT_UNKNOWN の場合、pvExtra は配列に渡されるインターフェイスの型を表す GUID へのポインターを含みます。

戻り値の型: SAFEARRAY*

公式ドキュメント

指定された VARTYPE、次元数、および境界からセーフ配列記述子を作成して返します。

戻り値

セーフ配列記述子。配列を作成できなかった場合は null。

解説(Remarks)

VARTYPE が VT_RECORD の場合は SafeArraySetRecordInfo が呼び出されます。VARTYPE が VT_DISPATCH または VT_UNKNOWN の場合、配列の要素はすべて同じ型のインターフェイスを含んでいる必要があります。この配列を他のプロセスへマーシャリングする処理の一部には、pvExtra パラメーターが指す IID のプロキシ/スタブコードの生成が含まれます。実際に異種のインターフェイスを渡すには、pvExtra に IID_IUnknown または IID_IDispatch のいずれかを指定し、呼び出し側が実際のインターフェイスを照会する方法を識別できる別の手段を用意する必要があります。

Examples

次の例は、ユーザー定義型のセーフ配列を VT_RECORD 型のバリアントに格納する方法を示しています。

SAFEARRAYBOUND * sab;
sab.cElements = 2;
sab.lLbound = 0;
hresult hr;

SAFEARRAY Sa;
Sa = SafeArrayCreateEx(VT_RECORD, 1, &sab, pRecInfo);
if (Sa == NULL)
   return E_OUTOFMEMORY;

PVOID pvData;
hr = SafeArrayAccessData(Sa, &pvData);
if (FAILED(hr)) {
   SafeArrayDestroy(Sa);
   return hr;
}

TEST * pTest;
pTest = (TEST *)pvData;
pTest[0] = a;
pTest[1] = b;
hr = SafeArrayUnaccessData(Sa);
if (FAILED(hr)) {
   SafeArrayDestroy(Sa);
   return hr;
}

VariantInit(&variant);
V_VT(&variant) = VT_ARRAY|VT_RECORD;
V_ARRAY(&variant) = Sa;

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

各言語での呼び出し定義

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

SAFEARRAY* SafeArrayCreateEx(
    VARENUM vt,
    DWORD cDims,
    SAFEARRAYBOUND* rgsabound,
    void* pvExtra
);

[DllImport("OLEAUT32.dll", ExactSpelling = true)]
static extern IntPtr SafeArrayCreateEx(
    ushort vt,   // VARENUM
    uint cDims,   // DWORD
    IntPtr rgsabound,   // SAFEARRAYBOUND*
    IntPtr pvExtra   // void*
);

<DllImport("OLEAUT32.dll", ExactSpelling:=True)>
Public Shared Function SafeArrayCreateEx(
    vt As UShort,   ' VARENUM
    cDims As UInteger,   ' DWORD
    rgsabound As IntPtr,   ' SAFEARRAYBOUND*
    pvExtra As IntPtr   ' void*
) As IntPtr
End Function

' vt : VARENUM
' cDims : DWORD
' rgsabound : SAFEARRAYBOUND*
' pvExtra : void*
Declare PtrSafe Function SafeArrayCreateEx Lib "oleaut32" ( _
    ByVal vt As Integer, _
    ByVal cDims As Long, _
    ByVal rgsabound As LongPtr, _
    ByVal pvExtra As LongPtr) As LongPtr
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SafeArrayCreateEx = ctypes.windll.oleaut32.SafeArrayCreateEx
SafeArrayCreateEx.restype = ctypes.c_void_p
SafeArrayCreateEx.argtypes = [
    ctypes.c_ushort,  # vt : VARENUM
    wintypes.DWORD,  # cDims : DWORD
    ctypes.c_void_p,  # rgsabound : SAFEARRAYBOUND*
    ctypes.POINTER(None),  # pvExtra : void*
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLEAUT32.dll')
SafeArrayCreateEx = Fiddle::Function.new(
  lib['SafeArrayCreateEx'],
  [
    -Fiddle::TYPE_SHORT,  # vt : VARENUM
    -Fiddle::TYPE_INT,  # cDims : DWORD
    Fiddle::TYPE_VOIDP,  # rgsabound : SAFEARRAYBOUND*
    Fiddle::TYPE_VOIDP,  # pvExtra : void*
  ],
  Fiddle::TYPE_VOIDP)

#[link(name = "oleaut32")]
extern "system" {
    fn SafeArrayCreateEx(
        vt: u16,  // VARENUM
        cDims: u32,  // DWORD
        rgsabound: *mut SAFEARRAYBOUND,  // SAFEARRAYBOUND*
        pvExtra: *mut ()  // void*
    ) -> *mut SAFEARRAY;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLEAUT32.dll")]
public static extern IntPtr SafeArrayCreateEx(ushort vt, uint cDims, IntPtr rgsabound, IntPtr pvExtra);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLEAUT32_SafeArrayCreateEx' -Namespace Win32 -PassThru
# $api::SafeArrayCreateEx(vt, cDims, rgsabound, pvExtra)

#uselib "OLEAUT32.dll"
#func global SafeArrayCreateEx "SafeArrayCreateEx" sptr, sptr, sptr, sptr
; SafeArrayCreateEx vt, cDims, varptr(rgsabound), pvExtra   ; 戻り値は stat
; vt : VARENUM -> "sptr"
; cDims : DWORD -> "sptr"
; rgsabound : SAFEARRAYBOUND* -> "sptr"
; pvExtra : void* -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLEAUT32.dll"
#cfunc global SafeArrayCreateEx "SafeArrayCreateEx" int, int, var, sptr
; res = SafeArrayCreateEx(vt, cDims, rgsabound, pvExtra)
; vt : VARENUM -> "int"
; cDims : DWORD -> "int"
; rgsabound : SAFEARRAYBOUND* -> "var"
; pvExtra : void* -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLEAUT32.dll"
#cfunc global SafeArrayCreateEx "SafeArrayCreateEx" int, int, sptr, sptr
; res = SafeArrayCreateEx(vt, cDims, varptr(rgsabound), pvExtra)
; vt : VARENUM -> "int"
; cDims : DWORD -> "int"
; rgsabound : SAFEARRAYBOUND* -> "sptr"
; pvExtra : void* -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。