interface.dd

Ddoc

$(SPEC_S Interfaces,

$(GRAMMAR
$(GNAME InterfaceDeclaration):
    $(D interface) $(I Identifier) $(D ;)
    $(D interface) $(I Identifier) $(GLINK BaseInterfaceList)$(OPT) $(GLINK2 struct, AggregateBody)
    $(GLINK2 template, InterfaceTemplateDeclaration)

$(GNAME BaseInterfaceList):
    $(D :) $(GLINK2 class, Interfaces)
)

    $(P Interfaces describe a list of functions that a class that inherits
    from the interface must implement.
    A class that implements an interface can be converted to a reference
    to that interface.)

    $(P Some operating system objects, like COM/OLE/ActiveX for Win32,
    have specialized interfaces. D interfaces that are compatible with
    COM/OLE/ActiveX are called $(LINK2 COM-Interfaces, $(I COM Interfaces)).
    )

    $(P $(LINK2 CPP-Interfaces, $(I C++ Interfaces)) are another
    form of interfaces, meant to be binary compatible with C++.
    )


    $(P Interfaces cannot derive from classes; only from other interfaces.
    Classes cannot derive from an interface multiple times.
    )

------
interface D
{
    void foo();
}

class A : D, D	// error, duplicate interface
{
}
------

    An instance of an interface cannot be created.


------
interface D
{
    void foo();
}

...

D d = new D();		// error, cannot create instance of interface
------


    $(P Virtual interface member functions do not have implementations.
    Interfaces are expected to implement static or final functions.
    )

------
interface D
{
    void bar() { }	// error, implementation not allowed
    static void foo() { } // ok
    final void abc() { } // ok
}
------

    $(P Classes that inherit from an interface may not override final or
    static interface member functions.)

------
interface D {
    void bar();
    static void foo() { }
    final void abc() { }
}

class C : D {
    void bar() { } // ok
    void foo() { } // error, cannot override static D.foo()
    void abc() { } // error, cannot override final D.abc()
}
------


    $(P All interface functions must be defined in a class that inherits
    from that interface:
    )
------
interface D
{
    void foo();
}

class A : D
{
    void foo() { }	// ok, provides implementation
}

class B : D
{
    int foo() { }	// error, no void foo() implementation
}
------

    Interfaces can be inherited and functions overridden:

------
interface D
{
    int foo();
}

class A : D
{
    int foo() { return 1; }
}

class B : A
{
    int foo() { return 2; }
}

...

B b = new B();
b.foo();		// returns 2
D d = cast(D) b;	// ok since B inherits A's D implementation
d.foo();		// returns 2;
------

    $(P Interfaces can be reimplemented in derived classes:)

------
interface D
{
    int foo();
}

class A : D
{
    int foo() { return 1; }
}

class B : A, D
{
    int foo() { return 2; }
}

...

B b = new B();
b.foo();		// returns 2
D d = cast(D) b;
d.foo();		// returns 2
A a = cast(A) b;
D d2 = cast(D) a;
d2.foo();		// returns 2, even though it is A's D, not B's D
------

    $(P A reimplemented interface must implement all the interface
    functions, it does not inherit them from a super class:
    )

------
interface D
{
    int foo();
}

class A : D
{
    int foo() { return 1; }
}

class B : A, D
{
}		// error, no foo() for interface D
------

$(SECTION2 $(LNAME2 InterfaceContracts, Interfaces with Contracts),

    $(P Interface member functions can have contracts even though there
    is no body for the function. The contracts are inherited by any
    class member function that implements that interface member function.
    )

---
interface I
{
    int foo(int i)
      in { assert(i > 7); }
      out (result) { assert(result & 1); }

    void bar();
}
---
)

$(SECTION2 $(LNAME2 ConstInterface, Const and Immutable Interfaces),
    $(P If an interface has $(CODE const) or $(CODE immutable) storage
    class, then all members of the interface are
    $(CODE const) or $(CODE immutable).
    This storage class is not inherited.
    )
)


$(SECTION2 $(LNAME2 COM-Interfaces, COM Interfaces),

    $(P A variant on interfaces is the COM interface. A COM interface is
    designed to map directly onto a Windows COM object. Any COM object
    can be represented by a COM interface, and any D object with
    a COM interface can be used by external COM clients.
    )

    $(P A COM interface is defined as one that derives from the interface
    $(D std.c.win)$(SHY)$(D dows.com.IUnknown). A COM interface differs from
    a regular D interface in that:
    )

    $(UL
    $(LI It derives from the interface $(D std.c.windows.com.IUnknown).)
    $(LI It cannot be the argument of a $(I DeleteExpression).)
    $(LI References cannot be upcast to the enclosing class object, nor
    can they be downcast to a derived interface. To accomplish this,
    an appropriate $(D QueryInterface()) would have to be implemented
    for that interface in standard COM fashion.)
    $(LI Classes derived from COM interfaces are COM classes.)
    $(LI The default linkage for member functions of COM classes
    is $(D extern(System)).

    Note that if you want to implement or override any base-class methods of
    D interfaces or classes (ones which do not inherit from $(D IUnknown)),
    you have to explicitly mark them as having the $(D extern(D)) linkage:

    ---
    import core.sys.windows.windows;
    import std.c.windows.com;

    interface IText
    {
        void write();
    }

    abstract class Printer : IText
    {
        void print() { }
    }

    class C : Printer, IUnknown
    {
        // Implements the IText $(D write) class method.
        extern(D) void write() { }

        // Overrides the Printer $(D print) class method.
        extern(D) override void print() { }

        // Overrides the Object base class $(D toString) method.
        extern(D) override string toString() { return "Class C"; }

        // Methods of class implementing the IUnknown interface have
        // the extern(System) calling convention by default.
        HRESULT QueryInterface(const(IID)*, void**);
        uint AddRef();
        uint Release();
    }
    ---

    The same applies to other $(D Object) methods such as $(D opCmp), $(D toHash), etc.

    )
    $(LI The first member of the $(D vtbl[]) is not the pointer
    to the InterfaceInfo, but the first virtual function pointer.)
    )

    $(P For more information, see
    $(XLINK2 http://lunesu.com/uploads/ModernCOMProgramminginD.pdf, Modern COM Programming in D)
    )

)

$(SECTION2 $(LNAME2 CPP-Interfaces, C++ Interfaces),

    $(P C++ interfaces are interfaces declared with C++ linkage:
    )

---
extern (C++) interface Ifoo
{
    void foo();
    void bar();
}
---

    $(P which is meant to correspond with the following C++ declaration:)

$(CPPLISTING
class Ifoo
{
    virtual void foo();
    virtual void bar();
};
)

    $(P Any interface that derives from a C++ interface is also
    a C++ interface.
    A C++ interface differs from a D interface in that:
    )

    $(UL
    $(LI It cannot be the argument of a $(I DeleteExpression).)
    $(LI References cannot be upcast to the enclosing class object, nor
    can they be downcast to a derived interface.)
    $(LI The C++ calling convention is the default convention
    for its member functions, rather than the D calling convention.)
    $(LI The first member of the $(D vtbl[]) is not the pointer
    to the $(D Interface), but the first virtual function pointer.)
    )
)


)

Macros:
    TITLE=Interfaces
    WIKI=Interface
    CATEGORY_SPEC=$0