SAFEARRAY structure (oaidl.h)

Represents a safe array.

Syntax

typedef struct tagSAFEARRAY {
  USHORT         cDims;
  USHORT         fFeatures;
  ULONG          cbElements;
  ULONG          cLocks;
  PVOID          pvData;
  SAFEARRAYBOUND rgsabound[1];
} SAFEARRAY;

Members

cDims

The number of dimensions.

fFeatures

Flags.

Value Meaning
FADF_AUTO
0x0001
An array that is allocated on the stack.
FADF_STATIC
0x0002
An array that is statically allocated.
FADF_EMBEDDED
0x0004
An array that is embedded in a structure.
FADF_FIXEDSIZE
0x0010
An array that may not be resized or reallocated.
FADF_RECORD
0x0020
An array that contains records. When set, there will be a pointer to the IRecordInfo interface at negative offset 4 in the array descriptor.
FADF_HAVEIID
0x0040
An array that has an IID identifying interface. When set, there will be a GUID at negative offset 16 in the safe array descriptor. Flag is set only when FADF_DISPATCH or FADF_UNKNOWN is also set.
FADF_HAVEVARTYPE
0x0080
An array that has a variant type. The variant type can be retrieved with SafeArrayGetVartype.
FADF_BSTR
0x0100
An array of BSTRs.
FADF_UNKNOWN
0x0200
An array of IUnknown*.
FADF_DISPATCH
0x0400
An array of IDispatch*.
FADF_VARIANT
0x0800
An array of VARIANTs.
FADF_RESERVED
0xF008
Bits reserved for future use.

cbElements

The size of an array element.

cLocks

The number of times the array has been locked without a corresponding unlock.

pvData

The data.

rgsabound[1]

One bound for each dimension.

Remarks

The array rgsabound is stored with the left-most dimension in rgsabound[0] and the right-most dimension in rgsabound[cDims - 1]. If an array was specified in a C-like syntax as a [2][5], it would have two elements in the rgsabound vector. Element 0 has an lLbound of 0 and a cElements of 2. Element 1 has an lLbound of 0 and a cElements of 5.

The fFeatures flags describe attributes of an array that can affect how the array is released. The fFeatures field describes what type of data is stored in the SAFEARRAY and how the array is allocated. This allows freeing the array without referencing its containing variant.

Thread Safety

All public static members of the SAFEARRAY data type are thread safe. Instance members are not guaranteed to be thread safe.

For example, consider an application that uses the SafeArrayLock and SafeArrayUnlock functions. If these functions are called concurrently from different threads on the same SAFEARRAY data type instance, an inconsistent lock count may be created. This will eventually cause the SafeArrayUnlock function to return E_UNEXPECTED. You can prevent this by providing your own synchronization code.

Requirements

Requirement Value
Header oaidl.h