Declare COM interface

Syntax

interface[@|#] typename :baseinterface memberfunctions [{guid}]

 

Parameters

typename - interface name.

baseinterface - interface from which this interface is inherited.

memberfunctions - list of member functions.

guid - GUID of the interface. It is implicitly used by _create and in some other cases.

 

Options:

@

Declare dispinterface.

  • Functions will be called through IDispatch::Invoke.
  • Default: declare interface. Functions will be called directly.
#

All functions are Automation-compatible.

  • The return value in the function's C++ declaration actually has HRESULT type. In QM it is hidden.
  • If a function returns negative HRESULT value, QM generates run-time error.

 

Member function syntax: 

 

[[attributes]][membertype]membername[(parameters)]

 

attributes - one or more of the following literals:

f method (default).
p property-put function.
g property-get function.
r property-put byref function.
h

function is Automation-compatible.

  • Optional if used option # or attribute a or l. Cannot be used with dispinterfaces.
  • QM 2.2.0. If function's return type is specified, [h] is interpreted like [a]. In previous versions, if only [h] was specified, the function was interpreted as not returning a value.
a

function is Automation-compatible. It has a hidden parameter for return value (not specified in parameters).

  • Optional if used option #.
  • Cannot be used with dispinterfaces.
l

function is Automation-compatible. It has a hidden parameter for locale (not specified in parameters).

  • Cannot be used with dispinterface.

membertype - type of the return value.

membername - function's name.

parameters - parameters. Same as with dll. Parentheses (maybe empty) must be used, unless parameters are not defined.

 

See also: declarations, scope

 

Remarks

Declares a COM interface. A COM interface defines functions that can be used with a COM object. Read more.

Physically, a COM interface is an array of function addresses. An interface pointer variable holds the address of a COM object, which holds the address of that array. A COM object can have one or more different interfaces. All COM interfaces are inherited from (i.e. includes functions of) base interface IUnknown (directly or through another base interface). IUnknown has 3 member functions: QueryInterface, AddRef and Release. QueryInterface gets pointer to some other supported interface, others control object's life time. IDispatch also has 4 member functions that allow calling other functions by name. Interfaces IUnknown and IDispatch are defined by QM. For all interfaces, QM implicitly calls functions of IUnknown and IDispatch when needed. It is not error to call them explicitly, although they are not included in the popup list of member functions of other interfaces.

 

For interfaces, must be declared all member functions. A function is called by the position in the array, therefore functions must be declared in exact order (but you can change names). You can fully declare only functions that you will use. All other functions can be for example x. If a function is declared without parameters, then, when calling, you can pass any number of arguments, but argument types are not converted therefore must match expected. To explicitly specify that a function has 0 parameters, use empty parentheses.

 

For dispinterfaces, can be declared only some functions, in arbitrary order. A function is called by name therefore names cannot be changed.

 

Interfaces also can be declared in reference files and type libraries, which allows you to use them without declaring explicitly. Many declarations are in WINAPI and WINAPIV reference files. Usage example:

 

WINAPI.ITaskScheduler ts

 

QM 2.3.0: Can be defined optional parameters, like with dll.

 

QM 2.3.0. Allowed comments, like with type.

 

QM 2.4.1. You can declare parameters as reference instead of pointer. For example, VARIANT&p is the same as VARIANT*p.

 

Examples

interface IDispatch :IUnknown
	#GetTypeInfoCount(*pctinfo)
	#GetTypeInfo(iTInfo lcid ITypeInfo*pTInfo)
	#GetIDsOfNames(GUID*riid word**rgszNames cNames lcid rgDispId)
	#Invoke(dispIdMember GUID*riid lcid @wFlags DISPPARAMS*pDispParams VARIANT*pVarResult EXCEPINFO*pExcepInfo *puArgErr)
	{00020400-0000-0000-C000-000000000046}

interface IAccessible :IDispatch
	[ga]IAccessible'Parent()
	[ga]ChildCount()
	[ga]IAccessible'Child(VARIANT'varChild)
	[ga]BSTR'Name(VARIANT'varChild)
	[ga]BSTR'Value(VARIANT'varChild)
	[ga]BSTR'Description(VARIANT'varChild)
	[ga]VARIANT'Role(VARIANT'varChild)
	[ga]VARIANT'State(VARIANT'varChild)
	[ga]BSTR'Help(VARIANT'varChild)
	[ga]HelpTopic(BSTR*pszHelpFile VARIANT'varChild)
	[ga]BSTR'KeyboardShortcut(VARIANT'varChild)
	[ga]VARIANT'Focus()
	[ga]VARIANT'Selection()
	[ga]BSTR'DefaultAction(VARIANT'varChild)
	[h]Select(flagsSelect VARIANT'varChild)
	[h]Location(*pxLeft *pyTop *pcxWidth *pcyHeight VARIANT'varChild)
	[a]VARIANT'Navigate(navDir VARIANT'varStart)
	[a]VARIANT'HitTest(xLeft yTop)
	[h]DoDefaultAction(VARIANT'varChild)
	[ph]Name(VARIANT'varChild BSTR'szName)
	[ph]Value(VARIANT'varChild BSTR'szValue)
	{618736e0-3c3d-11cf-810c-00aa00389b71}

interface# ITask :IScheduledWorkItem
	SetApplicationName(@*pwszApplicationName)
	GetApplicationName(@**ppwszApplicationName)
	SetParameters(@*pwszParameters)
	GetParameters(@**ppwszParameters)
	SetWorkingDirectory(@*pwszWorkingDirectory)
	GetWorkingDirectory(@**ppwszWorkingDirectory)
	SetPriority(dwPriority)
	GetPriority(*pdwPriority)
	SetTaskFlags(dwFlags)
	GetTaskFlags(*pdwFlags)
	SetMaxRunTime(dwMaxRunTimeMS)
	GetMaxRunTime(*pdwMaxRunTimeMS)
	{148BD524-A2AB-11CE-B11F-00AA00530503}

interface@ IExample :IDispatch #Method(VARIANT'v) [g]BSTR'Property() [p]Property(BSTR'name)