IPOutlookApp2::GetIDsFromNames

Windows Mobile 6.5
4/8/2010

The GetIDsFromNames method creates unique property ID's for named properties, as well as queries for the existence of, and gets a particular named property.


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

cPropNames

[in] The number of property names passed in the rgszPropNames array.

rgszPropNames

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

Bb415348.note(en-us,MSDN.10).gifNote:
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_CREATE option, 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_CREATE flag 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_CREATE flag is set.

Bb415348.note(en-us,MSDN.10).gifNote:
If GetIDsFromNames fails to find an index for a property ID, then the following value is returned in rgPropIDs.

If you do not specify any flags, then GetIDsFromNames returns the property ID if it exists, otherwise it returns PIMPR_INVALID_ID in 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).

This method returns the following:

S_OK

The method completed successfully.

S_FAIL

The method call failed.

E_INVALIDARG

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

HRESULT_FROM_WIN32(GetLastError())

Maps the last WIN32 error value into an HRESULT.

The GetIDsFromNames method is based on IMAPIProp::GetIDsFromNames.

Calling GetIDsFromNames multiple 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

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

Bb415348.note(en-us,MSDN.10).gifNote:
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.
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);

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

Bb415348.note(en-us,MSDN.10).gifNote:
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 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;
}

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 CEVALUNION union in Windbase.h header file.

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

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

Since IPOutlookApp2 descends from IPOutlookApp, you can initialize your POOM Session with a pointer to IID_IPOutlookApp2 instead 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:

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

Headerpimstore.h
LibraryPimstore.lib
Windows MobilePocket PC for Windows Mobile Version 5.0 and later, Smartphone for Windows Mobile Version 5.0 and later

Community Additions

Show: