IItem::SetProps

Article
08/28/2006

The SetProps method sets (updates) a PIM item's list of property values.

Syntax

HRESULT SetProps(
  ULONG ulFlags,
  WORD cProps,
  CEPROPVAL* rgVals
);

Parameters

ulFlags
[in] Not used. 0.
cProps
[in] The number of property values contained in rgVals.
rgVals
[in] Reference to an array of property ID's and their associated values.

Return Values

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

S_OK
The method completed successfully. All property values were set successfully.
E_ACCESSDENIED
Returned when you set the PIMPR_FOLDERNOTIFICATIONS property on a folder object, having logged onto POOM with an invalid window handle.

You must call IAppointment::Save on the appointment before using IItem::SetProps to set either PIMPR_MEETING_OWNER_CRITICAL_CHANGE or PIMPR_ATTENDEES_CRITICAL_CHANGE.

Remarks

S_FALSE is returned if one or more of the property values could not be set, or if you attempt to set a stream property (for example, PIMPR_PICTURE or PIMPR_BINARY_BODY).

If you use SetProps to change a single property value, none of the other PIM item properties are affected.

Code Example

The following code example demonstrates how to use SetProps.

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 SetPropsExample(IPOutlookApp2 *pPoom, OlItemType olItemType)
{

    HRESULT hr             = E_FAIL;
    IDispatch *pDisp       = NULL;
    IItem *pItem           = NULL;
    CEPROPVAL rgPropval[2] = {0};
    SYSTEMTIME st          = {0};

    // Create a new PIM item.
    hr = pPoom->CreateItem(olItemType, &pDisp);

    // Get the IItem interface for the newly created item.
    hr = pDisp->QueryInterface(IID_IItem, (LPVOID*)&pItem);

    // Set the item properties based on the PIM item type.
    switch(olItemType)

    {
        case olAppointmentItem:
            rgPropval[0].propid     = PIMPR_SUBJECT;
            rgPropval[1].propid     = PIMPR_START;
            rgPropval[0].val.lpwstr = L"Test Appt";

            // Set the start time to the current time.
            GetLocalTime(&st);
            SystemTimeToFileTime(&st, &(rgPropval[1].val.filetime));
            break;

        case olContactItem:
            rgPropval[0].propid     = PIMPR_FIRST_NAME;
            rgPropval[1].propid     = PIMPR_EMAIL1_ADDRESS;
            rgPropval[0].val.lpwstr = L"Test Contact";
            rgPropval[1].val.lpwstr = L"someone@example.com";
            break;
        
        case olTaskItem:
            rgPropval[0].propid     = PIMPR_SUBJECT;
            rgPropval[1].propid     = PIMPR_IMPORTANCE;
            rgPropval[0].val.lpwstr = L"Test Task";
            rgPropval[1].val.ulVal  = olImportanceHigh;
            break;

        default:
            hr = E_INVALIDARG;
            goto Exit;
    }

    hr = pItem->SetProps(0, 2, rgPropval);

    /*
    Expected return value:

    hr = S_OK          All props were set and there was no error.

    hr = S_FALSE       One or more propids passed in were either invalid or a
                       propid for a stream prop. (eg: rgPropval[0].propid = 0 or
                       rgPropval[0].propid = PIMPR_BINARY_BODY).

    hr = E_INVALIDARG: One or more propvals were invalid. (eg: for the tasks
                       case where the propid is PIMPR_IMPORTANCE and the
                       rgPropval[1].val.ulVal = 100 (which is invalid).
    */

    hr = pItem->Save();

Exit:
    pDisp->Release();
    pItem->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