Where is using null BSTR documented?

Question

It's at least common practice to treat null BSTR (null WCHAR* pointer) as an empty string and design all the code manipulating BSTRs accordingly. Answers to this question say the same.

Where is this practice documented? Is there any official document describing this convention?

Answer 1

Well, the link given in the accepted answer to that question is to an article by Eric Lippert, Eric's Complete Guide To BSTR Semantics. While it would most definitely not be official documentation, Lippert is a well know authority on COM (particularly in the scripting arena).

However, the official documentation has this to say:

A BSTR with no data elements is either an empty BSTR or a NULL BSTR. An empty BSTR indicates a present, but zero-length, data value. A NULL BSTR indicates a data value that is not present.

So, officially they are both BSTRs with no data elements, but with slightly different semantics (though there's nothing to say that those 2 cases need to be handled differently in your application). In this case, I'd certainly follow Lippert's advice of treating them identically. For me, his real-world experience with how actual implementations work carries more weight than the one sentence in the official BSTR doc.

Answer 2

Michael Burr gives what I think should be the accepted answer. It's unfortunate that the page for BSTR in MSDN doesn't document this practice.

In addition, you can infer this behavior from these pages in the MSDN documentation:

• SysFreeString page reports that if bstr is null the function simply returns.
• SysStringLen page reports that passing a null for the bstr parameter returns zero for the string length.
• SysStringByteLen page reports the same behavior; null means zero length.

However, the documentation is not complete:

• SysReAllocString does not mention what will happen if *pbstr is null.
• SysReAllocStringLen does not mention what will happen if *pbstr is null.