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