Share via

IUnknown (SAPI 5.4)

  • Article

Microsoft Speech API 5.4

COM Interface IUnknown

The IUnknown interface is a common interface supported by all COM objects and, therefore, by all speech objects. The IUnknown interface has the following member functions:

  • QueryInterface
  • AddRef
  • Release

An application uses IUnknown to obtain pointers to other interfaces supported by an object and to manage the interface pointers after obtaining them.

QueryInterface

  
    HRESULT QueryInterface(
   REFIID riid,			//Identifier of the requested interface
   LPVOID FAR   *ppvObj		//Address of output variable that receives the
                  		//interface pointer requested in iid
);

Retrieves the address of a specified interface on a particular object so that an application can query an object to determine what interfaces it supports.

Returns NOERROR, if successful, or one of these error values:

  • CO_E_OBJNOTCONNECTED
  • E_NOINTERFACE
  • E_OUTOFMEMORY
  • E_INVALIDARG
  • E_UNEXPECTED
  • REGDB_E_IIDNOTREG
Parameter Description
riid [in] Interface identifier of the interface to be retrieved.
ppvObj [out] Address of a variable that receives the address of the specified interface on the object. If the interface specified in riid is not supported by the object, the function returns E_NOINTERFACE. All errors set *ppvObj to NULL.

AddRef

  
    ULONG AddRef(void);
  • Increments a reference count for every new copy of an interface pointer to a specified interface on a particular object.
  • Returns the value of the reference count.

When an interface is fully released, the reference count is zero. This information should be used only for diagnostics and testing.

Release

  
    ULONG Release(void);
  • Decrements the reference count for the specified interface on a particular object.
  • Returns the value of the reference count.

When an interface is fully released, the reference count is zero. This information should be used only for diagnostics and testing.

If the object reference count goes to zero as a result of calling Release, the object is freed from memory.

If the AddRef member function has been called on this object's interface n times and this is the n+1th call to Release, the interface pointer frees itself. An object frees itself if the released pointer is the only pointer and if the object supports multiple interfaces through the QueryInterface member function.