IContactProperties::GetString Method

  • Article

Retrieves the string value at a specified property into a caller-allocated buffer.

Syntax

HRESULT GetString(      
    LPCWSTR pszPropertyName,
    DWORD dwFlags,
    LPWSTR pszValue,
    DWORD *cchValue,
    DWORD *pdwcchPropertyValueRequired
);

Parameters

  • pszPropertyName
    [in] Specifies the property to retrieve.
  • dwFlags
    [in] Must be CGD_DEFAULT.
  • pszValue
    [in, out] Specifies user-allocated buffer to store the property.
  • cchValue
    [in] Specifies allocated buffer size in characters.
  • pdwcchPropertyValueRequired
    [in, out] On failure, contains the required size for pszValue.

Return Value

Returns one of the following values:

S_OK pszValue contains the null-terminated value.
S_FALSE No data for this value. Either the property has been present in the past but its value has been removed or the property is a container of other properties (toplevel/secondlevel[3]). The buffer at pszValue has been zero'ed.
ERROR_PATH_NOT_FOUND No data found for this property name.
ERROR_INSUFFICIENT_BUFFER pszValue was not large enough to store the value. The required buffer size is stored in *pdwcchPropertyValueRequired.

Remarks

To retrieve a single level property, set pszPropertyName to the property name.

To retrieve a value from a multi-value (hierarchical) property, include the desired index as part of pszPropertyName in the form: toplevel/secondlevel[1]/thirdlevel. NOTE: the first element of a set is index 1, so index [0] is invalid. The following example retrieves the Title of the fourth Name property of a contact.

L"NameCollection/Name[4]/Title"