IStream_ReadPidl

This function reads a PIDL from a stream.

Declaration

HRESULT
IStream_ReadPidl (
    IStream *pstm,
    PIDLIST_RELATIVE *ppidlOut);

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.