IItem::SetProps

4/8/2010

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.

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

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

• 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. For more information, see Calendar Property ID's.

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

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

See Also

Reference

IItem
IMAPIProp::SetProps

Other Resources