Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
4/8/2010

The AddCategorymethod adds a category to a PIM item's PIMPR_CATEGORIESproperty.

Syntax 

HRESULT AddCategory(
  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_CATEGORIESrepresents the categories assigned to that item. For a root folders, PIMPR_CATEGORIESrepresents the set of categories available for that folder.

The string value for pszwCategorycannot contain "," or ";" characters, since they are used as delimiters. If the string does contain them, then IItem::AddCategoryreturns E_INVALIDARG.

Code Example

The following code example demonstrates how to use AddCategory.

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.
Copy Code 
HRESULT AddCategoryExample(IItem *pItem)
{
	HRESULT				hr = E_FAIL;
	CEPROPID propidCategories = PIMPR_CATEGORIES;
	CEPROPVAL *pValCategories = NULL;
	ULONG			cbBuffer = 0;
	HANDLE			hHeap = GetProcessHeap();

	// It would be a good idea to check each of these 
hr values to verify that the categories were in fact added.
	hr = pItem->AddCategory(L"Category1");
	hr = pItem->AddCategory(L"Category111");
	hr = pItem->AddCategory(L"Category11");

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

	// At this point, the list of categories set for this Item are
L"Category1, Category111, Category11".
	// They can be accessed from the pValCategories->val.lpwstr
variable after the call to GetProps.

	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