IItem::RemoveCategory

  • Article

4/8/2010

The RemoveCategory method removes a category from a PIM item's PIMPR_CATEGORIES property.

Syntax

HRESULT RemoveCategory(
  LPCWSTR pszwCategory
)

Parameters

  • pszwCategory
    [in] The category string value.

Return Value

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

  • S_OK
    The method completed successfully.

Remarks

For PIM items, PIMPR_CATEGORIES represents the categories assigned to that item. For a root folders, PIMPR_CATEGORIES represents the set of categories available for that folder.

When the user deletes the last PIM item associated with a particular category, Outlook Mobile automatically removes that category from the list of available categories, and it no longer shows up in the category picker in the user interface.

Code Example

The following code example demonstrates how to use RemoveCategory.

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 RemoveCategoryExample(IItem *pItem)
{
    HRESULT hr                = E_FAIL;

    CEPROPID propidCategories = PIMPR_CATEGORIES;
    CEPROPVAL *pValCategories = NULL;

    ULONG   cbBuffer          = 0;
    HANDLE hHeap              = GetProcessHeap();

    // Assume that the original categories set for this are Category1, Category11, and Category111. Check the HRESULT returned from 
    // each of these calls to make sure that the new category was actually added.
    hr = pItem->RemoveCategory(L"Category111");

    hr = pItem->Save();

    hr = pItem->GetProps(&propidCategories, CEDB_ALLOWREALLOC, 1, &pValCategories, &cbBuffer, hHeap);

    // At this point, the list is L"Category1, Category11".
    HeapFree(hHeap, 0, pValCategories);

    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

Reference

IItem

Other Resources