Where is using null BSTR documented?
-
06-07-2019 - |
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?
Solution
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 BSTR
s 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.
OTHER TIPS
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 ifbstr
isnull
the function simply returns.SysStringLen
page reports that passing anull
for thebstr
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
isnull
.SysReAllocStringLen
does not mention what will happen if*pbstr
isnull
.
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.