Click here to Skip to main content
15,860,844 members
Articles / Programming Languages / C++
Article

STL Compliant Class for SafeArrays

Rate me:
Please Sign up or sign in to vote.
4.42/5 (15 votes)
22 Nov 20066 min read 170.7K   2.3K   52   29
Encapsulates the details of SafeArray in a manner consistent with STL. Hides all the messy details.

What does it do?

It allows the transparent use of STL iterators, algorithms and idioms on SAFEARRAYs of all automation supported types.

When should I use it?

Whenever you wish to pass plain data to and/or from automation clients from C++. For VB clients, the use of Arrays is simple - now your use from C++ can be even more powerful. With the recent support of automation marshalling support for UDTs, this technique is an efficient means of transferring arbitrary quantities of semantically empty data from one process to another. You can even use the SAFEARRAY to transfer an array of COM interface (or IDispatch) pointers.

Why should I use it?

Look at this!

#include <algorithm>
#include "VectorSafeArray.h"
#include "VectorSafeArrayRecord.h"

IID StructIID = 
  {0xA8B2548C,0x9324,0x43B2,0xB1,0xAD,0x48,0xE2,0x84,0x05,0x2A,0x7E};

typedef safearrayvec::RecordType<TestStructure1, 
   &LIBID_ATLDEMO, &StructIID, 1, 0>  Struct1;
typedef safearrayvec::VectorSafeArray< TestStructure1, Struct1> Struct1Array;

STDMETHODIMP CTestVBStructure::ReverseArray(struct tagSAFEARRAY **sp)
{

    Struct1Array    a1;
// Since sp is an in,out parameter hand over
// ownership to the Array class for now.
    a1.Attach( sp);

// Let STL do the business
    std::reverse( a1.begin(), a1.end());

// Now transfer ownership back to the out parameter
    *sp = a1.Detach();
    return S_OK;
}

Five lines of code to reverse the order of a SAFEARRAY of user defined structures! This could equally well have been any arbitrary algorithm on any automation data type. Don't even consider doing this the hard way!

How do I use it?

Download the source code (Doh!). Make the header files available to your project. There is a small lib file which holds the definitions of a couple of static data members - include that in your link, or selectively add the appropriate .cpp files to your project. You will need to #include "VectorSafeArray.h" plus at least one of the VectorSafeArrayXXX files.

If you are using a structure, you will need to declare it in your IDL file, and ensure that it has an associated GUID. Then typedef the RecordType to suit.

For BSTR, VARIANT, IUnknown*, and IDispatch*, there are predefined types available for your use. For fundamental data types (automation compatible), simply typedef FundType<type, VARENUM>.

Sample Code

The sample code consists of an ATL DLL offering two interfaces through two classes (for no particular reason), and an MFC DLL with one class and interface which illustrates the use of the library. The associated VB6 clients serve to drive the samples and as a crude test harness. There is also a VBScript sample which uses a VARIANT to pass an array as an [in/out] parameter.

How efficient is it?

Reasonably! The VectorSafeArray<> class offers the same complexity guarantees as std::vector<>, but because it is using Windows 32 SafeArrayxxx functions, it is slower. The supplied template implementation of RecordType<> uses IRecordInfo functions to allocate, copy, and destroy memory. This is obviously slow, but it makes implementation easy. If you find that this is a problem in your application, you should replace it with a custom class to handle your structure.

The VariantType class is also very slow, it uses VariantXXX functions for copying, allocating, and destroying. Again, if this is a problem in your application, consider replacing it.

How does it work?

Glad you asked! But if you don't really want to know, you should still be able to use it quite happily - just like the rest of us use STL, ATL, or whatever!

I was motivated to write a generic handler for SAFEARRAYs of UDTs because I found myself writing reams of code just to test out an idea. Once started, it seemed to me that if I was to wrap the SAFEARRAY, it should be in the most useful way possible: which led me straight to the present implementation. I chose to emulate an std::vector<> because the internal structure of this class is just a chunk of memory with all the contained items arranged contiguously, just like a one dimensional SAFEARRAY! So I figured, I could 'leverage' a lot of existing code.

The VectorSafeArray<> is a rewrite of the <vector> header which comes with Visual C++ 6.0. The changes are to accommodate the fact that the underlying storage is owned by a SAFEARRAY, and all memory allocation, reallocation, and deallocation is done through SafeArrayXXX functions. For this reason, there is no Allocator template parameter to the class.

To support STL container operations, a class needs to have consistent copy construction, default construction, and assignment operations. The various types supported by automation in a SAFEARRAY have very different requirements for these operations. The most demanding of these types is the user defined structure. The template class RecordType:

template< typename sT, const IID *pLIBID, 
  const IID *pTypeID, const int vMajor = 1, const int vMinor = 0>
class RecordType : public sT

provides the required semantics through the use of IRecordInfo. typename sT is the user's structure type, the remaining parameters refer to the defining type library from which IRecordInfo will be initialized. Because the SAFEARRAY is a contiguous collection of 'user structures', it is clear that the RecordType cannot have any data members, or virtual functions - because if it did, it would no longer fit into the memory available in the SAFEARRAY! (see Notes below). But in order to verify the correctness of a passed array, it is necessary for the container to have access to the stored type. Each XXXXType instantiation holds a static copy of a TInfo class which stores the Flags required to validate the SAFEARRAY. This TInfo class has a function void Validate(SAFEARRAY *) which validates the SAFEARRAY flags, and optionally calls a static member of the XXXXType through a function pointer. XXXXType also holds a second function pointer for use by the XXXXType validation code if required. This second function pointer is currently used only by RecordType<> to access a cached copy of an ITypeInfo *.

This implementation through the use of the ITypeInfo is relatively slow. If you find that speed is an issue when testing, replace the generic RecordType with a specific implementation which makes use of your knowledge of the stored structure, to optimize construction and copying. E.g., a structure with only fundamental types can be copied bitwise by the compiler provided copy constructor.

The FundType<'>:

template< typename T, const VARENUM vt>
struct FundType

is used for all typed arrays of fundamental types. The SAFEARRAY will hold a VT type identifier which the class will verify against the provided template parameter. For valid values and types, see Platform SDK: Automation VARENUM - types indicated with S are OK.

The type VariantType is complete and requires no parameters.

template< typename iType, const unsigned short Flag>
struct InterfaceType

has two typedef'ed instances available for use for IUnknown and IDispatch.

typedef InterfaceType< IUnknown, FADF_UNKNOWN>    IUnknownType;
typedef InterfaceType< IDispatch, FADF_DISPATCH >    IDispatchType;

Limitations

Multi-threading has not been tested. I believe that the library should be safe for multiple thread access, provided that only one thread accesses any single instance of a container at one time. The only areas of concern are the use of ::VariantCopy in VariantType and access to the IRecordInfo * in RecordType<> - which could be called simultaneously by two or more threads if two or more instances of arrays of the same record type are in use. Both of these may be protected by a Critical Section by #define MULTITHREADING.

The library compiles in both UNICODE and MBCS. In fact, the MFC sample is MBCS and the ATL UNICODE.

When compiling IDL files with SAFEARRAY(type) *p parameters, you will see this message: "warning MIDL2039 : interface does not conform to [oleautomation] attribute :". This may be safely ignored.

Notes

MFCTest and VectorSafeArray have been compiled and tested under .NET Beta 2 (VC++ 7) and tested with the VB6 VBForMFC. The code works fine, there are a couple of warnings about signed/unsigned comparisons which may safely be ignored.

The library contains lines necessary to enforce the required size equivalence at compile time by using a small part of the Loki library - Andrei Alexandrescu "Modern C++ Design", Addison Wesley. If you haven't read it and you have an intellectual interest in C++ DO, it will blow your mind! The next version of VC++ (after .NET release!) should be able compile it! Some of the ideas presented would have been applicable to this library - if only VC++ supported partial template specialization!

License

This article has no explicit license attached to it but may contain usage terms in the article text or the download files themselves. If in doubt please contact the author via the discussion board below.

A list of licenses authors might use can be found here


Written By
Software Developer (Senior)
United Kingdom United Kingdom
I have been programming in C++ since Zortech (then called Zorland!) brought out a compiler for MSDOS. I continue to be amazed by the expressive power of the language.

Comments and Discussions

 
QuestionWhat license applies to the source code for VectorSafeArray? Pin
pmason104718-Feb-09 8:06
pmason104718-Feb-09 8:06 
QuestionRe: What license applies to the source code for VectorSafeArray? Pin
Anand Hariharan27-May-09 5:29
Anand Hariharan27-May-09 5:29 
AnswerRe: What license applies to the source code for VectorSafeArray? Pin
Julian Brown27-May-09 5:41
Julian Brown27-May-09 5:41 
GeneralTypo in VectorSafeArray::resize Pin
Volker von Einem20-Nov-06 4:48
Volker von Einem20-Nov-06 4:48 
AnswerRe: Typo in VectorSafeArray::resize Pin
Julian Brown22-Nov-06 11:37
Julian Brown22-Nov-06 11:37 
GeneralTypo in Message Now! Pin
Julian Brown22-Nov-06 13:23
Julian Brown22-Nov-06 13:23 
Generalpush_back bug Pin
cgough14-Apr-05 4:45
cgough14-Apr-05 4:45 
GeneralRe: push_back bug Pin
Julian Brown14-Apr-05 6:22
Julian Brown14-Apr-05 6:22 
GeneralCompiling App in VS2003 Pin
mubashar_2001@hotmail.com3-Apr-05 19:12
sussmubashar_2001@hotmail.com3-Apr-05 19:12 
GeneralRe: Compiling App in VS2003 Pin
Julian Brown3-Apr-05 21:34
Julian Brown3-Apr-05 21:34 
GeneralCompiling with newer compilers (like VS 2005 Beta Express) Pin
anybody anyone2-Jan-05 17:31
anybody anyone2-Jan-05 17:31 
GeneralMissing T_SafeVector.h Pin
Karan G.1-Jul-04 2:05
Karan G.1-Jul-04 2:05 
GeneralRe: Missing T_SafeVector.h Pin
Anonymous24-Apr-05 14:36
Anonymous24-Apr-05 14:36 
GeneralRe: Missing T_SafeVector.h Pin
Anonymous27-Jun-05 5:06
Anonymous27-Jun-05 5:06 
GeneralVB error Pin
imh4rdc0r317-May-04 9:27
sussimh4rdc0r317-May-04 9:27 
GeneralCan't get it to compile on VS.NET 2003 Pin
Anonymous18-Jun-03 18:28
Anonymous18-Jun-03 18:28 
GeneralRe: Can't get it to compile on VS.NET 2003 Pin
Julian Brown18-Jun-03 23:01
Julian Brown18-Jun-03 23:01 
Generalresize() correction Pin
Anonymous17-Sep-02 4:53
Anonymous17-Sep-02 4:53 
GeneralHEAP[...] Invalid Address Specified to RTLFreeHeap(....) Pin
4-Jul-02 11:44
suss4-Jul-02 11:44 
GeneralRe: HEAP[...] Invalid Address Specified to RTLFreeHeap(....) Pin
Julian Brown9-Jul-02 9:11
Julian Brown9-Jul-02 9:11 
GeneralRe: HEAP[...] Invalid Address Specified to RTLFreeHeap(....) Pin
Jim Heuring3-Jul-03 16:02
Jim Heuring3-Jul-03 16:02 
GeneralRe: HEAP[...] Invalid Address Specified to RTLFreeHeap(....) Pin
Micha13-Dec-03 7:11
Micha13-Dec-03 7:11 
GeneralRe: HEAP[...] Invalid Address Specified to RTLFreeHeap(....) Pin
valladis18-Apr-05 9:14
valladis18-Apr-05 9:14 
GeneralRe: HEAP[...] Invalid Address Specified to RTLFreeHeap(....) Pin
Smita Duraphe1-Sep-05 20:02
Smita Duraphe1-Sep-05 20:02 
GeneralLinker Warning in MFC Test build Pin
Julian Brown10-Feb-02 23:04
Julian Brown10-Feb-02 23:04 

General General    News News    Suggestion Suggestion    Question Question    Bug Bug    Answer Answer    Joke Joke    Praise Praise    Rant Rant    Admin Admin   

Use Ctrl+Left/Right to switch messages, Ctrl+Up/Down to switch threads, Ctrl+Shift+Left/Right to switch pages.