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.

Code Example

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

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.

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

See Also

Reference

IPOutlookApp2
IMAPIProp::GetIDsFromNames

Other Resources