IPOutlookApp2::GetIDsFromNames

Send Feedback

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, are limited to 255 characters in length, 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.

Return Values

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 of one of the types listed in the following table. For more information, see EDB Data Types and Size Limits.

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 rgPropIDs1[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, rgPropIDsGet);

Code Example

The following code example demonstrates how to use GetIDsFromNames.

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

    // All the named properties can be used for all PIM items.
    // Note that property names are not case sensitive.
    // To get/set the named properties, call GetProps/SetProps on the IItem.

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

    // Case 1: Create three string named props.
    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 int props.
    rgszNamedProps[0] = L"Height";
    rgszNamedProps[1] = L"Weight";
    hr                = pPoom->GetIDsFromNames(2, rgszNamedProps, PIM_CREATE | CEVT_I4, rgPropIds);

    // Case 3: Create one indexed uint prop that is not replicated when an item
    // is copied with the Copy function.
    rgszNamedProps[0] = L"RecordId";
    hr                = pPoom->GetIDsFromNames(1, rgszNamedProps, PIM_CREATE | PIM_INDEXED | PIM_DONTREPLICATE | CEVT_UI4, rgPropIds);

    // Case 4: Attempt to re-create a named property.
    rgszNamedProps[0] = L"PET";
    hr                = pPoom->GetIDsFromNames(1, rgszNamedProps, PIM_CREATE | PIM_INDEXED | PIM_DONTREPLICATE | CEVT_UI4, rgPropIds);

    // The propid returned will be the same one that was returned for case 1.
    // (ie you canmt re-create the item.

    return hr;

}

Requirements

Pocket PC: Windows Mobile Version 5.0 and later
Smartphone: Windows Mobile Version 5.0 and later
OS Versions: Windows CE 5.01 and later
Header: pimstore.h
Library: pimstore.lib

See Also

IPOutlookApp2 | IMAPIProp::GetIDsFromNames | IPOutlookApp | Pocket Outlook Object Model API Interfaces | Pocket Outlook Object Model API Enumerations

Send Feedback on this topic to the authors

Feedback FAQs

© 2006 Microsoft Corporation. All rights reserved.