This topic describes the COM interface to FlashBASIC. The objective is to allow a FlashBASIC module to act as an Automation Controller. This module can be a main, a trigger, or a rule module.
Methods, property get, and property set are called only by names. These are supported in dispInterface.
For more information on these interfaces, see FlashBASIC Automation Application Interfaces.
A FlashBASIC Module Example:
include dm,bp,includes nt_util.inc cFunction fsicli.builtin include dm,bp,includes flashauto.inc
* Initialize the COM library. hAutoCTRL = 0 code = %CoInitialize( &hAutoCTRL ) if code = 0 then stop
* Create a COM object and get the IUnknown interface pointer. pUnk = 0 code = %CoCreateObject( hAutoCTRL, "Excel.Application.15", &pUnk ) if code = 0 then goto error
* Call to Query for the IDispatch interface. hObjExApplication = 0 code = %CoQueryInterface( pUnk, IID_IDispatch, &hObjExApplication ) if code = 0 then goto error
* Call a property Put to make the Excel object visible. Note: b is the format string for the Boolean data type. true = 1 code = %CoPropertyPut( hObjExApplication, "Visible", "b", TRUE ) if code = 0 then goto error
* Call a property get dispatch to get the WorkBook collection. Note: 0 is a NULL format string, which means no argument to the invoked method. hObjWorkBooks = 0 code = %CoGetDispatch( hObjExApplication, "WorkBooks", &hObjWorkBooks, 0 ) if code = 0 then goto error
* Call a property get dispatch to add a WorkBook into this WorkBooks collection. Note : Add is the method name. 0 is a NULL format string, which means no arguments to the invoked method. hObjWorkBook = 0 code = %CoGetDispatch( hObjWorkBooks, "Add", &hObjWorkBook, 0 ) if code = 0 then goto error
* Call a property get dispatch to get the Worksheet. hObjActiveSheet = 0 code = %CoGetDispatch( hObjExApplication, "ActiveSheet", &hObjActiveSheet, 0 ) if code = 0 then goto error
* Call a property get dispatch to get a Range object in the worksheet. Note: s is the format string for the string data type. A1 is cell A1. hObjRange = 0 code = %CoGetDispatch( hObjActiveSheet, "Range", &hObjRange, "s", "A1" ) if code = 0 then goto error
* Call a property Put to put a string into A1. Note: Value is the property name. s is the format string for the string data type. Company A is the value to put in cell A1. code = %CoPropertyPut( hObjRange, "Value", "s", "Company A") if code = 0 then goto error
* Call a method to save this Excel Workbook as d:\autoctrl.xls. Note: 0 means not returning a dispatch object. code = %CoInvoke( hObjWorkBook, "SaveAs", DISPATCH_METHOD, 0, "s", "c:\temp\autoctrl.xlsx") if code = 0 then goto error
* Call a method to quit Excel. Note: The first 0 means not returning a dispatch object. The second 0 specifies that there is no argument to the invoked method. code = %CoInvoke( hObjExApplication, "Quit", DISPATCH_METHOD, 0, 0 ) if code = 0 then goto error goto done
error: ExceptStr = "" MsgLen = %CoGetException( hAutoCTRL, ExceptStr ) %CoUninitialize( hAutoCTRL ) stop
done: %CoUnInitialize( hAutoCTRL ) |
The object is an opaque handle to the IDispatch interface of the object.
NOTE |
As an enhancement, a precompiler could read the type library associated to an object and understand the various methods, properties, and arguments to generate the appropriate % function calls. |
The automation object handle is returned to FlashBASIC as an integer. This handle is a pointer to an internal FlashBASIC Automation object that contains the IDispatch interface pointer, exception information, and name cache.
For performance reasons, the FlashBASIC Automation object contains a cache of the methods to associate the name and type to a DISPID.
All FlashBASIC arguments are coerced into VARIANTS.
Flash Automation Reserved Arguments
TRUE and FALSE are reserved for the CoPropertyPut, CoPropertyGet, CoGetDispatch, and CoInvoke. For example:
* Call a property Put to make the Excel object visible. code = %CoPropertyPut( hObjExApplication, “Visible”, “b”, TRUE ) if code = 0 then goto error |
The FlashBASIC Automation object contains an EXCEPINFO structure that can be queried from FlashBASIC by %CoGetException, which returns a string containing the error description.