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.