SysAddRefString function (oleauto.h)

Article
02/22/2024

Note You should only call SysAddRefString if you are implementing a scripting engine that needs to guard against running potentially malicious scripts.

Increases the pinning reference count for the specified string by one.

Syntax

HRESULT SysAddRefString(
  [in] BSTR bstrString
);

Parameters

[in] bstrString

The string for which the pinning reference count should increase. While that count remains greater than 0, the memory for the string is prevented from being freed by calls to the SysFreeString function.

Return value

If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

Remarks

Strings with the BSTR data type have not traditionally had a reference count. All existing usage of these strings will continue to work with no changes. The SysAddRefString and SysReleaseString functions add the ability to use reference counting to pin the string into memory before calling from an untrusted script into an IDispatch method that may not expect the script to free that memory before the method returns, so that the script cannot force the code for that method into accessing memory that has been freed. After such a method safely returns, the pinning references should be released by calling SysReleaseString.

Requirements

Requirement	Value
Minimum supported client	Windows XP [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	oleauto.h
Library	Mincore.lib
DLL	Oleaut32.dll