Merge pull request #472 from weitzhandler/feature/additional-functions

Additional functions: EnumDisplayDevices

Author: AArnott

CONTRIBUTING.md

@@ -20,6 +20,8 @@ Please send pull requests to add what you've come up with.
 
 ### How to build
 
+Run the init script at the root of the repo. Run `init -installlocality machine` from an elevated prompt.
+
 The `build.ps1` script at the root of this project will restore packages, build, and run tests.
 With the appropriate switch, this script will perform a subset of these functions.
 

src/Directory.Build.props

@@ -31,7 +31,7 @@
     <IncludeSymbols>true</IncludeSymbols>
     <SymbolPackageFormat>snupkg</SymbolPackageFormat>
 
-    <NoWarn>$(NoWarn);CS1591</NoWarn>
+    <NoWarn>$(NoWarn);CS1591;CA1401</NoWarn>
     <CodeAnalysisRuleSet>$(MSBuildThisFileDirectory)PInvoke.ruleset</CodeAnalysisRuleSet>
     <AllowUnsafeBlocks>true</AllowUnsafeBlocks>
     <SignAssembly>true</SignAssembly>

src/User32/PublicAPI.Unshipped.txt

@@ -34,6 +34,14 @@ PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS.DDC_DEFAULT = 0 -> PInvoke.User32.DIA
 PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS.DDC_DISABLE_ALL = 1 -> PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS
 PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS.DDC_DISABLE_CONTROL_RELAYOUT = PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS.DDC_DISABLE_ALL | PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS.DDC_DISABLE_RESIZE -> PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS
 PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS.DDC_DISABLE_RESIZE = 2 -> PInvoke.User32.DIALOG_DPI_CHANGE_BEHAVIORS
+PInvoke.User32.DISPLAY_DEVICE
+PInvoke.User32.DISPLAY_DEVICE.DISPLAY_DEVICE() -> void
+PInvoke.User32.DISPLAY_DEVICE.DeviceID -> char*
+PInvoke.User32.DISPLAY_DEVICE.DeviceKey -> char*
+PInvoke.User32.DISPLAY_DEVICE.DeviceName -> char*
+PInvoke.User32.DISPLAY_DEVICE.DeviceString -> char*
+PInvoke.User32.DISPLAY_DEVICE.StateFlags -> PInvoke.User32.DisplayDeviceFlags
+PInvoke.User32.DISPLAY_DEVICE.cb -> uint
 PInvoke.User32.DPI_AWARENESS
 PInvoke.User32.DPI_AWARENESS.DPI_AWARENESS_INVALID = -1 -> PInvoke.User32.DPI_AWARENESS
 PInvoke.User32.DPI_AWARENESS.DPI_AWARENESS_PER_MONITOR_AWARE = 2 -> PInvoke.User32.DPI_AWARENESS
@@ -43,6 +51,15 @@ PInvoke.User32.DPI_HOSTING_BEHAVIOR
 PInvoke.User32.DPI_HOSTING_BEHAVIOR.DPI_HOSTING_BEHAVIOR_DEFAULT = 0 -> PInvoke.User32.DPI_HOSTING_BEHAVIOR
 PInvoke.User32.DPI_HOSTING_BEHAVIOR.DPI_HOSTING_BEHAVIOR_INVALID = -1 -> PInvoke.User32.DPI_HOSTING_BEHAVIOR
 PInvoke.User32.DPI_HOSTING_BEHAVIOR.DPI_HOSTING_BEHAVIOR_MIXED = 1 -> PInvoke.User32.DPI_HOSTING_BEHAVIOR
+PInvoke.User32.DisplayDeviceFlags
+PInvoke.User32.DisplayDeviceFlags.DISPLAY_DEVICE_ACTIVE = 1 -> PInvoke.User32.DisplayDeviceFlags
+PInvoke.User32.DisplayDeviceFlags.DISPLAY_DEVICE_MIRRORING_DRIVER = 8 -> PInvoke.User32.DisplayDeviceFlags
+PInvoke.User32.DisplayDeviceFlags.DISPLAY_DEVICE_MODESPRUNED = 134217728 -> PInvoke.User32.DisplayDeviceFlags
+PInvoke.User32.DisplayDeviceFlags.DISPLAY_DEVICE_PRIMARY_DEVICE = 4 -> PInvoke.User32.DisplayDeviceFlags
+PInvoke.User32.DisplayDeviceFlags.DISPLAY_DEVICE_REMOVABLE = 32 -> PInvoke.User32.DisplayDeviceFlags
+PInvoke.User32.DisplayDeviceFlags.DISPLAY_DEVICE_VGA_COMPATIBLE = 16 -> PInvoke.User32.DisplayDeviceFlags
+PInvoke.User32.EnumDisplayDevicesFlags
+PInvoke.User32.EnumDisplayDevicesFlags.EDD_GET_DEVICE_INTERFACE_NAME = 1 -> PInvoke.User32.EnumDisplayDevicesFlags
 PInvoke.User32.GetMenuDefaultItemFlags
 PInvoke.User32.GetMenuDefaultItemFlags.GMDI_GOINTOPOPUPS = 2 -> PInvoke.User32.GetMenuDefaultItemFlags
 PInvoke.User32.GetMenuDefaultItemFlags.GMDI_USEDISABLED = 1 -> PInvoke.User32.GetMenuDefaultItemFlags
@@ -180,6 +197,9 @@ static PInvoke.User32.CreateCursor(System.IntPtr hInst, int xHotspot, int yHotSp
 static PInvoke.User32.CreateCursor(System.IntPtr hInst, int xHotspot, int yHotSpot, int nWidth, int nHeight, byte[] pvANDPlane, byte[] pvXORPlane) -> PInvoke.User32.SafeCursorHandle
 static PInvoke.User32.CreateWindowEx(PInvoke.User32.WindowStylesEx dwExStyle, short lpClassName, string lpWindowName, PInvoke.User32.WindowStyles dwStyle, int x, int y, int nWidth, int nHeight, System.IntPtr hWndParent, System.IntPtr hMenu, System.IntPtr hInstance, System.IntPtr lpParam) -> System.IntPtr
 static PInvoke.User32.CreateWindowEx(PInvoke.User32.WindowStylesEx dwExStyle, short lpClassName, string lpWindowName, PInvoke.User32.WindowStyles dwStyle, int x, int y, int nWidth, int nHeight, System.IntPtr hWndParent, System.IntPtr hMenu, System.IntPtr hInstance, void* lpParam) -> System.IntPtr
+static PInvoke.User32.DISPLAY_DEVICE.Create() -> PInvoke.User32.DISPLAY_DEVICE
+static PInvoke.User32.EnumDisplayDevices(string lpDevice, uint iDevNum, System.IntPtr lpDisplayDevice, PInvoke.User32.EnumDisplayDevicesFlags dwFlags) -> bool
+static PInvoke.User32.EnumDisplayDevices(string lpDevice, uint iDevNum, ref PInvoke.User32.DISPLAY_DEVICE lpDisplayDevice, PInvoke.User32.EnumDisplayDevicesFlags dwFlags) -> bool
 static PInvoke.User32.GetCursorInfo(System.IntPtr pci) -> bool
 static PInvoke.User32.GetCursorInfo(out PInvoke.User32.CURSORINFO pci) -> bool
 static PInvoke.User32.GetMenuBarInfo(System.IntPtr hwnd, PInvoke.User32.MenuObject idObject, int idItem, System.IntPtr pmbi) -> bool
@@ -209,6 +229,7 @@ static extern PInvoke.User32.AreDpiAwarenessContextsEqual(System.IntPtr dpiConte
 static extern PInvoke.User32.CreateCursor(System.IntPtr hInst, int xHotspot, int yHotSpot, int nWidth, int nHeight, byte* pvANDPlane, byte* pvXORPlane) -> PInvoke.User32.SafeCursorHandle
 static extern PInvoke.User32.DestroyWindow(System.IntPtr hWnd) -> bool
 static extern PInvoke.User32.EnableNonClientDpiScaling(System.IntPtr hwnd) -> bool
+static extern PInvoke.User32.EnumDisplayDevices(string lpDevice, uint iDevNum, PInvoke.User32.DISPLAY_DEVICE* lpDisplayDevice, PInvoke.User32.EnumDisplayDevicesFlags dwFlags) -> bool
 static extern PInvoke.User32.GetAwarenessFromDpiAwarenessContext(System.IntPtr dpiAwarenessContext) -> PInvoke.User32.DPI_AWARENESS
 static extern PInvoke.User32.GetCursor() -> PInvoke.User32.SafeCursorHandle
 static extern PInvoke.User32.GetCursorInfo(PInvoke.User32.CURSORINFO* pci) -> bool

src/User32/User32+DISPLAY_DEVICE.cs

@@ -0,0 +1,58 @@
+// Copyright © .NET Foundation and Contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace PInvoke
+{
+    using System.Runtime.InteropServices;
+
+    /// <content>
+    /// Contains the <see cref="DISPLAY_DEVICE"/> nested type.
+    /// </content>
+    public partial class User32
+    {
+        /// <summary>
+        /// Receives information about the display device specified by the <c>iDevNum</c> parameter of the <see cref="User32.EnumDisplayDevices(string, uint, DISPLAY_DEVICE*, EnumDisplayDevicesFlags)"/> function.
+        /// </summary>
+        public unsafe struct DISPLAY_DEVICE
+        {
+            /// <summary>
+            /// Size, in bytes, of the DISPLAY_DEVICE structure. This must be initialized prior to calling <see cref="User32.EnumDisplayDevices(string, uint, DISPLAY_DEVICE*, EnumDisplayDevicesFlags)"/>.
+            /// </summary>
+            public uint cb;
+
+            /// <summary>
+            /// An array of characters identifying the device name. This is either the adapter device or the monitor device.
+            /// </summary>
+            public fixed char DeviceName[32];
+
+            /// <summary>
+            /// An array of characters containing the device context string. This is either a description of the display adapter or of the display monitor.
+            /// </summary>
+            public fixed char DeviceString[128];
+
+            /// <summary>
+            /// Device state flags.
+            /// </summary>
+            public DisplayDeviceFlags StateFlags;
+
+            /// <summary>
+            /// Not used.
+            /// </summary>
+            public fixed char DeviceID[128];
+
+            /// <summary>
+            /// Reserved.
+            /// </summary>
+            public fixed char DeviceKey[128];
+
+            /// <summary>
+            /// Initializes a new instance of the <see cref="DISPLAY_DEVICE"/> struct
+            /// with the <see cref="cb" /> field initialized.
+            /// </summary>
+            /// <returns>
+            /// An instance of the structure.
+            /// </returns>
+            public static DISPLAY_DEVICE Create() => new DISPLAY_DEVICE { cb = (uint)Marshal.SizeOf(typeof(DISPLAY_DEVICE)) };
+        }
+    }
+}

src/User32/User32+DisplayDeviceFlags.cs

@@ -0,0 +1,47 @@
+// Copyright © .NET Foundation and Contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace PInvoke
+{
+    using System;
+
+    /// <content>
+    /// Contains the <see cref="DisplayDeviceFlags"/> nested type.
+    /// </content>
+    public partial class User32
+    {
+        /// <summary>
+        /// Device state flags.
+        /// </summary>
+        [Flags]
+        public enum DisplayDeviceFlags : uint
+        {
+            /// <summary>
+            ///     DISPLAY_DEVICE_ACTIVE specifies whether a monitor is presented as being "on" by the respective GDI view.
+            ///     Windows Vista: EnumDisplayDevices will only enumerate monitors that can be presented as being "on".
+            /// </summary>
+            DISPLAY_DEVICE_ACTIVE = 0x00000001,
+
+            /// <summary>
+            ///     Represents a pseudo device used to mirror application drawing for remoting or other purposes. An invisible pseudo monitor is associated with this device.
+            ///     For example, NetMeeting uses it. Note that <see cref="User32.GetSystemMetrics(User32.SystemMetric)"/> (SM_MONITORS) only accounts for visible display monitors.
+            /// </summary>
+            DISPLAY_DEVICE_MIRRORING_DRIVER = 0x00000008,
+
+            /// <summary>The device has more display modes than its output devices support.</summary>
+            DISPLAY_DEVICE_MODESPRUNED = 0x08000000,
+
+            /// <summary>
+            ///     The primary desktop is on the device. For a system with a single display card, this is always set.
+            ///     For a system with multiple display cards, only one device can have this set.
+            /// </summary>
+            DISPLAY_DEVICE_PRIMARY_DEVICE = 0x00000004,
+
+            /// <summary>The device is removable; it cannot be the primary display.</summary>
+            DISPLAY_DEVICE_REMOVABLE = 0x00000020,
+
+            /// <summary>The device is VGA compatible.</summary>
+            DISPLAY_DEVICE_VGA_COMPATIBLE = 0x00000010,
+        }
+    }
+}

src/User32/User32+EnumDisplayDevicesFlags.cs

@@ -0,0 +1,16 @@
+// Copyright © .NET Foundation and Contributors. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+
+namespace PInvoke
+{
+    /// <content>
+    /// Contains the <see cref="EnumDisplayDevicesFlags"/> nested type.
+    /// </content>
+    public partial class User32
+    {
+        public enum EnumDisplayDevicesFlags : uint
+        {
+            EDD_GET_DEVICE_INTERFACE_NAME = 0x00000001,
+        }
+    }
+}

src/User32/User32+MonitorOptions.cs

@@ -3,9 +3,6 @@
 
 namespace PInvoke
 {
-    using System;
-    using System.Runtime.InteropServices;
-
     /// <content>
     /// Contains the <see cref="MonitorOptions"/> nested type.
     /// </content>

src/User32/User32.cs

@@ -1632,10 +1632,69 @@ public static extern unsafe int LookupIconIdFromDirectoryEx(
         [return: MarshalAs(UnmanagedType.Bool)]
         public static extern bool GetWindowDisplayAffinity(IntPtr hWnd, out int dwAffinity);
 
+        /// <summary>
+        /// Enumerates display monitors (including invisible pseudo-monitors associated with the mirroring drivers)
+        /// that intersect a region formed by the intersection of a specified clipping rectangle and the visible region of a device context.
+        /// EnumDisplayMonitors calls an application-defined <see cref="MONITORENUMPROC"/> callback function once for each monitor that is enumerated. Note that <see cref="GetSystemMetrics(SystemMetric)"/> counts only the display monitors.
+        /// </summary>
+        /// <param name="hdc">
+        /// A handle to a display device context that defines the visible region of interest.
+        /// If this parameter is NULL, the hdcMonitor parameter passed to the callback function will be NULL,
+        /// and the visible region of interest is the virtual screen that encompasses all the displays on the desktop.
+        /// </param>
+        /// <param name="lprcClip">
+        /// A pointer to a RECT structure that specifies a clipping rectangle.
+        /// The region of interest is the intersection of the clipping rectangle with the visible region specified by hdc.
+        /// If hdc is non-NULL, the coordinates of the clipping rectangle are relative to the origin of the hdc.If hdc is NULL, the coordinates are virtual-screen coordinates.
+        /// This parameter can be NULL if you don't want to clip the region specified by hdc.
+        /// </param>
+        /// <param name="lpfnEnum">A pointer to a <see cref="MONITORENUMPROC"/> application-defined callback function.</param>
+        /// <param name="dwData">Application-defined data that EnumDisplayMonitors passes directly to the MonitorEnumProc function.</param>
+        /// <returns>
+        /// If the function succeeds, the return value is nonzero.
+        /// If the function fails, the return value is zero.
+        /// </returns>
+        /// <remarks>
+        /// See: https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-enumdisplaymonitors#remarks.
+        /// </remarks>
         [DllImport(nameof(User32), SetLastError = true)]
         [return: MarshalAs(UnmanagedType.Bool)]
         public static extern unsafe bool EnumDisplayMonitors(IntPtr hdc, RECT* lprcClip, MONITORENUMPROC lpfnEnum, void* dwData);
 
+        /// <summary>
+        /// Lets you obtain information about the display devices in the current session.
+        /// </summary>
+        /// <param name="lpDevice">A pointer to the device name. If <c>NULL</c>, function returns information for the display adapter(s) on the machine, based on <paramref name="iDevNum"/>.</param>
+        /// <param name="iDevNum">
+        /// An index value that specifies the display device of interest.
+        /// The operating system identifies each display device in the current session with an index value.
+        /// The index values are consecutive integers, starting at 0. If the current session has three display devices, for example, they are specified by the index values 0, 1, and 2.
+        /// </param>
+        /// <param name="lpDisplayDevice">
+        /// A pointer to a <see cref="DISPLAY_DEVICE"/> structure that receives information about the display device specified by <paramref name="iDevNum"/>.
+        /// Before calling <see cref="EnumDisplayDevices(string, uint, DISPLAY_DEVICE*, EnumDisplayDevicesFlags)"/>, you must initialize the member <see cref="DISPLAY_DEVICE.cb"/> to the size, in bytes, of <see cref="DISPLAY_DEVICE"/>.
+        /// </param>
+        /// <param name="dwFlags">
+        /// Set this flag to <see cref="EnumDisplayDevicesFlags.EDD_GET_DEVICE_INTERFACE_NAME"/> to retrieve the device interface name for <c>GUID_DEVINTERFACE_MONITOR</c>, which is registered by the operating system on a per monitor basis.
+        /// The value is placed in the <see cref="DISPLAY_DEVICE.DeviceID"/> structure returned in <paramref name="lpDisplayDevice"/>.
+        /// The resulting device interface name can be used with SetupAPI functions and serves as a link between GDI monitor devices and SetupAPI monitor devices.
+        /// </param>
+        /// <returns>
+        /// If the function succeeds, the return value is nonzero.
+        /// If the function fails, the return value is zero.
+        /// The function fails if <paramref name="iDevNum"/> is greater than the largest device index.
+        /// </returns>
+        /// <remarks>
+        /// See https://docs.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-enumdisplaydevicesa#remarks.
+        /// </remarks>
+        [DllImport(nameof(User32), SetLastError = true, CharSet = CharSet.Unicode, EntryPoint = "EnumDisplayDevicesW")]
+        [return: MarshalAs(UnmanagedType.Bool)]
+        public static extern unsafe bool EnumDisplayDevices(
+            [MarshalAs(UnmanagedType.LPWStr)] string lpDevice,
+            uint iDevNum,
+            [Friendly(FriendlyFlags.Bidirectional)] DISPLAY_DEVICE* lpDisplayDevice,
+            EnumDisplayDevicesFlags dwFlags);
+
         [DllImport(nameof(User32), SetLastError = true, CharSet = CharSet.Unicode)]
         [return: MarshalAs(UnmanagedType.Bool)]
         public static extern bool GetClassInfoEx(