[转]Passing Managed Structures With Strings To Unmanaged Code Part 3

1. Introduction.

1.1 In part
1 of this series of blogs we studied how to pass a managed structure
(which contains strings) to unmanaged code. The structure was passed as an “in”
(by-value) parameter, i.e. the structure was passed to the unmanaged code as a
read-only parameter.

1.2 Then in part
2, we studied the techniques for receiving such a structure from
unmanaged code as an “out” parameter.

1.3 Here in part 3, I shall expound on passing a
structure (which contain strings) to and from unmanaged code. That is, as a
parameter passed in both “in” and “out” directions (or
a reference parameter).

2. Sample Structure, Unmanaged String Representations
and Marshaling Direction.

2.1 We shall continue to use the test structures that we
have bult up from part 1.

2.2 No matter the direction of parameter
passing, the ways that a string structure member can be represented in
unmanaged code remain the same :

• As a fixed length inline NULL-terminated character array
  (aka C-style string).
• As a pointer to a NULL-terminated character array
  (better known as LPCSTR in C/C++ lingo).
• As a BSTR.

2.3 Note that this time, the marshaling direction
will be 2-ways. That is, from the managed side to the unmanaged side and
reverse. Hence the string allocated on the managed side will be visible on
the unmanaged side. Furthermore, the string allocated on the
unmanaged side and returned “outwardly” to the managed side will also be
marshaled.

2.4 Throughout the various examples below,
attention will be given to the effects of marshaling an “in” and “out”
parameter.

3. Passing a Structure with a Fixed-Length Inline
String.

3.1 For the demonstrative codes presented in this
section, we shall use the C# structure TestStruct01 :

[StructLayout(LayoutKind.Sequential, Pack = 1, CharSet = CharSet.Ansi)]
public struct TestStruct01
{
  [MarshalAs(UnmanagedType.ByValTStr, SizeConst = 21)]
  public string m_strString;
};

3.2 And the C++ equivalent is as usual :

#pragma pack (1)

struct TestStruct01
{
  char m_szString[21];
};

3.3 An example C++-based unmanaged API that takes such a
structure as an “in” and “out” parameter is listed below :

void __stdcall ReferenceTestStruct01
(
  /*[in, out]*/ TestStruct01* ptest_struct_01
)
{
  printf
  (
    "Value of ptest_struct_01 -> m_szString before change : [%s].\r\n",
    ptest_struct_01 -> m_szString
  );
  strcpy (ptest_struct_01 -> m_szString, "From unmanaged code.");
}

3.4 The C# declaration for such an API is listed below
:

[DllImport("TestDLL01.dll", CallingConvention = CallingConvention.StdCall)]
public static extern void ReferenceTestStruct01([In][Out] ref TestStruct01 test_struct_01);

3.5 And a sample C# code for invoking the API
:

static void ReferenceTestStruct01()
{
  TestStruct01 test_struct_01 = new TestStruct01();

  test_struct_01.m_strString = "From managed code.";

  ReferenceTestStruct01(ref test_struct_01);

  DisplayTestStruct01(test_struct_01);
}

This time, the test_struct_01 structure is
both instantiated and initialized before the call to
ReferenceTestStruct01(). This is a necessary action because
“test_struct_01″ is to be passed as a “ref” parameter which means that
its value is both passed to and set by the ReferenceTestStruct01()
API.

We then used DisplayTestStruct01() (an API we have
already met in part 1) to display the value set for
“test_struct_01.m_strString”.

3.6 Under the covers, the following is how the interop
marshaler performs the marshaling process :

• When the ReferenceTestStruct01() API was called, the
  interop marshaler will allocate a buffer with space large enough to hold the
  structure which is listed in point 3.2.
• Note that this temporary buffer need not always be
  freshly allocated using Marshal.AllocHGlobal() or Marshal.AllocCoTaskMem(). This
  buffer may be from a cached and re-usable memory area managed by the
  CLR.
• But wherever it originated, this memory buffer serves to
  store a temporary unmanaged version of the TestStruct01
  structure.
• The interop marshaler will then pass a pointer to this
  structure to the ReferenceTestStruct01() API.
• This time, being passed as both “in” and “out”, the
  unmamaged test_struct_01 structure will contain its initialized field
  values. Hence the ptest_struct_01 -> m_szString will contain the string
  “From managed code.”
• The API will then re-assign the character
  values of ptest_struct_01 -> m_szString.
• When the API returns, the interop marshaler will assign
  the string value in the unmanaged “m_szString” field to the counterpart
  “m_strString” field of the managed “test_struct_01″ structure. This is the
  effect of being an “out” parameter.
• The managed “test_struct_01″ structure will now
  be completely re-set by the ReferenceTestStruct01() API.
• At this time, the interop marshaler is free to re-use
  (for other purposes) the original buffer space which was used to hold the
  temporary structure.

3.7 The following expected output will be displayed on
the console :

Value of ptest_struct_01 -> m_szString before change : [From managed code.].
test_struct_01.m_szString : [From unmanaged code.].

3.8 Whenever we deal with a structure with a string
field typed as an inline embedded character array, things are pretty
simple. Most of the marshaling work is done by the interop
marshaler.

3.9 It is the interop marshaler that allocates memory
space for the unmanaged structure and performs the marshaling of field values to
the unmanaged structure. When the unmanaged API returned, the interop
marshaler transcribes the new character values of the inline
character array field to the corresponding string field of the managed
structure. The interop marshaler then either destroys the unmanaged structure or
re-uses the memory occuppied by it.

4. Passing a Structure with a Pointer to a
NULL-terminated Character Array.

4.1 In this section, we use the TestStruct02 structure
that we first defined in part 1 :

[StructLayout(LayoutKind.Sequential, Pack = 1)]
public struct TestStruct02
{
  [MarshalAs(UnmanagedType.LPStr)]
  public string m_strString;
};

4.2 The corresponding C++ equivalent of such a structure
is :

#pragma pack(1)

struct TestStruct02
{
  LPCSTR m_pszString;
};

4.3 An example C++-based unmanaged API that takes such a
structure as an “in” and “out” parameter is listed below :

void __stdcall ReferenceTestStruct02(/*[in, out]*/ TestStruct02* ptest_struct_02)
{
  printf ("Value of ptest_struct_02 -> m_pszString before change : [%s].\r\n", ptest_struct_02 -> m_pszString);

  if (ptest_struct_02 -> m_pszString)
  {
    ::CoTaskMemFree((LPVOID)(ptest_struct_02 -> m_pszString));
    ptest_struct_02 -> m_pszString = NULL;
  }
  char szTemp[] = "From unmanaged code.";
  ptest_struct_02 -> m_pszString = (LPSTR)::CoTaskMemAlloc(sizeof(szTemp));
  strcpy ((LPSTR)(ptest_struct_02 -> m_pszString), szTemp);
}

4.4 The C# declaration for such an API is listed below
:

[DllImport("TestDLL01.dll", CallingConvention = CallingConvention.StdCall)]
public static extern void ReferenceTestStruct02([In][Out] ref TestStruct02 test_struct_02);

4.5 And a sample C# code for invoking the API
:

static void ReferenceTestStruct02()
{
  TestStruct02 test_struct_02 = new TestStruct02();

  test_struct_02.m_strString = "From managed code.";

  ReferenceTestStruct02(ref test_struct_02);

  DisplayTestStruct02(test_struct_02);
}

Just like the example we met in section 3, the
test_struct_02 structure is both instantiated and initialized before the call to
ReferenceTestStruct02(). This is a necessary action because test_struct_02 is to
be passed as a “ref” parameter which means that its value is both passed to and
set by the ReferenceTestStruct02() API.

We then used DisplayTestStruct02() (an API we have
already met in part 1) to display the value set for
test_struct_02.m_strString.

4.6 Under the covers, the following are the processes
that take place throughout the ReferenceTestStruct02() API call :

• When the ReferenceTestStruct02() API was called, the
  interop marshaler will allocate a buffer with space large enough to hold the
  structure which is listed in point 4.2.
• Note that this temporary buffer need not always be
  freshly allocated using Marshal.AllocHGlobal() or Marshal.AllocCoTaskMem(). This
  buffer may be from a cached and re-usable memory area managed by the
  CLR.
• But wherever it originated, this memory buffer serves to
  store a temporary unmanaged version of the TestStruct02
  structure.
• The interop marshaler will then pass a pointer to this
  structure to the ReferenceTestStruct02() API.
• This time, being passed as both “in” and “out”, the
  unmamaged test_struct_02 structure must contain the initialized field
  values of the managed test_struct_02 structure.
• Using the current value in test_struct_02.m_strString
  (i.e. “From managed code.”), the interop marshaler will allocate (using
  Marshal.StringToCoTaskMemAnsi()) a sufficiently-sized character buffer and then
  copy the managed string to it. A pointer to this buffer will be assigned to the
  m_pszString field of the unmanaged structure.
• This is done before ReferenceTestStruct02() is
  invoked.
• Hence when code control reaches ReferenceTestStruct02(),
  and ptest_struct_02 -> m_pszString is to be printed, “From managed
  code.” will be displayed on the console.
• The API will then re-assign ptest_struct_02 ->
  m_pszString by first freeing the buffer that it points to (using
  ::CoTaskMemFree()).
• Note that ::CoTaskMemFree() must be used because it
  matches Marshal.AllocCoTaskMem().
• The API will then re-allocate a new buffer using
  ::CoTaskMemAlloc() and make ptest_struct_02 -> m_pszString point to
  it.
• A new string will be assigned to the new
  buffer.
• Then when the API returns, the interop marshaler will
  assign the string contained in the buffer pointed to by ptest_struct_02
  -> m_pszString to the counterpart m_strString field of the managed
  test_struct_02 structure. This is the effect of being an “out”
  parameter.
• The managed test_struct_02 structure will now be
  completely re-set by the ReferenceTestStruct02() API.
• At this time, the interop marshaler is free to re-use
  (for other purposes) the original buffer space which was used to hold the
  temporary structure.

4.7 The following expected output will be displayed on
the console screen :

Value of ptest_struct_02 -> m_pszString before change : [From managed code.].
test_struct_02.m_pszString : [From unmanaged code.].

4.8 When we pass by reference a structure with a
string field typed as a pointer to a NULL-terminated character array, the
unmanaged code shares some responsibility in the re-allocation of memory for the
unmanaged string field. The memory allocation and deallocation must be done
using ::CoTaskMemAlloc() and ::CoTaskMemFree(). This is the required
protocol.

4.9 Note well that the managed client code need not
always pre-assign value to test_struct_02.m_strString before calling
ReferenceTestStruct02(). If a NULL pointer was set for ptest_struct_02 ->
m_pszString, then ReferenceTestStruct02() need not call
::CoTaskMemFree().

4.10 In the same way, if, on return from
ReferenceTestStruct02(), ptest_struct_02 -> m_pszString is NULL, the interop
marshaler will not free it. However, this will effective set the managed
test_struct_02.m_strString field to an empty string.

4.11 If ReferenceTestStruct02() simply
leaves ptest_struct_02 -> m_pszString alone and does not free it nor
re-assign it, then on return, the interop marshaler will use whatever buffer
that ptest_struct_02 -> m_pszString points to (as if it was freshly
allocated by ReferenceTestStruct02()) to assign to test_struct_02.m_strString.
It will then free the buffer pointed to by ptest_struct_02 ->
m_pszString.

5. Passing a Structure with a
BSTR.

5.1 For this section, we use the TestStruct03 structure
that we first defined in part 1 :

[StructLayout(LayoutKind.Sequential, Pack = 1)]
public struct TestStruct03
{
  [MarshalAs(UnmanagedType.BStr)]
  public string m_strString;
};

5.2 The corresponding C++ equivalent of such a structure
is :

#pragma pack(1)

struct TestStruct03
{
  BSTR m_bstr;
};

5.3 An example C++-based unmanaged API that takes such a
structure as an “in” and “out” parameter is listed below :

void __stdcall ReferenceTestStruct03(/*[in, out]*/ TestStruct03* ptest_struct_03)
{
  printf ("Value of ptest_struct_03 -> m_bstr before change : [%S].\r\n", ptest_struct_03 -> m_bstr);

  if (ptest_struct_03 -> m_bstr)
  {
    ::SysFreeString(ptest_struct_03 -> m_bstr);
    ptest_struct_03 -> m_bstr = NULL;
  }  

  ptest_struct_03 -> m_bstr = ::SysAllocString(L"BSTR from unmanaged code.");
}

5.4 The C# declaration for such an API is listed below
:

[DllImport("TestDLL01.dll", CallingConvention = CallingConvention.StdCall)]
public static extern void ReferenceTestStruct03([In][Out] ref TestStruct03 test_struct_03);

5.5 And a sample C# code for invoking the API
:

static void ReferenceTestStruct03()
{
  TestStruct03 test_struct_03 = new TestStruct03();

  test_struct_03.m_strString = "From managed code.";

  ReferenceTestStruct03(ref test_struct_03);

  DisplayTestStruct03(test_struct_03);
}

Just like the example we met in section 3 and 4, the
test_struct_03 structure is both instantiated and initialized before the call to
ReferenceTestStruct03(). This is a necessary action because test_struct_03 is to
be passed as a “ref” parameter which means that its value is both passed to and
set by the ReferenceTestStruct03() API.

We then used DisplayTestStruct03() (an API we have
already met in part 1) to display the value set for
test_struct_03.m_strString.

5.6 Under the covers, the following are the processes
that take place throughout the ReferenceTestStruct03() API call :

• When the ReferenceTestStruct03() API was called, the
  interop marshaler will allocate a buffer with space large enough to hold the
  structure which is listed in point 5.2.
• Note that this temporary buffer need not always be
  freshly allocated using Marshal.AllocHGlobal() or Marshal.AllocCoTaskMem(). This
  buffer may be from a cached and re-usable memory area managed by the
  CLR.
• But wherever it originated, this memory buffer serves to
  store a temporary unmanaged version of the TestStruct03
  structure.
• The interop marshaler will then pass a pointer to this
  structure to the ReferenceTestStruct03() API.
• This time, being passed as both “in” and “out”, the
  unmamaged test_struct_03 structure must contain the initialized field values of
  the managed test_struct_03 structure.
• Using the current value in test_struct_03.m_strString
  (i.e. “From managed code.”), the interop marshaler will allocate (using
  Marshal.StringToBSTR()) a BSTR with matching characters. A pointer to
  this BSTR will be assigned to the m_bstr field of the unmanaged
  structure.
• This is done before ReferenceTestStruct03() is
  invoked.
• Hence when code control reaches ReferenceTestStruct03(),
  and ptest_struct_03 -> m_bstr is to be printed, “From managed code.” will be
  displayed on the console.
• The API will then re-assign ptest_struct_03 -> m_bstr
  by first freeing the BSTR that it points to (using
  ::SysFreeString()).
• Note that ::SysFreeString() must be used because it
  matches Marshal.StringToBSTR().
• The API will then re-allocate a new BSTR (“BSTR
  from unmanaged code.”) using ::SysAllocString() and make ptest_struct_03 ->
  m_bstr point to it.
• Then when the API returns, the interop marshaler will
  assign the BSTR pointed to by ptest_struct_03 -> m_bstr to the
  counterpart m_strString field of the managed test_struct_03 structure. This is
  the effect of being an “out” parameter.
• The managed test_struct_03 structure will now be
  completely re-set by the ReferenceTestStruct03() API.
• At this time, the interop marshaler is free to re-use
  (for other purposes) the original buffer space which was used to hold the
  temporary structure.

5.7 The following expected output will be displayed on
the console screen :

Value of ptest_struct_03 -> m_bstr before change : [From managed code.].
test_struct_03.m_bstr : [BSTR from unmanaged code.].

5.8 Just like the case in section 4 where we used a
LPCSTR, when we pass by reference a structure with a string field typed as
a BSTR, the unmanaged code shares some responsibility in the re-allocation of
memory for the BSTR. The memory allocation and deallocation must be done using
::SysAllocString() and ::SysFreeString(). This is the required
protocol.

5.9 Again, just like the case in section
4, the managed client code need not always pre-assign value to
test_struct_03.m_strString before calling ReferenceTestStruct03(). If a NULL
pointer was set for ptest_struct_03 -> m_bstr, then ReferenceTestStruct03()
need not call ::SysFreeString().

5.10 In the same way, if, on return from
ReferenceTestStruct03(), ptest_struct_03 -> m_bstr is NULL, the interop
marshaler will not free it. However, this will effective set the managed
test_struct_03.m_strString field to an empty string.

5.11 If ReferenceTestStruct03() simply leaves
ptest_struct_03 -> m_bstr alone and does not free it nor re-assign it, then
on return, the interop marshaler will use whatever buffer that ptest_struct_03
-> m_bstr points to (as if it was freshly allocated by
ReferenceTestStruct03()) to assign to test_struct_03.m_strString. It will then
free the BSTR pointed to by ptest_struct_03 -> m_bstr.

6. Special Handling for a Structure Passed by
Pointer.

6.1 If the arrangement is such that a managed
structure (which contains a string field) is to be passed as a pointer to
an unmanaged API, and then get its string field assigned by the unmanaged API,
special processing will need to be done.

6.2 As usual an unmanaged representation of the
structure must be constructed somewhere in memory. And then a pointer to this
unmanaged structure is to be passed to the API.

6.3 Furthermore, because the spirit and intent of what
we are accomplishing now is to have the structure passed to the API in 2
directions “in” and “out” (in other words, as a reference “ref”
parameter), the unmanaged structure must be initialized (to the exact
values of the managed version) before being passed to the API. This point will
be emphasized in the example codes which will be presented later on.

6.4 Let’s revisit the ReferenceTestStruct01()
API :

void __stdcall ReferenceTestStruct01(/*[in, out]*/ TestStruct01* ptest_struct_01)
{
  printf ("Value of ptest_struct_01 -> m_szString before change : [%s].\r\n", ptest_struct_01 -> m_szString);
  strcpy (ptest_struct_01 -> m_szString, "From unmanaged code.");
}

6.5 The original C# declaration for
ReferenceTestStruct01() is as follows (as per point 3.4) :

[DllImport("TestDLL01.dll", CallingConvention = CallingConvention.StdCall)]
public static extern void ReferenceTestStruct01([In][Out] ref TestStruct01 test_struct_01);

6.6 Now, because the unmanaged API really does take a
pointer to an unmanaged TestStruct01 structure, we can import the same API (i.e.
ReferenceTestStruct01()) using a different declaration :

[DllImport("TestDLL01.dll", CallingConvention = CallingConvention.StdCall, EntryPoint = "ReferenceTestStruct01")]
public static extern void ReferenceTestStruct01_ByPointer(IntPtr ptest_struct_01);

6.7 This time, instead of passing in a managed
TestStruct01 structure to the API, we need to pass an IntPtr which points to an
unmanaged representation of a TestStruct01 structure. The following is a sample
code :

static void ReferenceTestStruct01_ByPointer()
{
  // Create TestStruct01 and assign value to its field as usual.
  TestStruct01 test_struct_01 = new TestStruct01();

  test_struct_01.m_strString = "From managed code.";

  // Determine the size of the TestStruct01 for marshaling.
  int iSizeOfTestStruct01 = Marshal.SizeOf(typeof(TestStruct01));
  // Allocate in unmanaged memory a block of memory the size
  // of an unmanaged TestStruct01 structure.
  IntPtr ptest_struct_01 = Marshal.AllocHGlobal(iSizeOfTestStruct01);
  // Transfer the contents of the managed TestStruct01
  // (i.e. test_struct_01) to the unmanaged memory
  // which now serves as the unmanaged representation
  // of test_struct_01.
  Marshal.StructureToPtr(test_struct_01, ptest_struct_01, false);
  // Call the API using a pointer to the unmanaged test_struct_01.
  ReferenceTestStruct01_ByPointer(ptest_struct_01);
  // We now transfer the contents of the unmanaged TestStruct01
  // (pointed to by ptest_struct_01) to the managed memory
  // of test_struct_01.
  //
  // Remember that the spirit and intent of the
  // ReferenceTestStruct01_ByPointer() API is to
  // pass a TestStruct01 structure 2 ways : "in" and "out".
  // Hence whatever changes done to the structure
  // inside the API must be reflected on return.
  test_struct_01 = (TestStruct01)Marshal.PtrToStructure(ptest_struct_01, typeof(TestStruct01));
  // We now display the contents of the managed test_struct_01.
  DisplayTestStruct01(test_struct_01);
  // We must remember to destroy the unmanaged test_struct_01 structure.
  // Doing this will free any fields which are references
  // to memory.
  Marshal.DestroyStructure(ptest_struct_01, typeof(TestStruct01));
  // Finally, the block of memory allocated for the
  // unmanaged test_struct_01 must itself be freed.
  Marshal.FreeHGlobal(ptest_struct_01);
  ptest_struct_01 = IntPtr.Zero;
}

This code will produce the following output on the
console :

Value of ptest_struct_01 -> m_szString before change : [From managed code.].
test_struct_01.m_szString : [From unmanaged code.].

6.8 Basically, the marshaling must be done completely
manually. The following are pertinent points concerning the code above
:

• A managed TestStruct01 structure is to be allocated and
  its string field assigned.
• An unmanaged representation of this structure will need
  to be allocated and initialized properly with field values from the managed
  version.
• We first need to calculate the size of the
  unmanaged representation. This is done by using Marshal.SizeOf() which uses the
  StructLayoutAttribute of the structure and various MarshalAsAttributes assigned
  to the fields to perform the calculation.
• With this size calculated, we can proceed to create the
  unmanaged representation by allocating in memory such a structure. This is done
  by using Marshal.AllocHGlobal(). Note that Marshal.AllocCoTaskMem() may be used
  as well. An IntPtr will be returned. This structure will have a memory format as
  depicted in the structure of point 3.2.
• Next, we need to ensure that the unmanaged TestStruct01
  structure is a replica of its managed counterpart. That is, all field values of
  the managed structure must be copied to the same values in the corresponding
  unmanaged fields. After all, remember that the structure is to be passed as
  an “in” parameter.
• We do this by using the Marshal.StructureToPtr()
  method.
• After this is done, the unmanaged representation of the
  TestStruct01 structure is complete. The IntPtr may be passed to the
  ReferenceTestStruct01_ByPointer() API.
• The ReferenceTestStruct01_ByPointer() API will use the
  passed in value of ptest_struct_01 -> m_szString to display the
  contained string. After that it will assign character values into the same
  string buffer.
• Now, remember that the spirit and intent of calling
  ReferenceTestStruct01_ByPointer() is to have this API display and then set the
  field values for the structure. Hence when the API returns, we need to transfer
  the contents of the unmanaged structure (which may have changed) to that of the
  managed version. This is done by using
  Marshal.PtrToStructure().
• When Marshal.PtrToStructure() is done, the managed
  TestStruct01 structure will contain the same string value as that of the
  unmanaged representation.
• Next comes the important task of memory deallocation :
  that of the fields of the unmanaged structure (which are not inline and embedded
  as part of the structure itself), and that of the unmanaged structure
  itself.
• Fields of a structure which are not embedded as
  part of the structure are usually references to memory elsewhere. These must be
  destroyed with the help of the Marshal.DestroyStructure() method. This method
  clears the non-embedded fields with help from the MarshalAsAttributes assigned
  to the fields.
• Now, with a field like TestStruct01.m_szString which is
  an inline embedded array of 21 ANSI characters, nothing needs to be done. The
  memory occuppied by this field is automatically recovered when the structure
  itself is recovered.
• If we were dealing with TestStruct02, then with a field
  like TestStruct02.m_pszString (LPCSTR), the memory pointed to by this field,
  which will be allocated when Marshal.StructureToPtr() is called,
  Marshal.DestroyStructure() will recover the memory occuppied by the buffer
  pointed to by TestStruct02.m_pszString.
• If we were dealing with TestStruct03, then with a field
  like TestStruct03.m_bstr (BSTR), the BSTR pointed to by this field, which will
  be allocated when Marshal.StructureToPtr() is called, Marshal.DestroyStructure()
  will free the BSTR pointed to by TestStruct03.m_bstr.

6.9 To help to test cases where we pass TestStruct02 and
TestStruct03 by pointers, I have prepared the following code constructs for
testing purposes :

static void InitializeStruct(ref TestStruct01 test_struct_01, string strInitial)
{
  test_struct_01.m_strString = strInitial;
}

static void InitializeStruct(ref TestStruct02 test_struct_02, string strInitial)
{
  test_struct_02.m_strString = strInitial;
}

static void InitializeStruct(ref TestStruct03 test_struct_03, string strInitial)
{
  test_struct_03.m_strString = strInitial;
}

delegate void Delegate_InitializeStruct<T>(ref T t, string strInitial);

delegate void Delegate_DisplayTestStruct0x<T>(T t);

[DllImport("TestDLL01.dll", CallingConvention = CallingConvention.StdCall, EntryPoint = "ReferenceTestStruct01")]
public static extern void ReferenceTestStruct01_ByPointer(IntPtr ptest_struct_01);

[DllImport("TestDLL01.dll", CallingConvention = CallingConvention.StdCall, EntryPoint = "ReferenceTestStruct02")]
public static extern void ReferenceTestStruct02_ByPointer(IntPtr ptest_struct_02);

[DllImport("TestDLL01.dll", CallingConvention = CallingConvention.StdCall, EntryPoint = "ReferenceTestStruct03")]
public static extern void ReferenceTestStruct03_ByPointer(IntPtr ptest_struct_03);

delegate void Delegate_ReferenceTestStruct0x_ByPointer(IntPtr ptest_struct_0x);

static void ReferenceTestStruct0x_ByPointer<T>
(
  Delegate_InitializeStruct<T> pInitializer,
  Delegate_ReferenceTestStruct0x_ByPointer pReferenceFunction,
  Delegate_DisplayTestStruct0x<T> pDisplayFunction
) where T : new()
{
  // Create an instance of T and assign value to its field as usual.
  T test_struct_0x = new T();

  pInitializer(ref test_struct_0x, "From managed code.");

  // Determine the size of T for marshaling.
  int iSizeOfTestStruct0x = Marshal.SizeOf(typeof(T));
  // Allocate in unmanaged memory a block of memory the size
  // of an unmanaged T structure.
  IntPtr ptest_struct_0x = Marshal.AllocHGlobal(iSizeOfTestStruct0x);
  // Transfer the contents of the managed T
  // (i.e. test_struct_0x) to the unmanaged memory
  // which now serves as the unmanaged representation
  // of T.
  Marshal.StructureToPtr(test_struct_0x, ptest_struct_0x, false);
  // Call the API using a pointer to the unmanaged test_struct_0x.
  pReferenceFunction(ptest_struct_0x);
  // We now transfer the contents of the unmanaged T
  // (pointed to by ptest_struct_0x) to the managed memory
  // of test_struct_0x.
  //
  // Remember that the spirit and intent of the
  // ReferenceTestStruct0x_ByPointer() API is to
  // pass a T structure 2 ways : "in" and "out".
  // Hence whatever changes done to the structure
  // inside the API must be reflected on return.
  test_struct_0x = (T)Marshal.PtrToStructure(ptest_struct_0x, typeof(T));
  // We now display the contents of the managed test_struct_01.
  pDisplayFunction(test_struct_0x);
  // We must remember to destroy the unmanaged test_struct_0x structure.
  // Doing this will free any fields which are references
  // to memory.
  Marshal.DestroyStructure(ptest_struct_0x, typeof(T));
  // Finally, the block of memory allocated for the
  // unmanaged test_struct_0x must itself be freed.
  Marshal.FreeHGlobal(ptest_struct_0x);
  ptest_struct_0x = IntPtr.Zero;
}

The above code provides the following :

• 3 overloaded initializer functions (InitializeStruct()),
  one each for the structs TestStruct01, TestStruct02 and TestStruct03. We have
  met these 3 functions previously in part 1.
• Delegate Delegate_InitializeStruct<T> which is
  meant to generically point to one of the initializer
  functions.
• Delegate Delegate_DisplayTestStruct0x<T> which is
  meant to point to one of the versions of the DisplayTestStructXX()
  APIs.
• C# declarations for the
  ReferenceTestStruct01_ByPointer(), ReferenceTestStruct02_ByPointer() and
  ReferenceTestStruct03_ByPointer() APIs.
• Delegate Delegate_ReferenceTestStruct0x_ByPointer
  which is meant to point to one of the ReferenceTestStructXX_ByPointer() APIs
  (i.e. ReferenceTestStruct01_ByPointer(), ReferenceTestStruct02_ByPointer() or
  ReferenceTestStruct02_ByPointer()).
• ReferenceTestStruct0x_ByPointer<T>() which
  generically performs the equivalent of the ReferenceTestStruct01_ByPointer()
  function (listed in point 6.7) but for all the test
  structs.

6.10 For more details on passing a pointer to a
structure from managed to unmanaged code, please refer to :

Passing a Pointer to a Structure from C# to C++ Part
1.

Passing a Pointer to a Structure from C# to C++ Part
2.

Passing a Pointer to a Structure from C# to C++ Part
3.

7. In Conclusion.

7.1 Here in part 3, we have examined how to pass a
structure (which contains a string field) from managed to unmanaged code as an
“in” and “out” (ref) parameter.

7.2 We have essentially combined the code actions done
in part 1 and part 2. The dual directionality of marshaling has been duely
emphasized.

7.3 We have learnt the 3 possible ways to express a
string in unmanage code : as an inline character array, as a pointer to a
character array, as a BSTR. We have also seen how each of these 3 types of
strings may be passed to and returned from unmanaged code.

7.4 We also touched a little on the
special handling required where the structures are passed by
pointer.

7.5 Throughout this series of blogs, I hope to
have demonstrated to the reader the basic principles behind marshaling :
that managed data structures must first be transformed into unmanaged
equivalents before they can be passed to unmanaged code. And that data to be
received from unmanaged code must be transformed to its managed equivalent
before it can be used in managed code.

7.6 It may take a while for the newbie to sink this in.
But it is certainly consistent and repeatable.