IContactProperties::CreateArrayNode method (icontact.h)

Article
02/22/2024

Creates a new array node in a multi-value property.

Syntax

HRESULT CreateArrayNode(
  [in]      LPCWSTR pszArrayName,
  [in]      DWORD   dwFlags,
  [in]      BOOL    fAppend,
  [in, out] LPWSTR  pszNewArrayElementName,
  [in]      DWORD   cchNewArrayElementName,
  [in, out] DWORD   *pdwcchNewArrayElementNameRequired
);

Parameters

[in] pszArrayName

Type: LPCWSTR

Specifies the top-level property for which to create a new node.

[in] dwFlags

Type: DWORD

Must be CGD_DEFAULT.

[in] fAppend

Type: BOOL

TRUE for insert after, FALSE for insert before.

[in, out] pszNewArrayElementName

Type: LPWSTR

Specifies a user-allocated buffer to store the new array element name.

[in] cchNewArrayElementName

Type: DWORD

Specifies an allocated buffer size in characters.

[in, out] pdwcchNewArrayElementNameRequired

Type: DWORD*

On failure, contains the required size for pszNewArrayElementName.

Return value

Type: HRESULT

Returns one of the following values:

Return code	Description
S_OK	New node is created and name is in pszNewArrayElementName.
ERROR_PATH_NOT_FOUND	Macro HRESULT_FROM_WIN32(ERROR_PATH_NOT_FOUND) returned when array name is invalid.
ERROR_INSUFFICIENT_BUFFER	Macro HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) returned when pszNewArrayElementName is not large enough to store the value. The required buffer size is stored in pdwcchNewArrayElementNameRequired.

Remarks

Note The first element of an existing set is at index 1.

To create a pszArrayName at toplevel/secondlevel[1], call this function with pszArrayName == toplevel, fAppend=FALSE.

To create an array node that is an extension at [namespace]toplevel/secondlevel[1], call this function with pszArrayName == [namespace:secondlevel]toplevel.

To append to the set, pass fAppend=TRUE instead; pszNewArrayElementName then contains the resulting array node name, including the index.

Requirements

Requirement	Value
Minimum supported client	Windows Vista [desktop apps only]
Minimum supported server	Windows Server 2003 [desktop apps only]
Target Platform	Windows
Header	icontact.h (include Contact.h)
DLL	Wab32.dll (Version 6.0 or later)

Share via