[转]Marshaling a SAFEARRAY of Managed Structures by P/Invoke Part 6.

1. Introduction.

1.1 Starting from part
4 I have started to discuss how to interop marshal a managed array of
TestStructure structs that is contained within a structure.

1.2 We have seen in part 4 an example for marshaling
such a container structure to unmanaged code “one way” (i.e. as an “in”
parameter).

1.3 In part
5 we learned how to marshal such a container structure from an
unmanaged function to managed code as an “out” (return) parameter.

1.4 Here in part 6, we shall look into how to marshal
such a container structure bi-directionally, i.e. as both an “in” and an
“out” (or reference) parameter.

1.5 Just as I did in part 5, I shall take this
opportunity to demonstrate the use of several IRecordInfo methods which pertain
to UDTs. Through these IRecordInfo methods I hope to show strong consistency and
robustness of both the IRecordInfo interface as well as the
SAFEARRAY.

2. The TestStructure, ArrayContainer Structures and
the CSConsoleApp.tlb Type
Library.

2.1 We shall continue to use the TestStructure and the
ArrayContainer structures that we have previously defined in part 1 and part 4
respectively.

2.2 We shall also be using the CSConsoleApp.tlb type
library that we have updated in part 4.

3. Unmanaged API that Returns an ArrayContainer
Structure as a Reference Parameter.

3.1 In this section, I shall present a new unmanaged
function to be exported from the UnmanagedDll.dll that
we have been using since part 1. This function takes a pointer to an
ArrayContainer structure as input parameter.

3.2 The intension of this function is to modify the
underlying ArrayContainer structure with new values for its fields. This
ArrayContainer structure is in this way returned to the calling function with
modified field data.

3.3 Full source codes of this unmanaged function is
listed below :

extern "C" __declspec(dllexport) void __stdcall ModifyArrayContainer
(
  /*[in, out]*/ ArrayContainer* pArrayContainerToModify
)
{
	IRecordInfoPtr spIRecordInfoArrayContainer = NULL;
	HRESULT hrRet;

	hrRet = GetIRecordType
	(
		TEXT("CSConsoleApp.tlb"),
		__uuidof(ArrayContainer),
		&spIRecordInfoArrayContainer
	);

	// We do something drastic : we completely clear the contents of
	// "pArrayContainerToModify". This will release object references
	// and other values of the UDT without deallocating the UDT.
	//
	// As a result, the "array_of_test_structures" SAFEARRAY contained
	// inside "pArrayContainerToModify" will be destroyed.
	spIRecordInfoArrayContainer -> RecordClear((PVOID)pArrayContainerToModify);

	// We now create an STL vector of TestStructure structs.
	std::vector<TestStructure> vecTestStructure;
	TestStructure test_structure;

	test_structure.m_integer = 100;
	test_structure.m_double = 100.0;
	test_structure.m_string = ::SysAllocString(L"New string");
	vecTestStructure.push_back(test_structure);

	test_structure.m_integer = 101;
	test_structure.m_double = 101.0;
	test_structure.m_string = ::SysAllocString(L"New string");
	vecTestStructure.push_back(test_structure);

	test_structure.m_integer = 102;
	test_structure.m_double = 102.0;
	test_structure.m_string = ::SysAllocString(L"New string");
	vecTestStructure.push_back(test_structure);

	test_structure.m_integer = 103;
	test_structure.m_double = 103.0;
	test_structure.m_string = ::SysAllocString(L"New string");
	vecTestStructure.push_back(test_structure);

	IRecordInfoPtr spIRecordInfoTestStructure = NULL;

	hrRet = GetIRecordType
	(
		TEXT("CSConsoleApp.tlb"),
		__uuidof(TestStructure),
		&spIRecordInfoTestStructure
	);

	// Define a receiver of the SAFEARRAY that we want
	// to now create using CreateSafeArrayEx<>().
	SAFEARRAY* pSafeArrayOfTestStructure = NULL;

	CreateSafeArrayEx<TestStructure, VT_RECORD>
	(
		(TestStructure*)&(vecTestStructure[0]),
		vecTestStructure.size(),
		(PVOID)spIRecordInfoTestStructure,
		pSafeArrayOfTestStructure
	);

	// At this point, "pSafeArrayOfTestStructures" contains
	// copies of TestStructure structs from "vecTestStructure".

	// Define a VARIANT that will contain "pSafeArrayOfTestStructure".
	VARIANT varFieldValue;

	VariantInit(&varFieldValue);
	V_VT(&varFieldValue) = (VT_ARRAY | VT_RECORD);
	V_ARRAY(&varFieldValue) = pSafeArrayOfTestStructure;

	// Set the "array_of_test_structures" field
	// of the "pArrayContainerReceiver" structure.
	//
	// As an alternative to PutFieldNoCopy() as
	// used in GetArrayContainer(), we now use
	// the PutField() method which will make a
	// complete copy of the data contained
	// inside "varFieldValue" to set as the
	// field value of "array_of_test_structures".
	//
	// Hence later on, we must either destroy
	// "pSafeArrayOfTestStructure" by a call to
	// SafeArrayDestroy() or by calling VariantClear().
	spIRecordInfoArrayContainer -> PutField
	(
		INVOKE_PROPERTYPUT,
		pArrayContainerToModify,
		L"array_of_test_structures",
		&varFieldValue
	);

	std::vector<TestStructure>::iterator theIterator;

	// The members of structures which are reference types
	// (e.g. m_string which is BSTR) must be freed here.
	// This is because SAFEARRAYs use copy-semantics.
	// That is, they store an entire copy of the structures
	// that we insert into it.
	//
	// Therefore each TestStructure structure inside the
	// SAFEARRAY will contain a BSTR copy in its m_string member.
	for (theIterator = vecTestStructure.begin(); theIterator != vecTestStructure.end(); theIterator++)
	{
		TestStructure& test_structure = *theIterator;

		spIRecordInfoTestStructure -> RecordClear((PVOID)&test_structure);
	}

	// Because we have used IRecordInfo::PutField()
	// to insert "pSafeArrayOfTestStructure" as a field
	// value into "ArrayContainer", we must now destroy
	// "pSafeArrayOfTestStructure" either by calling
	// SafeArrayDestroy() or by calling VariantClear()
	// but not both.
	//
	VariantClear(&varFieldValue);
}

The following is a summary of the workings of this
function :

• The function begins by completely clearing the fields of
  “pArrayContainerToModify”.
• This will result in the complete destruction of the
  “array_of_test_structures” SAFEARRAY field of
  “pArrayContainerToModify”.
• Later on in the function, a new SAFEARRAY will be
  created and will replace the one that has just been
  destroyed.
• This will present no problem to the corresponding
  “array_of_test_structures” field of the managed ArrayContainer structure that
  was passed to the ModifyArrayContainer() function in the managed client
  application. This is because a brand new managed array will be created and then
  initialized with new values from the new “array_of_test_structures” SAFEARRAY.
  But more on this when we get there later.
• A STL vector of TestStructure structs (i.e.
  “vecTestStructure”) will then be instantiated and filled with
  values.
• Then a new SAFEARRAY (i.e. “pSafeArrayOfTestStructure”)
  will be created using the CreateSafeArrayEx<>() helper function. The
  SAFEARRAY will be filled with TestStructure structs copied from the earlier
  “vecTestStructure” vector.
• And then the IRecordInfo::PutField() method will be
  called on the IRecordInfo interface associated with the ArrayContainer UDT to
  insert the values of “pSafeArrayOfTestStructure” into the
  “array_of_test_structures” field of the input
  “pArrayContainerToModify”.
• At this point, the whole purpose of the
  ModifyArrayContainer() function has been accomplished.
• What remains is clean-up.
• The TestStructure structs contained inside
  “vecTestStructure” must now each be destroyed. We loop through the elements of
  “vecTestStructure” and call on the IRecordInfo interface associated with
  the TestStructure UDT to clear each structure.
• Note that we must not call IRecordInfo::RecordDestroy()
  because this will cause the memory area occuppied by each TestStructure struct
  to be freed.
• This is not permitted because each TestStructure struct
  contained inside “vecTestStructure” remains owned by “vecTestStructure”. Only
  “vecTestStructure” can de-allocate each struct.
• Finally, we call on VariantClear() to clear the
  “varFieldValue” VARIANT that was used in the call to
  IRecordInfo::PutField().
• Alternatively, SafeArrayDestroy() can also be used to
  directly destroy “pSafeArrayOfTestStructure”.
• However, do not call both VariantClear() and
  SafeArrayDestroy().

4. Example Call to
ModifyArrayContainer().

4.1 The following is how the ModifyArrayContainer()
function is declared in a client C# code :

[DllImport("UnmanagedDll.dll", CallingConvention = CallingConvention.StdCall)]
private static extern void ModifyArrayContainer
(
  [In][Out] ref ArrayContainer ArrayContainerToModify
);

• When the interop marshaler internally makes a call to
  the ModifyArrayContainer() function, it will create the unmanaged version of the
  ArrayContainer structure and then pass a pointer to it as parameter to the
  ModifyArrayContainer() function.
• A pointer to this unmanaged ArrayContainer structure is
  passed instead of a complete structure itself due to the use of the OutAttribute
  as well as the out keyword.
• This is so that the underlying structure can be modified
  by the ModifyArrayContainer() function. The ModifyArrayContainer() function has
  the right to do so because the OutAttribute indicates that the parameter is to
  be returned from it.
• Now due to the presence of the InAttribute, the existing
  contents of the managed ArrayContainer structure will be transformed
  into respective fields of the unmanaged version of the ArrayContainer
  structure which is then passed along to the ModifyArrayContainer()
  function.

4.2 The following is a sample C# function that calls
ModifyArrayContainer() :

static void DoTest_ModifyArrayContainer()
{
    ArrayContainer ArrayContainerToModify = new ArrayContainer();
    // Define and instantiate a managed array of 3
    // TestStructure structs for the "array_of_test_structures"
    // field.
    ArrayContainerToModify.array_of_test_structures = new TestStructure[3];

    // Assign simple values to the elements of the array.
    for (int i = 0; i < ArrayContainerToModify.array_of_test_structures.Length; i++)
    {
        ArrayContainerToModify.array_of_test_structures[i].m_integer
		= i;
        ArrayContainerToModify.array_of_test_structures[i].m_double
		= (double)i;
        ArrayContainerToModify.array_of_test_structures[i].m_string
		= string.Format("Hello World [{0}]", i);
    }

    // Call on ModifyArrayContainer() to modify ArrayContainerToModify.
    ModifyArrayContainer(ref ArrayContainerToModify);

    // Display the contents of the "array_of_test_structures" array
    // inside ArrayContainerToModify.
    for (int i = 0; i < ArrayContainerToModify.array_of_test_structures.Length; i++)
    {
        Console.WriteLine("ArrayContainerToModify.array_of_test_structures[{0}].m_integer : [{1}]",
		i, ArrayContainerToModify.array_of_test_structures[i].m_integer);
        Console.WriteLine("ArrayContainerToModify.array_of_test_structures[{0}].m_double : [{1}]",
		i, ArrayContainerToModify.array_of_test_structures[i].m_double);
        Console.WriteLine("ArrayContainerToModify.array_of_test_structures[{0}].m_string : [{1:S}]",
		i, ArrayContainerToModify.array_of_test_structures[i].m_string);
    }
}

The following are some important points pertaining to
the code above :

• An ArrayContainer structure “ArrayContainerToModify” is
  defined and instantiated.
• The “array_of_test_structures” field of
  “ArrayContainerToModify” is instantiated to an array of 3 TestStructure
  structs.
• Simple values are then assigned to the elements of the
  array.
• The ModifyArrayContainer() function is then called with
  “ArrayContainerToModify” passed as a reference parameter.
• Under the covers, when the ModifyArrayContainer() is
  called, an unmanaged counterpart of the “ArrayContainerToModify”
  structure is allocated by the interop marshaler and filled with
  actual field values based on those of the managed “ArrayContainerToModify”
  structure.
• A pointer to this unmanaged “ArrayContainerToModify”
  structure is then passed to the ModifyArrayContainer() function.
• When the ModifyArrayContainer() returns, the latest
  contents of the unmanaged “ArrayContainerToModify” structure is used to rebuild
  the managed “ArrayContainerToModify” structure.
• The DoTest_ModifyArrayContainer() function then loops
  through the contents of the new “ArrayContainerToModify” structure and display
  all its new contents.

4.3 At runtime, the above function will produce the
following console output :

ArrayContainerToModify.array_of_test_structures[0].m_integer : [100]
ArrayContainerToModify.array_of_test_structures[0].m_double : [100]
ArrayContainerToModify.array_of_test_structures[0].m_string : [New string]
ArrayContainerToModify.array_of_test_structures[1].m_integer : [101]
ArrayContainerToModify.array_of_test_structures[1].m_double : [101]
ArrayContainerToModify.array_of_test_structures[1].m_string : [New string]
ArrayContainerToModify.array_of_test_structures[2].m_integer : [102]
ArrayContainerToModify.array_of_test_structures[2].m_double : [102]
ArrayContainerToModify.array_of_test_structures[2].m_string : [New string]
ArrayContainerToModify.array_of_test_structures[3].m_integer : [103]
ArrayContainerToModify.array_of_test_structures[3].m_double : [103]
ArrayContainerToModify.array_of_test_structures[3].m_string : [New string]

5. In Conclusion.

5.1 Here in part 6, we have looked at how managed
structures may be passed to and returned from unmanaged code bi-directionally by
way of a SAFEARRAY contained in an outer wrapping structure.

5.2 More good demonstrations of methods of the
IRecordInfo interface (RecordClear(), PutField()) was given. The
VariantClear() function was also used to completely clear a SAFEARRAY. I
certainly hope that the reader has benefitted from this.

5.3 In part 7, we shall shift gears again and up the
ante in complexity. We shall be explore marshaling a structure that contains an
array of ArrayContainer structures.

5.4 Noting that each ArrayContainer structue contains an
array of TestStructure structs, we are talking about marshaling a potentially
great number of TestStructure structs.