IContactProperties::GetLabels Method

  • Article

Retrieves the labels for a specified array element name.

Syntax

HRESULT GetLabels(      
    LPCWSTR pszArrayElementName,
    DWORD dwFlags,
    LPWSTR pszLabels,
    DWORD cchLabels,
    DWORD *pdwcchLabelsRequired
);

Parameters

  • pszArrayElementName
    [in] Specifies the array element name.
  • dwFlags
    [in] Must be CGD_DEFAULT.
  • pszLabels
    [in, out] Specifies user-allocated buffer to store the labels.
  • cchLabels
    [in] Specifies allocated buffer size in characters.
  • pdwcchLabelsRequired
    [in, out] On failure, contains the required size for pszLabels.

Return Value

Returns one of the following values:

S_OK Retrieval successful.
ERROR_PATH_NOT_FOUND No data found for this property name.
ERROR_INVALID_DATATYPE Unable to get value for this property due to schema.
ERROR_INSUFFICIENT_BUFFER pszLabels was not large enough to store the value. The required buffer size is stored in *pdwcchLabelsRequired.

Remarks

The user-allocated buffer in pszLabels receives a concatenated list of null-terminated strings, followed by an empty string. In other words, the last 4 bytes will be zero. For example, L"str1\0str2\0\0". NOTE: Succeeds only for multi-value properties. Also, may return labels in a different order than they were set.