Harden method overload support

[kennykerr]

Rust does not support method overloads so windows-bindgen handles overloads assumed by many Windows APIs in a way that those APIs can be both called, and if necessary implemented, in Rust. Today I came across some metadata for a new project that broke in some surprising ways. Unfortunately, developers may not think to test their APIs with languages that lack overload support and tools like MIDLRT don't help to catch such mistakes.

Consider a simple IDL example:

runtimeclass A 
{
    A();
    Int32 Method();
    Int32 Method(Int32 a);
}

This class has an overloaded method named "Method". MIDLRT will generate the Overload attribute to provide alternative method names for languages that lack overload support. You might not realize this but while C++ supports overloads, COM does not. So this impacts even C++ code using these APIs, although C++/WinRT will smooth things over for you. The metadata will look something like this (I've elided some unimportant details):

public sealed class A : IA
{
    public extern A();

    [Overload("Method")]
    public extern int Method();

    [Overload("Method2")]
    public extern int Method([In] int a);
}

The overloads are actually defined by the exclusive IA interface synthesized by MIDLRT, but it's convenient to think of them as class methods, logically speaking. Languages like Rust that don't support overloads can use the method names Method and Method2 to call this API.

So far so good. Consider a second IDL example:

runtimeclass B 
{
    B();
    [method_name("MethodOne")] Int32 Method();
    [method_name("MethodTwo")] Int32 Method(Int32 a);
}

This class defines the overload names explicitly so MIDLRT doesn't have to. The metadata will look something like this:

public sealed class B : IB 
{
    public extern B();

    [Overload("MethodOne")]
    public extern int Method();

    [Overload("MethodTwo")]
    public extern int Method([In] int a);
}

Languages like Rust that don't support overloads can use the method names MethodOne and MethodTwo to use this API. This is always preferred because the API author can decide what the overloads should be called and give them more descriptive and meaningful names.

But it's not just about making things easier for Rust developers. Consider the following IDL example:

[exclusiveto(D)]
interface ID
{
    Int32 Method();
    Int32 Method(Int32 a);
}

[exclusiveto(D)]
interface ID2
{
    Int32 Method(Int32 a, Int32 b);
    Int32 Method(Int32 a, Int32 b, Int32 c);
}

runtimeclass D: [default] ID, ID2
{
    D();
}

This class defines the overloads of Method across two different exclusive interfaces. The trouble is that MIDLRT will now, regrettably, add the Overload attributes for each interface without considering the fact that these interfaces have to overload with each other in the class. The metadata will look something like this:

public sealed class D : ID, ID2
{
    public extern D();

    [Overload("Method")]
    public extern int Method();

    [Overload("Method2")]
    public extern int Method([In] int a);

    [Overload("Method")]
    public extern int Method([In] int a, [In] int b);

    [Overload("Method2")]
    public extern int Method([In] int a, [In] int b, [In] int c);
}

See the problem? There are two overloads called "Method" and two overloads called "Method2".

In summary, don't rely on MIDLRT to deal with overloads. At best it will make it inconvenient for developers. At worst it will make your API unusable in some languages. Always specify the overloads explicitly. Something like this:

[exclusiveto(E)]
interface IE
{
    [method_name("MethodOne")] Int32 Method();
    [method_name("MethodTwo")] Int32 Method(Int32 a);
}

[exclusiveto(E)]
interface IE2
{
    [method_name("MethodThree")] Int32 Method(Int32 a, Int32 b);
    [method_name("MethodFour")] Int32 Method(Int32 a, Int32 b, Int32 c);
}

runtimeclass E: [default] IE, IE2
{
    E();
}

This update to windows-bindgen just further hardens the code generator to deal with this pathological case by detecting these machine-generated overload names and contextualizing them properly for APIs.

[riverar]

Thanks for the super quick turnaround!