Merge pull request #666 from elachlan/HRESULT

Improvements to HRESULT

Author: AArnott

README.md

@@ -52,6 +52,7 @@ Create a `NativeMethods.txt` file in your project directory that lists the APIs
 Each line may consist of *one* of the following:
 
 * Exported method name (e.g. `CreateFile`). This *may* include the `A` or `W` suffix, where applicable. This *may* be qualified with a namespace but is only recommended in cases of ambiguity, which CsWin32 will prompt where appropriate.
+* A macro name (e.g. `HRESULT_FROM_WIN32`). These are generated into the same class with extern methods. Macros must be hand-authored into CsWin32, so let us know if you want to see a macro added.
 * A namespace to generate all APIs from (e.g. `Windows.Win32.Storage.FileSystem` would search the metadata for all APIs within that namespace and generate them).
 * Module name followed by `.*` to generate all methods exported from that module (e.g. `Kernel32.*`).
 * The name of a struct, enum, constant or interface to generate. This *may* be qualified with a namespace but is only recommended in cases of ambiguity, which CsWin32 will prompt where appropriate.

src/Microsoft.Windows.CsWin32/Generator.cs

@@ -82,6 +82,7 @@ public class Generator : IDisposable
     private const string OriginalDelegateAnnotation = "OriginalDelegate";
 
     private static readonly Dictionary<string, MethodDeclarationSyntax> PInvokeHelperMethods;
+    private static readonly Dictionary<string, MethodDeclarationSyntax> PInvokeMacros;
 
     private static readonly string AutoGeneratedHeader = @"// ------------------------------------------------------------------------------
 // <auto-generated>
@@ -98,6 +99,12 @@ public class Generator : IDisposable
 /// <content>
 /// Contains extern methods from ""{0}"".
 /// </content>
+".Replace("\r\n", "\n");
+
+    private static readonly string PartialPInvokeMacrosContentComment = @"
+/// <content>
+/// Contains macros.
+/// </content>
 ".Replace("\r\n", "\n");
 
     private static readonly SyntaxTriviaList InlineArrayUnsafeAsSpanComment = ParseLeadingTrivia(@"/// <summary>
@@ -348,6 +355,7 @@ public class Generator : IDisposable
     private readonly IdentifierNameSyntax methodsAndConstantsClassName;
     private readonly HashSet<string> injectedPInvokeHelperMethods = new();
     private readonly HashSet<string> injectedPInvokeHelperMethodsToFriendlyOverloadsExtensions = new();
+    private readonly HashSet<string> injectedPInvokeMacros = new();
     private readonly Dictionary<TypeDefinitionHandle, bool> managedTypesCheck = new();
     private bool needsWinRTCustomMarshaler;
 
@@ -359,6 +367,13 @@ static Generator()
         }
 
         PInvokeHelperMethods = ((ClassDeclarationSyntax)member).Members.OfType<MethodDeclarationSyntax>().ToDictionary(m => m.Identifier.ValueText, m => m);
+
+        if (!TryFetchTemplate("PInvokeClassMacros", null, out member))
+        {
+            throw new GenerationFailedException("Missing embedded resource.");
+        }
+
+        PInvokeMacros = ((ClassDeclarationSyntax)member).Members.OfType<MethodDeclarationSyntax>().ToDictionary(m => m.Identifier.ValueText, m => m);
     }
 
     /// <summary>
@@ -477,34 +492,35 @@ private IEnumerable<MemberDeclarationSyntax> NamespaceMembers
         {
             IEnumerable<IGrouping<string, MemberDeclarationSyntax>> members = this.committedCode.MembersByModule;
             IEnumerable<MemberDeclarationSyntax> result = Enumerable.Empty<MemberDeclarationSyntax>();
-            for (int i = 0; i < members.Count(); i++)
+            int i = 0;
+            foreach (IGrouping<string, MemberDeclarationSyntax> entry in members)
             {
-                IGrouping<string, MemberDeclarationSyntax> entry = members.ElementAt(i);
-                if (i == 0)
+                ClassDeclarationSyntax partialClass = DeclarePInvokeClass(entry.Key)
+                    .AddMembers(entry.ToArray())
+                    .WithLeadingTrivia(ParseLeadingTrivia(string.Format(CultureInfo.InvariantCulture, PartialPInvokeContentComment, entry.Key)));
+                if (i++ == 0)
                 {
-                    result = result.Concat(new MemberDeclarationSyntax[]
-                    {
-                        ClassDeclaration(Identifier(this.options.ClassName))
-                        .AddModifiers(TokenWithSpace(this.Visibility), TokenWithSpace(SyntaxKind.StaticKeyword), TokenWithSpace(SyntaxKind.PartialKeyword))
-                        .AddMembers(entry.ToArray())
+                    partialClass = partialClass
+                        .WithoutLeadingTrivia()
                         .AddAttributeLists(AttributeList().AddAttributes(GeneratedCodeAttribute))
-                        .WithLeadingTrivia(ParseLeadingTrivia(string.Format(CultureInfo.InvariantCulture, PartialPInvokeContentComment, entry.Key)))
-                        .WithAdditionalAnnotations(new SyntaxAnnotation(SimpleFileNameAnnotation, $"{this.options.ClassName}.{entry.Key}")),
-                    });
-                }
-                else
-                {
-                    result = result.Concat(new MemberDeclarationSyntax[]
-                    {
-                        ClassDeclaration(Identifier(this.options.ClassName))
-                        .AddModifiers(TokenWithSpace(this.Visibility), TokenWithSpace(SyntaxKind.StaticKeyword), TokenWithSpace(SyntaxKind.PartialKeyword))
-                        .AddMembers(entry.ToArray())
-                        .WithLeadingTrivia(ParseLeadingTrivia(string.Format(CultureInfo.InvariantCulture, PartialPInvokeContentComment, entry.Key)))
-                        .WithAdditionalAnnotations(new SyntaxAnnotation(SimpleFileNameAnnotation, $"{this.options.ClassName}.{entry.Key}")),
-                    });
+                        .WithLeadingTrivia(partialClass.GetLeadingTrivia());
                 }
+
+                result = result.Concat(new MemberDeclarationSyntax[] { partialClass });
             }
 
+            ClassDeclarationSyntax macrosPartialClass = DeclarePInvokeClass("Macros")
+                .AddMembers(this.committedCode.Macros.ToArray())
+                .WithLeadingTrivia(ParseLeadingTrivia(PartialPInvokeMacrosContentComment));
+            if (macrosPartialClass.Members.Count > 0)
+            {
+                result = result.Concat(new MemberDeclarationSyntax[] { macrosPartialClass });
+            }
+
+            ClassDeclarationSyntax DeclarePInvokeClass(string fileNameKey) => ClassDeclaration(Identifier(this.options.ClassName))
+                .AddModifiers(TokenWithSpace(this.Visibility), TokenWithSpace(SyntaxKind.StaticKeyword), TokenWithSpace(SyntaxKind.PartialKeyword))
+                .WithAdditionalAnnotations(new SyntaxAnnotation(SimpleFileNameAnnotation, $"{this.options.ClassName}.{fileNameKey}"));
+
             result = result.Concat(this.committedCode.GeneratedTypes);
 
             ClassDeclarationSyntax inlineArrayIndexerExtensionsClass = this.DeclareInlineArrayIndexerExtensionsClass();
@@ -574,6 +590,8 @@ public void GenerateAll(CancellationToken cancellationToken)
         this.RequestAllInteropTypes(cancellationToken);
 
         this.GenerateAllConstants(cancellationToken);
+
+        this.GenerateAllMacros(cancellationToken);
     }
 
     /// <inheritdoc cref="TryGenerate(string, out IReadOnlyList{string}, CancellationToken)"/>
@@ -645,6 +663,12 @@ public bool TryGenerate(string apiNameOrModuleWildcard, out IReadOnlyList<string
                 return result;
             }
 
+            result = this.TryGenerateMacro(apiNameOrModuleWildcard, out preciseApi);
+            if (result || preciseApi.Count > 1)
+            {
+                return result;
+            }
+
             return false;
         }
     }
@@ -767,6 +791,30 @@ public void GenerateAllConstants(CancellationToken cancellationToken)
         }
     }
 
+    /// <summary>
+    /// Generates a projection of all macros.
+    /// </summary>
+    /// <param name="cancellationToken">A cancellation token.</param>
+    public void GenerateAllMacros(CancellationToken cancellationToken)
+    {
+        foreach (KeyValuePair<string, MethodDeclarationSyntax> macro in PInvokeMacros)
+        {
+            cancellationToken.ThrowIfCancellationRequested();
+
+            try
+            {
+                this.volatileCode.GenerationTransaction(delegate
+                {
+                    this.RequestMacro(macro.Value);
+                });
+            }
+            catch (GenerationFailedException ex) when (IsPlatformCompatibleException(ex))
+            {
+                // Something transitively required for this field is not available for this platform, so skip this method.
+            }
+        }
+    }
+
     /// <summary>
     /// Generates all extern methods exported from a particular module, along with all their supporting types.
     /// </summary>
@@ -1038,6 +1086,34 @@ public bool TryGenerateConstant(string possiblyQualifiedName, out IReadOnlyList<
         return false;
     }
 
+    /// <summary>
+    /// Generate code for the named macro, if it is recognized.
+    /// </summary>
+    /// <param name="macroName">The name of the macro. Never qualified with a namespace.</param>
+    /// <param name="preciseApi">Receives the canonical API names that <paramref name="macroName"/> matched on.</param>
+    /// <returns><see langword="true"/> if a match was found and the macro generated; otherwise <see langword="false"/>.</returns>
+    public bool TryGenerateMacro(string macroName, out IReadOnlyList<string> preciseApi)
+    {
+        if (macroName is null)
+        {
+            throw new ArgumentNullException(nameof(macroName));
+        }
+
+        if (!PInvokeMacros.TryGetValue(macroName, out MethodDeclarationSyntax macro))
+        {
+            preciseApi = Array.Empty<string>();
+            return false;
+        }
+
+        this.volatileCode.GenerationTransaction(delegate
+        {
+            this.RequestMacro(macro);
+        });
+
+        preciseApi = ImmutableList.Create(macroName);
+        return true;
+    }
+
     /// <summary>
     /// Produces a sequence of suggested APIs with a similar name to the specified one.
     /// </summary>
@@ -1525,6 +1601,24 @@ internal void RequestConstant(FieldDefinitionHandle fieldDefHandle)
         });
     }
 
+    internal void RequestMacro(MethodDeclarationSyntax macro)
+    {
+        this.volatileCode.GenerateMacro(macro.Identifier.ValueText, delegate
+        {
+            this.volatileCode.AddMacro(macro.Identifier.ValueText, (MethodDeclarationSyntax)this.ElevateVisibility(macro));
+
+            // Generate any additional types that this macro relies on.
+            foreach (QualifiedNameSyntax identifier in macro.DescendantNodes().OfType<QualifiedNameSyntax>())
+            {
+                string identifierString = identifier.ToString();
+                if (identifierString.StartsWith(GlobalNamespacePrefix, StringComparison.Ordinal))
+                {
+                    this.TryGenerateType(identifierString.Substring(GlobalNamespacePrefix.Length));
+                }
+            }
+        });
+    }
+
     internal TypeSyntax? RequestSafeHandle(string releaseMethod)
     {
         if (!this.options.UseSafeHandles)
@@ -5901,6 +5995,8 @@ private class GeneratedCode
 
         private readonly Dictionary<string, (MemberDeclarationSyntax Type, bool TopLevel)> specialTypes = new(StringComparer.Ordinal);
 
+        private readonly Dictionary<string, MethodDeclarationSyntax> macros = new(StringComparer.Ordinal);
+
         /// <summary>
         /// The set of types that are or have been generated so we don't stack overflow for self-referencing types.
         /// </summary>
@@ -5934,7 +6030,7 @@ internal GeneratedCode(GeneratedCode parent)
         }
 
         internal bool IsEmpty => this.modulesAndMembers.Count == 0 && this.types.Count == 0 && this.fieldsToSyntax.Count == 0 && this.safeHandleTypes.Count == 0 && this.specialTypes.Count == 0
-            && this.inlineArrayIndexerExtensionsMembers.Count == 0 && this.comInterfaceFriendlyExtensionsMembers.Count == 0;
+            && this.inlineArrayIndexerExtensionsMembers.Count == 0 && this.comInterfaceFriendlyExtensionsMembers.Count == 0 && this.macros.Count == 0;
 
         internal IEnumerable<MemberDeclarationSyntax> GeneratedTypes => this.GetTypesWithInjectedFields()
             .Concat(this.specialTypes.Values.Where(st => !st.TopLevel).Select(st => st.Type))
@@ -5961,6 +6057,8 @@ internal IEnumerable<IGrouping<string, MemberDeclarationSyntax>> MembersByModule
             }
         }
 
+        internal IEnumerable<MethodDeclarationSyntax> Macros => this.macros.Values;
+
         internal void AddSafeHandleType(ClassDeclarationSyntax safeHandleDeclaration)
         {
             this.ThrowIfNotGenerating();
@@ -5998,6 +6096,12 @@ internal void AddConstant(FieldDefinitionHandle fieldDefHandle, FieldDeclaration
             this.fieldsToSyntax.Add(fieldDefHandle, (constantDeclaration, fieldType));
         }
 
+        internal void AddMacro(string macroName, MethodDeclarationSyntax macro)
+        {
+            this.ThrowIfNotGenerating();
+            this.macros.Add(macroName, macro);
+        }
+
         internal void AddInlineArrayIndexerExtension(MethodDeclarationSyntax inlineIndexer)
         {
             this.ThrowIfNotGenerating();
@@ -6161,6 +6265,18 @@ internal void GenerateConstant(FieldDefinitionHandle fieldDefinitionHandle, Acti
             generator();
         }
 
+        internal void GenerateMacro(string macroName, Action generator)
+        {
+            this.ThrowIfNotGenerating();
+
+            if (this.macros.ContainsKey(macroName) || this.parent?.macros.ContainsKey(macroName) is true)
+            {
+                return;
+            }
+
+            generator();
+        }
+
         internal bool TryGetSafeHandleForReleaseMethod(string releaseMethod, out TypeSyntax? safeHandleType)
         {
             return this.releaseMethodsWithSafeHandleTypesGenerating.TryGetValue(releaseMethod, out safeHandleType)
@@ -6219,6 +6335,7 @@ private void Commit(GeneratedCode? parent)
             Commit(this.safeHandleTypes, parent?.safeHandleTypes);
             Commit(this.specialTypes, parent?.specialTypes);
             Commit(this.typesGenerating, parent?.typesGenerating);
+            Commit(this.macros, parent?.macros);
             Commit(this.methodsGenerating, parent?.methodsGenerating);
             Commit(this.specialTypesGenerating, parent?.specialTypesGenerating);
             Commit(this.releaseMethodsWithSafeHandleTypesGenerating, parent?.releaseMethodsWithSafeHandleTypesGenerating);

src/Microsoft.Windows.CsWin32/templates/HRESULT.cs

@@ -61,7 +61,7 @@ internal HRESULT ThrowOnFailure(IntPtr errorInfo = default)
         return this;
     }
 
-    public override string ToString() => this.Value.ToString();
+    public override string ToString() => string.Format(global::System.Globalization.CultureInfo.InvariantCulture, "0x{0:X8}", this.Value);
 
     internal string ToString(string format, IFormatProvider formatProvider) => ((uint)this.Value).ToString(format, formatProvider);
 }

src/Microsoft.Windows.CsWin32/templates/PInvokeClassMacros.cs

@@ -0,0 +1,15 @@
+/// <summary>
+/// This class wrapper is stripped so that individual macros can be requested for generation.
+/// </summary>
+internal class PInvokeClassMacros
+{
+	/// <summary>
+	/// Creates an <see cref="global::Windows.Win32.Foundation.HRESULT"/> that represents a given <see cref="global::Windows.Win32.Foundation.WIN32_ERROR"/>.
+	/// </summary>
+	/// <param name="error">The win32 error to be wrapped.</param>
+	/// <returns>An <see cref="global::Windows.Win32.Foundation.HRESULT"/>.</returns>
+	/// <remarks>
+	/// Learn more in <see href="https://docs.microsoft.com/windows/win32/api/winerror/nf-winerror-hresult_from_win32">the documentation for this API</see>.
+	/// </remarks>
+	internal static global::Windows.Win32.Foundation.HRESULT HRESULT_FROM_WIN32(global::Windows.Win32.Foundation.WIN32_ERROR error) => new(unchecked(error <= 0 ? (int)error : (int)(((uint)error & 0x0000FFFF) | 0x80070000)));
+}

test/Microsoft.Windows.CsWin32.Tests/GeneratorTests.cs

@@ -607,6 +607,29 @@ public void HandleStructsHaveStaticNullMember(string handleName)
         this.AssertGeneratedMember(handleName, "Null", $"internal static {handleName} Null => default;");
     }
 
+    [Theory, PairwiseData]
+    public void MacroAPIsGenerateWithAppropriateVisibility(bool publicVisibility)
+    {
+        this.generator = this.CreateGenerator(DefaultTestGeneratorOptions with { Public = publicVisibility });
+        Assert.True(this.generator.TryGenerate("HRESULT_FROM_WIN32", CancellationToken.None));
+        this.CollectGeneratedCode(this.generator);
+        this.AssertNoDiagnostics();
+        var method = Assert.Single(this.FindGeneratedMethod("HRESULT_FROM_WIN32"));
+
+        Assert.True(method.Modifiers.Any(publicVisibility ? SyntaxKind.PublicKeyword : SyntaxKind.InternalKeyword));
+    }
+
+    [Theory]
+    [InlineData("HRESULT_FROM_WIN32")]
+    public void MacroAPIsGenerate(string macro)
+    {
+        this.generator = this.CreateGenerator();
+        Assert.True(this.generator.TryGenerate(macro, CancellationToken.None));
+        this.CollectGeneratedCode(this.generator);
+        this.AssertNoDiagnostics();
+        Assert.Single(this.FindGeneratedMethod(macro));
+    }
+
     [Theory]
     [InlineData("BOOL")]
     [InlineData("BOOLEAN")]