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 GetIDsFromNamesmethod creates unique property ID's for named properties, as well as queries for the existence of, and gets a particular named property.

Syntax 

HRESULT GetIDsFromNames(
  ULONG 
cPropNames,
  LPCWSTR const * 
rgszPropNames,
  ULONG 
ulFlags,
   CEPROPID * 
rgPropIDs
);

Parameters

cPropNames

[in] The number of property names passed in the rgszPropNamesarray.

rgszPropNames

[in] Property names in a string array. Properties must be of the same data type.

Note:
Property names are case insensitive, and cannot include the following special characters: ,;[].
ulFlags

[in] Bitmask of flags that indicates how the named property is created. The following table shows the options the parameter can take. These are combined with the bitwise OR.

Option Value Description

PIM_CREATE

0x010000

Creates the named property if it does not already exist. If you use the PIM_CREATEoption, then you must combine the ulFlags bitmask (using the bitwise OR) with one of the data types listed below.

PIM_INDEXED

0x200000

Specifies whether the named property should be indexed for faster Find functionality.

Used only if the PIM_CREATEflag is set.

PIM_DONTREPLICATE

0x400000

Specifies whether the named property should not be copied along with the rest of the item's properties when a copy of the item is made.

Used only if the PIM_CREATEflag is set.
Note:
If GetIDsFromNamesfails to find an index for a property ID, then the following value is returned in rgPropIDs.

If you do not specify any flags, then GetIDsFromNamesreturns the property ID if it exists, otherwise it returns PIMPR_INVALID_IDin rgPropIDs.

Option Value Description

PIMPR_INVALID_ID

0xFFFF

Property ID not found.
rgPropIDs

[out] An array of property ID's. For information on CEPROPID, see CeOpenStream (EDB).

Return Value

This method returns the following:

S_OK

The method completed successfully.

S_FAIL

The method call failed.

E_INVALIDARG

When defining ulFlags, PIM_CREATEwas specified without also specifying a valid data type.

HRESULT_FROM_WIN32(GetLastError())

Maps the last WIN32 error value into an HRESULT.

Remarks

The GetIDsFromNamesmethod is based on IMAPIProp::GetIDsFromNames.

Calling GetIDsFromNamesmultiple times for the same property name produces the same property ID.

Named properties must be of one of the types listed in the following table.

Data Type Description

CEVT_BLOB

BLOB structure

CEVT_BOOL

Boolean value

CEVT_FILETIME

FILETIME structure

CEVT_I2

16-bit signed integer

CEVT_I4

32-bit signed integer

CEVT_LPWSTR

Null-terminated string

CEVT_R8

64-bit float

CEVT_UI2

16-bit unsigned integer

CEVT_UI4

32-bit unsigned integer

Code Example

The following code example demonstrates how to create three named properties.

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 
WCHAR *rgszNamedProps[3] = {0};
CEPROPID rgPropIDs[3]	= {0};

rgszNamedProps[0] = L"Blood Group";
rgszNamedProps[1] = L"Favorite Book";
rgszNamedProps[2] = L"Pet";

hr = m_polApp->GetIDsFromNames(3, rgszNamedProps, PIM_CREATE |
CEVT_LPWSTR, rgPropIDs);

Code Example

The following code example demonstrates how to use GetIDsFromNames. All of the named properties can be used with all of PIM item types. Property names are not case sensitive. To get/set the named properties, call IItem::GetPropsand IItem::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.
Copy Code 
HRESULT CreateNamedPropExample(IPOutlookApp2 *pPoom, OlItemType
olItemType)
{
	HRESULT hr = E_FAIL;

	WCHAR * rgszNamedProps[3] = {0};
	CEPROPID	 rgPropIds[3] = {0};

	// Case 1: Create three named properties of type String.
	rgszNamedProps[0] = L"Blood Group";
	rgszNamedProps[1] = L"Favorite Book";
	rgszNamedProps[2] = L"Pet";

	hr = pPoom->GetIDsFromNames(3, rgszNamedProps, PIM_CREATE |
CEVT_LPWSTR, rgPropIds);

	// Case 2: Create two named properties of type Integer.
	rgszNamedProps[0] = L"Height";
	rgszNamedProps[1] = L"Weight";
	hr = pPoom->GetIDsFromNames(2, rgszNamedProps, PIM_CREATE |
CEVT_I4, rgPropIds);

	// Case 3: Create one named property of type indexed uint, that
is not replicated when an item is copied by using 
IItem::Copy.
	rgszNamedProps[0] = L"RecordId";
	hr = pPoom->GetIDsFromNames(1, rgszNamedProps, PIM_CREATE |
PIM_INDEXED | PIM_DONTREPLICATE | CEVT_UI4, rgPropIds);

	return hr;
}

Remarks

Property ID's are of type CEPROPID, which is defined in the Windbase.h header file as a DWORD (unsigned long int). The two high-order bytes contain the identifier, and the two low-order bytes contain the type. For a list of supported types, see the CEVALUNIONunion in Windbase.h header file.

For example, Case 1 in the above sample code produces the following three Property IDs:

Copy Code 
2147549215 (1000000000000001 0000000000011111)
2147614751 (1000000000000010 0000000000011111)
2147680287 (1000000000000011 0000000000011111)

Since IPOutlookApp2descends from IPOutlookApp, you can initialize your POOM Session with a pointer to IID_IPOutlookApp2instead of IID_IPOutlookApp.

For your project to compile properly, you must add the statement #include <pimstore.h>to your source file's list of pre-processor directives, and you must add pimstore.lib to the project's list of Additional Dependencies ( Project Properties> Configuration Properties> Linker> Input> Additional Dependencies).

For your project to link properly, you must add the following two statements to the beginning of your source file's list of pre-processor directives:

Copy Code 
#include <objbase.h>
#include <initguid.h>

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