Export (0) Print
Expand All

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.


Show:
© 2014 Microsoft