Re: IStream.Read()

In this case, I would say that the documentation for the actual .NET
type is superceeded by the documentation for the IStream interface itself,
since the .NET type is nothing more than a representation of the COM
interface, and implementations should stick to the contract (in word and
spirit) defined by the COM interface, not what the .NET documentation
chooses to expose about the IStream interface.

Which brings up an interesting point. I agree, the current
documentation about the COM IStream interface indicates nothing about null
for that parameter. I would argue that the previous documentation trumps
the current documentation here because of the immutability of COM
interfaces. While immutability most certainly applies to the actual
physical structure of the interfaces, I believe it applies to the semantics
(the spirit) of the contract as well.

I can't imagine that MS, a company obsessed with backwards
compatability, suddenly decided, especially for an already published
interface as common as IStream, that all implementations are expected to
perform a null value check on that parameter and error when it was
previously published that they did not have to. I can see it going the
other way (initially saying that all implementations had to check for null,
then saying they could optionally check for null), but it doesn't make sense
in this case.


--
- Nicholas Paldino [.NET/C# MVP]
- mvp@xxxxxxxxxxxxxxxxxxxxxxxxxxx

"Willy Denoyette [MVP]" <willy.denoyette@xxxxxxxxxx> wrote in message
news:D53A03E9-9B5F-4124-8EDA-5D4E31CEEAFD@xxxxxxxxxxxxxxxx
"Nicholas Paldino [.NET/C# MVP]" <mvp@xxxxxxxxxxxxxxxxxxxxxxxxxxx> wrote
in message news:uPeoBdlkHHA.4676@xxxxxxxxxxxxxxxxxxxxxxx
Read allows the last pointer passed in to be null. From the
documentation for IStream from the Platform SDK:

pcbRead
[out] A pointer to a ULONG variable that receives the actual number of
bytes read from the stream object.
You can set this pointer to NULL. In this case, this method does not
return the number of bytes read.



From the latest greatest Windows SDK docs:

pcbRead
[out] A pointer to a ULONG variable that receives the actual number of
bytes read from the stream object.

and from MSDN:
http://msdn2.microsoft.com/en-us/library/aa380011.aspx

http://msdn2.microsoft.com/en-us/library/system.runtime.interopservices.comtypes.istream.read.aspx

Note this:
For more information, see the existing documentation for
ISequentialStream::Read in the MSDN library.

You see, nothing about NULL to be allowed.

This :
http://msdn2.microsoft.com/en-us/library/ms890697.aspx

effectively talks about NULL to be allowed....
<snip
pcbRead
[out] Pointer to a ULONG variable that receives the actual number of bytes
read from the stream object.
You can set this pointer to NULL to indicate that you are not interested
in this value. In this case, this method does not provide the actual
number of bytes read.
/snip>

but this is about the ole32 implementation for Windows CE.

Willy.





.

Relevant Pages

  • Re: IStream.Read()
    ... type is superceeded by the documentation for the IStream interface itself, since the .NET type is nothing more than a representation of the COM interface, and implementations should stick to the contract defined by the COM interface, not what the .NET documentation chooses to expose about the IStream interface. ... I can't imagine that MS, a company obsessed with backwards compatability, suddenly decided, especially for an already published interface as common as IStream, that all implementations are expected to perform a null value check on that parameter and error when it was previously published that they did not have to. ...
    (microsoft.public.dotnet.languages.csharp)
  • Re: How to get the documents in detail?
    ... Not MSDN Library. ... anyone trying to learn how/when to use a particular interface (I guess ... A halfway decent documentation on this interface would have put the ... blah blah blah is an example of a possible site and a yeah yeah yeah ...
    (microsoft.public.vc.atl)
  • Re: Bug with new interface dependencies on custom IStream with SDK
    ... > is an undocumented interface and IWMSyncReader2 depends on. ... > at least post a link to the documentation on MSDN. ... > When I set the interface pointer to NULL and return E_NOTIMPL, ... > IWMSyncReader2 object promptly dereferences it and causes an exception. ...
    (microsoft.public.windowsmedia.sdk)
  • Re: input from keyboard
    ... What's needed are documentation and examples. ... Xlib code to my program because on every Linux system Xlib ... One of the reasons you use the libraries is so you don't have to worry about those things. ... you tried to bypass the C interface to Windows and use its internals. ...
    (alt.lang.asm)
  • Re: IStream.Read()
    ... type is superceeded by the documentation for the IStream interface itself, since the .NET type is nothing more than a representation of the COM interface, and implementations should stick to the contract defined by the COM interface, not what the .NET documentation chooses to expose about the IStream interface. ... I can't imagine that MS, a company obsessed with backwards compatability, suddenly decided, especially for an already published interface as common as IStream, that all implementations are expected to perform a null value check on that parameter and error when it was previously published that they did not have to. ...
    (microsoft.public.dotnet.languages.csharp)