HRESULT SafeArrayAddRef( SAFEARRAY *psa, PVOID *ppDataToRelease );
The safe array for which the pinning reference count of the descriptor should increase. While that count remains greater than 0, the memory for the descriptor is prevented from being freed by calls to the SafeArrayDestroy or SafeArrayDestroyDescriptor functions.
Returns the safe array data for which a pinning reference was added, if SafeArrayAddRef also added a pinning reference for the safe array data. This parameter is NULL if SafeArrayAddRef did not add a pinning reference for the safe array data. SafeArrayAddRef does not add a pinning reference for the safe array data if that safe array data was not dynamically allocated.
If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.
Safe arrays have not traditionally had a reference count. All existing usage of safe arrays will continue to work with no changes. The SafeArrayAddRef, SafeArrayReleaseData, SafeArrayReleaseDescriptor functions add the ability to use reference counting to pin the safe array 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. You can release the pinning references by calling the following functions:
- SafeArrayReleaseData, for the data that the ppDataToRelease parameter points to, if it is not null.
- SafeArrayReleaseDescriptor, for the descriptor that the psa parameter specifies.
|Minimum supported client||Windows XP [desktop apps only]|
|Minimum supported server||Windows Server 2003 [desktop apps only]|