{"id":357,"date":"2013-04-20T10:19:28","date_gmt":"2013-04-20T14:19:28","guid":{"rendered":"http:\/\/templesystems.com\/?page_id=357"},"modified":"2013-04-20T10:19:28","modified_gmt":"2013-04-20T14:19:28","slug":"variants-safearrays-and-bstrs","status":"publish","type":"page","link":"http:\/\/templesystems.com\/?page_id=357","title":{"rendered":"Variants, Safearrays, and BSTR’s"},"content":{"rendered":"

VARIANTs, SAFEARRAYs, and BSTRs, Oh My!<\/p>\n

<\/p>\n
(Click here<\/a> to
\ngo back to the index page for my white papers.)<\/div>\n
\n

VARIANTs, SAFEARRAYs, and BSTRs, Oh My!<\/h2>\n

or, an Introduction to Common OLE Data Types for the C++ Programmer<\/h3>\n

by Rob Locher<\/a><\/h3>\n<\/div>\n

 <\/p>\n

So far, all the textbooks I have seen that\u00a0talk about VARIANTs,
\nSAFEARRAYs, and BSTRs\u00a0tend to lead\u00a0the C++ programmer learning COM
\ndown the primrose path, by implying that wrapper classes such as CComVariant<\/tt>
\nor _bstr_t<\/tt> are going to solve all your problems.\u00a0 Maybe such a
\nclass will, if you have a simple case, but what if you have to pass a VARIANT
\nholding a\u00a0SAFEARRAY of BSTRs?\u00a0 Well, then you need to understand
\nwhat\u00a0\u00a0VARIANTs, SAFEARRAYs, and BSTRs\u00a0really are, unless you
\nwant to wait around for somebody to create a wrapper class for VARIANTs
\nholding\u00a0SAFEARRAYs of BSTRs.<\/p>\n

For the rest of this article I will drop the capitalization of VARIANT,
\nSAFEARRAY, and BSTR for readability purposes most of the time, and I might call
\nthem “OLE types” or “VB types”.<\/p>\n

Why are variants, safearrays, and bstrs so hard to use?\u00a0 The problem, of
\ncourse, is that those OLE types aren’t simple to use at all, if you are a C++
\nprogrammer.\u00a0 If you are coding in Visual Basic, then the VB runtime takes
\ncare of that particular complexity for you.\u00a0 (Even then I’ve heard that
\nOLE types can be tricky sometimes.)\u00a0 If you as a C++ programmer are going
\nto use them, you will have to bear the same burden as the coders of the VB
\nruntime.\u00a0 In other words, you will have to understand what the VB types
\nactually\u00a0are, and follow the\u00a0poorly-documented rules about how to use
\nthem.\u00a0 Otherwise, you will find yourself causing memory leaks, or possibly
\neven using invalid pointers.<\/p>\n

In the discussion that follows, I will first talk about the fundamental types
\nand how to use them, and then I will discuss the shortcuts (helper classes) and
\ntheir limitations.<\/p>\n

 <\/p>\n

BSTRs<\/h3>\n

What is a BSTR?\u00a0 A bstr is a pointer to a string of wide characters (not
\nchar<\/tt> ).\u00a0 The string is not terminated.\u00a0 Instead, the length of
\nthe string is stored\u00a0as an unsigned long (four bytes)\u00a0just before the
\nfirst character of the string.\u00a0 Note that this is not how you would do it
\nin C++; in C++, the pointer would be to the first member of the structure, the
\nunsigned long, and not to the second.\u00a0 You might think that you could
\ncreate a bstr the C++ way, by creating a structure and then returning a pointer
\nto the second element, cast to bstr, but you should never do this; the memory
\npointed to by a bstr is actually owned by Windows.\u00a0 Because a bstr’s
\nmemory is owned by Windows, you can safely pass a bstr (which is a pointer)
\nbetween processes.\u00a0 Instead, you can use the function SysAllocString()<\/tt>
\nto create a bstr, and the function SysFreeString()<\/tt> to destroy it
\nproperly.\u00a0 In fact, you should use only platform SDK functions (or helper
\nclasses that use them internally)\u00a0to manipulate bstrs; see the platform
\nSDK help topic “String
\nManipulation Functions<\/a>“.<\/p>\n

It is a convention that a null pointer is a legal bstr, that represents an
\nempty string.\u00a0 A bstr must always either be a null pointer or point to an
\nactual allocated bstr; it should never be a random uninitialized pointer.
\nThere are also functions to reallocate or change a bstr. \u00a0As far as I can
\nsee, most of the string manipulation functions normally taken for granted, such
\nas finding a substring, comparing two strings,\u00a0and so on,\u00a0are
\nmissing.\u00a0 Most significantly, there seems to be no function to copy a
\nbstr.\u00a0 There are lots of functions to convert things to and from bstrs;
\nsee the platform SDK help topic “Data
\nType Conversion APIs<\/a>“, the help topic “ATL
\nand MFC String Conversion Macros<\/a>“, and the help topics for the functions
\n
\nConvertBSTRToString()<\/a><\/tt> and
\nConvertStringToBSTR()<\/a><\/tt>.<\/p>\n

When you pass a bstr across a COM boundary, you must give careful thought as
\nto whether the client or the server should be responsible for allocating and
\ndeallocating the bstr.\u00a0 Certain rules have been established by convention
\nthat determine who should create the bstr, and who should free it.
\nUnfortunately, these rules are poorly documented– see the platform SDK help
\ntopic “Allocating
\nand Releasing Memory for a BSTR<\/a>” for guidelines.\u00a0 Generally
\nspeaking, the client is responsible for the bstr.\u00a0 If the client is
\npassing a read-only string to the server, then usually it is passed as a
\nbstr.\u00a0 If the server is expected to change a string, then it might make
\nsense to have the client pass a pointer-to-bstr.\u00a0 If there is any
\nconfusion, you should probably test the server carefully against Visual Basic
\nto insure that the rules are being followed.\u00a0 (You can also import the
\ntype library into a C++ project and examine the wrapper classes generated.)<\/p>\n

There are two helper classes available when using\u00a0bstrs: the “native COM
\nsupport” class _bstr_t<\/tt>, and the ATL class CComBSTR<\/tt> .\u00a0 CComBSTR<\/tt>
\nhas a helpful CopyTo()<\/tt> method that fills a pointer-to-bstr
\nproperly, which is very useful for [out]<\/tt> parameters.\u00a0 Otherwise,
\nthe two classes are very similar.\u00a0 Both will take care of allocating and
\ndeallocating the wrapped bstr in the class constructor and destructor.
\nThey also can be used to take charge of an existing bstr with the Attach()<\/tt>
\nmethod, or can be made to abandon the bstr with the Detach()<\/tt> method.
\nThey have helpful operators and methods to compare two strings, check for
\nequality, copy a string, and so on.\u00a0 In many cases, _bstr_t<\/tt> and
\nCComBSTR<\/tt> instances can be passed as bstr substitutes — please read the
\nhelp pages on those classes carefully, because improperly attempting to use the
\nclasses as bstr substitutes can cause memory leaks.<\/p>\n

VARIANTs<\/h3>\n

What the heck is a variant?\u00a0 A variant is a structure containing a union
\nmember, and an unsigned integer member that describes which member of the union
\nis currently being used.\u00a0 (I’m oversimplifying a bit I think, but the
\noversimplification has gotten me through so\u00a0 far.)\u00a0 If you don’t know
\nwhat a union is,
\nread about it<\/a> first, and then come back.\u00a0 (But don’t feel bad,
\nbecause I’ve never used a union except as a variant and I don’t know of anybody
\nelse having done so either.)\u00a0 You might want to look up the system header
\nfile oaidl.h<\/tt> or the documentation topic “VARIANT
\nand VARIANTARG<\/a>“, which shows the juicy bits of the header file.\u00a0 All
\nthe typedefs and conditional defines in the header file are quite confusing,
\nbut what really matters is that there is a member vt<\/tt> which shows what
\nmember of the union is being used, and then one of the union members (llVal<\/tt>,
\nlVal<\/tt>, bVal<\/tt>, iVal<\/tt>, etc.) is actually holding the
\ndata, or a pointer to the data.\u00a0 By the way, VARIANT and VARIANTARG are
\ninterchangeable.<\/p>\n

The unsigned integer member that tells you what type the variant is actually
\nholding, vt<\/tt>, is itself a bit confusing.\u00a0 The various legal values
\nthat it can hold are enumerated in the system header file wtypes.h<\/tt>.
\nIf you look at the enumeration VARENUM<\/tt> in that file, you will see that
\nit is possible to combine certain values. \u00a0(The bitwise or operator “|<\/tt>
\n” is usually used to do the combining, but it seems to me that addition would
\nwork just as well.)\u00a0 The common values that I know of that are combined
\nwith other values are VT_ARRAY<\/tt> and VT_BYREF<\/tt>.\u00a0 If vt<\/tt>
\nequals VT_ARRAY |<\/tt> (something), then it means that the variant contains
\na safearray of (something). For example, (vt == VT_ARRAY | VT_BSTR)<\/tt> means
\nthat you are passing a safearray of bstr.\u00a0 Similarly, if vt<\/tt> equals
\nVT_BYREF |<\/tt> (something), it means that you are passing (something) by
\nreference.\u00a0 In this case, you are explicitly passing a type-safe pointer,
\nwhere (something)\u00a0indicates the type pointed to.<\/p>\n

By now, hopefully we can infer that the idea of a variant is to provide Visual
\nBasic\u00a0with a generic variable type that doesn’t waste too much space, that
\ncan hold just about anything,\u00a0including a pointer to or an array of just
\nabout anything.\u00a0 Although a variant is general-purpose, it is still
\npossible for a variant to be marshalled, because it is always possible to
\ndetermine how much space it uses.\u00a0 Or, if the variant holds a pointer to
\nsomething, or a safearray of something, it is still possible to determine how
\nmuch space the value pointed to takes up, because that might have to be
\nmarshalled too.<\/p>\n

Thanks to the way variants support weakly-typed languages, it is legal to
\nchange the type of the variant when it is holding a value.\u00a0 This is known
\nas type coercion.\u00a0 For example, you could coerce a variant holding the
\nbstr “3.0” to be type\u00a0 VT_R8<\/tt> (double).\u00a0 When a variant is
\ncoerced, what is happening inside the variant is that vt<\/tt> is being
\nchanged, and also the data is being converted internally.\u00a0 In the example,
\nthe bstr pointed to by the pbstrVal<\/tt> element would be freed, and an
\neight byte floating point representation of the number 3.0 would be placed in
\nthe dblVal<\/tt> element.\u00a0 The reason I mention coercion is that if you
\nhave a COM object written in C++ that accepts a variant from a Visual Basic
\nclient, the variant may have to be coerced to the type that you expect.
\nThe functions VariantChangeType()<\/tt> and VariantChangeTypeEx()<\/tt> are
\nvery useful if you have to do type coercion.<\/p>\n

If a variant is holding a bstr, then the variant owns the bstr, and properly
\ndeallocating the variant will result in the bstr being deallocated.\u00a0 If a
\nvariant holds a pointer, that is to say vt<\/tt> is VT_BYREF |<\/tt> (something),
\nthen the variant is being used to explicitly pass the pointer, and the variant
\ndoes not<\/em> own the memory pointed to.\u00a0 If a variant is holding a
\nsafearray, then the variant owns the safearray, and properly deallocating the
\nvariant will result in the safearray being deallocated.\u00a0 See the help
\ntopic “Variant
\nManipulation API Functions<\/a>“.\u00a0 That topic also mentions the API
\nfunctions that are provided to use variants.<\/p>\n

If you want to create and manipulate a variant yourself, without benefit of a
\nhelper class, then here is how you do it (mostly adapted from the book The
\nCOM and COM+ Programming Primer<\/em>, by Alan Gordon, published by Prentice
\nHall PTR):<\/p>\n

    \n
  1. If your variant is going to\u00a0explicitly pass\u00a0a pointer to something,
    \ndeclare and set the memory to which the pointer will point.<\/li>\n
  2. Declare a variant, or use the new<\/tt>
    \noperator to create a pointer to a variant.<\/li>\n
  3. Initialize the variant by calling VariantInit()<\/tt>.<\/li>\n
  4. Set vt<\/tt>
    \nin the variant to be the proper value.<\/li>\n
  5. Set the member variable in the variant that corresponds to the type in vt<\/tt>.<\/li>\n
  6. Use or pass your variant.<\/li>\n
  7. If the variant was used to explicitly pass a pointer, i.e. (vt & VT_BYREF
    \n!= 0)<\/tt>, then free the memory pointed to.<\/li>\n
  8. Use VariantClear()<\/tt>
    \nto free any resources that the variant owns.<\/li>\n
  9. Let the variant go out of scope, or use the delete<\/tt> operator on its
    \npointer, the same as you would for any other variable.<\/li>\n<\/ol>\n

    If that seems to you to be a lot of work, I agree with you.\u00a0 Fortunately,
    \nthere are two helper classes, CComVariant<\/tt> and _variant_t<\/tt>,
    \nthat you can use to make things easier.\u00a0 You can simply pass the pointer
    \nor value that you wish to wrap to the constructor, and the class will create a
    \nvariant to wrap the value or pointer, and take care of the variant.
    \nPlease note though that since a variant that wraps a pointer is not responsible
    \nfor the memory to which it points, neither is a _variant_t<\/tt> or CComVariant<\/tt>
    \ninstance.\u00a0 Both classes support Attach()<\/tt> and Detach()<\/tt> methods
    \nsimilar to the bstr wrapper classes.\u00a0 Attach()<\/tt> lets an instance
    \nof the class take charge of a pre-existing variant.\u00a0 Detach()<\/tt> forces
    \nthe instance to abandon its variant.\u00a0 Both classes also have a ChangeType()<\/tt>
    \nmethod that can be used to coerce the wrapped variant.<\/p>\n

    I would be remiss if I didn’t mention an
    \nexcellent article<\/a> pointed out to me, written by Microsoft’s Bruce
    \nMcKinney in 1996 and still appropriate, that talks about variants from both the
    \nVisual C++ and the Visual Basic points of view.\u00a0 It apparently was written
    \nbefore CComVariant<\/tt> and _variant_t<\/tt> came around, and does an
    \nexcellent job of describing how variants really work.<\/p>\n

     <\/p>\n

    SAFEARRAYs<\/h3>\n

    If you understand bstrs and variants, then you shouldn’t have much\u00a0trouble
    \nwith safearrays.\u00a0 SAFEARRAY was created to suit the needs of Visual Basic
    \nand other weakly-typed languages\u00a0for a type-safe array of one or more
    \ndimensions of arbitrary bounds.\u00a0 Note that it is not legal to pass a
    \nsafearray by itself via an IDispatch<\/tt> interface; for automation
    \npurposes, a safearray is only legal if it is wrapped by a variant.\u00a0 (The
    \nATL wizard won’t let you do it.)\u00a0 If you are wrapping a safearray with a
    \nvariant, then the member vt<\/tt> of the variant should be VT_ARRAY<\/tt>
    \nbitwise-or’ed (“|<\/tt>“) with (something), where (something) corresponds to
    \nthe type of the elements of the array.\u00a0 A safearray is<\/em> responsible
    \nfor its contents; properly deallocating a safearray will result in its contents
    \nbeing safely deallocated.\u00a0 Since a safearray should always be wrapped by a
    \nvariant, and a variant is responsible for its contents as long as the variant
    \ndoesn’t wrap a pointer, then\u00a0properly deallocating the variant holding the
    \nsafearray will properly take care of the variant, the safearray, and the
    \ncontents of the safearray.<\/p>\n

    A safearray can only hold one type at a time, as you might
    \nguess;\u00a0however, a safearray can hold variants, so that rule really isn’t
    \nmuch of a restriction.\u00a0 In fact, if you wanted to, you could have a
    \nmulti-dimensional safearray holding all different kinds of variants, some of
    \nwhich could themselves be safearrays, which in turn could hold other things…
    \nbut I recommend not making things that complicated if it can be avoided.<\/p>\n

    So, by now you probably are wondering what a safearray really is.\u00a0Here is
    \nsome code from oaidl.h<\/tt>:<\/p>\n

    typedef struct tagSAFEARRAYBOUND<\/p>\n

    {<\/p>\n

    ULONG cElements;<\/p>\n

    LONG lLbound;<\/p>\n

    } SAFEARRAYBOUND;<\/p>\n

    typedef struct tagSAFEARRAY<\/p>\n

    {<\/p>\n

    USHORT cDims;<\/p>\n

    USHORT fFeatures;<\/p>\n

    ULONG cbElements;<\/p>\n

    ULONG cLocks;<\/p>\n

    PVOID pvData;<\/p>\n

    SAFEARRAYBOUND rgsabound[ 1 ];<\/p>\n

    } SAFEARRAY;<\/p><\/div>\n

    The SAFEARRAYBOUND<\/tt> structure is simple: it describes how many elements
    \nthere are, and what the lower bound is, for a dimension.\u00a0 (The first
    \nelement of a VB array doesn’t have to be number zero.)\u00a0 As for the SAFEARRAY<\/tt>
    \nstructure itself, cDims<\/tt> has the number of dimensions, and rgsabound<\/tt>
    \nis an array of SAFEARRAYBOUND<\/tt>, where there is one element per
    \ndimension in the safearray (contrary to the declaration above).\u00a0 pvData<\/tt>
    \nof course points to the actual data.\u00a0 cLocks<\/tt> holds a lock count,
    \nand cbElements<\/tt> holds the size of an element.\u00a0 fFeatures<\/tt> somehow
    \ntells how the data is being stored, and therefore how it can be freed.
    \nSee the help topic “    SAFEARRAY
    \nData Type<\/a>” to see more about the fFeatures<\/tt> member.<\/p>\n

    There is a surprising number of API functions to deal with safearrays; see the
    \nhelp topic “    Array
    \nManipulation API Functions<\/a>“.\u00a0 You should not attempt to manipulate a
    \nsafearray or access an element manually; you should instead either use the API
    \nfunctions, or much better yet use the helper class CComSafeArray<\/tt>.
    \n(There doesn’t seem to be a _safearray_t<\/tt> class.)\u00a0 <\/tt><\/p>\n

    CComSafeArray<\/tt> is a template class; you provide the type of an element
    \nas one of the template parameters.\u00a0\u00a0(The example code in
    \nthe MSDN documentation for CComSafeArray<\/tt><\/a> is lousy, if you ask
    \nme.\u00a0\u00a0If you can’t figure it out, check out the\u00a0
    \nATLSafeArray sample<\/a>.)\u00a0 CComSafeArray<\/tt> provides Attach()<\/tt>
    \nand Detach()<\/tt> methods to take over an existing safearray or abandon the
    \nwrapped safearray, respectively, as you would expect.\u00a0 Perhaps the best
    \nfeature is the overridden operator[]<\/tt> method, which allows you to
    \naccess an array element safely and easily.<\/p>\n

    Well, that’s it for this article.\u00a0 I hope it helped you get pointed in
    \nthe right direction.\u00a0 (Getting pointed there myself was the main reason I
    \nwrote the article.)\u00a0 If it is incorrect anywhere, or you have any
    \nsuggestions, please email me.<\/p>\n<\/form>\n

     <\/p>\n","protected":false},"excerpt":{"rendered":"

    VARIANTs, SAFEARRAYs, and BSTRs, Oh My! (Click here to go back to the index page for my white papers.) VARIANTs, SAFEARRAYs, and BSTRs, Oh My! or, an Introduction to Common OLE Data Types for the C++ Programmer by Rob Locher … Continue reading →<\/span><\/a><\/p>\n","protected":false},"author":1,"featured_media":0,"parent":303,"menu_order":0,"comment_status":"open","ping_status":"open","template":"","meta":{"footnotes":""},"class_list":["post-357","page","type-page","status-publish","hentry"],"_links":{"self":[{"href":"http:\/\/templesystems.com\/index.php?rest_route=\/wp\/v2\/pages\/357","targetHints":{"allow":["GET"]}}],"collection":[{"href":"http:\/\/templesystems.com\/index.php?rest_route=\/wp\/v2\/pages"}],"about":[{"href":"http:\/\/templesystems.com\/index.php?rest_route=\/wp\/v2\/types\/page"}],"author":[{"embeddable":true,"href":"http:\/\/templesystems.com\/index.php?rest_route=\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"http:\/\/templesystems.com\/index.php?rest_route=%2Fwp%2Fv2%2Fcomments&post=357"}],"version-history":[{"count":2,"href":"http:\/\/templesystems.com\/index.php?rest_route=\/wp\/v2\/pages\/357\/revisions"}],"predecessor-version":[{"id":359,"href":"http:\/\/templesystems.com\/index.php?rest_route=\/wp\/v2\/pages\/357\/revisions\/359"}],"up":[{"embeddable":true,"href":"http:\/\/templesystems.com\/index.php?rest_route=\/wp\/v2\/pages\/303"}],"wp:attachment":[{"href":"http:\/\/templesystems.com\/index.php?rest_route=%2Fwp%2Fv2%2Fmedia&parent=357"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}