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

1. Introduction.

1.1 In part
1 of this series of articles, I demonstrated how to transfer managed
arrays to unmanaged code as SAFEARRAYs. The transfer was single-directional
“into” the unmanaged function and the SAFEARRAY that was passed to the unmanaged
function is treated as “read-only”.

1.2 Then in part
2, I showed how to return a SAFEARRAY from unmanaged code to
managed code as an “out” parameter. The transfer this time was also
single-directional but the direction is “outwards” towards the managed
code caller. The SAFEARRAY that was returned is used to generate a managed
array.

1.3 Here in part 3, I shall explain how to pass a
managed array “to and from” unmanaged code as both an “in” and “out” (i.e. by
reference) parameter.

1.4 A parameter passed this way is marshaled
“into” the unmanaged function when it is called and when the function returns,
the same parameter is marshaled “out of” the unmanaged function. The parameter
is also subject to modification by the target function.

1.5 As usual, throughout this article, we shall be
working only with single-dimensional managed
arrays and SAFEARRAYs.

2. TestStructure, CSConsoleApp.tlb Type
Library and UnmanagedDll.DLL

2.1 We shall be using the same TestStructure struct that
we have developed in part 1.

2.2 We shall also continue to use
the CSConsoleApp.tlb type
library that was produced from the CSConsoleApp console application
solution that was presented in part 1.

2.3 We shall augment UnmanagedDll.dll with
some helper functions as well as a new exported API to be called in
the CSConsoleApp console application.

2.4 The source codes of the CSConsoleApp console
application will also be updated with new test codes.

3. Unmanaged API that References a SAFEARRAY of
TestStructure.

3.1 The new exported function that we will
expose to C# takes as parameter a double pointer to a SAFEARRAY of
TestStructure structures.

3.2 This double pointer will be used to point to a
SAFEARRAY of TestStructure UDTs that derives from a managed array. It will also
be used to return a SAFEARRAY of TestStructure UDTs to the caller.

3.3 In our case, the caller will be the interop
marshaler which will first transform a managed array into a SAFEARRAY in order
to pass to the exported function. The interop marshaler will then transform the
returned SAFEARRAY back into a managed array.

3.4 Note the protocol on memory ownership : because the
interop marshaler is the eventual receiver of the SAFEARRAY which is
returned, the interop marshaler owns the SAFEARRAY and is at liberty
to destroy it when it no longer needs it.

3.5 The following is a full code listing of this
function :

// ModifyArrayOfTestStructure() will modify the contents
// of the input SAFEARRAY. It will also add new elements
// to the SAFEARRAY.
extern "C" __declspec(dllexport) void __stdcall ModifyArrayOfTestStructure
(
  /*[in, out]*/ SAFEARRAY** ppSafeArrayToModify
)
{
	IRecordInfoPtr spIRecordInfo = NULL;

	// We obtain a pointer to the IRecordInfo interface associated
	// with the SAFEARRAY. It is used to clear TestStructure structs.
	SafeArrayGetRecordInfo(*ppSafeArrayToModify, &spIRecordInfo);

	// If we are unable to obtain such an interface,
	if (spIRecordInfo == NULL)
	{
		return;
	}

	// First determine how many elements there are inside
	// "ppSafeArrayToModify".
	long LBound = 0;
	long UBound = 0;

	SafeArrayGetLBound(*ppSafeArrayToModify, 1, &LBound);
	SafeArrayGetUBound(*ppSafeArrayToModify, 1, &UBound);

	ULONG ulSafeArraySize = UBound - LBound + 1;

	if (ulSafeArraySize > 0)
	{
		// The SAFEARRAY must have at least one element
		// for us to modify.
		TestStructure test_structure;
		long rgIndices[1];

		// The UDT receiving structure must be cleared
		// before calling on SafeArrayGetElement() to
		// obtain a copy of an element.
		memset(&test_structure, 0, sizeof(TestStructure));

		// We will modify the very first element.
		rgIndices[0] = 0;

		SafeArrayGetElement
		(
			*ppSafeArrayToModify,
			rgIndices,
			(void FAR*)&test_structure
		);

		// Increment the values of the
		// "m_integer" and "m_double"
		// fields.
		test_structure.m_integer += 100;
		test_structure.m_double += 100;
		// Clear the original BSTR and
		// set it to a different value.
		::SysFreeString(test_structure.m_string);
		test_structure.m_string = ::SysAllocString(L"Modified String");

		// Insert "test_structure" into the SAFEARRAY
		// at the same index position (i.e. 0);
		SafeArrayPutElement
		(
			(SAFEARRAY*)*ppSafeArrayToModify,
			(long*)rgIndices,
			(void*)(&test_structure)
		);

		// After "inserting" "test_structure" into
		// the SAFEARRAY, we must remember to clear it.
		spIRecordInfo -> RecordClear((void*)(&test_structure));
	}

	// Now modify the size of the SAFEARRAY.
	// Increase it 3 more elements.
	SAFEARRAYBOUND rgsabound[1];

	rgsabound[0].lLbound = 0;
	rgsabound[0].cElements = ulSafeArraySize + 3;

	HRESULT hrRetTemp = SafeArrayRedim
	(
		*ppSafeArrayToModify,
		rgsabound
	);

	if (SUCCEEDED(hrRetTemp))
	{
		for (ULONG ulIndex = ulSafeArraySize; ulIndex < (ulSafeArraySize + 3); ulIndex++)
		{
			long rgIndices[1];
			TestStructure test_structure;

			rgIndices[0] = ulIndex;

			memset(&test_structure, 0, sizeof(TestStructure));

			// Add simple values to the fields of the new TestStructure
			// structs that are added to the SAFEARRAY.
			test_structure.m_integer = (int)ulIndex;
			test_structure.m_double = (double)ulIndex;
			test_structure.m_string = ::SysAllocString(L"New String");			

			SafeArrayPutElement
			(
				(SAFEARRAY*)*ppSafeArrayToModify,
				(long*)rgIndices,
				(void*)(&test_structure)
			);

			spIRecordInfo -> RecordClear((void*)(&test_structure));
		}
	}
}

The following is a synopsis of this function
:

• The function first tries to obtain a pointer to
  the IRecordInfo interface associated with the UDT contained in the
  SAFEARRAY. This is done by using SafeArrayGetRecordInfo().
• It then calculates the total number of elements in the
  SAFEARRAY (using SafeArrayGetLBound() and
  SafeArrayGetUBound()).
• Assuming that the SAFEARRAY contains at least one
  element, this function will modify the field values of the very first
  element.
• Note that SafeArrayGetElement() is used to obtain a copy
  of the target element and then SafeArrayPutElement() is used to replace the
  target element.
• When SafeArrayPutElement() is called, it will first
  clear the fields of the existing element residing at the target
  index.
• Then the onus is on the ModifyArrayOfTestStructure()
  function to clear the TestStructure struct which was used to insert the UDT at
  the target index. For this, IRecordInfo::RecordClear() is
  used.
• After that, the ModifyArrayOfTestStructure() function
  uses SafeArrayRedim() to resize the SAFEARRAY to a larger
  size.
• A loop is then performed to insert new additional UDTs
  into the SAFEARRAY.
• Note that as each UDT is inserted into the SAFEARRAY, a
  copy of the UDT is made and stored in the SAFEARRAY.
• Hence the original TestStructure UDT must be cleared
  after each call to SafeArrayPutElement().

4. Example C# Call to
ModifyArrayOfTestStructure().

4.1 The following shows how the
ModifyArrayOfTestStructure() API should be declared in a C# program :

[DllImport("UnmanagedDll.dll", CallingConvention = CallingConvention.StdCall)]
private static extern void ModifyArrayOfTestStructure
(
  [In][Out] [MarshalAs(UnmanagedType.SafeArray, SafeArraySubType = VarEnum.VT_RECORD)]
  ref TestStructure[] SafeArrayToModify
);

Now note the use of the various attributes :

• The presence of the InAttribute and the OutAttribute
  indicate that the managed array parameter (i.e. “SafeArrayToModify”) is to be
  marshaled into and out of the ModifyArrayOfTestStructure() function. The “ref”
  keyword further indicates this to the C# compiler.
• These attributes also indicate to the interop
  marshaler that whatever form the counterpart parameter (i.e. the parameter
  of the unmanaged function) takes when it is passed to the target function, it
  may be eventually modified before its return.
• However, it is nevertheless owned by the caller
  which is at liberty to destroy it when it is returned from the unmanaged
  function.
• The way the MarshalAsAttribute is specified as well as
  the presence of the OutAttribute indicate to the interop marshaler that the
  counterpart parameter will take the form of a double pointer to a
  SAFEARRAY.
• The “SafeArraySubType” field for the MarshalAsAttribute,
  being equal to “VarEnum.VT_RECORD”, indicates to the interop marshaler that the
  SAFEARRAY will contain UDTs.
• And since the “SafeArrayToModify” parameter is typed as
  an array of TestStructure, the UDT must be the equivalent of the
  TestStructure.

4.2 The following is a sample C# function that makes a
call to GetArrayOfTestStructure() :

static void DoTest_ModifyArrayOfTestStructure()
{
    // Define and instantiate a managed array of 3
    // TestStructure structs.
    TestStructure[] SafeArrayOfTestStructure = new TestStructure[3];

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

    // Call on ModifyArrayOfTestStructure() to modify
    // this array.
    ModifyArrayOfTestStructure(ref SafeArrayOfTestStructure);

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

The following is a synopsis :

• A managed array of 3 TestStructure structs is defined
  and instantiated.
• Simple values are assigned to the field values of each
  element.
• The ModifyArrayOfTestStructure() API is then invoked and
  the managed array is passed as a parameter by reference.
• Thereafter, we display all the contents of the managed
  array.

4.3 The following is what happened under the
covers :

• When ModifyArrayOfTestStructure() is called, the interop
  marshaler will internally prepare a SAFEARRAY and fill it with the (unmanaged)
  UDT equivalent of each of the (managed) TestStructure structs contained in the
  “SafeArrayOfTestStructure” array.
• Then, sensing that the “SafeArrayToModify” parameter of
  the ModifyArrayOfTestStructure() function has been designated as an “in” and
  “out” parameter, the interop marshaler passes a double pointer to the SAFEARRAY
  as parameter when it calls the ModifyArrayOfTestStructure()
  function.
• The ModifyArrayOfTestStructure() function is free to
  modify the SAFEARRAY in whatever way it deems fit.
• When ModifyArrayOfTestStructure() returns, the interop
  marshaler will use the returned SAFEARRAY to internally modify the managed
  array.
• However, very likely, the interop marshaler will simply
  delete the entire original managed array and re-create a new one from the latest
  contents of the SAFEARRAY.
• When the managed array of TestStructure is finally
  modified/re-created, the returned SAFEARRAY which was shared by both the interop
  marshaler and the ModifyArrayOfTestStructure() API will be destroyed. Each
  TestStructure contained inside the SAFEARRAY will be destroyed by calling on the
  RecordDestroy() method using the IRecordInfo pointer which is already contained
  within the SAFEARRAY.

4.4 At runtime, the C# function
DoTest_GetArrayOfTestStructure() will produce the following expected output
:

SafeArrayOfTestStructure[0].m_integer : [100]
SafeArrayOfTestStructure[0].m_double : [100]
SafeArrayOfTestStructure[0].m_string : [Modified String]
SafeArrayOfTestStructure[1].m_integer : [1]
SafeArrayOfTestStructure[1].m_double : [1]
SafeArrayOfTestStructure[1].m_string : [Hello World [1]]
SafeArrayOfTestStructure[2].m_integer : [2]
SafeArrayOfTestStructure[2].m_double : [2]
SafeArrayOfTestStructure[2].m_string : [Hello World [2]]
SafeArrayOfTestStructure[3].m_integer : [3]
SafeArrayOfTestStructure[3].m_double : [3]
SafeArrayOfTestStructure[3].m_string : [New String]
SafeArrayOfTestStructure[4].m_integer : [4]
SafeArrayOfTestStructure[4].m_double : [4]
SafeArrayOfTestStructure[4].m_string : [New String]
SafeArrayOfTestStructure[5].m_integer : [5]
SafeArrayOfTestStructure[5].m_double : [5]
SafeArrayOfTestStructure[5].m_string : [New String]

The following is a general summary for the results shown
above :

• At the start of the DoTest_ModifyArrayOfTestStructure()
  function, a managed array of 3 TestStructure structs is
  created.
• Then the ModifyArrayOfTestStructure() function modified
  the very first element to contain values 100, 100 and “Modified String” for its
  “m_integer”, “m_double” and “m_string” field values
  respectively.
• The ModifyArrayOfTestStructure() function also added 3
  new TestStructure UDTs with numeric values that correspond with their SAFEARRAY
  index positions and a standard string value of “New String”.
• Hence eventually, the “SafeArrayOfTestStructure” array
  contained 6 elements with values as shown.

5. In Conclusion.

5.1 Here in part 3, I have demonstrated sending and
returning a SAFEARRAY to and from an unmanaged function in managed
code.

5.2 Various SAFEARRAY APIs are used to demonstrate ways
to modify both the contents of SAFEARRAYs as well as the size of
SAFEARRAYs.

5.3 I have also shown that the modified contents of a
SAFEARRAY is used by the interop marshaler to modify/re-create the original
managed array.

5.4 Again I emphasized that with memory ownership,
the interop marshaler is at liberty to destroy the returned
SAFEARRAY.

5.5 This part marks the end of my basic treatment
of marshaling a managed array to and from unmanaged functions by way of
SAFEARRAYs.

5.6 Further parts of this series of articles are
not required reading for those who are not interested in more complex
containment of managed arrays as UDTs in SAFEARRAYs.