Void pointer pointer (void **)

Question

I am reading a COM sample at http://msdn.microsoft.com/en-us/library/windows/desktop/dd389098(v=vs.85).aspx

I really cannot comprehend (void **) in

hr = pGraph->QueryInterface(IID_IMediaControl, (void **)&pControl);

So I have tried some values returned by different types of pointers by the class

class Point{
private:
    int x, y;
public:
    Point(int inputX, int inputY){x = inputX, y = inputY;}
    int getX(){return x;}
    int getY(){return y;}
    friend ostream& operator << (ostream &out, Point &cPoint);
    Point operator-(){
        return Point(-x, -y);
    }
};

ostream& operator << (ostream &out, Point &cPoint){
    return out<< "(" << cPoint.x << ", " << cPoint.y << ")";
}

and printing out

Point *p = new Point(1,2);
cout << p << endl << &p << endl << endl
<< *&p << endl<< **&p << endl<<endl 
<< (void *) &p << endl << (void **) &p ;

(void*) really has no difference with (void **). What does (void **)&pControl want to return?

Answer 1

 hr = pGraph->QueryInterface(IID_IMediaControl, (void **)&pControl); 

What does (void **)&pControl want to return?

QueryInterface() is one of the three methods of IUnknown , which is the base root interface of all COM interfaces.

The MSDN documentation for IUnknown::QueryInterface() clearly states that:

 HRESULT QueryInterface( [in] REFIID riid, [out] void **ppvObject ); 

ppvObject [out] The address of a pointer variable that receives the interface pointer requested in the riid parameter. Upon successful return, *ppvObject contains the requested interface pointer to the object. If the object does not support the interface, *ppvObject is set to NULL .

So, in your particular case, upon successful return, pControl will contain the requested pointer to the IMediaControl interface, as specified in your function call via the first argument IID_IMediaControl .

---

Now, let's try to better understand why the double pointer indirection: void** .

void* means "pointer to anything" .

So, one might think: "Why isn't the second parameter of QueryInterface() just a void* ?"

The problem is that this parameter is an output parameter. This means that QueryInterface() will write something into that parameter, for the caller to use it.

And, in C (and COM has several C-isms), when you have an output parameter, you must use a pointer ( * ).
( Note In C++ you can also use a reference & .)

So, in this case we have the first level of indirection of void* that means "pointer to anything" .
And the second level of indirection (the other * ), that means: "This is an output parameter" .

You can think of it also in this way:

typedef void* PointerToAnything;

HRESULT QueryInterface(..., /* [out] */ PointerToAnything* pSomeInterface);

// pSomeInterface is an output parameter.
//
// [out] --> use * (pointer), 
// so it's 'PointerToAnything*' (not just 'PointerToAnything'),
// so, with proper substitution, it's 'void**' (not just 'void*').