SafeArrayCreateEx Function

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

SAFEARRAY SafeArrayCreateEx(  
  VARTYPE  vt,                     
  unsigned int  cDims,             
  SAFEARRAYBOUND * rgsabound  
  PVOID  pvExtra
);

vt

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. For more information about the FADF_RECORD, FADF_HAVEIID or FADF_HAVEVARTYPE flags see SAFEARRAY Data Type [Automation].

cDims

Number of dimensions in the array.

rgsabound

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

pvExtra

Points to 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.

Points to the 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 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:

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;
Show:
© 2014 Microsoft