Re: IStream.Read()

Tech-Archive recommends: Repair Windows Errors & Optimize Windows Performance

"Jon Skeet [C# MVP]" <skeet@xxxxxxxxx> wrote in message news:MPG.20ac426d68ba0f82bd@xxxxxxxxxxxxxxxxxxxxxxx
Willy Denoyette [MVP] <willy.denoyette@xxxxxxxxxx> wrote:
> It depends on what you mean by "the MSDN library". In the offline
> version of the MSDN library (which is what I'd certainly look it up in
> normally) it *does* specify it.

I mean both, the on-line MSDN Library (msdn2), this one holds the latest
update, and,
Off-line, the latest MSDN from the subscribers download site (Build date:
2/1/2007), and the version that comes with Orcas Beta1 both have the same
description for both IStream.Read and ISequentialStream - no mention about
null pointers.

Odd - I've got the same quote as Nick had in ISequentialStream::Read,
and I'm sure I've been installing all the latest disks... Is there a
decent way of finding the version of any particular file? The URL in
the offline MSDN is
ms-help://MS.MSDNQTR.v80.en/MS.MSDN.v80/MS.WIN32COM.v10.en/oledb/htm/
oledbisequentialstream__read.htm

Hmmm, I see ....
I'm on - ms-help://MS.MSDNQTR.v80.en/MS.MSDN.v80/MS.WIN32COM.v10.en/stg/stg/isequentialstream_read.htm -
see, ISTREAM is part of the "structured storage" interfaces, while you are at the "oledb programmers reference " stuff, it's not surprising to find this here, it's old hat that never gest updated in the post OLEDB age ;-), IMO it doesn't even belong there.

Also take note that I did not install from the distribution, but I install the latest download available from the MSDN subscribers area, more exactly, the April 2007 MSDN Library (en_msdn_library_2007_04_dvd_X13-63638.iso ISO-9660 DVD Image ).




> My guess is that the docs are wrong/incomplete. I'm surprised at the
> difference between the offline and online docs though :(

Incomplete, I agree, wrong? (take care [1]) possibly, confusing -
certainly....

I think it counts as "wrong" if it's been introduced into the
documentation as if it had always been part of the interface contract,
when older implementations could have legitimately returned the
appropriate error code instead.


Return values are never part of the contract, a COM interface is carved in stone, right, that means you cannot change the return type nor the argument types and number of arguments, but the value returned is not part of the contract
The documentation specifies the "standard" return values, like S_OK, E_FAIL etc.., but the implementor of an interface method is free to return what he sees fit.

Now, when you look at the ISequential::Read method, you'll see that STG_E_INVALIDPOINTER is one of the values that could "possibly" be returned from a typical implemetation. If the implementor , requires the pointers to be valid, it can return STG_E_INVALIDPOINTER when one of them is not. I have found one implementation that actually does that. So IMO, the parameter description was too general, in the sense that it makes you fell that null is valid irrespective the implementaton of the interface.
So, again be prepared to get an exception thrown on you when passing null, note that this is extremely rare to happen, besides, you should never pass a null pointer, as it's nearly impossible to know what exactly has been returned from the callee (0 values is valid data to be returned in the buffer).
..


This is a general complaint of mine, the .NET MSDN docs are produced by
"robots", no longer by humans, they offer not much more than what's actually
documented in the .NET library code, that is the minimum, programmers are no
technical writers and having both is a slow and too expensive process, even
for MSFT , so they expect from us that we add the missing pieces and
possibly correct what's wrong (see the MSDN's Community contents), which is
not a bad idea after all.
[1] Finally it will be the community's fault the docs are wrong ;-).

Indeed. I'm ashamed to say I haven't found time to contribute to the
MSDN pages, beyond mailing appropriate people when I've spotted
mistakes.


Same here, but I'm not ashamed ;-)

Willy.

.

Relevant Pages

  • Re: How do I get Registry key permissions for a specific user or group via WMI? - Update with co
    ... my boss found something buried deep inside MSDN but I was able to use it ... ' - specify a Registry path ... > ' Create constants for access rights and registry hive ... > Wscript.Echo "Has Query Value Access Rights on ...
    (microsoft.public.windowsxp.wmi)
  • Re: tDriveComboBox on component palate?
    ... I don't know whether the shell's IMalloc interface ... uses reference counting to manage its lifetime; ... or that the MSDN example was flawed. ... which we all know is the superior language. ...
    (comp.lang.pascal.delphi.misc)
  • Re: com interop
    ... what im trying to ask is how do i get the interface for IMediaControl like ... I want to know the way to get it so that i can get ms-words Interface. ... >> i got this example from msdn, that makes use of com interop. ... >> display the AVI.The main thread blocks on a ReadLine until ...
    (microsoft.public.dotnet.languages.csharp)
  • IBidiSpl interface
    ... I have compiled example from MSDN under Windows XP and try to run it. ... It says "The request is not ... Do you know where can I find more information regarding this interface? ... CoTaskMemFree (pData); ...
    (microsoft.public.development.device.drivers)
  • VOIPUI MSDN Beispiel Applikation unter evC
    ... Der Beispielcode ist auf der MSDN ... an IP Telephony User Interface sample application that uses the VoIP Application Interface Layer is included. ... Dazu habe ich erst mal alle erforlichern Dateien aus dem Plattformbuilder herausgesucht und nachdem ich es linken konnte alle zugehörigen Bibliothekn. ...
    (microsoft.public.de.german.windowsce.entwickler)