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?

Upcoming

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.

Avigation

I was not the architect for VBScript, either de jure or de facto; I was a developer on the scripting team and implemented many features in VBScript, but I was certainly not at the architect level. – Lahr

Eric - I removed that bit. Sorry about the mistake (I hope you take it as a compliment). – Avigation

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.

Tallyho

Answer 3

Handling null BSTR as an empty string seams to be a common practice, but the technical documentation found at Microsoft actually states that there is a difference between those two.

For any document referencing both [MS-DTYP] and [MS-OAUT], specifying BSTR in a wire representation context MUST be considered as a reference to the transmitted BSTR type, while specifying BSTR in a memory representation context MUST be considered as a reference to the presented BSTR type ([MS-DTYP] section 2.2.5). Reflecting the terminology used for presented BSTRs, a NULL BSTR, or NULL transmitted BSTR, is defined as the wire representation of a NULL presented BSTR; and an empty BSTR, or empty transmitted BSTR, is defined as the wire representation of a zero-length presented BSTR. Preserving this distinction in the wire representation enables clients and servers to distinguish between NULL presented BSTRs and zero-length presented BSTRs, and thus associate possibly different, application-specific semantics to these two values.

https://msdn.microsoft.com/en-us/library/cc237580.aspx

So it's up to the implementations whether they handle both equal or not.

Declarer