Get parent COM object from a child COM object

Question

The ID3D12GraphicsCommandList interface inherits from ID3D12CommandList. So, if I have a ID3D12GraphicsCommandList object, how do I get get the corresponding ID3D12CommandList object?

1. Will typecasting work?

    ID3D12GraphicsCommandList *gcl = ...;
    ID3D12CommandList *cl = (ID3D12CommandList*)gcl;

2. Will QueryInterface work?

    ID3D12GraphicsCommandList *gcl = ...;
    ID3D12CommandList *cl;
    HRESULT result = ID3D12GraphicsCommandList_QueryInterface(gcl,
                                                              &IID_ID3D12CommandList,
                                                              (void**)&cl);

3. Do I need to do something else?

Thanks.

Answer 1

1. Will typecasting work?

No, not in C. Requesting a different interface through an interface pointer may require pointer adjustments. Simply reinterpreting a pointer to one interface as a pointer to another interface will break in those circumstances (see below for a more in-depth exploration).

In C++ this can be made to work by supplying a user-defined conversion function, though it is extremely brittle, and can spectacularly break in subtle and not-so-subtle ways.

2. Will QueryInterface work?

Yes. It's the correct approach to request a different interface through an interface pointer. The code you provided is correct.

3. Do I need to do something else?

No, not really, as long as you follow COM rules. One detail is frequently overlooked: A successful call to QueryInterface increases the reference count on the interface, so you will have to Release every interface that was returned from a call to QueryInterface.

---

Why casting isn't safe

So if IDerived inherits from IBase then why isn't the obvious choice, a pointer cast from IDerived* to IBase*, valid? The TL;DR is, because COM doesn't provide the guarantees that would make this valid.

COM is mind-numbingly minimalistic in its requirements. In fact,

The only language requirement for COM is that code is generated in a language that can create structures of pointers and, either explicitly or implicitly, call functions through pointers.

This allows for a wide range of programming languages to be used in implementing COM interfaces. The flip side of this is that COM offers very few guarantees in how the ABI maps to language-level constructs. This is particularly true for interface inheritance:

Inheritance in COM does not mean code reuse.

An implementation of IDerived can choose to reuse IBase's implementation, or provide its own implementation. It also allows for calls to IBase's interface to have different behavior depending on which interface (IDerived or IBase) it is invoked on. That's flexible but with the pitfall that navigating an interface hierarchy through pointer casts is not guaranteed to work.

But there's more! COM has another rule that's trivially easy to understand, yet frequently overlooked:

From a COM client's perspective, reference counting is always done for each interface. Clients should never assume that an object uses the same counter for all interfaces.

Again, this gives implementations lots of flexibility but requires clients to meticulously manage their interface pointers. QueryInterface is the tool used by an implementation to track outstanding interface references. Casting pointers sidesteps this crucial management task, creating the opportunity to wind up with an interface pointer whose reference count is zero.

Those are the rules and derived guarantees at play. Now, in reality, pointer casts will surprisingly often appear to work. So if you're a developer that doesn't much differentiate between code that's correct, and code that hasn't failed yet, then by all means go ahead and cast pointers to your heart's delight.

If, on the other hand, you're a developer that takes pride in delivering software that works by virtue of being correct, then QueryInterface is always required to navigate an implementation's interface surface.

---

Ok, but DirectX doesn't actually use COM!

True. DirectX uses a small subset of COM, frequently referred to as Nano-COM. While much of COM doesn't apply, the ABI aspects of COM do. Since this answer talks about the ABI aspects only, it applies to COM and DirectX alike.

See Microsoft Docs.

Answer 2

It is always okay to upcast a COM interface pointer

The actual spec can be found here, in MS-Word format (Microsoft no longer hosts it to my understanding):

http://web.archive.org/web/20030201093710/http://www.microsoft.com/Com/resources/comdocs.asp

It is very easy to read, and clarifies a lot of details about COM which aren't made obvious on MS-docs currently.

Per the spec, a COM interface pointer is defined as a pointer to a pointer to an array of function pointers (called the VTable). The first argument to every entry in the VTable is the interface pointer itself. An interface "Inherits" from another interface by listing the other interface's functions first, followed by its own. Note, that this requirement means that only single-inheritance is supported, as explained in The COM Specification, chapter 2 part 1.2 (emphasis mine):

Interfaces and Inheritance

COM separates class hierarchy (or indeed any other implementation technology) from interface hierarchy and both of those from any implementation hierarchy. Therefore, interface inheritance is only applied to reuse the definition of the contract associated with the base interface. There is no selective inheritance in COM: if one interface inherits from another, it includes all the functions that the other interface defines, for the same reason than an object must implement all interface functions it inherits. Inheritance is used sparingly in the COM interfaces. Most of the pre-defined interfaces inherit directly from IUnknown (to receive the fundamental functions like QueryInterface), rather than inheriting from another interface to add more functionality. Because COM interfaces are inherited from IUnknown, they tend to be small and distinct from one another. This keeps functionality in separate groups that can be independently updated from the other interfaces, and can be recombined with other interfaces in semantically useful ways. In addition, interfaces only use single inheritance, never multiple inheritance, to obtain functions from a base interface. Providing otherwise would significantly complicate the interface method call sequence, which is just an indirect function call, and, further, the utility of multiple inheritance is subsumed within the capabilities provided by QueryInterface.

Note that last portion: The COM design uses single-inheritance specifically so that it is simple to call the base interface from a child interface, i.e. specifically so that you can just cast the interface pointer.

The structure of the interface VTable (and therefore, the viability of pointer casting) is confirmed in several other places as well. See the description of inheritance in the description of the IDL, chapter 13, part 1.4 (emphasis mine):

Interface Inheritance

Single inheritance of interfaces is supported, using the C++ notation for same. Referring again to [CAE RPC], page 238:

<interface_header> ::= 
  <[> <interface_attributes> <]> interface <Identifier> [ <:> <Identifier> ]

For example:

[object, uuid(b5483f00-4f6c-101b-a1c7-00aa00389acb)]
  interface IBar : IWazoo {
      HRESULT Bar([in] short i, [in] IFoo * pIF);
      };

cases the first methods in IBar to be the methods of IWazoo.

Pointer casting is even explicitly called out as okay when describing inheritance from IUknown in Chapter 3, part 1.3 (emphasis mine):

The IUnknown Interface

This specification has already mentioned the IUnknown interface many times. It is the fundamental interface in COM that contains basic operations of not only all objects, but all interfaces as well: reference counting and QueryInterface. All interfaces in COM are polymorphic with IUnknown, that is, if you look at the first three functions in any interface you see QueryInterface, AddRef, and Release. In other words, IUnknown is base interface from which all other interfaces inherit. Any single object usually only requires a single implementation of the IUnknown member functions. This means that by virtue of implementing any interface on an object you completely implement the IUnknown functions. You do not generally need to explicitly inherit from nor implement IUnknown as its own interface: when queried for it, simply typecast another interface pointer into an IUnknown* which is entirely legal with polymorphism.

We can also confirm the interface layout by examining the header file definitions for those interfaces, which all include a vTable which contains the base vTable as a first element (to use d2d1.h as an example):

typedef struct ID2D1ResourceVtbl {
    IUnknownVtbl Base;

    STDMETHOD_(void, GetFactory)(ID2D1Resource *This, ID2D1Factory **factory) PURE;
} ID2D1ResourceVtbl;

In fact, the very functions one might use to avoid casting when calling base interface methods are actually macros which perform casts!

#define ID2D1Resource_QueryInterface(this,A,B) (this)->lpVtbl->Base.QueryInterface((IUnknown*)(this),A,B)
                                                                                    ^^^^^^^^^

Pointer upcasts don't just work by coincidence, it's both guaranteed by the spec, and verifiable in your header files.

Addressing concerns raised by others:

What about pointer adjustments?

Because COM only supports single, pure-virtual inheritance, there is never a need for pointer adjustments when performing a cast. This is deliberate, as pointer adjustments when casting are very C++-specific behavior and COM tries to be language-independent. You can confirm this by looking at the machine-code output by your C++ compiler when casting COM interface pointers. There will be no adjustments.

What about different interface method implementations based on which interface the pointer actually points to?

That's why you always call functions using the vTable! This is the magic of polymorphism: that a function can be dispatched dynamically based on the type of the object without the caller knowing the type of the object. An object theoretically could do something differently based on which interface pointer you used to call a given interface method, but that's its business, not the client's. (edit: I've added some more details about both this and reference counting below)

But what about separate reference counts for different interfaces?

Again, that's why you always call functions using the vTable. The call is guaranteed to be dispatched to the correct place. There would be no point in having a vTable otherwise (we could just use static dispatch). Note that you should call AddRef whenever you make a copy of an interface pointer, regardless of whether or not that copy was made using a cast.

Final Notes/Warnings:

• Just because you can always cast to a base interface does not mean that the pointer you get is the same one that would have been returned had you called QueryInterface. This detail isn't important most of the time but comes into play if you ever have check whether two interfaces belong to the same COM object. You can't just compare the interface pointers directly; you have to compare the values returned by calling QueryInterface(IID_IUnknown, ...) on both.
• "Up"-casting (implicit casting) is also perfectly valid to do in C++, since C++ compilers are required to conform to similar ABI requirements to what COM lays out (by no coincidence).
• Pointer-casting is not okay for "cross"-casting or "down"-casting, only "up"-casting (an implicit cast in C++). If I1 does not inherit from I2, you cannot cast to an I2.
• The first argument to an interface method should only ever be the interface pointer from which you got lpVtbl. Such a mistake should be pretty easy to spot in C, and is not even possible in C++.
• Notably, the current documentation on COM as hosted on MS-docs is edited slightly from the original spec to remove alot of the concrete details and real-life examples. Specifically, it is difficult to find examples/explanations which involve C, which might mislead the reader into believing that the rules surrounding inheritance simply follow C++ inheritance rules, rather than a very strict subset of them.

In Short:

The example you gave with typecasting will work, because ID3D12GraphicsCommandList inherits from ID3D12CommandList.

---

Edit: More Notes on interface vs implementation:

As stated above, it is perfectly legal for a COM object to return different pointer from QueryInterface() to the one you would get by upcasting. Some have pointed out that this opens the door for the pointers in the interface vTable to point to completely different functions, and therefore result in different object behaviors when called. While it would be incredibly confusing and awful for a COM object to do this in a way that's visible to the API consumer, it is nevertheless legal per the COM spec. This does not mean that "always use QueryInterface() and never upcast the pointer" is good advice, though.

Note: To reduce confusion, I'm going to call the behavior that you get from the child interface (same as the behavior you get when casting a pointer) the "inherited" behavior, while the behavior of the interface returned by QueryInterface will be the "queried" behavior.

Firstly: different "inherited" and "queried" behaviors would be such a strange thing to do, that any reasonable designer would have to put that information in the object's documentation. It doesn't make sense for the API consumer to always try to account for the possibility of such weirdness, in the same way that it wouldn't make sense to only call COM methods on a Tuesday just because it's not illegal per the spec for a COM object to change its behavior based on the day of the week.

Secondly: There's no guarantee that the "queried" behavior is what you want vs the "inherited" behavior. In fact, if our theoretical object were deliberately designed to have different per-interface behaviors, you would probably want the "inherited" behavior, since it might be more likely to play nice with whatever you were doing with the child interface to begin with.

Finally: Reference counting will continue to work just fine, even if different interfaces correspond to different reference counts. I discussed this somewhat above, but I'll be more specific here. You should always call Release on the same pointer you used to call AddRef, regardless of its type (same type != same pointer, even if they are from the same object). Because the calls to AddRef and Release are dispatched dynamically (the whole point of having a vTable!), calling Release on the correct pointer will decrement the correct reference count. Avoiding pointer upcasting will not save you if you handle this incorrectly.

As an aside: your code should not use the exact value of the reference count for any reason. COM exposes this value for debugging purposes only (say, for when you're tracking down a memory leak), and it is not intended for general program use. Client code's only concern is calling "AddRef" and "Release" at the right times, and the server is responsible for the rest.

Here is some info on MS-Docs about reference counts which might be helpful:

https://learn.microsoft.com/en-us/windows/win32/learnwin32/managing-the-lifetime-of-an-object

Answer 3

Will QueryInterface work?

Yes.

Do I need to do something else?

No.

The code you have is OK. You can also do like this:

ID3D12GraphicsCommandList *gcl = ...;
ID3D12CommandList *cl;
HRESULT result = gcl->lpVtbl->QueryInterface(gcl,
                                             &IID_ID3D12CommandList,
                                             (void**)&cl);

Answer 4

in case c++ you already have pointer to ID3D12CommandList because ID3D12GraphicsCommandList inherited from ID3D12CommandList. in case c you need formal cast (ID3D12CommandList*)gcl for use this as ID3D12CommandList* pointer. use QueryInterface not need in concrete case - it can be used of course but no sense do this. again - pointer to ID3D12GraphicsCommandList - already valid pointer to ID3D12CommandList too. because pointer to ID3D12GraphicsCommandList - this is pointer to pointer to table of function (ID3D12GraphicsCommandListVtbl) which is layout compatible (containing at the begin) with ID3D12CommandListVtbl. so any method of ID3D12CommandList can be called via ID3D12GraphicsCommandList pointer as is

---

if we have pointer to some interface - we can call any method of this interface pointer.

in particular - if we have pointer (gcl) to ID3D12GraphicsCommandList interface we can call any method of ID3D12GraphicsCommandList with this (gcl) pointer.

as result we can call any method of ID3D12CommandList with exactly binary value gcl as is - because method of ID3D12CommandList also method of ID3D12GraphicsCommandList too.

in general if some object implement 2 interfaces I2 and I1 and I2 inherit from I1 ( I2 : I1 in c++ terms) we always can cast I2* pointer to I1* pointer.

Do this in the opposite direction is wrong - if we have pointer to I1* we can not cast it I2*. this already require use QueryInterface. for example - let exist I3 : I1 and object implement all 3 interfaces - I1, I2 and I3. both I2 and I3 inherit from I1 but I2 and I3 not inherit one from another, have different layout. in this case I2 and I3 always will be have different pointers. 2 different vtables. and I1* can point to I3* vtable instead I2* vtable.

so

I2* p2;
I1* p1 = (I1*)p2;// cast need only for c, not need for c++

always ok. but next code is wrong

I1* p1;
I2* p2 = (I2*)p1;// wrong !!

but question was about I2 -> I1 cast, not about I1 -> I2 cast