等位範例
更新：2007 年 11 月
這個範例示範如何將只包含實值型別的結構、含有實值型別及字串做為參數的結構傳遞至預期等位的 Unmanaged 函式。等位表示兩個或以上的變數可以共用的記憶體位置。
等位範例使用下列 Unmanaged 函式，顯示其原始函式宣告：
從 PinvokeLib.dll 匯出 TestUnion
void TestUnion(MYUNION u, int type);
PinvokeLib.dll 是自訂的 Unmanaged 程式庫，包含先前列在函式和兩個等位 (MYUNION 和 MYUNION2) 的實作。這兩個等位包含下列元素：
union MYUNION
{
int number;
double d;
}
union MYUNION2
{
int i;
char str[128];
};
在 Managed 程式碼中，等位是定義為結構。MyUnion 結構包含兩個實值型別做為它的成員：整數和雙精度浮點數 (Double)。StructLayoutAttribute 屬性可設定來控制每一個資料成員的精確位置。FieldOffsetAttribute 屬性提供等位的 Unmanaged 表示內欄位的實際位置。請注意，這兩個成員都有相同的位移值，所以成員可以定義相同的記憶體片段。
MyUnion2_1 和 MyUnion2_2 各包含了實值型別 (整數) 和字串。在 Managed 程式碼中，實值型別和參考型別不被允許重疊。這個範例使用方法多載化 (Overloading)，讓呼叫端在呼叫相同的 Unmanaged 函式時使用這兩個型別。MyUnion2_1 的配置是明確的，而且有精確的位移值。相較之下，MyUnion2_2 有循序的配置，因為使用參考型別不允許有明確配置。MarshalAsAttribute 屬性會將 UnmanagedType 列舉型別設定為 ByValTStr，用來識別出現在等位 Unmanaged 表示之中的內嵌、固定長度的字元陣列。
LibWrap 類別包含 TestUnion 和 TestUnion2 方法的原型。TestUnion2 會被多載來宣告 MyUnion2_1 或 MyUnion2_2 做為參數。
下列程式碼範例的原始程式碼是由 .NET Framework 平台叫用技術範例所提供。
宣告原型
' Declares managed structures instead of unions.
< StructLayout( LayoutKind.Explicit )> _
Public Structure MyUnion
< FieldOffset( 0 )> Public i As Integer
< FieldOffset( 0 )> Public d As Double
End Structure 'MyUnion
< StructLayout( LayoutKind.Explicit, Size := 128 )> _
Public Structure MyUnion2_1
< FieldOffset( 0 )> Public i As Integer
End Structure 'MyUnion2_1
< StructLayout( LayoutKind.Sequential )> _
Public Structure MyUnion2_2
< MarshalAs( UnmanagedType.ByValTStr, SizeConst := 128 )> _
Public str As String
End Structure 'MyUnion2_2
Public Class LibWrap
' Declares managed prototypes for unmanaged function.
Declare Sub TestUnion Lib "..\LIB\PinvokeLib.dll" ( _
ByVal u As MyUnion, ByVal type As Integer )
Overloads Declare Sub TestUnion2 Lib "..\LIB\PinvokeLib.dll" ( _
ByVal u As MyUnion2_1, ByVal type As Integer )
Overloads Declare Sub TestUnion2 Lib "..\LIB\PinvokeLib.dll" ( _
ByVal u As MyUnion2_2, ByVal type As Integer )
End Class 'LibWrap
// Declares managed structures instead of unions.
[ StructLayout( LayoutKind.Explicit )]
public struct MyUnion
{
[ FieldOffset( 0 )]
public int i;
[ FieldOffset( 0 )]
public double d;
}
[ StructLayout( LayoutKind.Explicit, Size=128 )]
public struct MyUnion2_1
{
[ FieldOffset( 0 )]
public int i;
}
[ StructLayout( LayoutKind.Sequential )]
public struct MyUnion2_2
{
[ MarshalAs( UnmanagedType.ByValTStr, SizeConst=128 )]
public String str;
}
public class LibWrap
{
// Declares managed prototypes for unmanaged function.
[ DllImport( "..\\LIB\\PinvokeLib.dll" )]
public static extern void TestUnion( MyUnion u, int type );
[ DllImport( "..\\LIB\\PinvokeLib.dll" )]
public static extern void TestUnion2( MyUnion2_1 u, int type );
[ DllImport( "..\\LIB\\PinvokeLib.dll" )]
public static extern void TestUnion2( MyUnion2_2 u, int type );
}
呼叫函式
Public Class App
Public Shared Sub Main()
Dim mu As New MyUnion()
mu.i = 99
LibWrap.TestUnion( mu, 1 )
mu.d = 99.99
LibWrap.TestUnion( mu, 2 )
Dim mu2_1 As New MyUnion2_1()
mu2_1.i = 99
LibWrap.TestUnion2( mu2_1, 1 )
Dim mu2_2 As New MyUnion2_2()
mu2_2.str = "*** string ***"
LibWrap.TestUnion2( mu2_2, 2 )
End Sub 'Main
End Class 'App
public class App
{
public static void Main()
{
MyUnion mu = new MyUnion();
mu.i = 99;
LibWrap.TestUnion( mu, 1 );
mu.d = 99.99;
LibWrap.TestUnion( mu, 2 );
MyUnion2_1 mu2_1 = new MyUnion2_1();
mu2_1.i = 99;
LibWrap.TestUnion2( mu2_1, 1 );
MyUnion2_2 mu2_2 = new MyUnion2_2();
mu2_2.str = "*** string ***";
LibWrap.TestUnion2( mu2_2, 2 );
}
}