NAME

node-win32ole - win32ole bindings for node.js powered by v8 engine .

win32ole makes accessibility from node.js to Excel, Word, Access, Outlook, InternetExplorer, WSH ( ActiveXObject / COM ) and so on. It does not need a type library, although it will function better if OLE objects provide type information.

USAGE

Install with (nothing yet, this is still a private fork. Soon?)

It works as... (version 0.1.x)

try{
  var win32ole = require('win32ole');
  // documented at https://msdn.microsoft.com/en-us/library/microsoft.office.interop.excel._application_members.aspx
  // var xl = new ActiveXObject('Excel.Application'); // You may write it as:
  var xl = win32ole.client.Dispatch('Excel.Application');
  xl.Visible = true;
  var book = xl.Workbooks.Add();
  var sheet = book.Worksheets[1];
  try{
    sheet.Name = 'sheetnameA utf8';
    sheet.get_Cells(1, 2).Value = 'test utf8';
    var rg = sheet.get_Range(sheet.get_Cells(2, 2), sheet.get_Cells(4, 4));
    rg.RowHeight = 5.18;
    rg.ColumnWidth = 0.58;
    rg.Interior.ColorIndex = 6; // Yellow
    var result = book.SaveAs('testfileutf8.xls');
    console.log(result);
  }catch(e){
    console.log('(exception cached)\n' + e);
  }
  xl.ScreenUpdating = true;
  xl.Workbooks.Close();
  xl.Quit();
}catch(e){
  console.log('*** exception cached ***\n' + e);
}

Intro

Microsoft introduced COM in 1993 and pushed it as the primary means of having applications communicate with each other. While more recently Microsoft has been transitioning to use of .NET components which cannot be seen or used by COM applications, they are still providing COM interfaces for most of their products (and making it easy for developers to make C# COM-visible).

This library permits call to COM objects that support the IDispatch interface. This allows us to interrogate the object's properties and gives us a means to call into it designed for scripting languages. IDispatch is tightly built around the Visual Basic and the VBScript languages and share many of the assumptions that those languages make, which can be very different from Javascript.

The IDispatch interface permits objects to refuse to tell us what properties they have. In this case this library will still permit the objects to be used, but will fall back to less intelligent behavior.

Members and Types

Objects can contain methods and properties. Methods are similar to function calls and do something, while properties are similar to variables and can be read (and sometimes assigned). Both methods and properties can take parameters (although for properties they are called "indexes".

thisObject.action(); // method call with no arguments
thisObject.action(argA, argB, argC); // method call with three arguments

var here = thisObject.prop; // retrieving a property value
thisObject.prop = 3.4; // assigning a property value

// a propety with a single index parameter is treated as a property or array
var here = thisObject.indexedProp['abc'];
thisObject.indexedProp[123] = 3.4;
var here = thisObject.indexedProp.abc;
thisObject.indexedProp.abc = 3.4;

// a property with more than one index parameter needs to be treated as if it were a method
var here = thisObject.get_complexProp('abc', 123);
thisObject.put_complexProp('abc', 123, 3.4); // value to set is in the last parameter

Arguments: The simplest way to call a method is to call it with a number of arguments i.e. thisObject.action(argA, argB, argC). In this instance the three arguments will be translated to their COM equivalents and passed by-value to the action method of thisObject. (TODO) Visual Basic (and COM) permit the use of "optional parameters", if argB was an optional paramter not specified then you could call it with thisObject.action(argA, undefined, argC)

Default members: Visual Basic uses separate commands when GET'ting or PUT'ting a value from or to a property depending on whether or not an object is involved and COM does the same. Assignment or retrieval of non-objects from object properties might be forwarded to "default members" in the property. For instance, this page here describes the two VB commands as equivalent:

Debug.Print objRs.Fields.Item(0)  ' Both statements print 
Debug.Print objRs(0)              '  the Value of Item(0).

This is because in this context Fields is the default property of objRS and Item is the default property of Fields. This library tries to support the shortcut syntax described here by attempting to detect when you are attempting to use an object as if it were a non-object. If you try to do any arithmatic operations on a COM object or convert it to a string, it will retrieve its "shortcut" property. Our COM objects also have a special property _ that does this as well (which is the same as calling .valueOf().

Indirect Arguments (TODO): In addition to a list of parameters specified by-value, COM also supports by-reference, return-only, and named parameters. We can simulate this using the indcall_, indget_, and indput_ special prefixes. The parameters may include an array of specified parameters, and an object of named parameters. If any of the parameters have changed the new values will be replaced in the array or object:

//TODO thisObject.indcall_action([1, 2, 3], {argA:'valA', argB:456});
var args = [4, 'abc', 9.3];
//TODO thisObject.indcall_anotherAction(args); // values in args may change
//TODO var here = thisObject.indget_someProp(args);
//TODO thisObject.indput_someProp(args, {argC:4.6}, 3.4); // value to set is still in the last parameter

Translation: Most values that are returned from a COM object will be translated to an equivalent (or approximate) Javascript value. Most COM datatypes can be translated; if we cannot translate it we will place it within a V8Variant wrapper object so it can be passed as-is back to COM (i.e. as a parameter in a method call or a property value in an assignment).

Passing Javascript values into COM requires translating the values. The datatypes are translated as follows:

Garbage Collection

There are 3 ways to make force Garbage Collection for node.js / v8 .

• 1. use huge memory to run GC automatically ( causes abnormal termination )
• 2. win32ole.force_gc_extension(1);
• 3. win32ole.force_gc_internal(1);

see also examples/ole_args_test_client.js

Tutorial and Examples

• test/init_win32ole.test.js
• test/unicode.test.js
• examples/maze_creator.js
• examples/maze_solver.js
• examples/word_sample.js
• examples/access_mdb_sample.js
• examples/outlook_sample.js
• examples/ie_sample.js
• examples/typelibrary_sample.js
• examples/uncfinder_sample.js
• examples/activex_filesystemobject_sample.js
• examples/wmi_sample.js
• examples/wsh_sample.js
• examples/ole_args_test_client.js
• examples/ole_args_test_client_metamorphoses.js

Other built in functions

• win32ole.version(void) // returns version string
• win32ole.printACP(utf8string) // Utf8 to .ACP
• win32ole.print(utf8string) // ASCII
• win32ole.gettimeofday(struct timeval &tv, null) // now arg2 is not used
• win32ole.sleep(long milliseconds, bool withmessage=false, bool with\n=false)
• win32ole.force_gc_extension(long flag) // now flag is dummy
• win32ole.force_gc_internal(long flag, string) // now flag is dummy

TODO

• Need to define undefined as DISP_E_PARAMNOTFOUND (currently it's going in as VT_EMPTY)
• There may be more than one property defined on an object with the same name, depending on the specific parameters we are calling it with. Right now we are only using the first one with the (case-insensitive) name we are looking for.
• Put-property doesn't look for default properties when setting a non-object on an object parameter, depends on the object itself forwarding the request. Does this work?
• Indirect calls (indcall_ indget_ indput_) have not been implemented
• Asynchronous calls using Promise and worker threads (I consider this critical to implement before this can be used in a production environment)
• Drop the remaining functions that have nothing to do with calling into COM objects, and all stdout/stderr outputs when not using debugging tools.

API

See the API documentation in the wiki.

BUILDING

This project uses VC++ 2008 Express (or later) and Python 2.6 (or later) . (When using Python 2.5, it needs multiprocessing 2.5 back port .) It needs neither ATL nor MFC.

Bulding also requires node-gyp to be installed. You can do this with npm:

npm install -g node-gyp

To obtain and build the bindings:

git clone git://github.com/idobatter/node-win32ole.git
cd node-win32ole
node-gyp configure
node-gyp build

You can also use npm to download and install them:

npm install win32ole

TESTS

mocha is required to run unit tests.

npm install -g mocha
nmake /a test

CONTRIBUTORS

• idobatter

ACKNOWLEDGEMENTS

Inspired Win32OLE

LICENSE

node-win32ole is BSD licensed.