SAFEARRAY structure (oaidl.h)

Article
09/01/2022

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

Share via