IContentList::SetData
.gif "Ee810625.c++_off(en-US,CS.10).gif")
.gif "Ee810625.vb_on(en-US,CS.10).gif")
This is one of the two ContentList methods that do not support a scriptable interface. The other method is GetData. They are only intended for use in C++.
Definition
HRESULT IContentList::SetData(longiRow,longiCol,BYTE*pData);
Parameters
iRow
[in] A long that contains the position of the row into which the data should be written. Row positions are counted from zero (0), not one (1).
iCol
[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 zero (0), not one (1).
pData
[in] A pointer to the data to write into the ContentList object.
Return Values
This method returns an HRESULT indicating whether or not it completed successfully. See the Error Values section for more details.
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.
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 ContentList object.
The ContentList 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 ContentList object, not the pointer. The GetData method returns a pointer to the String in the ContentList object, but not the String. Do not hold a reference to the String in the ContentList object beyond the lifetime of the object, as it will be invalid after the object is destroyed. The ContentList 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 AddRef on the interface pointer and stores it in the ContentList object. The GetData method returns this pointer and calls AddRef on it. The caller must call release on 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 ContentList 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 ContentList object. It is safe to store the array in a Variant of type VT_ARRAY or VT_VARIANT, as a call to ::VariantClear will not release the SafeArray because it is locked. When the ContentList object is being destroyed the SafeArray will be unlocked and SafeArrayDestroy 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.
GetData reads and SetData stores all other supported data types by value.
Objects must be "both threaded" and must aggregate the Free Threaded Marshaller object in order to be stored in a ContentList object. If you ignore this restriction, marshalling errors may occur.
This method is functionally identical to the one of the same name in the ContentListFactory object.
.gif "Ee810625.caution(en-US,CS.10).gif")
Caution
- Because ContentList objects do not perform synchronization or locking, take caution when you are writing string, array, or object values in multi-threaded scenarios. Race conditions could exist that might result in resource leaks.