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


    ULONG ulFlags,
    WORD cProps,
    CEPROPVAL* rgVals


  • ulFlags
    [in] Not used. 0.
  • cProps
    [in] The number of property values contained in rgVals.
  • prgVals
    [in] Reference to an array of property ID's and their associated values. For information about CEPROPVAL, see CEPROPVAL.

Return Value

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

  • S_OK
    The method completed successfully. All property values were set successfully.
    Returned if:

    • one or more of the property values could not be set,
    • one or more of the properties originally had the same value that you attempted to set (rewriting the same value),
    • you attempt to set a stream property (for example, PIMPR_PICTURE or PIMPR_BINARY_BODY).
    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. For more information, see Calendar Property ID's.


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 IItem::SetProps.


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.
        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.
            SystemTimeToFileTime(&st, &(rgPropval[1].val.filetime));


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

        case olTaskItem:

            rgPropval[0].propid     = PIMPR_SUBJECT;
            rgPropval[1].propid     = PIMPR_IMPORTANCE;

            rgPropval[0].val.lpwstr = L"Test Task";
            rgPropval[1].val.ulVal  = olImportanceHigh;



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


    return hr;


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



Other Resources