Ecng.Interop 1.0.300

Ecng.Interop

A comprehensive .NET library for Platform/Invoke (P/Invoke) operations and native code interoperability. This library provides safe, easy-to-use wrappers for working with unmanaged memory, native libraries, and low-level data structures.

Table of Contents

• Overview
• Key Features
• Installation
• Core Components
  • Dynamic Library Loading
  • Memory Management
  • Pointer Utilities
  • String Marshaling
  • Type Marshaling
  • Fixed-Size Strings
  • Time Structures
  • Hardware Information
• Usage Examples
• Best Practices
• Platform Support

Overview

Ecng.Interop simplifies the complexity of interoperating with native code by providing:

• Type-safe wrappers for unmanaged memory operations
• Automatic memory management with safe handles
• Helper methods for common marshaling scenarios
• Optimized fixed-size string types for performance-critical interop scenarios
• Utilities for loading and calling native libraries dynamically

Key Features

• Safe Memory Management: RAII-style memory management with HGlobalSafeHandle and SafePointer
• Dynamic Library Loading: Load and call functions from native DLLs at runtime
• String Marshaling: Support for ANSI, Unicode, UTF-8, and BSTR string formats
• Fixed-Size Strings: Pre-defined fixed-size string types (ASCII and UTF-8) for efficient marshaling
• Pointer Reading/Writing: Sequential pointer reading with PtrReader and type-safe pointer operations
• Blittable Types: Specialized types like BlittableDecimal for direct memory layout compatibility
• Time Structures: Compact time representations optimized for interop scenarios
• Cross-Platform: Works on Windows, Linux, and macOS

Installation

Add a reference to the Ecng.Interop project or include the compiled DLL in your project.

<ProjectReference Include="path\to\Ecng.Interop\Interop.csproj" />

Core Components

Dynamic Library Loading

Using DllLibrary Base Class

The DllLibrary class provides a managed way to load native libraries and access their functions.

using Ecng.Interop;

// Define your library wrapper
public class MyNativeLibrary : DllLibrary
{
    public MyNativeLibrary(string dllPath) : base(dllPath)
    {
        // Retrieve function pointers as delegates
        Add = GetHandler<AddDelegate>("Add");
        Multiply = TryGetHandler<MultiplyDelegate>("Multiply"); // Returns null if not found
    }

    // Define delegate types matching native function signatures
    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
    private delegate int AddDelegate(int a, int b);

    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
    private delegate int MultiplyDelegate(int a, int b);

    // Public wrapper methods
    public Func<int, int, int> Add { get; }
    public Func<int, int, int> Multiply { get; }
}

// Usage
using (var lib = new MyNativeLibrary(@"C:\path\to\native.dll"))
{
    int result = lib.Add(10, 20); // Returns 30
    Console.WriteLine($"Result: {result}");

    // Check DLL version
    Console.WriteLine($"DLL Version: {lib.DllVersion}");
}

Manual Library Loading

using Ecng.Interop;

// Load library manually
IntPtr libraryHandle = Marshaler.LoadLibrary(@"C:\path\to\library.dll");

try
{
    // Get function pointer
    IntPtr funcPtr = libraryHandle.GetProcAddress("MyFunction");

    // Convert to delegate
    var myFunc = funcPtr.GetDelegateForFunctionPointer<MyFunctionDelegate>();

    // Call the function
    int result = myFunc(42);
}
finally
{
    // Free the library
    libraryHandle.FreeLibrary();
}

Memory Management

HGlobalSafeHandle

HGlobalSafeHandle provides automatic cleanup of unmanaged memory allocated with Marshal.AllocHGlobal.

using Ecng.Interop;

// Allocate 1024 bytes of unmanaged memory
using (var handle = 1024.ToHGlobal())
{
    IntPtr ptr = handle.DangerousGetHandle();

    // Use the memory
    Marshal.WriteInt32(ptr, 42);
    int value = Marshal.ReadInt32(ptr);

    Console.WriteLine($"Value: {value}"); // Output: Value: 42
}
// Memory is automatically freed when disposed

// Allocate and write a string
using (var handle = Encoding.UTF8.ToHGlobal("Hello, World!"))
{
    IntPtr ptr = handle.DangerousGetHandle();
    string decoded = Encoding.UTF8.ToString(ptr);
    Console.WriteLine(decoded); // Output: Hello, World!
}

SafePointer

SafePointer wraps an unmanaged pointer with bounds checking and automatic shifting.

using Ecng.Interop;

// Allocate memory
IntPtr memory = Marshal.AllocHGlobal(100);
try
{
    // Create a SafePointer with size boundary
    var safePtr = new SafePointer(memory, 100);

    // Read a value and auto-shift the pointer
    int value1 = safePtr.Read<int>(autoShift: true);
    int value2 = safePtr.Read<int>(autoShift: true);

    // Read a structure
    MyStruct myStruct = safePtr.ToStruct<MyStruct>(autoShift: true);

    // Copy to byte array
    byte[] buffer = new byte[20];
    safePtr.CopyTo(buffer, autoShift: true);

    // Manual shifting
    safePtr.Shift<long>(); // Shift by sizeof(long)
    safePtr.Shift(16);     // Shift by 16 bytes
}
finally
{
    Marshal.FreeHGlobal(memory);
}

GCHandle<T>

Generic wrapper around GCHandle for pinning managed objects.

using Ecng.Interop;

byte[] data = new byte[] { 1, 2, 3, 4, 5 };

// Pin the array in memory
using (var gcHandle = new GCHandle<byte[]>(data, GCHandleType.Pinned))
{
    // Create a safe pointer to the pinned data
    SafePointer pointer = gcHandle.CreatePointer();

    // Pass pointer to native code
    NativeFunction(pointer.Pointer);
}
// Array is automatically unpinned when disposed

Pointer Utilities

PtrReader

Sequential reading from unmanaged memory pointers.

using Ecng.Interop;

IntPtr dataPtr = GetSomeNativeData();

var reader = new PtrReader(dataPtr);

// Read various types sequentially
byte b = reader.GetByte();
short s = reader.GetShort();
int i = reader.GetInt();
long l = reader.GetLong();
IntPtr p = reader.GetIntPtr();

// Read null-terminated strings
string str1 = reader.GetString();

// Read fixed-length strings
string str2 = reader.GetString(20); // Read 20 characters

Direct Pointer Operations

using Ecng.Interop;

IntPtr ptr = Marshal.AllocHGlobal(100);
try
{
    // Write values
    ptr.Write<int>(42);
    (ptr + 4).Write<short>(100);
    (ptr + 6).Write<byte>(255);

    // Read values
    int intValue = ptr.Read<int>();
    short shortValue = (ptr + 4).Read<short>();
    byte byteValue = (ptr + 6).Read<byte>();

    // Copy to managed array
    byte[] buffer = new byte[10];
    ptr.CopyTo(buffer);
    ptr.CopyTo(buffer, offset: 0, length: 10);

    // Create spans (modern .NET)
    Span<byte> span = ptr.ToSpan(100);
    ReadOnlySpan<byte> roSpan = ptr.ToReadOnlySpan(100);
}
finally
{
    ptr.FreeHGlobal();
}

String Marshaling

The library provides comprehensive string marshaling for different encodings.

using Ecng.Interop;

// ANSI strings
string text = "Hello, World!";
IntPtr ansiPtr = text.FromAnsi();
try
{
    string decoded = ansiPtr.ToAnsi();
    Console.WriteLine(decoded);
}
finally
{
    Marshal.FreeHGlobal(ansiPtr);
}

// Unicode strings
IntPtr unicodePtr = text.FromUnicode();
try
{
    string decoded = unicodePtr.ToUnicode();
    Console.WriteLine(decoded);
}
finally
{
    Marshal.FreeHGlobal(unicodePtr);
}

// Platform-dependent (Auto)
IntPtr autoPtr = text.FromAuto();
try
{
    string decoded = autoPtr.ToAuto();
    Console.WriteLine(decoded);
}
finally
{
    Marshal.FreeHGlobal(autoPtr);
}

// BSTR (COM interop)
IntPtr bstrPtr = text.FromBSTR();
try
{
    string decoded = bstrPtr.ToBSTR();
    Console.WriteLine(decoded);
}
finally
{
    Marshal.FreeBSTR(bstrPtr);
}

// UTF-8 with unsafe pointers
unsafe
{
    byte* utf8Buffer = stackalloc byte[100];
    text.ToUtf8(utf8Buffer, 100);

    string decoded = 100.ToUtf8(utf8Buffer);
    Console.WriteLine(decoded);
}

// ASCII with unsafe pointers
unsafe
{
    byte* asciiBuffer = stackalloc byte[100];
    text.ToAscii(asciiBuffer, 100);

    string decoded = 100.ToAscii(asciiBuffer);
    Console.WriteLine(decoded);
}

Type Marshaling

Structure Marshaling

using Ecng.Interop;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
public struct MyNativeStruct
{
    public int Id;
    public double Value;
    public byte Flag;
}

// Marshal from structure to pointer
MyNativeStruct data = new MyNativeStruct
{
    Id = 1,
    Value = 3.14,
    Flag = 1
};

IntPtr ptr = data.StructToPtr();
try
{
    // Pass ptr to native code
    NativeFunction(ptr);

    // Marshal back from pointer to structure
    MyNativeStruct result = ptr.ToStruct<MyNativeStruct>();
    Console.WriteLine($"ID: {result.Id}, Value: {result.Value}");
}
finally
{
    Marshal.FreeHGlobal(ptr);
}

// Get pointer and size
(IntPtr ptr, int size) = data.StructToPtrEx();
try
{
    Console.WriteLine($"Structure size: {size} bytes");
    // Use ptr and size
}
finally
{
    Marshal.FreeHGlobal(ptr);
}

BlittableDecimal

BlittableDecimal is a struct that matches the memory layout of decimal for direct marshaling.

using Ecng.Interop;

[StructLayout(LayoutKind.Sequential)]
public struct PriceData
{
    public int Quantity;
    public BlittableDecimal Price; // Can be marshaled directly
}

PriceData data = new PriceData
{
    Quantity = 100,
    Price = (BlittableDecimal)123.45m
};

// Marshal to unmanaged memory
IntPtr ptr = data.StructToPtr();
try
{
    // Pass to native code
    NativeFunction(ptr);

    // Read back
    PriceData result = ptr.ToStruct<PriceData>();
    decimal price = result.Price; // Implicit conversion
    Console.WriteLine($"Quantity: {result.Quantity}, Price: {price}");
}
finally
{
    Marshal.FreeHGlobal(ptr);
}

Fixed-Size Strings

Fixed-size string types provide efficient marshaling for scenarios where string length is known at compile time.

UTF-8 Fixed Strings

using Ecng.Interop;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
public struct NetworkPacket
{
    public int PacketId;
    public Utf8String16 Symbol;    // 16 bytes
    public Utf8String32 Message;   // 32 bytes
    public Utf8String8 Source;     // 8 bytes
}

// Usage
NetworkPacket packet = new NetworkPacket
{
    PacketId = 123,
    Symbol = (Utf8String16)"AAPL",
    Message = (Utf8String32)"Order executed",
    Source = (Utf8String8)"NYSE"
};

// Convert to strings
string symbol = packet.Symbol;   // Implicit conversion
string message = packet.Message;
string source = packet.Source.ToString();

Console.WriteLine($"Symbol: {symbol}, Message: {message}");

// Available UTF-8 sizes: 1-33, 48, 64, 65, 128, 129, 256

ASCII Fixed Strings

using Ecng.Interop;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
public struct LegacyRecord
{
    public int RecordId;
    public AsciiString32 Name;     // 32 bytes ASCII
    public AsciiString64 Address;  // 64 bytes ASCII
    public AsciiString16 City;     // 16 bytes ASCII
}

// Usage
LegacyRecord record = new LegacyRecord
{
    RecordId = 1,
    Name = (AsciiString32)"John Doe",
    Address = (AsciiString64)"123 Main Street",
    City = (AsciiString16)"New York"
};

// Convert to strings
string name = record.Name;      // Implicit conversion
string address = record.Address;
string city = record.City.ToString();

Console.WriteLine($"{name} from {city}");

// Available ASCII sizes: 1-32, 64, 128

Time Structures

Compact time representations optimized for native interop.

Time4Sec (4-byte time with second resolution)

using Ecng.Interop;

[StructLayout(LayoutKind.Sequential)]
public struct LogEntry
{
    public Time4Sec Timestamp;  // 4 bytes instead of 8
    public int EventId;
}

// Usage
LogEntry entry = new LogEntry
{
    Timestamp = (Time4Sec)DateTime.UtcNow,
    EventId = 123
};

// Convert to DateTime
DateTime dt = entry.Timestamp;  // Implicit conversion
DateTimeOffset dto = entry.Timestamp;

Console.WriteLine($"Event at: {dt}");
Console.WriteLine($"Formatted: {entry.Timestamp.ToString("yyyy-MM-dd HH:mm:ss", null)}");

Time8Mls (8-byte time with millisecond resolution)

using Ecng.Interop;

[StructLayout(LayoutKind.Sequential)]
public struct TradeData
{
    public Time8Mls ExecutionTime;
    public double Price;
    public int Volume;
}

// Usage
TradeData trade = new TradeData
{
    ExecutionTime = (Time8Mls)DateTime.UtcNow,
    Price = 150.25,
    Volume = 1000
};

DateTime executionTime = trade.ExecutionTime;
Console.WriteLine($"Trade executed at: {executionTime:yyyy-MM-dd HH:mm:ss.fff}");

Time8Mcs (8-byte time with microsecond resolution)

using Ecng.Interop;

[StructLayout(LayoutKind.Sequential)]
public struct HighFrequencyTick
{
    public Time8Mcs Timestamp;
    public double BidPrice;
    public double AskPrice;
}

// Usage
HighFrequencyTick tick = new HighFrequencyTick
{
    Timestamp = (Time8Mcs)DateTime.UtcNow,
    BidPrice = 100.50,
    AskPrice = 100.51
};

DateTime tickTime = tick.Timestamp;
Console.WriteLine($"Tick at: {tickTime:HH:mm:ss.ffffff}");

TimeNano (nanosecond resolution)

using Ecng.Interop;

[StructLayout(LayoutKind.Sequential)]
public struct PrecisionEvent
{
    public TimeNano Timestamp;
    public int EventType;
}

// Usage
PrecisionEvent evt = new PrecisionEvent
{
    Timestamp = (TimeNano)DateTime.UtcNow,
    EventType = 5
};

DateTime eventTime = evt.Timestamp;
Console.WriteLine($"Precise event time: {eventTime:O}");

Hardware Information

Generate hardware-based identifiers for licensing or device identification.

using Ecng.Interop;

// Synchronous
string hardwareId = HardwareInfo.GetId();
Console.WriteLine($"Hardware ID: {hardwareId}");

// Asynchronous
string hardwareIdAsync = await HardwareInfo.GetIdAsync();
Console.WriteLine($"Hardware ID: {hardwareIdAsync}");

// With cancellation
using var cts = new CancellationTokenSource(TimeSpan.FromSeconds(5));
try
{
    string id = await HardwareInfo.GetIdAsync(cts.Token);
    Console.WriteLine($"Hardware ID: {id}");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Hardware ID retrieval timed out");
}

The hardware ID is generated based on:

• Windows: CPU ID + Motherboard Serial Number (or MAC Address)
• Linux: Root partition UUID
• macOS: Platform UUID

Usage Examples

Complete Example: Calling Native Library

using Ecng.Interop;
using System.Runtime.InteropServices;

// Define the native structure
[StructLayout(LayoutKind.Sequential)]
public struct Point3D
{
    public double X;
    public double Y;
    public double Z;
}

// Create library wrapper
public class MathLibrary : DllLibrary
{
    public MathLibrary() : base("mathlib.dll")
    {
        CalculateDistance = GetHandler<CalculateDistanceDelegate>("CalculateDistance");
    }

    [UnmanagedFunctionPointer(CallingConvention.Cdecl)]
    private delegate double CalculateDistanceDelegate(IntPtr point1, IntPtr point2);

    private CalculateDistanceDelegate CalculateDistance;

    public double GetDistance(Point3D p1, Point3D p2)
    {
        IntPtr ptr1 = p1.StructToPtr();
        IntPtr ptr2 = p2.StructToPtr();
        try
        {
            return CalculateDistance(ptr1, ptr2);
        }
        finally
        {
            ptr1.FreeHGlobal();
            ptr2.FreeHGlobal();
        }
    }
}

// Usage
using (var lib = new MathLibrary())
{
    Point3D p1 = new Point3D { X = 0, Y = 0, Z = 0 };
    Point3D p2 = new Point3D { X = 3, Y = 4, Z = 0 };

    double distance = lib.GetDistance(p1, p2);
    Console.WriteLine($"Distance: {distance}"); // Output: Distance: 5
}

Complete Example: Working with Native Arrays

using Ecng.Interop;
using System.Runtime.InteropServices;

// Allocate array in unmanaged memory
int[] numbers = new int[] { 1, 2, 3, 4, 5 };
int sizeInBytes = sizeof(int) * numbers.Length;

using (var handle = sizeInBytes.ToHGlobal())
{
    IntPtr ptr = handle.DangerousGetHandle();

    // Copy managed array to unmanaged memory
    Marshal.Copy(numbers, 0, ptr, numbers.Length);

    // Create SafePointer for safe iteration
    var safePtr = new SafePointer(ptr, sizeInBytes);

    // Read values
    for (int i = 0; i < numbers.Length; i++)
    {
        int value = safePtr.Read<int>(autoShift: true);
        Console.WriteLine($"Value {i}: {value}");
    }
}

Complete Example: Reading Native Structure with Strings

using Ecng.Interop;
using System.Runtime.InteropServices;

[StructLayout(LayoutKind.Sequential)]
public unsafe struct UserData
{
    public int UserId;
    public AsciiString32 UserName;
    public AsciiString64 Email;
    public Time8Mls RegistrationDate;
}

// Read from native memory
IntPtr nativeDataPtr = GetUserDataFromNativeCode();

UserData user = nativeDataPtr.ToStruct<UserData>();

Console.WriteLine($"User ID: {user.UserId}");
Console.WriteLine($"Name: {(string)user.UserName}");
Console.WriteLine($"Email: {(string)user.Email}");
Console.WriteLine($"Registered: {(DateTime)user.RegistrationDate}");

Best Practices

Memory Management

1. Always dispose resources: Use using statements for DllLibrary, HGlobalSafeHandle, and GCHandle<T>
2. Prefer safe wrappers: Use SafePointer over raw IntPtr when possible for bounds checking
3. Match allocation/deallocation: Use FreeHGlobal() for memory allocated with AllocHGlobal()

// Good
using (var handle = 1024.ToHGlobal())
{
    // Use memory
} // Automatically freed

// Avoid
IntPtr ptr = Marshal.AllocHGlobal(1024);
// ... might forget to free

String Marshaling

1. Choose the right encoding: Use UTF-8 for modern APIs, ASCII for legacy systems
2. Use fixed-size strings for structures: More efficient than string marshaling
3. Be aware of null terminators: ANSI/Unicode strings are null-terminated

// Good for structures
[StructLayout(LayoutKind.Sequential)]
public struct Config
{
    public Utf8String32 Name;  // Fixed size, no allocation
}

// Avoid for structures (requires marshaling)
[StructLayout(LayoutKind.Sequential)]
public struct ConfigBad
{
    [MarshalAs(UnmanagedType.LPStr)]
    public string Name;  // Requires allocation and marshaling
}

Platform Considerations

1. Check platform: Use OperatingSystem checks when necessary
2. Handle pointer size: Use IntPtr.Size for platform-dependent sizes
3. Test on target platforms: Marshaling behavior can differ between platforms

if (OperatingSystem.IsWindows())
{
    // Windows-specific code
}
else if (OperatingSystem.IsLinux())
{
    // Linux-specific code
}

Performance

1. Pin arrays for bulk operations: Use GCHandle<T> to avoid copying
2. Use stackalloc for small buffers: Avoid heap allocation when possible
3. Batch operations: Minimize transitions between managed and unmanaged code

// Good: Single pinning for bulk operation
byte[] data = new byte[1000];
using (var handle = new GCHandle<byte[]>(data, GCHandleType.Pinned))
{
    SafePointer ptr = handle.CreatePointer();
    NativeBulkOperation(ptr.Pointer, data.Length);
}

// Avoid: Multiple small transitions
for (int i = 0; i < 1000; i++)
{
    NativeSingleOperation(data[i]); // Many transitions
}

Platform Support

• .NET Standard 2.0: Compatible with .NET Framework 4.6.1+ and .NET Core 2.0+
• .NET 6.0: Full support
• .NET 10.0: Full support with latest features
• Operating Systems: Windows, Linux, macOS

Dependencies

• Ecng.Common: Core utilities
• WmiLight: Windows Management Instrumentation for hardware info
• Microsoft.Windows.CsWin32: Windows API source generator

Thread Safety

• Most classes are not thread-safe by default
• DllLibrary instances should not be shared between threads without synchronization
• Memory allocation/deallocation is thread-safe (handled by the runtime)

License

This library is part of the StockSharp/Ecng project.