IContactProperties::GetLabels method

Retrieves the labels for a specified array element name.

Syntax

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

Parameters

pszArrayElementName

Type: LPCWSTR

Specifies the array element name.

dwFlags

Type: DWORD

Must be CGD_DEFAULT.

pszLabels

Type: LPWSTR

Specifies user-allocated buffer to store the labels.

cchLabels

Type: DWORD

Specifies allocated buffer size in characters.

pdwcchLabelsRequired

Type: DWORD*

On failure, contains the required size for pszLabels.

Return Value

Type: HRESULT

Returns one of the following values:

Return code Description
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.

Requirements

   
Windows version Windows Vista [desktop apps only] Windows Server 2003 [desktop apps only]
Target Platform Windows
Header icontact.h (include Contact.h)
DLL Wab32.dll (Version 6.0 or later)