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 GetPropsmethod gets a PIM item's list of property values.

Syntax

HRESULT GetProps(
  const CEPROPID * 
rgPropID,
  ULONG 
ulFlags,
  WORD 
cProps,
  CEPROPVAL ** 
prgVals,
  ULONG * 
pcbBuffer,
  HANDLE 
hHeap
);

Parameters

rgPropID

[in] An array of property ID's.

ulFlags

[in] Flag specifying memory allocation for prgVals. To allocate memory for prgVals, set to CEDB_ALLOWREALLOC. Set to zero if already allocated.

cProps

[in] The number of property values contained in rgPropID.

prgVals

[out] Reference to an array used to return the list of property values if you allocate memory (i.e., set ulFlagsto CEDB_ALLOWREALLOC). If you do not allocate memory, then prgValsis NULL, and GetPropsallocates the memory for you. If there is insufficient memory, E_OUTOFMEMORYis returned. For information about CEPROPVAL, see CEPROPVAL.

pcbBuffer

[in/out] Reference to the count of bytes passed in prgValsif you allocate memory. If you do not allocate memory, then pcbBufferis the size of the buffer that GetPropsallocated instead.

hHeap

[in] Handle to the heap memory to allocate prgVals(if you allocate memory). If you do not allocate memory, then hHeapmust be NULL.

Return Value

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

S_OK

The method completed successfully.

Remarks

If you call IITem::GetPropson a PIM item before you have committed it to the database (by calling IItem::Save), the call fails and returns MAPI_W_ERRORS_RETURNEDbecause IITem::GetPropsqueries the database for the properties. As such, a call to IItem::Displayproduces an unpopulated Summary Card. You can still access a PIM item's "cached" properties using Property Getters though. For example, to retrieve the Subjectof a new appointment, call IAppointment::get_Subject.

Note:
There are no Property Getters for Named Properties. To retrieve Named Properties, you must save the PIM item first.

Be aware that getting properties of default Appointment and Contact items yields dissimilar types of results. If you create a new Contact item and then query its properties with IItem::GetProps, it's Source ID will be a random number, and each of its property values will be CEDB_PROPNOTFOUND ( wFlags= CEDB_PROPNOTFOUND). If you create a new Appointment item and then query its properties, it's Source ID and each of its property values will be zero ( srcID= 0 and wFlags= 0).

The GetPropsmethod supports the allocation of heap memory. This allows you to allocate a single block of memory for efficiency. If you do not allocate memory with prgVals, you must free * prgValswith HeapFree.

Code Example

The following code example demonstrates how to use GetProps.

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.
Copy Code
HRESULT GetPropsExample(IItem *pItem, OlItemType olItemType)
{
	HRESULT				 hr = E_FAIL;
	int				 cProps = 3;
	CEPROPID	 rgPropId[3] = {0};
	CEPROPVAL * prgPropvalPoom = NULL;
	CEPROPVAL * prgPropvalUser = NULL;
	ULONG			 cbBuffer = 0;
	HANDLE			 hHeap = GetProcessHeap();

	// Get properties based on item type.
	switch(olItemType)
	{
		case olAppointmentItem:
			rgPropId[0] = PIMPR_SUBJECT;
			rgPropId[1] = PIMPR_START;
			rgPropId[2] = PIMPR_BUSY_STATUS;
			break;

		case olContactItem:
			rgPropId[0] = PIMPR_FIRST_NAME;
			rgPropId[1] = PIMPR_LAST_NAME;
			rgPropId[2] = PIMPR_EMAIL1_ADDRESS;
			break;

		case olTaskItem:
			rgPropId[0] = PIMPR_SUBJECT;
			rgPropId[1] = PIMPR_TEAM_TASK;
			rgPropId[2] = PIMPR_IMPORTANCE;
			break;

		default:
			hr = E_INVALIDARG;
			goto Exit;
}

	// Allocate memory, then get item properties.
	cbBuffer = 0;
	hr = pItem->GetProps(rgPropId, 0, cProps,
&prgPropvalUser, &cbBuffer, NULL);
	if(HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) == hr)
		prgPropvalUser = (CEPROPVAL *) LocalAlloc(0, cbBuffer);

	// cbBuffer is set to the number of bytes required to hold the
data.
	hr = pItem->GetProps(rgPropId, 0, cProps, (CEPROPVAL
**)&prgPropvalUser, &cbBuffer, NULL);

	// Alternately, you can let Outlook Mobile allocate memory,
then get item properties.
	cbBuffer = 0;
	hr = pItem->GetProps(rgPropId, CEDB_ALLOWREALLOC, cProps,
&prgPropvalPoom, &cbBuffer, hHeap);
	hr = S_OK;

Exit:
	// Free memory.
	LocalFree(prgPropvalUser); 
	HeapFree(hHeap, 0, prgPropvalPoom);
	return hr;
}

Requirements

Header pimstore.h
Library Pimstore.lib
Windows Mobile Pocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

See Also