3.1 LuaCOM API

LuaCOM

next up previous contents Next: 3.2 LuaCOM objects Up: 3. LuaCOM Elements Previous: 3. LuaCOM Elements   Contents

3.1 LuaCOM API

The LuaCOM API is divided in two parts: the standard API and the extended API. The standard API comprises the core functionality needed to use COM objects. The extended API includes more advanced features to Lua API that simplify the development of applications using LuaCOM. This distinction has been made due to the possible unbounded growth of features, which could end up cluttering the library and making it bigger and bigger and more and more difficult to use. For now, the extended API is entirely implemented in Lua 5 and can be easily removed without trouble.

The standard API is further divided in two classes: the Lua API and the C/C++ API. The C/C++ API is used primarily for initialization of the library and for low-level construction of LuaCOM objects. It is declared in the header file luacomh. The Lua API permits Lua programs to access all the functionality of LuaCOM. It is implemented as a set of functions inside a global table named luacom; hereafter these functions will be called LuaCOM methods. This table is created and populated when the C/C++ API function luacom_open is called. Notice that the extended API lies in a different table, called luacomE. Below there is summary of the LuaCOM API. Detailed information on these methods is available in chapter 6.

Standard Lua API
Method
Description
CreateObject Creates a LuaCOM object.
NewObject Creates a LuaCOM object implemented in Lua.
GetObject Creates a LuaCOM object associated with an instance of an already running COM object.
ExposeObject Exposes a LuaCOM object, so that other applications can get a reference to it.
RevokeObject Undoes the operation of ExposeObject.
RegisterObject Fills in the registry entries necessary for exposing a COM object.
UnRegisterObject Removes the registry entries necessary for exposing a COM object.
Connect Creates a connection point between an object and a Lua table.
ImplInterface Implements an IDispatch interface using a Lua table.
ImplInterfaceFromTypelib Implements an IDispatch interface described in a Type Library using a Lua table.
addConnection Connects two LuaCOM objects.
releaseConnection Disconnects a LuaCOM object from its connection point.
isMember Checks whether a name correspond to a method or a property of an LuaCOM object.
ProgIDfromCLSID Gets the ProgID associated with a CLSID.
CLSIDfromProgID Gets the CLSID associated with a ProgID.
GetIUnknown Returns an IUnknown interface to a LuaCOM object as a full userdata.
DumpTypeInfo Dumps to the console the type information of the specified LuaCOM object. This method should be used only for debugging purposes.

Standard Lua API (continued)
Method
Description
GetCurrentDirectory Returns the current directory.
CreateLuaCOM Transforms an IUnknown full userdata into a LuaCOM object.
ImportIUnknown Converts a light userdata (pointer) to an IUnknown full userdata.
DetectAutomation Used to implement COM servers. Looks in the command-line for /Register or /UnRegister /Automation (not case-sensitive) and calls user-defined functions to register, unregister, or expose objects, entering a message loop in the latter case. If there is no command-line then assume it is being run in-process, calls the expose function and returns.

Extended Lua API
Method
Description
CreateLocalObject Creates a LuaCOM object as an out-of-process server.
CreateInprocObject Creates a LuaCOM object as an in-process server.
ExportConstants Exports all the constants of a type library (standalone or bound to a LuaCOM object) to the global environment (or optionally to a table).
DumpTypeLib Creates an HTML file describing a type library.
GetType Returns a string describing the type of object, in the case its an object belonging to the LuaCOM library.
ViewTypeLib Runs DumpTypeLib and shows the created file using Internet Explorer©.
pairs Does the same as pairs for COM Enumerators.
FillTypeLib Creates a table describing a type library.
FillTypeInfo Creates a table describing a type info.

Standard C/C++ API
Function
Description
luacom_open Initializes the LuaCOM library in a Lua state. It must be called before any use of LuaCOM features.
luacom_close LuaCOM's termination function.
luacom_detectAutomation This function is a helper to create COM servers. It looks in the command line for the switches ``/Automation'' and ``/Register'' and call some user-defined Lua functions accordingly.
luacom_IDispatch2LuaCOM Takes an IDispatch interface and creates a LuaCOM object to expose it, pushing the object on the Lua stack.


next up previous contents
Next: 3.2 LuaCOM objects Up: 3. LuaCOM Elements Previous: 3. LuaCOM Elements   Contents
Fabio Mascarenhas de Queiroz 2005-01-07