IContentList::GetData Method
Use this method to read data from a specified row and column in a ContentList object, and through aggregation, the corresponding ContentListFactory object.
This is one of the two ContentList methods that do not support a scriptable interface. The other method is SetData. They are only intended for use in C++.
Due to performance considerations and compatibility issues, this method cannot be used from Microsoft Visual Basic or Microsoft Visual Basic Scripting Edition (VBScript).
HRESULT IContentList::GetData(
long iRow,
long iCol,
BYTE* pData
);
Parameters
iRow
[C++][in] A long that contains the position of the row from which the data should be read. Row positions are counted from zero (0), not one (1).
pData
[C++][out] A pointer to where the data should be written.
Return Value
[C++]
This method returns an HRESULT indicating whether it completed successfully. See the Error Values section for more details.
Error Values
[C++]
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 GetData method does not do type checking. The memory pointed to by the pData parameter must be large enough to receive the value being read. If the allotted memory is too small, memory corruption occurs.
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.
This method is functionally identical to the one of the same name in the ContentListFactory object.