IItem::OpenProperty

Article
08/28/2006

The OpenProperty method opens a stream property for a PIM item (for example, a picture). The length (size) of the stream is limited only by the amount of available storage memory.

Syntax

HRESULT OpenProperty(
  CEPROPID propID,
  DWORD dwMode,
  IStream ** ppStream
)

Parameters

propID
[in] The unique Object Identifier (OID) of the stream property to open.
dwMode
[in] Bitmask of flags that indicates the stream access mode used to open the stream. The following table shows the values the parameter can take.

Option Description

GENERIC_READ Read access to the stream.

GENERIC_WRITE Write access to the stream.
ppStream
[out] Reference to the stream property.

Option	Description
GENERIC_READ	Read access to the stream.
GENERIC_WRITE	Write access to the stream.

Return Values

This method returns the standard values HRESULT_FROM_WIN32(GetLastError()), E_INVALIDARG, and S_FAIL, as well as the following:

S_OK
The method completed successfully.

Remarks

Streams behave differently depending on whether the item has been saved. You must call IStream::Commit(0) (note the parameter of zero) on the stream before calling IItem::Save on the item. If you do not, then the Item might not be saved. This depends on whether you have previously saved the item.

The following IStream methods return the error value E_NOTIMPL: LockRegion, UnLockRegion, Revert, Clone, and Stat.

IItem::OpenProperty returns E_ACCESSDENIED if you attempt to open a second stream on the same property, or if you attempt to open a 0-byte stream with only the GENERIC_READ flag set.

Code Example

The following code example demonstrates how to use OpenProperty.

Note To make the following code example easier to read, security checking and error handling are not included. This code example should not be used in a release configuration unless it has been modified to include them.

HRESULT OpenPropertyExample(IItem *pItem, LPBYTE pbStore, ULONG cbStore)
{

    HRESULT  hr        = E_FAIL;
    IStream  *pStream  = NULL;
    CEPROPID propid    = PIMPR_BODY_BINARY;
    ULONG    cbWritten = 0;

    // Write the byte data passed into the body property of the IItem.
    hr = pItem->OpenProperty(propid, GENERIC_READ | GENERIC_WRITE, &pStream);
    hr = pStream->Write(pbStore, cbStore, &cbWritten);

    // Commit the stream.
    hr = pStream->Commit(0);

    // Save the stream to the underlying datastore.
    hr = pItem->Save();

    pStream->Release();

    return hr;

}

Requirements

Pocket PC: Windows Mobile Version 5.0 and later
Smartphone: Windows Mobile Version 5.0 and later
OS Versions: Windows CE 5.01 and later
Header: pimstore.h
Library: pimstore.lib