with-query-interface

Macro

Summary

Used to simplify reference counting when querying a COM interface pointer.

Package

com

Signature

with-query-interface
disp
interface-ptr
form
* =>
values

disp
::= (
punknown
interface-name
&key
errorp
dispatch
)

Arguments

punknown

A variable which is bound to the queried interface pointer while the
form
s are evaluated.

interface-name

A symbol which names the COM interface. It is not evaluated.

errorp

A boolean indicating whether an error should be signaled if
interface-name
is not implemented by
interface-ptr
.

dispatch

A symbol which will be defined as a local macro, as if by
macrolet
as if by
with-com-interface
. The macro can be used by the
form
s to invoke the methods on
punknown
.

interface-ptr

A form which is evaluated to yield a COM interface pointer to query.

form

A form to be evaluated.

Values

values

The values returned by the last
form
.

Description

The macro
with-query-interface
calls
query-interface
to find an interface pointer for
interface-name
from the existing COM interface pointer
interface-ptr
. While evaluates the
form
s, the variable
punknown
is bound to the queried pointer and the pointer is released when control leaves the body (whether directly or due to a non-local exit).

If
errorp
is
nil
then
punknown
is bound to
nil
if the interface pointer cannot be found, otherwise an error of type
com-error
is signalled.

If
dispatch
is specified, then a local macro is created as if by
with-com-interface
to invoke COM interface methods on
punknown
.

Example

This example invokes the methods on an
i-bar
interface pointer queried from an existing interface pointer.