Class: WIN32OLE

Relationships & Source Files
Namespace Children
Modules: VARIANT
Inherits:	Object
Defined in:	ext/win32ole/win32ole.c, ext/win32ole/win32ole.c

Overview

WIN32OLE objects represent OLE Automation object in Ruby.

By using WIN32OLE, you can access OLE server like VBScript.

Here is sample script.

require 'win32ole'

excel = WIN32OLE.new('Excel.Application')
excel.visible = true
workbook = excel.Workbooks.Add();
worksheet = workbook.Worksheets(1);
worksheet.Range("A1:D1").value = ["North","South","East","West"];
worksheet.Range("A2:B2").value = [5.2, 10];
worksheet.Range("C2").value = 8;
worksheet.Range("D2").value = 20;

range = worksheet.Range("A1:D2");
range.select
chart = workbook.Charts.Add;

workbook.saved = true;

excel.ActiveWorkbook.Close(0);
excel.Quit();

Unfortunately, Win32OLE doesn't support the argument passed by reference directly. Instead, Win32OLE provides ARGV or ::WIN32OLE_VARIANT object. If you want to get the result value of argument passed by reference, you can use ARGV or ::WIN32OLE_VARIANT.

oleobj.method(arg1, arg2, refargv3)
puts WIN32OLE::ARGV[2]   # the value of refargv3 after called oleobj.method

refargv3 = WIN32OLE_VARIANT.new(XXX,
            WIN32OLE::VARIANT::VT_BYREF|WIN32OLE::VARIANT::VT_XXX)
oleobj.method(arg1, arg2, refargv3)
p refargv3.value # the value of refargv3 after called oleobj.method.

Constant Summary

ARGV =
After invoking OLE methods with reference arguments, you can access the value of arguments by using ARGV.

If the method of OLE(COM) server written by C#.NET is following:
```
void calcsum(int a, int b, out int c) {
    c = a + b;
}
```
then, the Ruby OLE(COM) client script to retrieve the value of argument c after invoking calcsum method is following:
```
a = 10
b = 20
c = 0
comserver.calcsum(a, b, c)
p c # => 0
p WIN32OLE::ARGV # => [10, 20, 30]
```
You can use ::WIN32OLE_VARIANT object to retrieve the value of reference arguments instead of refering ARGV.
# File 'ext/win32ole/win32ole.c', line 3998
```
rb_ary_new()
```
CP_ACP =

ANSI code page. See .codepage and .codepage=.

# File 'ext/win32ole/win32ole.c', line 4003
```
0
```
CP_MACCP =

2

# File 'ext/win32ole/win32ole.c', line 4013
```
INT2FIX(CP_MACCP)
```
CP_OEMCP =

OEM code page. See .codepage and .codepage=.

# File 'ext/win32ole/win32ole.c', line 4008
```
1
```
CP_SYMBOL =

symbol code page. See .codepage and .codepage=.

# File 'ext/win32ole/win32ole.c', line 4024
```
42
```
CP_THREAD_ACP =

current thread ANSI code page. See .codepage and .codepage=.

# File 'ext/win32ole/win32ole.c', line 4019
```
3
```
CP_UTF7 =

UTF-7 code page. See .codepage and .codepage=.

# File 'ext/win32ole/win32ole.c', line 4029
```
65000
```
CP_UTF8 =

UTF-8 code page. See .codepage and .codepage=.

# File 'ext/win32ole/win32ole.c', line 4034
```
65001
```
LOCALE_SYSTEM_DEFAULT =

default locale for the operating system. See .locale and .locale=.

# File 'ext/win32ole/win32ole.c', line 4040
```
0x0800
```
LOCALE_USER_DEFAULT =

default locale for the user or process. See .locale and .locale=.

# File 'ext/win32ole/win32ole.c', line 4046
```
0x0400
```
VERSION =

Version string of WIN32OLE.

# File 'ext/win32ole/win32ole.c', line 3972
```
rb_str_new2(WIN32OLE_VERSION)
```

Class Attribute Summary

.codepage rw

Returns current codepage.
.codepage=(CP) rw

Sets current codepage.
.locale ⇒ locale id. rw

Returns current locale id (lcid).
.locale=(lcid) rw

Sets current locale id (lcid).

Class Method Summary

.connect(ole ) --> aWIN32OLE)

Returns running OLE Automation object or WIN32OLE object from moniker.
.const_load(ole, mod = WIN32OLE)

Defines the constants of OLE Automation server as mod's constants.
.create_guid

Creates GUID.
.new(server, [host]) ⇒ WIN32OLE constructor

Returns a new WIN32OLE object(OLE Automation object).
.ole_free(aWIN32OLE) --> number)

Invokes Release method of Dispatch interface of WIN32OLE object.
.ole_reference_count(aWIN32OLE) --> number)

Returns reference counter of Dispatch interface of WIN32OLE object.
.ole_show_help(obj [,helpcontext])

Displays helpfile.

Instance Method Summary

#[](a1,a2,...)

Returns the value of Collection specified by a1, a2,.…
#[]=(*args)

Sets the value to WIN32OLE object specified by a1, a2, …
#_getproperty(dispid, args, types)

Runs the early binding method to get property.
#_invoke(dispid, args, types)

Runs the early binding method.
#_setproperty(dispid, args, types)

Runs the early binding method to set property.
#each {|i| ... }

Iterates over each item of OLE collection which has IEnumVARIANT interface.
#invoke(method, [arg1,...]) ⇒ return value of method.

Runs OLE method.
#method_missing(id [,arg1, arg2, ...])

Calls #invoke method.
#ole_activex_initialize ⇒ Qnil

Initialize WIN32OLE object(ActiveX Control) by calling IPersistMemory::InitNew.
#ole_free

invokes Release method of Dispatch interface of WIN32OLE object.
#ole_func_methods

Returns the array of ::WIN32OLE_METHOD object .
#ole_get_methods

Returns the array of ::WIN32OLE_METHOD object .
#ole_method_help(method) (also: #ole_method_help)

Returns WIN32OLE_METHOD object corresponding with method specified by 1st argument.
#ole_method_help(method)

Alias for #ole_method.
#ole_methods

Returns the array of ::WIN32OLE_METHOD object.
#ole_obj_help

Alias for #ole_type.
#ole_put_methods

Returns the array of ::WIN32OLE_METHOD object .
#ole_query_interface(iid) ⇒ WIN32OLE

Returns WIN32OLE object for a specific dispatch or dual interface specified by iid.
#ole_respond_to?(method) ⇒ Boolean

Returns true when OLE object has OLE method, otherwise returns false.
#ole_type (also: #ole_obj_help)

Returns WIN32OLE_TYPE object.
#ole_typelib ⇒ WIN32OLE

Returns the ::WIN32OLE_TYPELIB object.
#setproperty('property', [arg1, arg2,...] val)

Sets property of OLE object.

Constructor Details

.new(server, [host]) ⇒ `WIN32OLE`

Returns a new WIN32OLE object(OLE Automation object). The first argument server specifies OLE Automation server. The first argument should be CLSID or PROGID. If second argument host specified, then returns OLE Automation object on host.

WIN32OLE.new('Excel.Application') # => Excel OLE Automation WIN32OLE object.
WIN32OLE.new('{00024500-0000-0000-C000-000000000046}') # => Excel OLE Automation WIN32OLE object.

Dynamic Method Handling

This class handles dynamic methods through the method_missing method

#method_missing(id [,arg1, arg2, ...])

Calls #invoke method.

Class Attribute Details

.codepage (rw)

Returns current codepage.

WIN32OLE.codepage # => WIN32OLE::CP_ACP

.codepage=(CP) (rw)

Sets current codepage. The .codepage is initialized according to Encoding.default_internal. If Encoding.default_internal is nil then .codepage is initialized according to Encoding.default_external.

WIN32OLE.codepage = WIN32OLE::CP_UTF8
WIN32OLE.codepage = 65001

.locale ⇒ locale `id`. (rw)

Returns current locale id (lcid). The default locale is LOCALE_SYSTEM_DEFAULT.

lcid = WIN32OLE.locale

.locale=(lcid) (rw)

Sets current locale id (lcid).

WIN32OLE.locale = 1033 # set locale English(U.S)
obj = WIN32OLE_VARIANT.new("$100,000", WIN32OLE::VARIANT::VT_CY)

Class Method Details

.connect(ole ) --> aWIN32OLE)

Returns running OLE Automation object or WIN32OLE object from moniker. 1st argument should be OLE program id or class id or moniker.

WIN32OLE.connect('Excel.Application') # => WIN32OLE object which represents running Excel.

.const_load(ole, mod = WIN32OLE)

Defines the constants of OLE Automation server as mod's constants. The first argument is WIN32OLE object or type library name. If 2nd argument is omitted, the default is WIN32OLE. The first letter of Ruby's constant variable name is upper case, so constant variable name of WIN32OLE object is capitalized. For example, the 'xlTop' constant of Excel is changed to 'XlTop' in WIN32OLE. If the first letter of constant variable is not [A-Z], then the constant is defined as CONSTANTS hash element.

module EXCEL_CONST
end
excel = WIN32OLE.new('Excel.Application')
WIN32OLE.const_load(excel, EXCEL_CONST)
puts EXCEL_CONST::XlTop # => -4160
puts EXCEL_CONST::CONSTANTS['_xlDialogChartSourceData'] # => 541

WIN32OLE.const_load(excel)
puts WIN32OLE::XlTop # => -4160

module MSO
end
WIN32OLE.const_load('Microsoft Office 9.0 Object Library', MSO)
puts MSO::MsoLineSingle # => 1

.create_guid

Creates GUID.

WIN32OLE.create_guid # => {1CB530F1-F6B1-404D-BCE6-1959BF91F4A8}

.ole_free(aWIN32OLE) --> number)

Invokes Release method of Dispatch interface of WIN32OLE object. You should not use this method because this method exists only for debugging WIN32OLE. The return value is reference counter of OLE object.

.ole_reference_count(aWIN32OLE) --> number)

Returns reference counter of Dispatch interface of WIN32OLE object. You should not use this method because this method exists only for debugging WIN32OLE.

.ole_show_help(obj [,helpcontext])

Displays helpfile. The 1st argument specifies ::WIN32OLE_TYPE object or ::WIN32OLE_METHOD object or helpfile.

excel = WIN32OLE.new('Excel.Application')
typeobj = excel.ole_type
WIN32OLE.ole_show_help(typeobj)

Instance Method Details

#[](a1,a2,...)

Returns the value of Collection specified by a1, a2,.…

dict = WIN32OLE.new('Scripting.Dictionary')
dict.add('ruby', 'Ruby')
puts dict['ruby'] # => 'Ruby' (same as `puts dict.item('ruby')')

Remark: You can not use this method to get the property.

excel = WIN32OLE.new('Excel.Application')
# puts excel['Visible']  This is error !!!
puts excel.Visible # You should to use this style to get the property.

#[]=(*args)

Sets the value to WIN32OLE object specified by a1, a2, …

dict = WIN32OLE.new('Scripting.Dictionary')
dict.add('ruby', 'RUBY')
dict['ruby'] = 'Ruby'
puts dict['ruby'] # => 'Ruby'

Remark: You can not use this method to set the property value.

excel = WIN32OLE.new('Excel.Application')
# excel['Visible'] = true # This is error !!!
excel.Visible = true # You should to use this style to set the property.

#_getproperty(dispid, args, types)

Runs the early binding method to get property. The 1st argument specifies dispatch ID, the 2nd argument specifies the array of arguments, the 3rd argument specifies the array of the type of arguments.

excel = WIN32OLE.new('Excel.Application')
puts excel._getproperty(558, [], []) # same effect as puts excel.visible

#_invoke(dispid, args, types)

Runs the early binding method. The 1st argument specifies dispatch ID, the 2nd argument specifies the array of arguments, the 3rd argument specifies the array of the type of arguments.

excel = WIN32OLE.new('Excel.Application')
excel._invoke(302, [], []) #  same effect as excel.Quit

#_setproperty(dispid, args, types)

Runs the early binding method to set property. The 1st argument specifies dispatch ID, the 2nd argument specifies the array of arguments, the 3rd argument specifies the array of the type of arguments.

excel = WIN32OLE.new('Excel.Application')
excel._setproperty(558, [true], [WIN32OLE::VARIANT::VT_BOOL]) # same effect as excel.visible = true

#each {|i| ... }

Iterates over each item of OLE collection which has IEnumVARIANT interface.

excel = WIN32OLE.new('Excel.Application')
book = excel.workbooks.add
sheets = book.worksheets(1)
cells = sheets.cells("A1:A5")
cells.each do |cell|
  cell.value = 10
end

#invoke(method, [arg1,...]) ⇒ `return` `value` `of` `method`.

Runs OLE method. The first argument specifies the method name of OLE Automation object. The others specify argument of the method. If you can not execute method directly, then use this method instead.

excel = WIN32OLE.new('Excel.Application')
excel.invoke('Quit')  # => same as excel.Quit

#ole_activex_initialize ⇒ `Qnil`

Initialize WIN32OLE object(ActiveX Control) by calling IPersistMemory::InitNew.

Before calling OLE method, some kind of the ActiveX controls created with MFC should be initialized by calling IPersistXXX::InitNew.

If and only if you received the exception “HRESULT error code: 0x8000ffff catastrophic failure”, try this method before invoking any ole_method.

obj = WIN32OLE.new("ProgID_or_GUID_of_ActiveX_Control")
obj.ole_activex_initialize
obj.method(...)

#ole_free

invokes Release method of Dispatch interface of WIN32OLE object. Usually, you do not need to call this method because Release method called automatically when WIN32OLE object garbaged.

#ole_func_methods

Returns the array of ::WIN32OLE_METHOD object . The element of the array is property (settable) of WIN32OLE object.

excel = WIN32OLE.new('Excel.Application')
properties = excel.ole_func_methods

#ole_get_methods

Returns the array of ::WIN32OLE_METHOD object . The element of the array is property (gettable) of WIN32OLE object.

excel = WIN32OLE.new('Excel.Application')
properties = excel.ole_get_methods

#ole_method_help(method) Also known as: #ole_method_help

Returns WIN32OLE_METHOD object corresponding with method specified by 1st argument.

excel = WIN32OLE.new('Excel.Application')
method = excel.ole_method_help('Quit')

#ole_method_help(method) #ole_method_help(method)

Alias for #ole_method.

#ole_methods

Returns the array of ::WIN32OLE_METHOD object. The element is OLE method of WIN32OLE object.

excel = WIN32OLE.new('Excel.Application')
methods = excel.ole_methods

#ole_type #ole_obj_help

Alias for #ole_type.

#ole_put_methods