Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/8/2010

The OpenPropertymethod returns a pointer to an interface to be used to access a property.

Note:
Windows Mobile Messaging implements this method only for IAttachand IMessageinterface objects.

Syntax 

HRESULT OpenProperty (
  ULONG 
ulPropTag,
  LPCIID 
lpiid,
  ULONG 
ulInterfaceOptions,
  ULONG 
ulFlags,
  LPUNKNOWN FAR * 
lppUnk
);

Parameters

ulPropTag

[in] Property tag for the property to be accessed; cannot be zero. Both the identifier and the type must be included in the property tag.

lpiid

[in] Ignored.

ulInterfaceOptions

[in] Ignored.

ulFlags

[in] Bitmask of flags that controls access to the property. The following flag can be set:

MAPI_MODIFY

Requests read/write access to the property. The default access is read-only.

lppUnk

[out] Reference to the requested interface object to be used for property access.

Return Value

This method returns the standard values E_INVALIDARG, E_OUTOFMEMORY, E_UNEXPECTED, and E_FAIL, as well as the following:

S_OK

Indicates success.

MAPI_E_INTERFACE_NOT_SUPPORTED

The requested interface is not supported for this property.

MAPI_E_NO_ACCESS

The caller has insufficient permissions to access the property.

MAPI_E_NO_SUPPORT

The object cannot provide access to this property through the requested interface.

MAPI_E_NOT_FOUND

The requested property does not exist.

MAPI_E_INVALID_PARAMETER

The property type in the tag is set to PT_UNSPECIFIED.

Remarks

OpenPropertyis an alternate to IMAPIProp::GetPropsand IMAPIProp::SetProps. When either GetPropsor SetPropsfails because the property is too large or too complex, call OpenProperty. OpenPropertyis commonly used to access properties of type PT_OBJECT.

If OpenPropertyis called from an IAttachinterface object, the property represented by ulPropTagcan only equal PR_ATTACH_DATA_BIN.

In Windows Mobile Messaging, lppUnkalways returns a reference to an IStreaminterface object. You are responsible for recasting *lppUnkto an IStreampointer. You must also use the returned IStreampointer to call its Releasemethod when you have finished with it.

Do not use the IStreampointer that you receive to call either its Seekor SetSizemethod, unless you use an offset position or size variable. Also, do not rely on the value of the plibNewPositionoutput parameter returned from the Seekcall.

If you call OpenPropertyto access a property with the IStreaminterface, use only that interface to make changes to it. Do not attempt to update the property with any of the other IMAPIPropmethods such as SetPropsor DeleteProps.

Do not try to open a property with OpenPropertymore than once. The results are undefined because they can vary from provider to provider.

If you need to modify the property to be opened, set the MAPI_MODIFYflag. If you are not sure whether the object supports the property but think it should, set the MAPI_MODIFYflags.

Requirements

Header mapidefs.h
Library cemapi.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Pocket PC 2002 and later, Smartphone 2002 and later

See Also