Method ITcUnknown:TcQueryInterface

Query of an interface pointer with regard to an interface that is given by interface ID (IID).

Syntax

HRESULT TcQueryInterface(RITCID iid, PPVOID pipItf )

iid: (Type: RITCID) Interface IID.

pipItf: (PPVOID Type) pointer to interface pointer. Is set when the requested interface type is available from the corresponding instance.

Return value

If successful, S_OK ("0") or another positive value will be returned, cf. Return values. Extended messages refer in particular to the column HRESULT in ADS Return Codes.

If the demanded interface is not available, the method returns ADSERR_DEVICE_NOINTERFACE.

Description

Query reference to an implemented interface by the IID. It is recommended to use smart pointers to initialize and hold interface pointers.

Variant 1:

HRESULT GetTraceLevel(ITcUnkown* ip, TcTraceLevel& tl)
{
    HRESULT hr = S_OK;
    if (ip != NULL)
    {
        ITComObjectPtr spObj;
        hr = ip->TcQueryInterface(spObj.GetIID(), &spObj);
        if (SUCCEEDED(hr))
        {
            hr = spObj->TcGetObjPara(PID_TcTraceLevel, &tl, sizeof(tl));
        } 
        return hr;
    }
}

The interface id associated with the smart pointer can be used as parameter in TcQueryInterface. The operator “&” will return pointer to internal interface pointer member of the smart pointer. Variant 1 assumes that interface pointer is initialized if TcQueryInterface indicates success. If scope is left the destructor of the smart pointer spObj releases the reference.

Variant 2:


HRESULT GetTraceLevel(ITcUnkown* ip, TcTraceLevel& tl)
{
    HRESULT hr = S_OK;
    ITComObjectPtr spObj = ip;     
    if (spObj != NULL)
    {
        spObj->TcGetObjParam(PID_TcTraceLevel, &tl);
    } 
    else
    {
        hr = ADS_E_NOINTERFACE;
    }
    return hr;
}

When assigning interface pointer ip to smart pointer spObj method TcQueryInterface is implicitly called with IID_ITComObject on the instance ip refers to. This results in shorter code, however it loses the original return code of TcQueryInterface.