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

1. Introduction.

1.1 In part
4, I have started to discuss how to interop marshal a managed array that is
contained within a structure.

1.2 I have given a specific working example for
marshaling such a container structure to unmanaged code “one way”
(i.e. as an “in” parameter).

1.3 Here in part 5, I shall demonstrate how to marshal
such a container structure from an unmanaged function to managed code as an
“out” (return) parameter.

1.4 Just like the case in part 4, the example codes that
will be presented here are practically not much more complicated than
direct marshaling of a SAFEARRAY from unmanaged code to managed code, to be
eventually transformed into a managed array.

1.5 I have endeavoured to cover this aspect of
marshaling in order to pave the way for a later installment in which an array of
an array of structures are to be marshaled.

1.6 It is also an opportunity for me 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 an “Out” 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 fill the
underlying ArrayContainer structure with values for its fields. This
ArrayContainer structure is in this way returned to the calling
function.

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

extern "C" __declspec(dllexport) void __stdcall GetArrayContainer
(
  /*[out]*/ ArrayContainer* pArrayContainerReceiver
)
{
	std::vector<TestStructure> vecTestStructure;
	TestStructure test_structure;

	test_structure.m_integer = 0;
	test_structure.m_double = 0;
	test_structure.m_string = ::SysAllocString(L"Hello World");
	vecTestStructure.push_back(test_structure);

	test_structure.m_integer = 1;
	test_structure.m_double = 1.0;
	test_structure.m_string = ::SysAllocString(L"Hello World");
	vecTestStructure.push_back(test_structure);

	test_structure.m_integer = 2;
	test_structure.m_double = 2.0;
	test_structure.m_string = ::SysAllocString(L"Hello World");
	vecTestStructure.push_back(test_structure);

	test_structure.m_integer = 3;
	test_structure.m_double = 3.0;
	test_structure.m_string = ::SysAllocString(L"Hello World");
	vecTestStructure.push_back(test_structure);

	HRESULT hrRet;
	IRecordInfoPtr spIRecordInfoTestStructure = NULL;

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

	// Define a receiver of the SAFEARRAY.
	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".

	IRecordInfoPtr spIRecordInfoArrayContainer = NULL;

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

	spIRecordInfoArrayContainer -> RecordClear((PVOID)pArrayContainerReceiver);		

	// Define a VARIANT that will contain "pSafeArrayOfTestStructures".
	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.
	spIRecordInfoArrayContainer -> PutFieldNoCopy
	(
		INVOKE_PROPERTYPUT,
		pArrayContainerReceiver,
		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;

		::SysFreeString(test_structure.m_string);
	}

	// Because we have used IRecordInfo::PutFieldNoCopy()
	// to insert "pSafeArrayOfTestStructure" as a field
	// value into "ArrayContainer", we must not destroy
	// "pSafeArrayOfTestStructure".
	//
	// If we had used IRecordInfo::PutField() then we
	// must call SafeArrayDestroy() on "pSafeArrayOfTestStructure"
	// or use VariantClear() on the VARIANT that was
	// used in the IRecordInfo::PutField() call.
	// Otherwise there will be a memory leakage.
	//
	//::SafeArrayDestroy(pSafeArrayOfTestStructure);
	//pSafeArrayOfTestStructure = NULL;
	//VariantClear(&varFieldValue);
}

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

• An STL vector “vecTestStructure” is
  defined.
• The vector is used to insert 4 copies of TestStructure
  structs each of which has different values for its “m_integer” and “m_double”
  fields. The “m_string” fields are set to a standard value.
• The GetIRecordType() helper function (first introduced
  in part 2) is used to obtain a pointer to the IRecordInfo interface which is
  associated with the TestStructure UDT.
• The CreateSafeArrayEx<>() helper function is then
  used to copy each of the TestStructure UDTs from “vecTestStructure” to a
  SAFEARRAY.
• Instead of directly using the SAFEARRAY field
  of the input “pArrayContainerReceiver” ArrayContainer structure to hold the
  SAFEARRAY created inside CreateSafeArrayEx<>(), I have used a separate
  SAFEARRAY “pSafeArrayOfTestStructure” to point to it.
• What I intend to do is to use the IRecordInfo::PutFieldNoCopy()
  method to insert the SAFEARRAY directly into the
  “array_of_test_structures” field of “pArrayContainerReceiver”.
• To do this, we need to use a VARIANT to contain
  “pSafeArrayOfTestStructure”.
• Before the function completes and returns to the caller,
  we must clear the TestStructure structs contained inside
  “vecTestStructure”.
• This is necessary because the SAFEARRAY that was
  eventually inserted into “pArrayContainerReceiver” holds a complete copy of
  each of the UDTs contained inside “vecTestStructure”.
• Hence the UDTs inside “vecTestStructure” are no longer
  needed anywhere and if we do not clear them, memory leakage will
  result.
• However, note well that because we have used
  IRecordInfo::PutFieldNoCopy() to insert “pSafeArrayOfTestStructure” as a field
  value into “pArrayContainerReceiver”, we must not destroy
  “pSafeArrayOfTestStructure”.
• As the documentation of IRecordInfo::PutFieldNoCopy() indicated,
  the ownership of “pSafeArrayOfTestStructure” was transferred to the receiving
  “pArrayContainerReceiver”.
• If we had used IRecordInfo::PutField() then we must call
  SafeArrayDestroy() on “pSafeArrayOfTestStructure” or use VariantClear() on the
  VARIANT that was used in the IRecordInfo::PutField() call. Otherwise there will
  be a memory leak.

4. Example Call to
GetArrayContainer().

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

[DllImport("UnmanagedDll.dll", CallingConvention = CallingConvention.StdCall)]
private static extern void GetArrayContainer([Out] out ArrayContainer ArrayContainerReceiver);

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

• When the interop marshaler internally makes a call to
  the GetArrayContainer() function, it will create the unmanaged version of the
  ArrayContainer structure and then pass a pointer to it as parameter to the
  GetArrayContainer() function.
• The unmanaged version of the
  ArrayContainer structure is the one which is created by the Visual C++
  compiler when it processed the “CSConsoleApp.tlb”
  type library via an #import statement in a C++ project :

struct __declspec(uuid("42d386a1-aae1-445e-a755-00aa7b2c1753"))
ArrayContainer
{
    SAFEARRAY * array_of_test_structures;
};

• 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 GetArrayContainer() function.

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

static void DoTest_GetArrayContainer()
{
    ArrayContainer ArrayContainerReceiver;

    GetArrayContainer(out ArrayContainerReceiver);

    for (int i = 0; i < ArrayContainerReceiver.array_of_test_structures.Length; i++)
    {
        Console.WriteLine("ArrayContainerReceiver.array_of_test_structures[{0}].m_integer : [{1}]",
            i, ArrayContainerReceiver.array_of_test_structures[i].m_integer);
        Console.WriteLine("ArrayContainerReceiver.array_of_test_structures[{0}].m_double : [{1}]",
            i, ArrayContainerReceiver.array_of_test_structures[i].m_double);
        Console.WriteLine("ArrayContainerReceiver.array_of_test_structures[{0}].m_string : [{1:S}]",
            i, ArrayContainerReceiver.array_of_test_structures[i].m_string);
    }
}

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

• An ArrayContainer structure “ArrayContainerReceiver” is
  defined but is not instantiated.
• This is acceptable because it is used as an “out”
  parameter to a call to GetArrayContainer().
• Under the covers, when the GetArrayContainer() returns,
  a new ArrayContainer structure will be created by the interop marshaler
  and the unmanaged ArrayContainer structure the pointer to which was
  passed to the function would be filled with actual field
  values.
• These field values will be used to set the corresponding
  ones in the newly created managed ArrayContainer structure.
• The new field values of the managed ArrayContainer
  structure will be displayed via a loop.

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

ArrayContainerReceiver.array_of_test_structures[0].m_integer : [0]
ArrayContainerReceiver.array_of_test_structures[0].m_double : [0]
ArrayContainerReceiver.array_of_test_structures[0].m_string : [Hello World]
ArrayContainerReceiver.array_of_test_structures[1].m_integer : [1]
ArrayContainerReceiver.array_of_test_structures[1].m_double : [1]
ArrayContainerReceiver.array_of_test_structures[1].m_string : [Hello World]
ArrayContainerReceiver.array_of_test_structures[2].m_integer : [2]
ArrayContainerReceiver.array_of_test_structures[2].m_double : [2]
ArrayContainerReceiver.array_of_test_structures[2].m_string : [Hello World]
ArrayContainerReceiver.array_of_test_structures[3].m_integer : [3]
ArrayContainerReceiver.array_of_test_structures[3].m_double : [3]
ArrayContainerReceiver.array_of_test_structures[3].m_string : [Hello World]

5. In Conclusion.

5.1 Here in part 5, we have looked at how managed
structures may be derived from unmanaged code by way of a SAFEARRAY contained in
an outer wrapping structure.

5.2 I have made a good
attempt at demonstrating the use of the
IRecordInfo::PutFieldNoCopy() method to insert a field value into a
UDT.

5.3 Part of my aim was to demontrate a solid
example of memory ownership.

5.4 I certainly hope that the reader has benefitted from
this demonstration.