IContactProperties::CreateArrayNode Method

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

pszArrayName [in]
LPCWSTR

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

dwFlags [in]
DWORD

Must be CGD_DEFAULT.

fAppend [in]
BOOL

TRUE for insert after, FALSE for insert before.

pszNewArrayElementName [in, out]
LPWSTR

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

cchNewArrayElementName [in]
DWORD

Specifies an allocated buffer size in characters.

pdwcchNewArrayElementNameRequired [in, out]
DWORD

On failure, contains the required size for pszNewArrayElementName.

Return Value

HRESULT

Returns one of the following values:

Return codeDescription
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

Minimum supported client

Windows Vista

Minimum supported server

Windows Server 2003

Header

Contact.h

IDL

Icontact.idl

DLL

Wab32.dll version 6.0 or later

See Also

IContactProperties

 

 

Send comments about this topic to Microsoft

Build date: 6/30/2010

Show: