SafeArrayAddRef

関数

SAFEARRAYの参照カウントを増やしロックする。

DLLOLEAUT32.dll呼出規約winapi対応OSWindows XP 以降

シグネチャ

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

HRESULT SafeArrayAddRef(
    SAFEARRAY* psa,
    void** ppDataToRelease
);

パラメーター

名前	型	方向	説明
psa	SAFEARRAY*	in	ディスクリプタのピン留め参照カウントを増やす対象の safe array。このカウントが 0 より大きい間は、SafeArrayDestroy 関数や SafeArrayDestroyDescriptor 関数の呼び出しによってディスクリプタのメモリが解放されることが防止されます。
ppDataToRelease	void**	out	SafeArrayAddRef が safe array のデータに対してもピン留め参照を追加した場合に、ピン留め参照が追加された safe array のデータを返します。SafeArrayAddRef が safe array のデータに対してピン留め参照を追加しなかった場合、このパラメーターは NULL になります。safe array のデータが動的に割り当てられていない場合、SafeArrayAddRef はそのデータに対してピン留め参照を追加しません。

戻り値の型: HRESULT

公式ドキュメント

指定された safe array のディスクリプタのピン留め参照カウントを 1 つ増やします。また、そのデータが動的に割り当てられている場合(safe array のディスクリプタによって判定されます)は、指定された safe array のデータのピン留め参照カウントも 1 つ増やすことがあります。

戻り値

この関数が成功した場合は S_OK を返します。それ以外の場合は HRESULT エラーコードを返します。

解説(Remarks)

safe array には従来、参照カウントがありませんでした。safe array の既存の使用方法はすべて、変更なしで引き続き動作します。SafeArrayAddRef、SafeArrayReleaseData、SafeArrayReleaseDescriptor の各関数は、信頼できないスクリプトから IDispatch メソッドを呼び出す前に、参照カウントを使用して safe array をメモリにピン留めする機能を追加します。これは、メソッドが返る前にスクリプトがそのメモリを解放することを想定していないメソッドに対して、スクリプトがそのメソッドのコードに解放済みメモリへアクセスさせることを防ぐためのものです。そのようなメソッドが安全に返った後は、ピン留め参照を解放する必要があります。ピン留め参照は、次の関数を呼び出すことで解放できます。

SafeArrayReleaseData: ppDataToRelease パラメーターが指すデータが null でない場合、そのデータに対して使用します。
SafeArrayReleaseDescriptor: psa パラメーターが指定するディスクリプタに対して使用します。

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

各言語での呼び出し定義

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

HRESULT SafeArrayAddRef(
    SAFEARRAY* psa,
    void** ppDataToRelease
);

[DllImport("OLEAUT32.dll", ExactSpelling = true)]
static extern int SafeArrayAddRef(
    IntPtr psa,   // SAFEARRAY*
    IntPtr ppDataToRelease   // void** out
);

<DllImport("OLEAUT32.dll", ExactSpelling:=True)>
Public Shared Function SafeArrayAddRef(
    psa As IntPtr,   ' SAFEARRAY*
    ppDataToRelease As IntPtr   ' void** out
) As Integer
End Function

' psa : SAFEARRAY*
' ppDataToRelease : void** out
Declare PtrSafe Function SafeArrayAddRef Lib "oleaut32" ( _
    ByVal psa As LongPtr, _
    ByVal ppDataToRelease As LongPtr) As Long
' VBA7前提(PtrSafe)。32bit Office では LongPtr→Long。Integer=16bit / Long=32bit / LongLong=64bit。

import ctypes
from ctypes import wintypes

SafeArrayAddRef = ctypes.windll.oleaut32.SafeArrayAddRef
SafeArrayAddRef.restype = ctypes.c_int
SafeArrayAddRef.argtypes = [
    ctypes.c_void_p,  # psa : SAFEARRAY*
    ctypes.c_void_p,  # ppDataToRelease : void** out
]

require 'fiddle'
require 'fiddle/import'

lib = Fiddle.dlopen('OLEAUT32.dll')
SafeArrayAddRef = Fiddle::Function.new(
  lib['SafeArrayAddRef'],
  [
    Fiddle::TYPE_VOIDP,  # psa : SAFEARRAY*
    Fiddle::TYPE_VOIDP,  # ppDataToRelease : void** out
  ],
  Fiddle::TYPE_INT)

#[link(name = "oleaut32")]
extern "system" {
    fn SafeArrayAddRef(
        psa: *mut SAFEARRAY,  // SAFEARRAY*
        ppDataToRelease: *mut *mut ()  // void** out
    ) -> i32;
}
// crates: windows-sys provides ready-made bindings for this API.

$sig = @"
[DllImport("OLEAUT32.dll")]
public static extern int SafeArrayAddRef(IntPtr psa, IntPtr ppDataToRelease);
"@
$api = Add-Type -MemberDefinition $sig -Name 'OLEAUT32_SafeArrayAddRef' -Namespace Win32 -PassThru
# $api::SafeArrayAddRef(psa, ppDataToRelease)

#uselib "OLEAUT32.dll"
#func global SafeArrayAddRef "SafeArrayAddRef" sptr, sptr
; SafeArrayAddRef varptr(psa), ppDataToRelease   ; 戻り値は stat
; psa : SAFEARRAY* -> "sptr"
; ppDataToRelease : void** out -> "sptr"
; ※HSP3.7は #func のため戻り値はシステム変数 stat に格納されます。

出力引数:

#uselib "OLEAUT32.dll"
#cfunc global SafeArrayAddRef "SafeArrayAddRef" var, sptr
; res = SafeArrayAddRef(psa, ppDataToRelease)
; psa : SAFEARRAY* -> "var"
; ppDataToRelease : void** out -> "sptr"
; ※出力/バッファ引数は var 方式(変数を直接渡す)。varptr 方式にも切替可。#uselib "OLEAUT32.dll"
#cfunc global SafeArrayAddRef "SafeArrayAddRef" sptr, sptr
; res = SafeArrayAddRef(varptr(psa), ppDataToRelease)
; psa : SAFEARRAY* -> "sptr"
; ppDataToRelease : void** out -> "sptr"
; ※出力/バッファ引数はポインタ方式(token=sptr / 呼び出しは varptr(変数))。