IItem::GetProps

Article
08/28/2006

The GetProps method 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 ulFlags to CEDB_ALLOWREALLOC). If you do not allocate memory, then prgVals is NULL, and GetProps allocates the memory for you. If there is insufficient memory, E_OUTOFMEMORY is returned.
pcbBuffer
[in/out] Reference to the count of bytes passed in prgVals if you allocate memory. If you do not allocate memory, then pcbBuffer is the size of the buffer that GetProps allocated instead.
hHeap
[in] Handle to the heap memory to allocate prgVals (if you allocate memory). If you do not allocate memory, then hHeap must be NULL.

Return Values

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

This method 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 *prgVals with HeapFree.

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).

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.

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);

    if(FAILED(hr) || 0 == cbBuffer)
     {
         goto Exit;
     }

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

    if(FAILED(hr) || NULL == prgPropvalPoom || 0 == cbBuffer)
    {
        goto Exit;
    }

    hr = S_OK;

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

    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