Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This structure holds a safe array and its attributes.

Syntax 

typedef struct FARSTRUCT tagSAFEARRAY {
  unsigned short 
cDims;
  unsigned short 
fFeatures;
  unsigned short 
cbElements;
  unsigned short 
cLocks;
  unsigned long 
handle;
  void HUGEP* 
pvData;
  SAFEARRAYBOUND
 rgsabound[1];
} SAFEARRAY;

Members

cDims

Count of dimensions in this array.

fFeatures

Flags used by the SafeArrayroutines.

cbElements

Size of an element of the array. This does not include the size of pointed-to data.

cLocks

Number of times the array has been locked without corresponding unlock.

handle

Unused, but kept for compatibility.

pvData

Void pointer to the data.

rgsabound

One bound for each dimension.

Remarks

The array rgsaboundis stored with the left-most dimension in rgsabound[0] and the right-most dimension in rgsabound[ cDims1]. If an array was specified in a C-like syntax as a [2][5], it would have two elements in the rgsaboundvector. Element 0 has an lLboundof 0 and a cElementsof 2. Element 1 has an lLboundof 0 and a cElementsof 5.

The fFeaturesflags describe array attributes that can affect how the array is released. This allows freeing the array without referencing its containing variant. The bits are accessed using the following constants.

Copy Code 
#define FADF_AUTO 0x0001 // Array is allocated on the stack.
#define FADF_STATIC 0x0002 // Array is statically allocated.
#define FADF_EMBEDDED 0x0004 // Array is embedded in a structure.
#define FADF_FIXEDSIZE 0x0010 // Array may not be resized or 
 // reallocated.
#define FADF_BSTR 0x0100 // An array of BSTRs.
#define FADF_UNKNOWN 0x0200 // An array of IUnknown*.
#define FADF_DISPATCH 0x0400 // An array of IDispatch*.
#define FADF_VARIANT 0x0800 // An array of VARIANTs.
#define FADF_RESERVED 0xF0E8 // Bits reserved for future use.

Requirements

Header oaidl.h
Windows Embedded CE Windows CE 1.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also