The LuaCOM Library
The LuaCOM Library |
|
LuaCOM is an add-on library to the Lua language that allows Lua programs to use and implement objects that follow Microsoft's Component Object Model (COM) specification and use the ActiveX technology for property access and method calls. LuaCOM is implemented as a C++ library and must be embedded in some application in order to be used. LuaCOM is provided with its source code and the makefiles required to build it.
LuaCOM has been designed and implemented by Vinicius Almendra and Renato Cerqueira, at TeCGraf, the Computer Graphics Technology Group of PUC-Rio (the Pontifical Catholic University of Rio de Janeiro in Brazil). TeCGraf is a laboratory of the Department of Computer Science.
LuaCOM is available under the same terms and conditions as the Lua language, that is, it can be used at no cost for both academic and commercial purposes. Send your comments, bug reports and anything else to luacom % tecgraf.puc-rio.br
Copyright © 1998-2004 TeCGraf, PUC-Rio. All rights reserved.
Version 1.1 (for Lua 4 and Lua 5)
Online documentation
Browse online documentation (multiple HTML files)
Browse online documentation (single HTML file)
Download
- Manual (PDF, gzipped HTML)
- Binary Distribution Package (including a DLL version)
- Source Distribution Package
Version 1.0 (for Lua 4)
Online documentation
Browse online documentation (multiple HTML files)
Browse online documentation (single HTML file)
Download
- Manual (PDF, gzipped HTML)
- Binary Distribution Package (including a DLL version)
- Source Distribution Package
Older version
These versions are supplied for test purposes only and for those who need features recently added.
Version 1.2 Release Candidate 1
Online documentation
Browse online documentation (multiple HTML files)
Browse online documentation (single HTML file)
Download
- Manual (PDF, gzipped HTML)
- Binary Distribution Package (including a DLL version)
- Source Distribution Package
New features
- New table, called luacomE, that holds all extended API methods, to differentiate from the standard API methods;
- New extended method DumpTypeLib: it receives a COM object or a type library and outputs an HTML file describing the contents of the type library. Other method, ViewTypeLib, also shows the created HTML file.
- New extended method ExportConstants: receives a type library or a COM object and exports to the global environment all the constants defined in the type library. Can also export them to a table.
- New extented method GetType: identifies the type of an object managed by LuaCOM.
- LuaCOM now can receive events from all COM objects, not just those created with CreateObject or GetObject.
- New method CreateLuaCOM: creates a LuaCOM object using an IUnknown pointer.
- New method GetCurrentDirectory
- New method ImportIUnknown: transforms an userdata pointer into a LuaCOM-recognizable IUnknown pointer.
- Values of constants of an object's type library can be accessed through the object, as they were fields in the table.
- Now LuaCOM object have a predefined fields called "IUnknown", that returns IUnknown pointer of the object (not the IUnknown pointer recognized by LuaCOM, but an userdata to be used by C/C++ code.
- It's now possible to use a CLSID where a ProgID is expected.
- Now methods with variable number of arguments can be called.
- Arrays of bytes are automatically converted to and from strings with embedded zeros.
- To ease debugging, errors inside event calls can now be logged, as they are only sent to the callee and do not generate any message.
- Now it's possible to implement a parametrized property, storing a function in the field instead of a value.
- Changed features
- Type library objects now just have a subset of the methods available through ITypeLib (no more coclass field, enum etc). The same for type info objects.
- Removed features
- No more "typeinfo" and "typelib" fields in LuaCOM objects: now its necessary to use GetTypeInfo LuaCOM method and then the type info method "GetTypeLib".
- Files created by DumpTypeInfo and ViewTypeLib are no more automatically removed.
- ViewTypeLib creates its files in the directory pointed by the variables TEMP or TMP (in this order). If they don't exist, creates the files in the current directory.
Version 1.2beta (for Lua 4 and Lua 5) October, 13th
- New features:
- Part of the LuaCOM API for Lua5 now is implemented in Lua; nevertheless, this is transparent to the library user.
- luacom.CreateObject now accepts an optional paramenter telling the context in which the object should be created; e.g. luacom.CreateObject("MediaPlayer.MediaPlayer.1", "local_server")
- Added support for loading enumeration constants of the object's type library in the global lua environment (Lua5 only); e.g.: excel.typelib:LoadConstants()
- Now it is possible to browse through the type information of an object using obj.typeinfo and obj.typelib. These fields hold tables containing the type information.
- Added support for default methods. To call the default method of a COM object, do the call using the object, e.g.: Sheets(1) is the same as Sheets:Item(1). This replaces the deprecated feature of indexing collections like tables.
- Fixed bug of parameter order when LuaCOM objects where called using named parameters.
- support for enumerations: now it's possible get an enumerator with luacom.GetEnumerator(object) and to use its methods (Next, Skip, Reset, Clone).
- LuaCOM API function luacom.pairs, which does the same as pairs function in Lua5 for collections. It must be called supplying the Collection object, not the enumerator.
- luacom.GetObject now works with Monikers, e.g. object = luacom.GetObject("winmgmts::"). This can work too with file paths. Useful for WMI and powerpoint (at least).
- Better support for WMI objects: some fields that weren't accessible now can be accessed as methods e.g. drive:Caption(). In fact, LuaCOM can now access fields that aren't described in the type library.
- New configuration table: luacom.config, with some useful fields: abort_on_errors (default: true, if false luacom won't abort on errors outside LuaCOM API calls), abort_on_API_errors (default: false, if true the API functions will generate lua_errors), last_error (holds the text of the last exception or errors, in the case it has been ignored by the preceding flags).
- New log facility
- LuaCOM can log errors and exceptions. Can be used together with luacom.config.abort_on_... to track errors without stopping the applications.
- New API functions: luacom.StartLog(filename) and luacom.EndLog. Can be used to programmaticaly start and stop the log facility.
- If LUACOM_LOGFILE is defined with a filename when compiling lib, it automaticaly starts logging when luacom_open is called. E.g.: LUACOM_LOGFILE="\"luacomapplog.txt\""
- If LuaCOM is compiled with VERBOSE defined, it creates a default log file luacom.log in the current directory (if LUACOM_LOGFILE is not defined); it also makes LuaCOM log creation and destruction of LuaCOM internal objects. Useful to track application bugs and object leaks.
- luacom.DumpTypeInfo now prints better type information for LuaCOM objects, including IID.
- When LuaCOM gets an IUnknown value, it tests it for an IDispatch interface or for an IEnumVARIANT interface. If so, it creates a LuaCOM object for it, instead of returning a IUnknown object.
- Removed features:
- Use of the indexing operator ([]) with collections
Download
This page is maintained by Vinicius Almendra.