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

1. Introduction.

1.1 In parts 1 through 3 of this series of articles, I
have thoroughly discussed the techniques for exchanging arrays between
managed and unmanaged code by way of SAFEARRAYs.

1.2 The knowledge that can be gained from the first 3
parts of this series is sufficient for general development purposes.

1.3 From part 4 onwards, I shall be covering cases where
an outer structure is used to contain the array of structures.

1.4 The use of SAFEARRAYs for marshaling managed
arrays is particularly useful when the array is meant to be variable in
length.

1.5 I have previously written about marshaling managed
structures that contain arrays (see the
“Passing Managed Structures With Arrays To Unmanaged Code” series beginning from
part 1).

1.6 However, the array contained in the example
structure is an integer array whereas the arrays that are used in this
series of articles will be arrays of structures, hence serving an alternate
(and more complex) example.

2. A New Structure –
ArrayContainer.

2.1 Along with using the same TestStructure struct which
was first defined in part 1, we shall be using a new structure : ArrayContainer
:

[ComVisible(true)]
[StructLayout(LayoutKind.Sequential, Pack = 1)]
[Guid("42D386A1-AAE1-445e-A755-00AA7B2C1753")]
public struct ArrayContainer
{
    [MarshalAs(UnmanagedType.SafeArray, SafeArraySubType = VarEnum.VT_RECORD)]
    public TestStructure[] array_of_test_structures;
}

2.2 For the purpose of this article, I have defined
this structure inside the source codes of the C# console client application
CSConsoleApp which was first introduced in part 1.

2.3 After compiling the CSConsoleApp project into an
output EXE assembly, we must call on the Type Library Exporter (TLBEXP.EXE)
to produce a type library that will contain the COM-visible constructs defined
in CSConsoleApp.exe :

tlbexp CSConsoleApp.exe /out:CSConsoleApp.tlb

2.4 After this is done, we can
examine CSConsoleApp.tlb via OLEVIEW.EXE and
observe the following definitions contained inside the type
library :

// Generated .IDL file (by the OLE/COM Object Viewer)
// 

[
  uuid(4E765D3B-C1F5-4CDE-8095-1E9614E0AE3F),
  version(1.0)
]
library CSConsoleApp
{
    	// TLib :     // Forward declare all types defined in this typelib
	typedef
	[
		uuid(42D386A1-AAE1-445E-A755-00AA7B2C1753), version(1.0)    ,
		custom({0F21F359-AB84-41E8-9A78-36D110E6D2F9}, "CSConsoleApp.ArrayContainer")
	]
	struct tagArrayContainer
	{
		SAFEARRAY(TestStructure) array_of_test_structures;
	} ArrayContainer;

	typedef
	[
		uuid(1979BCD7-1062-44D8-B3FC-A2686C61E715), version(1.0)    ,
		custom({0F21F359-AB84-41E8-9A78-36D110E6D2F9}, "CSConsoleApp.TestStructure")
	]
	struct tagTestStructure
	{
		long m_integer;
		double m_double;
		BSTR m_string;
	} TestStructure;
};

We can see that the ArrayContainer structure contains a
SAFEARRAY of TestStructure structs.

2.5 That the ArrayContainer structure is a wrapper for a
SAFEARRAY of TestStructure does not add very much more complexity
to its management unless ArrayContainer also contains other
fields.

2.6 I have, however, defined it in the simple way
it is so that when we reach later parts of this series of articles where we
actually define a structure that contains an array of ArrayContainer structures,
things do not get overly complicated and difficult to understand.

3. Unmanaged API that takes an ArrayContainer Structure
as an “In” Parameter.

3.1 In this section, I shall present a new function to
be exported from the UnmanagedDll.dll that
we have been using since part 1. This function takes an ArrayContainer structure
as input parameter and then displays the field values of each TestStructure
struct contained inside the “array_of_test_structures” SAFEARRAY
field.

3.2 Full source codes listed below :

extern "C" __declspec(dllexport) void __stdcall SetArrayContainer
(
  /*[in]*/ ArrayContainer array_container
)
{
	std::vector<TestStructure> vecTestStructure;

	// Copy the TestStructure elements of the SAFEARRAY
	// in "array_container.array_of_test_structures"
	// into a vector of TestStructure structs.
	CopySafeArrayToVector<TestStructure, VT_RECORD>
	(
		array_container.array_of_test_structures,
		vecTestStructure
	);

	// Display the field values of each TestStructure
	// within the "vecTestStructure" vector.
	std::for_each
	(
		vecTestStructure.begin(),
		vecTestStructure.end(),
		display_test_structure()
	);

	// Obtain the IRccordInfo interface associated with
	// the TestStructure UDT.
	IRecordInfoPtr spIRecordInfoTestStructure = NULL;

	SafeArrayGetRecordInfo
	(
		array_container.array_of_test_structures,
		&spIRecordInfoTestStructure
	);

	// Before the end of this function, each of the
	// TestStructure structs inside vecTestStructure
	// must be cleared.
	std::for_each
	(
		vecTestStructure.begin(),
		vecTestStructure.end(),
		clear_test_structure(spIRecordInfoTestStructure)
	);
}

The following is a synopsis of the function above
:

• It defines a vector of TestStructure structs
  “vecTestStructure”.
• A helper function CopySafeArrayToVector<>() is
  used to copy the TestStructure elements of
  “array_container.array_of_test_structures” (i.e. the SAFEARRAY of TestStructure
  structs contained in the input ArrayContainer “array_container”) to the
  “vecTestStructure” vector.
• It then use the for_each() algorithm function to
  loop through the elements of the “vecTestStructure” vector and display the field
  values of each TestStructure struct element.
• It then calls on SafeArrayGetRecordInfo() to obtain a
  pointer to the IRecordInfo interface associated with the TestStructure
  UDT.
• Another for_each() loop is called, this time to clear
  each TestStructure struct element contained inside
  “vecTestStructure”.
• This last action is necessary because each TestStructure
  struct element contained inside “vecTestStructure” is a copy of its
  corresponding TestStructure contained inside
  “array_container.array_of_test_structures”.
• While “array_container.array_of_test_structures” will
  eventually be destroyed by the interop marshaler (it owns the entire
  ArrayContainer structure passed to the SetArrayContainer() function, the
  TestStructure structs contained inside “vecTestStructure” must be cleared
  manually.

3.3 The CopySafeArrayToVector<>() helper function
source codes are listed below :

template <class T, VARTYPE v>
void CopySafeArrayToVector
(
  /*[in]*/ SAFEARRAY*& pSafeArray,
  /*[out]*/ std::vector<T>& vecReceiver
)
{
	VARTYPE vt;	

	SafeArrayGetVartype(pSafeArray, &vt);

	// We assert that the Variant Type is "v".
	_ASSERT(vt == v);

	long LBound = 0;
	long UBound = 0;

	SafeArrayGetLBound(pSafeArray, 1, &LBound);
	SafeArrayGetUBound(pSafeArray, 1, &UBound);

	ULONG ulSafeArraySize = UBound - LBound + 1;

	for (ULONG ulIndex = 0; ulIndex < ulSafeArraySize; ulIndex++)
	{
		long lIndexVector[1];
		T data;
		HRESULT hrRetTemp;

		lIndexVector[0] = ulIndex;

		// Must initialize memory area of "data"
		// before calling SafeArrayGetElement().
		memset(&data, 0, sizeof(T));

		hrRetTemp = SafeArrayGetElement
		(
			(SAFEARRAY*)pSafeArray,
			(long*)lIndexVector,
			(void*)(&data)
		);

		if (SUCCEEDED(hrRetTemp))
		{
			vecReceiver.push_back(data);
		}
	}
}

The following is a summary of this helper function
:

• This function takes 2 template parameters “T” which
  specifies the type of data contained in the SAFEARRAY parameter. “T” is
  also the data type of the vector paraneter that receives a copy of the
  contents of the SAFEARRAY.
• It first ues the SafeArrayGetVartype() function to
  obtain the variant type of the elements contained in the
  SAFEARRAY.
• This is asserted to match the VARTYPE “v” which is
  specified by template parameter.
• The SafeArrayGetLBound() and SafeArrayGetUBound()
  functions are then used to calculate the number of elements contained inside the
  SAFEARRAY.
• The SAFEARRAY is then looped through and with each
  iteration, SafeArrayGetElement() is called to obtain a copy of an
  element.
• The element is then pushed into the receiving
  vector.

3.4 The “display_test_structure” functor class which was
used in the for_each() loop is listed below :

struct display_test_structure :
	public std::unary_function<TestStructure, void>
{
	// Constructor
	display_test_structure() :
		m_iCounter(0)
	{
	}

	// Copy constructor.
	display_test_structure(const display_test_structure& rhs) :
		m_iCounter(rhs.m_iCounter)
	{
	}

	void operator () (TestStructure& test_structure)
	{
		printf ("TestStructure[%d].m_integer : [%d]\r\n",
			m_iCounter, test_structure.m_integer);
		printf ("TestStructure[%d].m_double  : [%f]\r\n",
			m_iCounter, test_structure.m_double);
		printf ("TestStructure[%d].m_string  : [%S]\r\n",
			m_iCounter, test_structure.m_string);
		m_iCounter++;
	};

	int m_iCounter;
};

3.5 The “clear_test_structure” functor class which was
used in a for_loop to clear the TestStructure struct elements of the
“vecTestStructure” vector is listed below :

struct clear_test_structure :
	public std::unary_function<TestStructure, void>
{
  // Constructor.
  clear_test_structure(IRecordInfoPtr& refIRecordInfoPtr) :
    m_refIRecordInfoPtr(refIRecordInfoPtr)
  {
  }

  // Copy constructor.
  clear_test_structure(const clear_test_structure& rhs) :
    m_refIRecordInfoPtr(rhs.m_refIRecordInfoPtr)
  {
  }

  void operator () (TestStructure& test_structure)
  {
	m_refIRecordInfoPtr -> RecordClear((PVOID)&test_structure);
  }

  IRecordInfoPtr& m_refIRecordInfoPtr;
};

4. Example C# Call to
SetArrayContainer().

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

[DllImport("UnmanagedDll.dll", CallingConvention = CallingConvention.StdCall)]
private static extern void SetArrayContainer([In] ArrayContainer array_container);

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

• The ArrayContainer parameter “array_container”,
  when passed to the unmanaged world, will be transformed into the following
  “unmanaged equivalent” format :

struct ArrayContainer
{
    SAFEARRAY * array_of_test_structures;
};

• When the interop marshaler is about to call
  SetArrayContainer(), it first creates such an unmanaged structure and then
  translates the fields of the managed ArrayContainer structure to their
  equivalents in the unmanaged ArrayContainer structure.
• For example, the “array_of_test_structures” field which
  is a managed array of TestStructure structs is transformed into an equivalent
  SAFEARRAY and the “array_of_test_structures” field of the unmanaged
  ArrayContainer struct will point to it.
• The InAttribute indicates that the unmanaged
  ArrayContainer structure will be passed as a read-only parameter. It is not to
  be modified by the SetArrayContainer() function.

4.2 The following is a sample function that calls
SetArrayContainer() :

static void DoTest_SetArrayContainer()
{
    ArrayContainer array_container = new ArrayContainer();

    array_container.array_of_test_structures = new TestStructure[3];

    for (int i = 0; i < array_container.array_of_test_structures.Length; i++)
    {
        array_container.array_of_test_structures[i].m_integer = i;
        array_container.array_of_test_structures[i].m_double = (double)i;
        array_container.array_of_test_structures[i].m_string = string.Format("Hello World [{0}]", i);
    }

    SetArrayContainer(array_container);
}

The following is a synopsis of the function above
:

• It instantiates a ArrayContainer
  structure.
• The “array_of_test_structures” member is instantiated to
  an array of 3 TestStructure structs.
• The “array_of_test_structures” array is filled with
  values.
• SetArrayContainer() is called.

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

TestStructure[0].m_integer : [0]
TestStructure[0].m_double  : [0.000000]
TestStructure[0].m_string  : [Hello World [0]]
TestStructure[1].m_integer : [1]
TestStructure[1].m_double  : [1.000000]
TestStructure[1].m_string  : [Hello World [1]]
TestStructure[2].m_integer : [2]
TestStructure[2].m_double  : [2.000000]
TestStructure[2].m_string  : [Hello World [2]]

5. In Conclusion.

5.1 Here in part 4, we have shifted gears and looked at
how managed structures may be marshaled to unmanaged code by way of a SAFEARRAY
contained in an outer wrapping structure.

5.2 Although the concept is practically not
much more complicated than direct marshaling of a managed array to unmanaged
code via SAFEARRAYs, I have endeavoured to cover this in order to pave the way
for a later installment in which an array of an array of structures are to be
marshaled.

5.3 It is also an opportunity for me to introduce and
expound on some useful helper functions for the benefit of the
reader.