Understanding Strings In COM[3]

bstrs

b-strings, more properly called basic strings, are a special kind of string format. instead of comprising a classic array of characters followed by a nul character (code \0) that marks the termination of the array, the structure of the data in memory is a superset of olechar. in short, a bstr is a null-terminated array of olechars prefixed by its length. the string length is determined by the character count, not by the index of the first null character.

this presence of the length of the object before the actual array data renders these strings suitable for manipulation in high-level tools like visual basic (for which this string format was invented in the first place) and java on a com-aware virtual machine like microsoft's jvm. actually, there is no other way to exchange string-like data with components written in those languages than to employ bstrs. while in c and c++ the developer has to understand and use the data type in a rather uncomfortable manner, both visual basic and java encapsulate them into their traditional string types, respectively string and java.lang.string. the final developer is therefore shielded from the subtleties of the organization of the raw bytes in memory. moreover, the tools take care of allocating and freeing the memory required to contain their content without the programmer needing to know how this process works behind the scenes.

this is the brilliant side of the medal of course. you as the c/c++ hardcore engineer get the tough part of the work, since you need to learn a completely new specific set of apis that carry out the basic operations with basic strings. the family of functions is amazingly named "system strings management api" and its members can easily be distinguished by the "sys" prefix in their names.

the following code snippet, borrowed from oleauto.h (this stuff used to be most useful when coupled with automation, as visual basic's com support was a lot less powerful then), shows the prototypes of each of the functions in the group:

/*---------------------------------------------------------------------*/

/*                            bstr api                                 */

/*---------------------------------------------------------------------*/

winoleautapi_(bstr) sysallocstring(const olechar *);

winoleautapi_(int)  sysreallocstring(bstr *, const olechar *);

winoleautapi_(bstr) sysallocstringlen(const olechar *, uint);

winoleautapi_(int)  sysreallocstringlen(bstr *, const olechar *, uint);

winoleautapi_(void) sysfreestring(bstr);

winoleautapi_(uint) sysstringlen(bstr);

#ifdef _win32

winoleautapi_(uint) sysstringbytelen(bstr bstr);

winoleautapi_(bstr) sysallocstringbytelen(lpcstr psz, uint len);

#endif

don't be unnerved by the probably unfamiliar winoleautapi_() word preceding all the functions; it is simply a macro defined in the same header file that expands to a long list of modifiers necessary to adjust the calling convention, exportation details, and return type. you can blissfully ignore it for our purposes.

the following table briefly describes the task of each routine: