2.2.1.7 Array Data Types - Non-Groupable
This section specifies the encoding of array data types. The encoding of all arrays has a common form:
The first two bytes are a datatype identifier for the array. Arrays MUST have the same datatype for every element.
An array metadata section, which specifies key features of the array and specifies syntax and semantics for the data following the array metadata. The syntax of the array metadata section is described by ARRAYMD.
An array data element section, which consists of an array of actual data elements of a data type specified in the preceding ARRAYMD. The number of data elements in the array is determined in ARRAYMD. If the datatype identifier is VT-ARRAY-EMPTY or VT-ARRAY-NULL, the elements section MUST be omitted.
Alternately, the datatype identifier can be followed by the one-byte NULLARRAY constant instead of the ARRAYMD and the array elements, which specifies that the array has no data and is the last byte in the serialization of the array.
All array types in RDST are non-groupable. The syntax of an encoded array, known as ARRAY-VTDATA-NONGROUPABLE, is
-
ARRAY-VTDATA-NONGROUPABLE = FIXED-LEN-ARRAY BSTR-ARRAY / VARIANT-ARRAY / UNKNOWN-ARRAY / DISPATCH-ARRAY FIXED-LEN-ARRAY = EMPTY-ARRAY / I2-ARRAY / I4-ARRAY / R4-ARRAY / R8-ARRAY / CY-ARRAY / DATE-ARRAY / ERROR-ARRAY / BOOL-ARRAY / UI1-ARRAY EMPTY-ARRAY = VT-ARRAY-EMPTY / VT-ARRAY-NULL NULLARRAY / ( ARRAYMD ()) I2-ARRAY = VT-ARRAY-I2 NULLARRAY / (ARRAYMD *WORD) I4-ARRAY = VT-ARRAY-I4 NULLARRAY / (ARRAYMD *LONG) R4-ARRAY = VT-ARRAY-R4 NULLARRAY / (ARRAYMD *FLOAT) R8-ARRAY = VT-ARRAY-R8 NULLARRAY / (ARRAYMD *DOUBLE) CY-ARRAY = VT-ARRAY-CY NULLARRAY / (ARRAYMD *CY) DATE-ARRAY = VT-ARRAY-DATE NULLARRAY / (ARRAYMD *DATE) ERROR-ARRAY = VT-ARRAY-ERROR NULLARRAY / (ARRAYMD *VARIANTERROR) BOOL-ARRAY = VT-ARRAY-BOOL NULLARRAY / (ARRAYMD *VARIANT-BOOL) UI1-ARRAY = VT-ARRAY-UI1 NULLARRAY / (ARRAYMD *BYTE) ARRAYMD = ZEROBYTE NUMDIMS ARRAYFEATURES-FIXED-VT SIZEOFELEMENT BOUNDSDATA BSTR-ARRAY = VT-ARRAY-BSTR NULLARRAY / ( ZEROBYTE NUMDIMS ARRAYFEATURES-BSTR SIZEOFELEMBSTR BOUNDSDATA SAFEARRAYDATABSTR ) VARIANT-ARRAY = VT-ARRAY-VARIANT NULLARRAY / ( ZEROBYTE NUMDIMS ARRAYFEATURES-VARIANT SIZEOFELEMVARIANT BOUNDSDATA SAFEARRAYDATAVARIANT ) UNKNOWN-ARRAY = VT-ARRAY-UNKNOWN NULLARRAY / ( ZEROBYTE NUMDIMS ARRAYFEATURES-UNKNOWN SIZEOFELEMINTERFACE BOUNDSDATA SAFEARRAYDATAINTERFACE ) DISPATCH-ARRAY = VT-ARRAY-DISPATCH NULLARRAY / ( ZEROBYTE NUMDIMS ARRAYFEATURES-DISPATCH SIZEOFELEMINTERFACE BOUNDSDATA SAFEARRAYDATAINTERFACE ) NULLARRAY = NULLINDICATOR NUMDIMS = USHORT SIZEOFELEMENT = ULONG SIZEOFELEMBSTR = %x04.00.00.00 SIZEOFELEMVARIANT = %x10.00.00.00 SIZEOFELEMINTERFACE = %x04.00.00.00 BOUNDSDATA = *(SAFEARRAYBOUND) SAFEARRAYBOUND = SAFEARRAYBOUNDELEMS SAFEARRAYBOUNDLOWER SAFEARRAYBOUNDELEMS = ULONG SAFEARRAYBOUNDLOWER = LONG SAFEARRAYDATABSTR = *BSTRNULLABLE SAFEARRAYDATAINTERFACE = *INTERFACEVAL SAFEARRAYDATAVARIANT = *(FIXED-LEN-VTDATA-GROUPABLE / VAR-LEN-VTDATA-GROUPABLE / EXTERNAL-VTDATA-NONGROUPABLE / ARRAY-VTDATA-NONGROUPABLE)
ARRAYFEATURES:
Datatype: USHORT
A 2-byte bit field that represents features of the array. The type of the array used imposes constraints on the range of values of ARRAYFEATURES as listed below.<14> The syntax of ARRAYFEATURES is
ARRAYFEATURES = ARRAYFEATURES-FIXED-VT / ARRAYFEATURES-BSTR / ARRAYFEATURES-UNKNOWN / ARRAYFEATURES-DISPATCH / ARRAYFEATURES-VARIANT ARRAYFEATURES-FIXED-VT = FADF-FIXED-LEN-BIT ARRAYOPTIMIZATIONS FADF-FIXED-LEN-TYPE ARRAYFEATURES-BSTR = FADF-VAR-LEN-BIT ARRAYOPTIMIZATIONS FADF-BSTR-TYPE ARRAYFEATURES-UNKNOWN = FADF-VAR-LEN-BIT ARRAYOPTIMIZATIONS FADF-UNKNOWN-TYPE ARRAYFEATURES-DISPATCH = FADF-VAR-LEN-BIT ARRAYOPTIMIZATIONS FADF-DISPATCH-TYPE ARRAYFEATURES-VARIANT = FADF-VAR-LEN-BIT ARRAYOPTIMIZATIONS FADF-VARIANT-TYPE ARRAYOPTIMIZATIONS = RESERVEDBIT ; bitmask %x40.00 FADF-HAVEVARTYPE-BIT; bitmask %x80.00 FADF-RECORD-BIT ; bitmask %x20.00 RESERVEDBIT ; bitmask %x10.00 RESERVEDBIT ; bitmask %x08.00 FADF-EMBEDDED-BIT ; bitmask %x04.00 FADF-STATIC-BIT ; bitmask %x02.00 FADF-AUTO-BIT ; bitmask %x01.00 FADF-HAVEVARTYPE-BIT = BIT FADF-RECORD-BIT = BIT FADF-EMBEDDED-BIT = BIT FADF-STATIC-BIT = BIT FADF-AUTO-BIT = BIT FADF-BSTR-TYPE = %x01 FADF-UNKNOWN-TYPE = %x02 FADF-DISPATCH-TYPE = %x04 FADF-VARIANT-TYPE = %x08 FADF-FIXED-LEN-TYPE = ZEROBYTE FADF-FIXED-LEN-BIT = %b1 FADF-VAR-LEN-BIT = ZEROBIT
FADF-RECORD-BIT: An array optimization bit that can be set to ZEROBIT, and can be safely ignored. However, for implementers wanting to implement the optimization technique, the following invariant can be used to optimize allocation, deallocation, and lookup techniques. When the value FADF-RECORD-BIT is %b1, each element in the array MUST have the same length in bytes.
FADF-AUTO-BIT, FADF-STATIC-BIT, and FADF-EMBEDDED-BIT: These bits indicate the use of memory-management optimizations. These bits can be set in the in-memory data structure that is encoded as an ARRAY-VTDATA-NONGROUPABLE, and as part of ARRAYFEATURES. However, these bits have no meaning to the receiver and MUST be ignored.
FADF-BSTR-TYPE, FADF-UNKNOWN-TYPE, FADF-DISPATCH-TYPE, FADF-VARIANT-TYPE, FADF-FIXED-LEN-TYPE: These bytes specify the data type of the array elements.
FADF-FIXED-LEN-BIT: This bit is set to %b1 in ARRAYFEATURES-FIXED-VT to indicate a fixed length array.
FADF-VAR-LEN-BIT: This bit is set to ZEROBIT in ARRAYFEATURES-BSTR, ARRAYFEATURES-UNKNOWN, ARRAYFEATURES-DISPATCH, and ARRAYFEATURES-VARIANT to indicate a variable length array.
SIZEOFELEMENT:
Datatype: USHORT
The length, in bytes, of each element in the array. For arrays of the variable-length types VT-ARRAY-BSTR, VT-ARRAY-VARIANT, VT-ARRAY-UNKNOWN, and VT-ARRAY-DISPATCH, the special constants SIZEOFELEMBSTR, SIZEOFELEMVARIANT, and SIZEOFELEMINTERFACE are used in place of SIZEOFELEMENT.
BOUNDSDATA: Defines the size of each dimension of the array parameter. SAFEARRAYBOUND MUST occur exactly NUMDIMS times.
NUMDIMS: The number of dimensions of the array parameter used in the BOUNDSDATA field. NUMDIMS MUST be greater than zero. A maximum limit MAY be imposed by the implementation of the protocol.
SAFEARRAYBOUND: Represents the bounds of one dimension of the array. The lower bound of the dimension is represented by SAFEARRAYBOUNDLOWER. This allows the declaration of arrays that are not zero-based. SAFEARRAYBOUNDELEMS represents the number of elements in the dimension.
The first dimension appears in the first occurrence of SAFEARRAYBOUND. Additional bounds are represented in order. If an array was specified in a C-like syntax as a [2][5], it would have two occurrences of SAFEARRAYBOUND in the BOUNDSDATA component. The first occurrence of SAFEARRAYBOUND would have SAFEARRAYBOUNDLOWER of 0 and SAFEARRAYBOUNDELEMS of 2. The second occurrence would have SAFEARRAYBOUNDLOWER of 0 and SAFEARRAYBOUNDELEMS of 5. For more information, see [MSDN-SAFEARRAY].
The actual data of an array are elements of a specific data type following the array metadata. The total number of elements in the array is calculated as the product of the value of SAFEARRAYBOUNDELEMS components of all occurrences of SAFEARRAYBOUND in the preceding BOUNDSDATA component.
For example, if an array is two-dimensional and has dimensions two and five, then NUMDIMS will be 2, and two occurrences of SAFEARRAYBOUND will be present inside the BOUNDSDATA component. The total number of elements will be 10 (2 * 5).
In this example, the array has 10 elements. They occur in order from the lowest dimension to the highest. For this example the array elements would encode as follows:
[0][0], [0][1], [0][2], [0][3], [0][4], [1][0], [1][1], [1][2], [1][3], [1][4], [1][5]