ControllerQuery method

Description

VWorks software uses the ControllerQuery method in conjunction with the IWorksController Query method to provide the means for two plugins to communicate with each other. (See “Query method” .) VWorks software acts as the intermediary between the source plugin and the destination plugin by receiving and forwarding the plugins’ queries and responses in the input and output parameters of these two methods.

Interplugin communication

The following diagram shows how interplugin communication is done using the IWorksController Query and IWorksDriver ControllerQuery methods.

Figure Interplugin communication using the Query and ControllerQuery methods

 

1	To send a query to Plugin B, Plugin A calls the IWorksController Query method and passes the query to VWorks software in the input parameter. Then the plugin waits for a reply.

2	VWorks software forwards the query to Plugin B by calling the IWorksDriver ControllerQuery method and passing the query in the input parameter.

3	Plugin B returns the query response to VWorks software in the output parameter of the IWorksDriver ControllerQuery method.

4	VWorks software forwards the query response to Plugin A in the output parameter of the IWorksController Query method.

Interplugin queries and query responses

Interplugin communication enables two plugins to work together as a team. For plugins to exchange information, they must be able to understand the queries they receive from each other and respond appropriately. The developers of the two plugins are responsible for defining and parsing the contents of the XML documents that are passed between the plugins (with VWorks software as the intermediary). The developers must define their own mutually agreed-upon values for the Parameter elements’ Name and Value attributes that are contained in the following XML blocks:

•	IWorksDriver ControllerQuery and ControllerResponse XML blocks, which are explained in this section

•	IWorksController Query and Response XML blocks, which are explained in “Query method”

Syntax

 

HRESULT ControllerQuery( [in] BSTR Query, [out,retval] BSTR *QueryResult );

Parameters

 

Query	[in] A ControllerQuery XML block that contains the query from the source plugin, which VWorks software provides in this parameter.
QueryResult	[out, retval] A ControllerResponse XML block that contains the query response from the destination plugin, which VWorks software receives in this parameter.

ControllerQuery method input

The plugin passes a ControllerQuery XML block into the Query parameter of the ControllerQuery method.

ControllerQuery XML block

The ControllerQuery XML block contains the Query element and all its children. This XML block includes the query from the source plugin.

XML structure

The value of the file attribute for the Velocity11 element is Query. See “Velocity11 element” .

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11> <Query Category='InterPlugin' ... > <Parameters> <Parameter /> </Parameters> </Query> </Velocity11>

Query element

The Query element contains one Parameters element and has the following attributes:

 

Name	Value
Category	The value InterPlugin. Required: Yes
Destination	The name of the plugin that is to receive the query. Required: Yes
Source	The name of the plugin that is sending the query. Required: Yes

Parameters element

The Parameters element contains one Parameter element.

Parameter element

The Parameter element has the following attributes:

 

Name	Value
Name	The developer-defined name for the interplugin query parameter. Required: Determined by the plugin developer
Style	See “Style attribute” . Required: No Default value: 0
Type	See “Type attribute” . Required: Yes
Value	The developer-defined interplugin query. Required: Determined by the plugin developer

Example of a ControllerQuery method query

The following sample code is a query from Plugin A for Plugin B that is received by VWorks software as a string in the Query parameter of the IWorksController Query method. (See “Query method” .) VWorks software then passes the query to Plugin B in the IWorksController Query parameter of the ControllerQuery method.

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11 file='Query' md5sum='77406e9e4b59a02f7f058223bc1a81ce' version='1.0' > <Query Category='InterPlugin' Destination='Plugin A'' Source='Plugin B' > <Parameters> <Parameter Name='InterPlugin Param' Style='0' Type='1' Value='Query test'/> </Parameters> </Query> </Velocity11>

ControllerQuery method output

The plugin passes a ControllerResponse XML block into the QueryResult parameter of the ControllerQuery method.

ControllerResponse XML block

The ControllerResponse XML block contains the Response element and all its children. This XML block includes the query response from the destination plugin.

XML structure

The value of the file attribute for the Velocity11 element is QueryResponse. See “Velocity11 element” .

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11> <Response Category='InterPlugin' ... > <Parameters> <Parameter /> </Parameters> </Response> </Velocity11>

Response element

The Response element contains one Parameters element and has the following attributes:

 

Name	Value
Category	The value InterPlugin. Required: Yes
Destination	The name of the plugin that is to receive the query response. Required: Yes
Source	The name of the plugin that is sending the query response. Required: Yes

Parameters element

The Parameters element contains one Parameter element.

Parameter element

The ControllerResponse XML block’s Parameter element must have the same attributes as the ControllerQuery XML block’s Parameter element. See “Parameter element” .

 

Name	Value
Name	The developer-defined name for the interplugin query response parameter. Required: Determined by the plugin developer
Style	See “Style attribute” . Required: No Default value: 0
Type	See “Type attribute” . Required: Yes
Value	The developer-defined interplugin query response. Required: Determined by the plugin developer

Example of a ControllerQuery method query response

The following sample code is the query response from Plugin B that is received by VWorks software as a string in the QueryResult parameter of the ControllerQuery method. VWorks software then passes the query response to Plugin A in the QueryResult parameter of the IWorksController Query method. See “Query method” .

 

<?xml version='1.0' encoding='ASCII' ?> <Velocity11 file='QueryResponse' md5sum='77406e9e4b59a02f7f058223bc1a81ce' →version='1.0' > <Response Category='InterPlugin' Destination='Plugin A'' Source='Plugin B' > <Parameters> <Parameter Name='InterPlugin Param' Style='0' Type='1' →Value='Receive test'/> </Parameters> </Response> </Velocity11>

Related information

 

For information about...	See...
IWorksController Query method	“Query method”