2.2.30.10 SAFEARRAY

The SAFEARRAY structure defines a multidimensional array of OLE automation types. The definitions of SAFEARRAY data types provided in this section correspond to the wire formats of these data types.<10>

 typedef[unique] 
    struct _wireSAFEARRAY {
   USHORT cDims;
   USHORT fFeatures;
   ULONG cbElements;
   ULONG cLocks;
   SAFEARRAYUNION uArrayStructs;
   [size_is(cDims)] SAFEARRAYBOUND rgsabound[];
 } *SAFEARRAY;

cDims: MUST be set to the number of dimensions of the array. cDims MUST NOT be set to 0.

fFeatures: MUST be set to a combination of the bit flags specified in section 2.2.9.

cbElements: MUST be set to the size, in bytes, of an element in the SAFEARRAY, as specified in the table in section 2.2.8.

cLocks: If the fFeatures field contains FADF_HAVEVARTYPE (see section 2.2.9), the cLocks field MUST contain a VARIANT (section 2.2.7) type constant in its high word that specifies the type of the elements in the array. Otherwise, the high word of the cLocks field MUST be set to 0.

The low word of the cLocks field MAY<11> be set to an implementation-specific value, and MUST be ignored on receipt.

uArrayStructs: MUST be a SAFEARRAYUNION (section 2.2.30.9).

rgsabound: MUST contain an array of bounds, specifying the shape of the array. This array MUST be represented in reverse order. That is, for an array [0:5][0:2][0:10], the bounds would be represented as (10, 0), (2, 0), (5, 0).

The following consistency statements MUST hold, where sfType is the discriminant field in the SAFEARRAYUNION data member.

If sfType equals	fFeatures MUST be set to
SF_HAVEIID	FADF_UNKNOWN | FADF_HAVEIID or FADF_DISPATCH | FADF_HAVEIID
SF_BSTR	FADF_BSTR or FADF_BSTR | FADF_HAVEVARTYPE
SF_UNKNOWN	FADF_UNKNOWN or FADF_UNKNOWN | FADF_HAVEVARTYPE or FADF_UNKNOWN | FADF_HAVEIID
SF_DISPATCH	FADF_DISPATCH or FADF_DISPATCH | FADF_HAVEVARTYPE or FADF_DISPATCH | FADF_HAVEIID
SF_VARIANT	FADF_VARIANT or FADF_VARIANT | FADF_HAVEVARTYPE
SF_RECORD	FADF_RECORD

If fFeatures field specifies FADF_HAVEVARTYPE, the following additional statements MUST hold, where vt is the high word of the cLocks field.

If vt (the high word of cLocks) equals	sfType MUST be set to
VT_I1 VT_UI1	SF_I1
VT_I2 VT_UI2 VT_BOOL	SF_I2
VT_ERROR VT_I4 VT_UI4 VT_R4 VT_INT VT_UINT	SF_I4
VT_I8 VT_UI8 VT_R8 VT_CY VT_DATE	SF_I8
VT_BSTR	SF_BSTR
VT_VARIANT	SF_VARIANT
VT_UNKNOWN	SF_UNKNOWN or SF_HAVEIID
VT_DISPATCH	SF_DISPATCH or SF_HAVEIID
VT_RECORD	SF_RECORD

In addition, the type of vt MUST NOT equal VT_DECIMAL.

If any of the consistency checks fail, the protocol implementation SHOULD<12>

Data of this type MUST be marshaled as specified in [C706] section 14, with the exception that it MUST be marshaled by using a little-endian data representation, regardless of the data representation format label. For more information, see [C706] section 14.2.5.