IStream_ReadPidl

Declaration

Parameters

The pstm argument provides the address of an
IStream interface to some stream object.

The ppidlOut argument provides the address of a
variable that is to receive the address of the PIDL.

Return Value

The function returns zero for success, else an error code.

Behaviour

The PIDL is to be introduced by a dword that gives the size of the PIDL in
bytes. The PIDL follows immediately. It is expected to be a sequence of
SHITEMID structures. Each structure has its size in
bytes as its first word. The sequence terminates with a word whose value is
zero, as if to begin a structure whose size is zero.

If the function cannot read the introductory dword from the stream, it fails.
If the function cannot get memory for the PIDL, it fails, with
E_OUTOFMEMORY as the error code. If the function
cannot read from the stream to fill that memory block, it fails. If the data
that is read into the memory block is not plausibly a PIDL, the function fails,
with
HRESULT_FROM_WIN32 (ERROR_INVALID_DATA) as the error
code.

The memory block for the PIDL is obtained through
CoTaskMemAlloc
and may be freed through CoTaskMemFree when the
caller is done with it.

Availability

The IStream_ReadPidl function is exported from
SHLWAPI as ordinal 512 in version 6.00 and higher.

Though this function dates from 2001, it was still not documented by
Microsoft in the MSDN Library at least as late as the CD edition dated January
2004.

However, the function did eventually get documented, apparently sometime in
2006. This article now conforms to Microsoft’s nomenclature.

What documentation is provided in the January 2007 edition of the Windows
SDK, and it really is very little, puts “Windows Vista” as the minimum operating
system. Whatever the reason that this function remained undocumented, it is
evidently not that Microsoft was taking its time to be accurate.

This page was created on 3rd October 2004 and was last
modified on 29th March 2008.