SafeArrayCreateEx function

Creates and returns a safe array descriptor from the specified VARTYPE, number of dimensions and bounds.


SAFEARRAY * SafeArrayCreateEx(
  VARTYPE        vt,
  UINT           cDims,
  SAFEARRAYBOUND *rgsabound,
  PVOID          pvExtra



The base type or the VARTYPE of each element of the array. The FADF_RECORD flag can be set for a variant type VT_RECORD, The FADF_HAVEIID flag can be set for VT_DISPATCH or VT_UNKNOWN, and FADF_HAVEVARTYPE can be set for all other VARTYPEs.


The number of dimensions in the array.


A vector of bounds (one for each dimension) to allocate for the array.


the type information of the user-defined type, if you are creating a safe array of user-defined types. If the vt parameter is VT_RECORD, then pvExtra will be a pointer to an IRecordInfo describing the record. If the vt parameter is VT_DISPATCH or VT_UNKNOWN, then pvExtra will contain a pointer to a GUID representing the type of interface being passed to the array.

Return value

A safe array descriptor, or null if the array could not be created.


If the VARTYPE is VT_RECORD then SafeArraySetRecordInfo is called. If the VARTYPE is VT_DISPATCH or VT_UNKNOWN then the elements of the array must contain interfaces of the same type. Part of the process of marshaling this array to other processes does include generating the proxy/stub code of the IID pointed to by the pvExtra parameter. To actually pass heterogeneous interfaces one will need to specify either IID_IUnknown or IID_IDispatch in pvExtra and provide some other means for the caller to identify how to query for the actual interface.


The following example describes how a safe array of user-defined types is stored into a variant of type VT_RECORD.

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

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

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

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

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


Target Platform Windows
Header oleauto.h
Library OleAut32.lib
DLL OleAut32.dll