Skip to content

Commit

Permalink
Merge pull request #543 from AndrejMitrovic/Fix12607
Browse files Browse the repository at this point in the history 
Issue 12607 - Document that IUnknown classes must mark toString with extern(D) when overriding it
  • Loading branch information
@MartinNowak
MartinNowak committed Apr 21, 2014
2 parents 968e8c1 + 1bf4ff0 commit 652b96b
Showing 1 changed file with 110 additions and 85 deletions.
195 changes: 110 additions & 85 deletions interface.dd
View file
Expand Up @@ -12,24 +12,24 @@ $(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 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 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 $(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.
)
$(P Interfaces cannot derive from classes; only from other interfaces.
Classes cannot derive from an interface multiple times.
)

------
interface D
Expand All @@ -42,7 +42,7 @@ class A : D, D // error, duplicate interface
}
------

An instance of an interface cannot be created.
An instance of an interface cannot be created.


------
Expand All @@ -57,9 +57,9 @@ 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.
)
$(P Virtual interface member functions do not have implementations.
Interfaces are expected to implement static or final functions.
)

------
interface D
Expand All @@ -70,8 +70,8 @@ interface D
}
------

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

------
interface D {
Expand All @@ -88,9 +88,9 @@ class C : D {
------


$(P All interface functions must be defined in a class that inherits
from that interface:
)
$(P All interface functions must be defined in a class that inherits
from that interface:
)
------
interface D
{
Expand All @@ -108,7 +108,7 @@ class B : D
}
------

Interfaces can be inherited and functions overridden:
Interfaces can be inherited and functions overridden:

------
interface D
Expand All @@ -134,7 +134,7 @@ 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:)
$(P Interfaces can be reimplemented in derived classes:)

------
interface D
Expand Down Expand Up @@ -163,9 +163,9 @@ 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:
)
$(P A reimplemented interface must implement all the interface
functions, it does not inherit them from a super class:
)

------
interface D
Expand All @@ -185,10 +185,10 @@ class B : A, 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.
)
$(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
Expand All @@ -203,51 +203,76 @@ interface I
)

$(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.
)
$(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)).)
$(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)
)
$(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 override the $(D Object) base class methods
such as the $(D toString) method, you have to explicitly mark them as
having the $(D extern(D)) linkage:

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

class C : IUnknown
{
// Must be marked with extern(D) since IUnknown-derived classes have
// their methods set to the extern(System) calling convention by default.
extern(D) override string toString() { return "Class C"; }

// These all have the extern(System) calling convention.
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:
)
$(P C++ interfaces are interfaces declared with C++ linkage:
)

---
extern (C++) interface Ifoo
Expand All @@ -257,7 +282,7 @@ extern (C++) interface Ifoo
}
---

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

$(CPPLISTING
class Ifoo
Expand All @@ -267,27 +292,27 @@ class Ifoo
};
)

$(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.)
)
$(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
TITLE=Interfaces
WIKI=Interface
CATEGORY_SPEC=$0

0 comments on commit 652b96b

Please sign in to comment.