IPOutlookApp2::GetIDsFromNames

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.

Syntax

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

Parameters

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

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

    Note

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

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_CREATE was specified without also specifying a valid data type.
  • HRESULT_FROM_WIN32(GetLastError())
    Maps the last WIN32 error value into an HRESULT.

Remarks

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

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.

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

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

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

IPOutlookApp2
IMAPIProp::GetIDsFromNames

Other Resources