Skip to content
This repository has been archived by the owner on Jul 26, 2023. It is now read-only.

Latest commit

 

History

History
144 lines (112 loc) · 10.3 KB

README.md

File metadata and controls

144 lines (112 loc) · 10.3 KB
Raw

P/Invoke

⚠ NOTICE: Check out CsWin32: A new, preferred approach for Win32 p/invokes now exists for C# developers.

This repo is no longer maintained.

A collection of libraries intended to contain all P/Invoke method signatures for popular operating systems. Think of it as https://pinvoke.net, but proven to compile and work properly, and often with sample usage in the form of unit tests.

A unique C# project wraps each native library. The C# project may multi-target in order to support many versions of .NET Framework, .NET Core and .NET Standard.

Win32 APIs for all Windows versions are welcome. Special Windows Store targeted assemblies omit p/invoke signatures to banned APIs so your Store apps can depend on these libraries without getting rejected by the Store certification process.

This project is supported by the .NET Foundation.

Usage

Install the NuGet package(s) for the DLLs you want to P/Invoke into. For example, if you want to P/Invoke into Win32's BCrypt.dll, install this package:

Install-Package PInvoke.BCrypt

Then import the following namespaces, as demonstrated below (if using C# 6):

using PInvoke;
using static PInvoke.BCrypt; // Supported in C# 6 (VS2015) and later.

This will allow you to conveniently call these methods directly by method name:

var error = BCryptOpenAlgorithm(AlgorithmIdentifiers.BCRYPT_SHA256_ALGORITHM); // C# 6 syntax
var error = BCrypt.BCryptOpenAlgorithm(BCrypt.AlgorithmIdentifiers.BCRYPT_SHA256_ALGORITHM); // C# 5 syntax

Sometimes a PInvoke method may have multiple overloads. For example every method that accepts struct* parameters has an overload that accepts IntPtr in its place. In other cases there may be overloads that accept struct* and struct?. In some of these cases that can lead to compiler errors if you pass in null because both struct* and struct? overloads can match. To resolve the issue, add a cast to your null: (struct?)null to resolve the ambiguity.

What if I need custom uint value not provided in enum?

Cast any uint to specific enum type and pass as parameter.

Design goals

Provide a slightly higher than lowest level API for P/Invoke signatures. For example, instead of IntPtr parameters and uint flags, you'll see SafeHandle-derived types as parameters and flags enum types. API documentation will be provided via XML doc comments for easy reading with Intellisense, along with links to the describing pages on MSDN or elsewhere as applicable.

In some cases we offer several overloads of a given native method to offer native pointer and IntPtr access. We encourage folks to try writing C# unsafe code before using IntPtr because it (ironically) can often be easier to write correct and efficient code using native pointers than all the casting and Marshal call overhead that IntPtr requires. Note that when a method's only use of a native pointer is its return type, the IntPtr returning variant must be given a different method name by CLR overloading rules, so look for the same method but with an _IntPtr suffix.

Distribution

This library should be available on NuGet for easy consumption by your projects. You may also copy and paste the P/Invoke signatures you need directly into your projects if desired.

Packages:

Library Package name NuGet Description
advapi32.dll PInvoke.AdvApi32 NuGet Windows Advanced Services
bcrypt.dll PInvoke.BCrypt NuGet Windows Cryptography API: Next Generation
cabinet.dll PInvoke.Cabinet NuGet Cabinet API Functions
cfgmgr32.dll PInvoke.CfgMgr32 NuGet Device and Driver Installation
crypt32.dll PInvoke.Crypt32 NuGet Windows Cryptography API
DwmApi.dll PInvoke.DwmApi NuGet Desktop Window Manager
fusion.dll PInvoke.Fusion NuGet .NET Framework Fusion
gdi32.dll PInvoke.Gdi32 NuGet Windows Graphics Device Interface
hid.dll PInvoke.Hid NuGet Windows Human Interface Devices
iphlpapi.dll PInvoke.IPHlpApi NuGet IP Helper
kernel32.dll PInvoke.Kernel32 NuGet Windows Kernel API
magnification.dll PInvoke.Magnification NuGet Windows Magnification API
mscoree.dll PInvoke.MSCorEE NuGet .NET Framework CLR host
msi.dll PInvoke.Msi NuGet Microsoft Installer
ncrypt.dll PInvoke.NCrypt NuGet Windows Cryptography API: Next Generation
netapi32.dll PInvoke.NetApi32 NuGet Network Management
newdev.dll PInvoke.NewDev NuGet Device and Driver Installation
ntdll.dll PInvoke.NTDll NuGet Windows NTDll
psapi.dll PInvoke.Psapi NuGet Windows Process Status API
setupapi.dll PInvoke.SetupApi NuGet Windows setup API
SHCore.dll PInvoke.SHCore NuGet Windows Shell
shell32.dll PInvoke.Shell32 NuGet Windows Shell
user32.dll PInvoke.User32 NuGet Windows User Interface
userenv.dll PInvoke.Userenv NuGet Windows User Environment
uxtheme.dll PInvoke.UxTheme NuGet Windows Visual Styles
winusb.dll PInvoke.WinUsb NuGet USB Driver
WtsApi32.dll PInvoke.WtsApi32 NuGet Windows Remote Desktop Services

Check out the P/Invoke coverage we have for each library.

If you need a P/Invoke that is in our source code but not yet released to nuget.org, you can consume the packages directly from our CI feed by adding this package source to your nuget.config file

<add key="PInvoke" value="https://pkgs.dev.azure.com/andrewarnott/OSS/_packaging/PublicCI/nuget/v3/index.json" />

Contribution

Please consider contributing more P/Invoke method signatures to this project. Once you contribute, you can immediately consume your additions without waiting for another public release of the library.

This project has adopted the code of conduct defined by the Contributor Covenant to clarify expected behavior in our community. For more information see the .NET Foundation Code of Conduct.