IContentListFactory::SetData Method [C++]

  • Article

[C++] Use this method to write data to a specified row and column in a ContentListFactory object.

[C++] This is one of the two ContentListFactory methods that do not support a scriptable interface. The other method is GetData. They are only intended for use in C++.

[Visual Basic] Due to performance considerations, this method is not intended for use from Visual Basic or VBScript.

[C++]

Definition

HRESULT IContentListFactory::SetData(longiRow,
 longiCol,
 BYTE*pData);

[C++]

Parameters

  • iRow[C++]
    [in] A long that contains the position of the row into which the data should be written. Row positions are counted from 0, not 1.
  • iCol[C++]
    [in] A long that contains the position of the column within the specified row into which the data should be written. Column positions are counted from 0, not 1.
  • pData[C++]
    [in] A pointer to the data to write into the ContentListFactory object.

[C++]

Return Values

This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.

[C++]

Error Values

This method returns S_OK (0x00000000) to indicate success and standard COM HRESULT error values to indicate failure. For more information about standard COM errors, see Standard COM Errors. Additional information may be available using the global Err object, which can be accessed using the API function GetErrorInfo. In particular, the GetDescription method of the IErrorInfo interface may return a text description of the error.

[C++]

Remarks

The SetData method does not do type checking for the data being written. The data pointed to by the pData parameter must be of the correct type for the column. Type (and especially size) mismatches will not result in memory scribbles (which is possible with the GetData method), but some of the data may not be written into the ContentListFactory object.

The ContentListFactory object stores some types of data by value and other types of data by reference. Therefore, how you use the GetData and SetData methods depends on the data type.

When you pass a pointer to a String to the SetData method, it stores the String in the ContentListFactory object, not the pointer. The GetData method returns a pointer to the String in the ContentListFactory object, but not the String. Do not hold a reference to the String in the ContentListFactory object beyond the lifetime of the object, as it will be invalid after the object is destroyed. The ContentListFactory object only stores wide character Unicode strings. ANSI strings are not supported.

When you pass an interface pointer to an object to the SetData method, it calls the AddRef method on the interface referenced by the pointer and stores the pointer in the ContentListFactory object. The GetData method returns this pointer and calls the AddRef method on the interface referenced by it. The caller must release the pointer returned by the GetData method.

When you pass a pointer to a SafeArray to the SetData method, it locks the SafeArray and stores a reference to it in the ContentListFactory object. The GetData method returns a reference to the locked array. The caller should not unlock the array as this could invalidate the reference stored in the ContentListFactory object. It is safe to store the array in a Variant of type VT_ARRAY or VT_VARIANT, as a call to the VariantClear method will not release the SafeArray because it is locked. When the ContentListFactory object is destroyed, the SafeArray will be unlocked and the SafeArrayDestroy method will be called. Since SafeArrays have a lock count similar to reference counting the array data will be released only if the lock count is zero.

The SetData method stores all other supported data types by value.

Objects must be "both threaded" and must aggregate the Free Threaded Marshaller in order to be stored in a ContentListFactory object. If you ignore this restriction, marshalling errors may occur.

This method is functionally identical to the one of the same name to be found in the ContentList object.

See Also

[C++]ContentListFactory Object

[Visual Basic]ContentListFactory Object

Copyright © 2005 Microsoft Corporation.
All rights reserved.