Safe array

In computer programming, a safe array is a data type provided in the Windows API as a handle to a dynamic array. It is also referred to by its typedef SAFEARRAY. A Component Object Model (COM) type, it was originally created as part of the OLE Automation mechanism. In user code, safe arrays are primarily used to facilitate application binary interface–level interoperability between software modules, possibly written in different programming languages.

Safe arrays may vary by element size, length and dimensionality, but also by the numeric index assigned to their first element, called their lower bound. This is done to support interoperability with programming languages such as Visual Basic for which zero-based indexing does not necessarily apply.

Besides Microsoft Windows, the ReactOS project also includes a reimplementation of the COM safe array functionality.

Struct definition

The safe array struct is defined in the Windows-specific system header file <oaidl.h>.

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

The above struct definition, in keeping with the convention of the Windows API, uses Hungarian notation on all its members, as well as using a separate "tag" name for the name of the struct itself as opposed to the typedef for the struct type. The latter is a holdover from early versions of the C language, which did not permit both to have the same name.

Because safe arrays are agnostic with respect to the runtime type of the element being contained, the storage size of the element type is stored in the cbElements data member, while pointer to the beginning of the actual data in the array is stored as a void pointer in pvData.

The safe array struct contains another struct, SAFEARRAYBOUND, which stores the size and lower bound of the array for a given dimension.

typedef struct tagSAFEARRAYBOUND {
    ULONG cElements;
    LONG  lLbound;
} SAFEARRAYBOUND;

The dimensionality of the referent safe array is stored in the cDims data member. For each dimension of the array, there is a corresponding SAFEARRAYBOUND object in the array indicated by the rgsabound member, the count of which is indicated by the value in cDims.

Usage

The COM programming interface provides a number of APIs for managing safe arrays. These functions enable programs to create, access, and destroy safe arrays of various dimensions and sizes.

The safe array API exhibits ad hoc polymorphism, with the element types which a safe array can be used to store comprising a closed set as the members of the VARENUM enum type. These include many of the primitive data types available in the C++ programming language, as well as certain WinAPI structs such as VARIANT. In cases where a safe array needs to contain user-defined types, the value VT_RECORD can be supplied, whereby the safe array creation function must be given an "extra" pointer to an instance of the associated IRecordInfo class. As there is no field in the SAFEARRAY handle struct itself in which this pointer may be stored, the allocator stores it in memory immediately before the struct.

To create a multidimensional safe array, a program must first create and initialize an array of SAFEARRAYBOUND objects which collectively describe the dimensionality of the desired safe array. A pointer to the first element of this array can then be passed as the third and final function argument to the SafeArrayCreate function, which allocates the appropriate amount of storage for both the safe array descriptor and the array data itself.