File: C:/Ruby27-x64/share/doc/ruby/html/WIN32OLE.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class WIN32OLE - RDoc Documentation</title>
<script type="text/javascript">
var rdoc_rel_prefix = "./";
var index_rel_prefix = "./";
</script>
<script src="./js/navigation.js" defer></script>
<script src="./js/search.js" defer></script>
<script src="./js/search_index.js" defer></script>
<script src="./js/searcher.js" defer></script>
<script src="./js/darkfish.js" defer></script>
<link href="./css/fonts.css" rel="stylesheet">
<link href="./css/rdoc.css" rel="stylesheet">
<body id="top" role="document" class="class">
<nav role="navigation">
<div id="project-navigation">
<div id="home-section" role="region" title="Quick navigation" class="nav-section">
<h2>
<a href="./index.html" rel="home">Home</a>
</h2>
<div id="table-of-contents-navigation">
<a href="./table_of_contents.html#pages">Pages</a>
<a href="./table_of_contents.html#classes">Classes</a>
<a href="./table_of_contents.html#methods">Methods</a>
</div>
</div>
<div id="search-section" role="search" class="project-section initially-hidden">
<form action="#" method="get" accept-charset="utf-8">
<div id="search-field-wrapper">
<input id="search-field" role="combobox" aria-label="Search"
aria-autocomplete="list" aria-controls="search-results"
type="text" name="search" placeholder="Search" spellcheck="false"
title="Type to search, Up and Down to navigate, Enter to load">
</div>
<ul id="search-results" aria-label="Search Results"
aria-busy="false" aria-expanded="false"
aria-atomic="false" class="initially-hidden"></ul>
</form>
</div>
</div>
<div id="class-metadata">
<div id="parent-class-section" class="nav-section">
<h3>Parent</h3>
<p class="link"><a href="Object.html">Object</a>
</div>
<!-- Method Quickref -->
<div id="method-list-section" class="nav-section">
<h3>Methods</h3>
<ul class="link-list" role="directory">
<li ><a href="#method-c-codepage">::codepage</a>
<li ><a href="#method-c-codepage-3D">::codepage=</a>
<li ><a href="#method-c-connect">::connect</a>
<li ><a href="#method-c-const_load">::const_load</a>
<li ><a href="#method-c-create_guid">::create_guid</a>
<li ><a href="#method-c-locale">::locale</a>
<li ><a href="#method-c-locale-3D">::locale=</a>
<li ><a href="#method-c-new">::new</a>
<li ><a href="#method-c-ole_free">::ole_free</a>
<li ><a href="#method-c-ole_reference_count">::ole_reference_count</a>
<li ><a href="#method-c-ole_show_help">::ole_show_help</a>
<li ><a href="#method-i-5B-5D">#[]</a>
<li ><a href="#method-i-5B-5D-3D">#[]=</a>
<li ><a href="#method-i-_getproperty">#_getproperty</a>
<li ><a href="#method-i-_invoke">#_invoke</a>
<li ><a href="#method-i-_setproperty">#_setproperty</a>
<li ><a href="#method-i-each">#each</a>
<li ><a href="#method-i-invoke">#invoke</a>
<li ><a href="#method-i-method_missing">#method_missing</a>
<li class="calls-super" ><a href="#method-i-methods">#methods</a>
<li ><a href="#method-i-ole_activex_initialize">#ole_activex_initialize</a>
<li ><a href="#method-i-ole_free">#ole_free</a>
<li ><a href="#method-i-ole_func_methods">#ole_func_methods</a>
<li ><a href="#method-i-ole_get_methods">#ole_get_methods</a>
<li ><a href="#method-i-ole_method">#ole_method</a>
<li ><a href="#method-i-ole_method_help">#ole_method_help</a>
<li ><a href="#method-i-ole_methods">#ole_methods</a>
<li ><a href="#method-i-ole_methods_safely">#ole_methods_safely</a>
<li ><a href="#method-i-ole_obj_help">#ole_obj_help</a>
<li ><a href="#method-i-ole_put_methods">#ole_put_methods</a>
<li ><a href="#method-i-ole_query_interface">#ole_query_interface</a>
<li ><a href="#method-i-ole_respond_to-3F">#ole_respond_to?</a>
<li ><a href="#method-i-ole_type">#ole_type</a>
<li ><a href="#method-i-ole_typelib">#ole_typelib</a>
<li ><a href="#method-i-setproperty">#setproperty</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-WIN32OLE">
<h1 id="class-WIN32OLE" class="class">
class WIN32OLE
</h1>
<section class="description">
<p><a href="WIN32OLE.html"><code>WIN32OLE</code></a></p>
<p><code>WIN32OLE</code> objects represent OLE Automation object in Ruby.</p>
<p>By using <a href="WIN32OLE.html"><code>WIN32OLE</code></a>, you can access OLE server like VBScript.</p>
<p>Here is sample script.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'win32ole'</span>
<span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">excel</span>.<span class="ruby-identifier">visible</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">workbook</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-constant">Workbooks</span>.<span class="ruby-constant">Add</span>();
<span class="ruby-identifier">worksheet</span> = <span class="ruby-identifier">workbook</span>.<span class="ruby-constant">Worksheets</span>(<span class="ruby-value">1</span>);
<span class="ruby-identifier">worksheet</span>.<span class="ruby-constant">Range</span>(<span class="ruby-string">"A1:D1"</span>).<span class="ruby-identifier">value</span> = [<span class="ruby-string">"North"</span>,<span class="ruby-string">"South"</span>,<span class="ruby-string">"East"</span>,<span class="ruby-string">"West"</span>];
<span class="ruby-identifier">worksheet</span>.<span class="ruby-constant">Range</span>(<span class="ruby-string">"A2:B2"</span>).<span class="ruby-identifier">value</span> = [<span class="ruby-value">5.2</span>, <span class="ruby-value">10</span>];
<span class="ruby-identifier">worksheet</span>.<span class="ruby-constant">Range</span>(<span class="ruby-string">"C2"</span>).<span class="ruby-identifier">value</span> = <span class="ruby-value">8</span>;
<span class="ruby-identifier">worksheet</span>.<span class="ruby-constant">Range</span>(<span class="ruby-string">"D2"</span>).<span class="ruby-identifier">value</span> = <span class="ruby-value">20</span>;
<span class="ruby-identifier">range</span> = <span class="ruby-identifier">worksheet</span>.<span class="ruby-constant">Range</span>(<span class="ruby-string">"A1:D2"</span>);
<span class="ruby-identifier">range</span>.<span class="ruby-identifier">select</span>
<span class="ruby-identifier">chart</span> = <span class="ruby-identifier">workbook</span>.<span class="ruby-constant">Charts</span>.<span class="ruby-constant">Add</span>;
<span class="ruby-identifier">workbook</span>.<span class="ruby-identifier">saved</span> = <span class="ruby-keyword">true</span>;
<span class="ruby-identifier">excel</span>.<span class="ruby-constant">ActiveWorkbook</span>.<span class="ruby-constant">Close</span>(<span class="ruby-value">0</span>);
<span class="ruby-identifier">excel</span>.<span class="ruby-constant">Quit</span>();
</pre>
<p>Unfortunately, Win32OLE doesn't support the argument passed by reference directly. Instead, Win32OLE provides <a href="WIN32OLE.html#ARGV"><code>WIN32OLE::ARGV</code></a> or <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> object. If you want to get the result value of argument passed by reference, you can use <a href="WIN32OLE.html#ARGV"><code>WIN32OLE::ARGV</code></a> or <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">oleobj</span>.<span class="ruby-identifier">method</span>(<span class="ruby-identifier">arg1</span>, <span class="ruby-identifier">arg2</span>, <span class="ruby-identifier">refargv3</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-constant">WIN32OLE</span><span class="ruby-operator">::</span><span class="ruby-constant">ARGV</span>[<span class="ruby-value">2</span>] <span class="ruby-comment"># the value of refargv3 after called oleobj.method</span>
</pre>
<p>or</p>
<pre class="ruby"><span class="ruby-identifier">refargv3</span> = <span class="ruby-constant">WIN32OLE_VARIANT</span>.<span class="ruby-identifier">new</span>(<span class="ruby-constant">XXX</span>,
<span class="ruby-constant">WIN32OLE</span><span class="ruby-operator">::</span><span class="ruby-constant">VARIANT</span><span class="ruby-operator">::</span><span class="ruby-constant">VT_BYREF</span><span class="ruby-operator">|</span><span class="ruby-constant">WIN32OLE</span><span class="ruby-operator">::</span><span class="ruby-constant">VARIANT</span><span class="ruby-operator">::</span><span class="ruby-constant">VT_XXX</span>)
<span class="ruby-identifier">oleobj</span>.<span class="ruby-identifier">method</span>(<span class="ruby-identifier">arg1</span>, <span class="ruby-identifier">arg2</span>, <span class="ruby-identifier">refargv3</span>)
<span class="ruby-identifier">p</span> <span class="ruby-identifier">refargv3</span>.<span class="ruby-identifier">value</span> <span class="ruby-comment"># the value of refargv3 after called oleobj.method.</span>
</pre>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section class="constants-list">
<header>
<h3>Constants</h3>
</header>
<dl>
<dt id="ARGV">ARGV
<dd><p>After invoking OLE methods with reference arguments, you can access the value of arguments by using <a href="WIN32OLE.html#ARGV"><code>ARGV</code></a>.</p>
<p>If the method of OLE(COM) server written by C#.NET is following:</p>
<pre>void calcsum(int a, int b, out int c) {
c = a + b;
}</pre>
<p>then, the Ruby OLE(COM) client script to retrieve the value of argument c after invoking calcsum method is following:</p>
<pre class="ruby"><span class="ruby-identifier">a</span> = <span class="ruby-value">10</span>
<span class="ruby-identifier">b</span> = <span class="ruby-value">20</span>
<span class="ruby-identifier">c</span> = <span class="ruby-value">0</span>
<span class="ruby-identifier">comserver</span>.<span class="ruby-identifier">calcsum</span>(<span class="ruby-identifier">a</span>, <span class="ruby-identifier">b</span>, <span class="ruby-identifier">c</span>)
<span class="ruby-identifier">p</span> <span class="ruby-identifier">c</span> <span class="ruby-comment"># => 0</span>
<span class="ruby-identifier">p</span> <span class="ruby-constant">WIN32OLE</span><span class="ruby-operator">::</span><span class="ruby-constant">ARGV</span> <span class="ruby-comment"># => [10, 20, 30]</span>
</pre>
<p>You can use <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> object to retrieve the value of reference arguments instead of referring <a href="WIN32OLE.html#ARGV"><code>WIN32OLE::ARGV</code></a>.</p>
<dt id="CP_ACP">CP_ACP
<dd><p>ANSI code page. See <a href="WIN32OLE.html#method-c-codepage"><code>WIN32OLE.codepage</code></a> and <a href="WIN32OLE.html#method-c-codepage-3D"><code>WIN32OLE.codepage=</code></a>.</p>
<dt id="CP_MACCP">CP_MACCP
<dd><p>2</p>
<dt id="CP_OEMCP">CP_OEMCP
<dd><p>OEM code page. See <a href="WIN32OLE.html#method-c-codepage"><code>WIN32OLE.codepage</code></a> and <a href="WIN32OLE.html#method-c-codepage-3D"><code>WIN32OLE.codepage=</code></a>.</p>
<dt id="CP_SYMBOL">CP_SYMBOL
<dd><p>symbol code page. See <a href="WIN32OLE.html#method-c-codepage"><code>WIN32OLE.codepage</code></a> and <a href="WIN32OLE.html#method-c-codepage-3D"><code>WIN32OLE.codepage=</code></a>.</p>
<dt id="CP_THREAD_ACP">CP_THREAD_ACP
<dd><p>current thread ANSI code page. See <a href="WIN32OLE.html#method-c-codepage"><code>WIN32OLE.codepage</code></a> and <a href="WIN32OLE.html#method-c-codepage-3D"><code>WIN32OLE.codepage=</code></a>.</p>
<dt id="CP_UTF7">CP_UTF7
<dd><p>UTF-7 code page. See <a href="WIN32OLE.html#method-c-codepage"><code>WIN32OLE.codepage</code></a> and <a href="WIN32OLE.html#method-c-codepage-3D"><code>WIN32OLE.codepage=</code></a>.</p>
<dt id="CP_UTF8">CP_UTF8
<dd><p>UTF-8 code page. See <a href="WIN32OLE.html#method-c-codepage"><code>WIN32OLE.codepage</code></a> and <a href="WIN32OLE.html#method-c-codepage-3D"><code>WIN32OLE.codepage=</code></a>.</p>
<dt id="LOCALE_SYSTEM_DEFAULT">LOCALE_SYSTEM_DEFAULT
<dd><p>default locale for the operating system. See <a href="WIN32OLE.html#method-c-locale"><code>WIN32OLE.locale</code></a> and <a href="WIN32OLE.html#method-c-locale-3D"><code>WIN32OLE.locale=</code></a>.</p>
<dt id="LOCALE_USER_DEFAULT">LOCALE_USER_DEFAULT
<dd><p>default locale for the user or process. See <a href="WIN32OLE.html#method-c-locale"><code>WIN32OLE.locale</code></a> and <a href="WIN32OLE.html#method-c-locale-3D"><code>WIN32OLE.locale=</code></a>.</p>
<dt id="VERSION">VERSION
<dd><p>Version string of <a href="WIN32OLE.html"><code>WIN32OLE</code></a>.</p>
</dl>
</section>
<section id="public-class-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Class Methods</h3>
</header>
<div id="method-c-codepage" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
codepage
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns current codepage.</p>
<pre class="ruby"><span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">codepage</span> <span class="ruby-comment"># => WIN32OLE::CP_ACP</span>
</pre>
<div class="method-source-code" id="codepage-source">
<pre>static VALUE
fole_s_get_code_page(VALUE self)
{
return RB_INT2FIX(cWIN32OLE_cp);
}</pre>
</div>
</div>
</div>
<div id="method-c-codepage-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
codepage = CP
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sets current codepage. The <a href="WIN32OLE.html#method-c-codepage"><code>WIN32OLE.codepage</code></a> is initialized according to <a href="Encoding.html#method-c-default_internal"><code>Encoding.default_internal</code></a>. If <a href="Encoding.html#method-c-default_internal"><code>Encoding.default_internal</code></a> is nil then <a href="WIN32OLE.html#method-c-codepage"><code>WIN32OLE.codepage</code></a> is initialized according to <a href="Encoding.html#method-c-default_external"><code>Encoding.default_external</code></a>.</p>
<pre class="ruby"><span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">codepage</span> = <span class="ruby-constant">WIN32OLE</span><span class="ruby-operator">::</span><span class="ruby-constant">CP_UTF8</span>
<span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">codepage</span> = <span class="ruby-value">65001</span>
</pre>
<div class="method-source-code" id="codepage-3D-source">
<pre>static VALUE
fole_s_set_code_page(VALUE self, VALUE vcp)
{
UINT cp = RB_FIX2INT(vcp);
set_ole_codepage(cp);
/*
* Should this method return old codepage?
*/
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-c-connect" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
connect( ole ) -→ aWIN32OLE
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns running OLE Automation object or <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object from moniker. 1st argument should be OLE program id or class id or moniker.</p>
<pre class="ruby"><span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">connect</span>(<span class="ruby-string">'Excel.Application'</span>) <span class="ruby-comment"># => WIN32OLE object which represents running Excel.</span>
</pre>
<div class="method-source-code" id="connect-source">
<pre>static VALUE
fole_s_connect(int argc, VALUE *argv, VALUE self)
{
VALUE svr_name;
VALUE others;
HRESULT hr;
CLSID clsid;
OLECHAR *pBuf;
IDispatch *pDispatch;
void *p;
IUnknown *pUnknown;
/* initialize to use OLE */
ole_initialize();
rb_scan_args(argc, argv, "1*", &svr_name, &others);
StringValue(svr_name);
/* get CLSID from OLE server name */
pBuf = ole_vstr2wc(svr_name);
hr = CLSIDFromProgID(pBuf, &clsid);
if(FAILED(hr)) {
hr = CLSIDFromString(pBuf, &clsid);
}
SysFreeString(pBuf);
if(FAILED(hr)) {
return ole_bind_obj(svr_name, argc, argv, self);
}
hr = GetActiveObject(&clsid, 0, &pUnknown);
if (FAILED(hr)) {
ole_raise(hr, eWIN32OLERuntimeError,
"OLE server `%s' not running", StringValuePtr(svr_name));
}
hr = pUnknown->lpVtbl->QueryInterface(pUnknown, &IID_IDispatch, &p);
pDispatch = p;
if(FAILED(hr)) {
OLE_RELEASE(pUnknown);
ole_raise(hr, eWIN32OLERuntimeError,
"failed to create WIN32OLE server `%s'",
StringValuePtr(svr_name));
}
OLE_RELEASE(pUnknown);
return create_win32ole_object(self, pDispatch, argc, argv);
}</pre>
</div>
</div>
</div>
<div id="method-c-const_load" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
const_load( ole, mod = WIN32OLE)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Defines the constants of OLE Automation server as mod's constants. The first argument is <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object or type library name. If 2nd argument is omitted, the default is <a href="WIN32OLE.html"><code>WIN32OLE</code></a>. The first letter of Ruby's constant variable name is upper case, so constant variable name of <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object is capitalized. For example, the 'xlTop' constant of Excel is changed to 'XlTop' in <a href="WIN32OLE.html"><code>WIN32OLE</code></a>. If the first letter of constant variable is not [A-Z], then the constant is defined as CONSTANTS hash element.</p>
<pre class="ruby"><span class="ruby-keyword">module</span> <span class="ruby-constant">EXCEL_CONST</span>
<span class="ruby-keyword">end</span>
<span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">const_load</span>(<span class="ruby-identifier">excel</span>, <span class="ruby-constant">EXCEL_CONST</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-constant">EXCEL_CONST</span><span class="ruby-operator">::</span><span class="ruby-constant">XlTop</span> <span class="ruby-comment"># => -4160</span>
<span class="ruby-identifier">puts</span> <span class="ruby-constant">EXCEL_CONST</span><span class="ruby-operator">::</span><span class="ruby-constant">CONSTANTS</span>[<span class="ruby-string">'_xlDialogChartSourceData'</span>] <span class="ruby-comment"># => 541</span>
<span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">const_load</span>(<span class="ruby-identifier">excel</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-constant">WIN32OLE</span><span class="ruby-operator">::</span><span class="ruby-constant">XlTop</span> <span class="ruby-comment"># => -4160</span>
<span class="ruby-keyword">module</span> <span class="ruby-constant">MSO</span>
<span class="ruby-keyword">end</span>
<span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">const_load</span>(<span class="ruby-string">'Microsoft Office 9.0 Object Library'</span>, <span class="ruby-constant">MSO</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-constant">MSO</span><span class="ruby-operator">::</span><span class="ruby-constant">MsoLineSingle</span> <span class="ruby-comment"># => 1</span>
</pre>
<div class="method-source-code" id="const_load-source">
<pre>static VALUE
fole_s_const_load(int argc, VALUE *argv, VALUE self)
{
VALUE ole;
VALUE klass;
struct oledata *pole = NULL;
ITypeInfo *pTypeInfo;
ITypeLib *pTypeLib;
unsigned int index;
HRESULT hr;
OLECHAR *pBuf;
VALUE file;
LCID lcid = cWIN32OLE_lcid;
rb_scan_args(argc, argv, "11", &ole, &klass);
if (!RB_TYPE_P(klass, T_CLASS) &&
!RB_TYPE_P(klass, T_MODULE) &&
!RB_TYPE_P(klass, T_NIL)) {
rb_raise(rb_eTypeError, "2nd parameter must be Class or Module");
}
if (rb_obj_is_kind_of(ole, cWIN32OLE)) {
pole = oledata_get_struct(ole);
hr = pole->pDispatch->lpVtbl->GetTypeInfo(pole->pDispatch,
0, lcid, &pTypeInfo);
if(FAILED(hr)) {
ole_raise(hr, eWIN32OLEQueryInterfaceError, "failed to GetTypeInfo");
}
hr = pTypeInfo->lpVtbl->GetContainingTypeLib(pTypeInfo, &pTypeLib, &index);
if(FAILED(hr)) {
OLE_RELEASE(pTypeInfo);
ole_raise(hr, eWIN32OLEQueryInterfaceError, "failed to GetContainingTypeLib");
}
OLE_RELEASE(pTypeInfo);
if(!RB_TYPE_P(klass, T_NIL)) {
ole_const_load(pTypeLib, klass, self);
}
else {
ole_const_load(pTypeLib, cWIN32OLE, self);
}
OLE_RELEASE(pTypeLib);
}
else if(RB_TYPE_P(ole, T_STRING)) {
file = typelib_file(ole);
if (file == Qnil) {
file = ole;
}
pBuf = ole_vstr2wc(file);
hr = LoadTypeLibEx(pBuf, REGKIND_NONE, &pTypeLib);
SysFreeString(pBuf);
if (FAILED(hr))
ole_raise(hr, eWIN32OLERuntimeError, "failed to LoadTypeLibEx");
if(!RB_TYPE_P(klass, T_NIL)) {
ole_const_load(pTypeLib, klass, self);
}
else {
ole_const_load(pTypeLib, cWIN32OLE, self);
}
OLE_RELEASE(pTypeLib);
}
else {
rb_raise(rb_eTypeError, "1st parameter must be WIN32OLE instance");
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-c-create_guid" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
create_guid
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Creates GUID.</p>
<pre class="ruby"><span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">create_guid</span> <span class="ruby-comment"># => {1CB530F1-F6B1-404D-BCE6-1959BF91F4A8}</span>
</pre>
<div class="method-source-code" id="create_guid-source">
<pre>static VALUE
fole_s_create_guid(VALUE self)
{
GUID guid;
HRESULT hr;
OLECHAR bstr[80];
int len = 0;
hr = CoCreateGuid(&guid);
if (FAILED(hr)) {
ole_raise(hr, eWIN32OLERuntimeError, "failed to create GUID");
}
len = StringFromGUID2(&guid, bstr, sizeof(bstr)/sizeof(OLECHAR));
if (len == 0) {
rb_raise(rb_eRuntimeError, "failed to create GUID(buffer over)");
}
return ole_wc2vstr(bstr, FALSE);
}</pre>
</div>
</div>
</div>
<div id="method-c-locale" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
locale → locale id.
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns current locale id (lcid). The default locale is <a href="WIN32OLE.html#LOCALE_SYSTEM_DEFAULT"><code>WIN32OLE::LOCALE_SYSTEM_DEFAULT</code></a>.</p>
<pre class="ruby"><span class="ruby-identifier">lcid</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">locale</span>
</pre>
<div class="method-source-code" id="locale-source">
<pre>static VALUE
fole_s_get_locale(VALUE self)
{
return RB_INT2FIX(cWIN32OLE_lcid);
}</pre>
</div>
</div>
</div>
<div id="method-c-locale-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
locale = lcid
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sets current locale id (lcid).</p>
<pre class="ruby"><span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">locale</span> = <span class="ruby-value">1033</span> <span class="ruby-comment"># set locale English(U.S)</span>
<span class="ruby-identifier">obj</span> = <span class="ruby-constant">WIN32OLE_VARIANT</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"$100,000"</span>, <span class="ruby-constant">WIN32OLE</span><span class="ruby-operator">::</span><span class="ruby-constant">VARIANT</span><span class="ruby-operator">::</span><span class="ruby-constant">VT_CY</span>)
</pre>
<div class="method-source-code" id="locale-3D-source">
<pre>static VALUE
fole_s_set_locale(VALUE self, VALUE vlcid)
{
LCID lcid = RB_FIX2INT(vlcid);
if (lcid_installed(lcid)) {
cWIN32OLE_lcid = lcid;
} else {
switch (lcid) {
case LOCALE_SYSTEM_DEFAULT:
case LOCALE_USER_DEFAULT:
cWIN32OLE_lcid = lcid;
break;
default:
rb_raise(eWIN32OLERuntimeError, "not installed locale: %u", (unsigned int)lcid);
}
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-c-new" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
new(server, [host]) → WIN32OLE object
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-heading">
<span class="method-callseq">
new(server, license: 'key') → WIN32OLE object
</span>
</div>
<div class="method-description">
<p>Returns a new <a href="WIN32OLE.html"><code>WIN32OLE</code></a> 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. If :license keyword argument is provided, IClassFactory2::CreateInstanceLic is used to create instance of licensed server.</p>
<pre class="ruby"><span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>) <span class="ruby-comment"># => Excel OLE Automation WIN32OLE object.</span>
<span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'{00024500-0000-0000-C000-000000000046}'</span>) <span class="ruby-comment"># => Excel OLE Automation WIN32OLE object.</span>
</pre>
<div class="method-source-code" id="new-source">
<pre>static VALUE
fole_initialize(int argc, VALUE *argv, VALUE self)
{
VALUE svr_name;
VALUE host;
VALUE others;
VALUE opts;
HRESULT hr;
CLSID clsid;
OLECHAR *pBuf;
OLECHAR *key_buf;
IDispatch *pDispatch;
IClassFactory2 * pIClassFactory2;
void *p;
static ID keyword_ids[1];
VALUE kwargs[1];
rb_call_super(0, 0);
rb_scan_args(argc, argv, "11*:", &svr_name, &host, &others, &opts);
StringValue(svr_name);
if (!NIL_P(host)) {
StringValue(host);
return ole_create_dcom(self, svr_name, host, others);
}
/* get CLSID from OLE server name */
pBuf = ole_vstr2wc(svr_name);
hr = CLSIDFromProgID(pBuf, &clsid);
if(FAILED(hr)) {
hr = CLSIDFromString(pBuf, &clsid);
}
SysFreeString(pBuf);
if(FAILED(hr)) {
ole_raise(hr, eWIN32OLERuntimeError,
"unknown OLE server: `%s'",
StringValuePtr(svr_name));
}
if (!keyword_ids[0]) {
keyword_ids[0] = rb_intern_const("license");
}
rb_get_kwargs(opts, keyword_ids, 0, 1, kwargs);
if (kwargs[0] == Qundef) {
/* get IDispatch interface */
hr = CoCreateInstance(
&clsid,
NULL,
CLSCTX_INPROC_SERVER | CLSCTX_LOCAL_SERVER,
&IID_IDispatch,
&p
);
} else {
hr = CoGetClassObject(
&clsid,
CLSCTX_INPROC_SERVER | CLSCTX_LOCAL_SERVER,
NULL,
&IID_IClassFactory2,
(LPVOID)&pIClassFactory2
);
if (hr == S_OK) {
key_buf = ole_vstr2wc(kwargs[0]);
hr = pIClassFactory2->lpVtbl->CreateInstanceLic(pIClassFactory2, NULL, NULL, &IID_IDispatch, key_buf, &p);
SysFreeString(key_buf);
OLE_RELEASE(pIClassFactory2);
}
}
pDispatch = p;
if(FAILED(hr)) {
ole_raise(hr, eWIN32OLERuntimeError,
"failed to create WIN32OLE object from `%s'",
StringValuePtr(svr_name));
}
ole_set_member(self, pDispatch);
return self;
}</pre>
</div>
</div>
</div>
<div id="method-c-ole_free" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ole_free(aWIN32OLE) -→ number
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Invokes Release method of Dispatch interface of <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object. You should not use this method because this method exists only for debugging <a href="WIN32OLE.html"><code>WIN32OLE</code></a>. The return value is reference counter of OLE object.</p>
<div class="method-source-code" id="ole_free-source">
<pre>static VALUE
fole_s_free(VALUE self, VALUE obj)
{
ULONG n = 0;
struct oledata * pole = NULL;
pole = oledata_get_struct(obj);
if(pole->pDispatch) {
if (reference_count(pole) > 0) {
n = OLE_RELEASE(pole->pDispatch);
}
}
return RB_INT2NUM(n);
}</pre>
</div>
</div>
</div>
<div id="method-c-ole_reference_count" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ole_reference_count(aWIN32OLE) -→ number
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns reference counter of Dispatch interface of <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object. You should not use this method because this method exists only for debugging <a href="WIN32OLE.html"><code>WIN32OLE</code></a>.</p>
<div class="method-source-code" id="ole_reference_count-source">
<pre>static VALUE
fole_s_reference_count(VALUE self, VALUE obj)
{
struct oledata * pole = NULL;
pole = oledata_get_struct(obj);
return RB_INT2NUM(reference_count(pole));
}</pre>
</div>
</div>
</div>
<div id="method-c-ole_show_help" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
ole_show_help(obj [,helpcontext])
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Displays helpfile. The 1st argument specifies <a href="WIN32OLE_TYPE.html"><code>WIN32OLE_TYPE</code></a> object or <a href="WIN32OLE_METHOD.html"><code>WIN32OLE_METHOD</code></a> object or helpfile.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">typeobj</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">ole_type</span>
<span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">ole_show_help</span>(<span class="ruby-identifier">typeobj</span>)
</pre>
<div class="method-source-code" id="ole_show_help-source">
<pre>static VALUE
fole_s_show_help(int argc, VALUE *argv, VALUE self)
{
VALUE target;
VALUE helpcontext;
VALUE helpfile;
VALUE name;
HWND hwnd;
rb_scan_args(argc, argv, "11", &target, &helpcontext);
if (rb_obj_is_kind_of(target, cWIN32OLE_TYPE) ||
rb_obj_is_kind_of(target, cWIN32OLE_METHOD)) {
helpfile = rb_funcall(target, rb_intern("helpfile"), 0);
if(strlen(StringValuePtr(helpfile)) == 0) {
name = rb_ivar_get(target, rb_intern("name"));
rb_raise(rb_eRuntimeError, "no helpfile of `%s'",
StringValuePtr(name));
}
helpcontext = rb_funcall(target, rb_intern("helpcontext"), 0);
} else {
helpfile = target;
}
if (!RB_TYPE_P(helpfile, T_STRING)) {
rb_raise(rb_eTypeError, "1st parameter must be (String|WIN32OLE_TYPE|WIN32OLE_METHOD)");
}
hwnd = ole_show_help(helpfile, helpcontext);
if(hwnd == 0) {
rb_raise(rb_eRuntimeError, "failed to open help file `%s'",
StringValuePtr(helpfile));
}
return Qnil;
}</pre>
</div>
</div>
</div>
</section>
<section id="public-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Public Instance Methods</h3>
</header>
<div id="method-i-5B-5D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE[a1,a2,...]
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the value of Collection specified by a1, a2,.…</p>
<pre class="ruby"><span class="ruby-identifier">dict</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Scripting.Dictionary'</span>)
<span class="ruby-identifier">dict</span>.<span class="ruby-identifier">add</span>(<span class="ruby-string">'ruby'</span>, <span class="ruby-string">'Ruby'</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">dict</span>[<span class="ruby-string">'ruby'</span>] <span class="ruby-comment"># => 'Ruby' (same as `puts dict.item('ruby')')</span>
</pre>
<p>Remark: You can not use this method to get the property.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-comment"># puts excel['Visible'] This is error !!!</span>
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">excel</span>.<span class="ruby-constant">Visible</span> <span class="ruby-comment"># You should to use this style to get the property.</span>
</pre>
<div class="method-source-code" id="5B-5D-source">
<pre>static VALUE
fole_getproperty_with_bracket(int argc, VALUE *argv, VALUE self)
{
VALUE v = ole_invoke(argc, argv, self, DISPATCH_PROPERTYGET, TRUE);
if (v == rb_eNoMethodError) {
return rb_call_super(argc, argv);
}
return v;
}</pre>
</div>
</div>
</div>
<div id="method-i-5B-5D-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE[a1, a2, ...]=val
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sets the value to <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object specified by a1, a2, …</p>
<pre class="ruby"><span class="ruby-identifier">dict</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Scripting.Dictionary'</span>)
<span class="ruby-identifier">dict</span>.<span class="ruby-identifier">add</span>(<span class="ruby-string">'ruby'</span>, <span class="ruby-string">'RUBY'</span>)
<span class="ruby-identifier">dict</span>[<span class="ruby-string">'ruby'</span>] = <span class="ruby-string">'Ruby'</span>
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">dict</span>[<span class="ruby-string">'ruby'</span>] <span class="ruby-comment"># => 'Ruby'</span>
</pre>
<p>Remark: You can not use this method to set the property value.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-comment"># excel['Visible'] = true # This is error !!!</span>
<span class="ruby-identifier">excel</span>.<span class="ruby-constant">Visible</span> = <span class="ruby-keyword">true</span> <span class="ruby-comment"># You should to use this style to set the property.</span>
</pre>
<div class="method-source-code" id="5B-5D-3D-source">
<pre>static VALUE
fole_setproperty_with_bracket(int argc, VALUE *argv, VALUE self)
{
VALUE v = ole_invoke(argc, argv, self, DISPATCH_PROPERTYPUT, TRUE);
if (v == rb_eNoMethodError) {
return rb_call_super(argc, argv);
}
return v;
}</pre>
</div>
</div>
</div>
<div id="method-i-_getproperty" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#_getproperty(dispid, args, types)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">_getproperty</span>(<span class="ruby-value">558</span>, [], []) <span class="ruby-comment"># same effect as puts excel.visible</span>
</pre>
<div class="method-source-code" id="_getproperty-source">
<pre>static VALUE
fole_getproperty2(VALUE self, VALUE dispid, VALUE args, VALUE types)
{
return ole_invoke2(self, dispid, args, types, DISPATCH_PROPERTYGET);
}</pre>
</div>
</div>
</div>
<div id="method-i-_invoke" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#_invoke(dispid, args, types)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">excel</span>.<span class="ruby-identifier">_invoke</span>(<span class="ruby-value">302</span>, [], []) <span class="ruby-comment"># same effect as excel.Quit</span>
</pre>
<div class="method-source-code" id="_invoke-source">
<pre>static VALUE
fole_invoke2(VALUE self, VALUE dispid, VALUE args, VALUE types)
{
return ole_invoke2(self, dispid, args, types, DISPATCH_METHOD);
}</pre>
</div>
</div>
</div>
<div id="method-i-_setproperty" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#_setproperty(dispid, args, types)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>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.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">excel</span>.<span class="ruby-identifier">_setproperty</span>(<span class="ruby-value">558</span>, [<span class="ruby-keyword">true</span>], [<span class="ruby-constant">WIN32OLE</span><span class="ruby-operator">::</span><span class="ruby-constant">VARIANT</span><span class="ruby-operator">::</span><span class="ruby-constant">VT_BOOL</span>]) <span class="ruby-comment"># same effect as excel.visible = true</span>
</pre>
<div class="method-source-code" id="_setproperty-source">
<pre>static VALUE
fole_setproperty2(VALUE self, VALUE dispid, VALUE args, VALUE types)
{
return ole_invoke2(self, dispid, args, types, DISPATCH_PROPERTYPUT);
}</pre>
</div>
</div>
</div>
<div id="method-i-each" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#each {|i|...}
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Iterates over each item of OLE collection which has IEnumVARIANT interface.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">book</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">workbooks</span>.<span class="ruby-identifier">add</span>
<span class="ruby-identifier">sheets</span> = <span class="ruby-identifier">book</span>.<span class="ruby-identifier">worksheets</span>(<span class="ruby-value">1</span>)
<span class="ruby-identifier">cells</span> = <span class="ruby-identifier">sheets</span>.<span class="ruby-identifier">cells</span>(<span class="ruby-string">"A1:A5"</span>)
<span class="ruby-identifier">cells</span>.<span class="ruby-identifier">each</span> <span class="ruby-keyword">do</span> <span class="ruby-operator">|</span><span class="ruby-identifier">cell</span><span class="ruby-operator">|</span>
<span class="ruby-identifier">cell</span>.<span class="ruby-identifier">value</span> = <span class="ruby-value">10</span>
<span class="ruby-keyword">end</span>
</pre>
<div class="method-source-code" id="each-source">
<pre>static VALUE
fole_each(VALUE self)
{
LCID lcid = cWIN32OLE_lcid;
struct oledata *pole = NULL;
unsigned int argErr;
EXCEPINFO excepinfo;
DISPPARAMS dispParams;
VARIANT result;
HRESULT hr;
IEnumVARIANT *pEnum = NULL;
void *p;
RETURN_ENUMERATOR(self, 0, 0);
VariantInit(&result);
dispParams.rgvarg = NULL;
dispParams.rgdispidNamedArgs = NULL;
dispParams.cNamedArgs = 0;
dispParams.cArgs = 0;
memset(&excepinfo, 0, sizeof(excepinfo));
pole = oledata_get_struct(self);
hr = pole->pDispatch->lpVtbl->Invoke(pole->pDispatch, DISPID_NEWENUM,
&IID_NULL, lcid,
DISPATCH_METHOD | DISPATCH_PROPERTYGET,
&dispParams, &result,
&excepinfo, &argErr);
if (FAILED(hr)) {
VariantClear(&result);
ole_raise(hr, eWIN32OLEQueryInterfaceError, "failed to get IEnum Interface");
}
if (V_VT(&result) == VT_UNKNOWN) {
hr = V_UNKNOWN(&result)->lpVtbl->QueryInterface(V_UNKNOWN(&result),
&IID_IEnumVARIANT,
&p);
pEnum = p;
} else if (V_VT(&result) == VT_DISPATCH) {
hr = V_DISPATCH(&result)->lpVtbl->QueryInterface(V_DISPATCH(&result),
&IID_IEnumVARIANT,
&p);
pEnum = p;
}
if (FAILED(hr) || !pEnum) {
VariantClear(&result);
ole_raise(hr, eWIN32OLEQueryInterfaceError, "failed to get IEnum Interface");
}
VariantClear(&result);
rb_ensure(ole_each_sub, (VALUE)pEnum, ole_ienum_free, (VALUE)pEnum);
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-invoke" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#invoke(method, [arg1,...]) → return value of method.
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Runs OLE method. The first argument specifies the method name of OLE Automation object. The others specify argument of the <em>method</em>. If you can not execute <em>method</em> directly, then use this method instead.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">excel</span>.<span class="ruby-identifier">invoke</span>(<span class="ruby-string">'Quit'</span>) <span class="ruby-comment"># => same as excel.Quit</span>
</pre>
<div class="method-source-code" id="invoke-source">
<pre>static VALUE
fole_invoke(int argc, VALUE *argv, VALUE self)
{
VALUE v = ole_invoke(argc, argv, self, DISPATCH_METHOD|DISPATCH_PROPERTYGET, FALSE);
if (v == rb_eNoMethodError) {
return rb_call_super(argc, argv);
}
return v;
}</pre>
</div>
</div>
</div>
<div id="method-i-method_missing" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#method_missing(id [,arg1, arg2, ...])
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Calls <a href="WIN32OLE.html#method-i-invoke"><code>WIN32OLE#invoke</code></a> method.</p>
<div class="method-source-code" id="method_missing-source">
<pre>static VALUE
fole_missing(int argc, VALUE *argv, VALUE self)
{
VALUE mid, org_mid, sym, v;
const char* mname;
long n;
rb_check_arity(argc, 1, UNLIMITED_ARGUMENTS);
mid = org_mid = argv[0];
sym = rb_check_symbol(&mid);
if (!NIL_P(sym)) mid = rb_sym2str(sym);
mname = StringValueCStr(mid);
if(!mname) {
rb_raise(rb_eRuntimeError, "fail: unknown method or property");
}
n = RSTRING_LEN(mid);
if(mname[n-1] == '=') {
rb_check_arity(argc, 2, 2);
argv[0] = rb_enc_associate(rb_str_subseq(mid, 0, n-1), cWIN32OLE_enc);
return ole_propertyput(self, argv[0], argv[1]);
}
else {
argv[0] = rb_enc_associate(rb_str_dup(mid), cWIN32OLE_enc);
v = ole_invoke(argc, argv, self, DISPATCH_METHOD|DISPATCH_PROPERTYGET, FALSE);
if (v == rb_eNoMethodError) {
argv[0] = org_mid;
return rb_call_super(argc, argv);
}
return v;
}
}</pre>
</div>
</div>
</div>
<div id="method-i-methods" class="method-detail ">
<div class="method-heading">
<span class="method-name">methods</span><span
class="method-args">(*args)</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>By overriding <a href="Object.html#method-i-methods"><code>Object#methods</code></a>, <a href="WIN32OLE.html"><code>WIN32OLE</code></a> might work well with did_you_mean gem. This is experimental.</p>
<pre class="ruby"><span class="ruby-identifier">require</span> <span class="ruby-string">'win32ole'</span>
<span class="ruby-identifier">dict</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Scripting.Dictionary'</span>)
<span class="ruby-identifier">dict</span>.<span class="ruby-constant">Ade</span>(<span class="ruby-string">'a'</span>, <span class="ruby-value">1</span>)
<span class="ruby-comment">#=> Did you mean? Add</span>
</pre>
<div class="method-calls-super">
Calls superclass method
<a href="Object.html#method-i-methods"><code>Object#methods</code></a>
</div>
<div class="method-source-code" id="methods-source">
<pre><span class="ruby-comment"># File ext/win32ole/lib/win32ole.rb, line 21</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">methods</span>(<span class="ruby-operator">*</span><span class="ruby-identifier">args</span>)
<span class="ruby-keyword">super</span> <span class="ruby-operator">+</span> <span class="ruby-identifier">ole_methods_safely</span>.<span class="ruby-identifier">map</span>(<span class="ruby-operator">&</span><span class="ruby-value">:name</span>).<span class="ruby-identifier">map</span>(<span class="ruby-operator">&</span><span class="ruby-value">:to_sym</span>)
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
<div id="method-i-ole_activex_initialize" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_activex_initialize() → Qnil
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Initialize <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object(ActiveX Control) by calling IPersistMemory::InitNew.</p>
<p>Before calling OLE method, some kind of the ActiveX controls created with MFC should be initialized by calling IPersistXXX::InitNew.</p>
<p>If and only if you received the exception “HRESULT error code: 0x8000ffff catastrophic failure”, try this method before invoking any ole_method.</p>
<pre>obj = WIN32OLE.new("ProgID_or_GUID_of_ActiveX_Control")
obj.ole_activex_initialize
obj.method(...)</pre>
<div class="method-source-code" id="ole_activex_initialize-source">
<pre>static VALUE
fole_activex_initialize(VALUE self)
{
struct oledata *pole = NULL;
IPersistMemory *pPersistMemory;
void *p;
HRESULT hr = S_OK;
pole = oledata_get_struct(self);
hr = pole->pDispatch->lpVtbl->QueryInterface(pole->pDispatch, &IID_IPersistMemory, &p);
pPersistMemory = p;
if (SUCCEEDED(hr)) {
hr = pPersistMemory->lpVtbl->InitNew(pPersistMemory);
OLE_RELEASE(pPersistMemory);
if (SUCCEEDED(hr)) {
return Qnil;
}
}
if (FAILED(hr)) {
ole_raise(hr, eWIN32OLERuntimeError, "fail to initialize ActiveX control");
}
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-ole_free" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_free
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>invokes Release method of Dispatch interface of <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object. Usually, you do not need to call this method because Release method called automatically when <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object garbaged.</p>
<div class="method-source-code" id="ole_free-source">
<pre>static VALUE
fole_free(VALUE self)
{
struct oledata *pole = NULL;
pole = oledata_get_struct(self);
OLE_FREE(pole->pDispatch);
pole->pDispatch = NULL;
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-ole_func_methods" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_func_methods
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the array of <a href="WIN32OLE_METHOD.html"><code>WIN32OLE_METHOD</code></a> object . The element of the array is property (settable) of <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">properties</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">ole_func_methods</span>
</pre>
<div class="method-source-code" id="ole_func_methods-source">
<pre>static VALUE
fole_func_methods(VALUE self)
{
return ole_methods( self, INVOKE_FUNC);
}</pre>
</div>
</div>
</div>
<div id="method-i-ole_get_methods" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_get_methods
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the array of <a href="WIN32OLE_METHOD.html"><code>WIN32OLE_METHOD</code></a> object . The element of the array is property (gettable) of <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">properties</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">ole_get_methods</span>
</pre>
<div class="method-source-code" id="ole_get_methods-source">
<pre>static VALUE
fole_get_methods(VALUE self)
{
return ole_methods( self, INVOKE_PROPERTYGET);
}</pre>
</div>
</div>
</div>
<div id="method-i-ole_method" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_method_help(method)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <a href="WIN32OLE_METHOD.html"><code>WIN32OLE_METHOD</code></a> object corresponding with method specified by 1st argument.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">method</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">ole_method_help</span>(<span class="ruby-string">'Quit'</span>)
</pre>
<div class="method-source-code" id="ole_method-source">
<pre>static VALUE
fole_method_help(VALUE self, VALUE cmdname)
{
ITypeInfo *pTypeInfo;
HRESULT hr;
struct oledata *pole = NULL;
VALUE obj;
SafeStringValue(cmdname);
pole = oledata_get_struct(self);
hr = typeinfo_from_ole(pole, &pTypeInfo);
if(FAILED(hr))
ole_raise(hr, eWIN32OLEQueryInterfaceError, "failed to get ITypeInfo");
obj = create_win32ole_method(pTypeInfo, cmdname);
OLE_RELEASE(pTypeInfo);
if (obj == Qnil)
rb_raise(eWIN32OLERuntimeError, "not found %s",
StringValuePtr(cmdname));
return obj;
}</pre>
</div>
</div>
<div class="aliases">
Also aliased as: <a href="WIN32OLE.html#method-i-ole_method_help">ole_method_help</a>
</div>
</div>
<div id="method-i-ole_method_help" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">ole_method_help</span><span
class="method-args">(p1)</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="WIN32OLE.html#method-i-ole_method">ole_method</a>
</div>
</div>
<div id="method-i-ole_methods" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_methods
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the array of <a href="WIN32OLE_METHOD.html"><code>WIN32OLE_METHOD</code></a> object. The element is OLE method of <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">methods</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">ole_methods</span>
</pre>
<div class="method-source-code" id="ole_methods-source">
<pre>static VALUE
fole_methods(VALUE self)
{
return ole_methods( self, INVOKE_FUNC | INVOKE_PROPERTYGET | INVOKE_PROPERTYPUT | INVOKE_PROPERTYPUTREF);
}</pre>
</div>
</div>
</div>
<div id="method-i-ole_obj_help" class="method-detail method-alias">
<div class="method-heading">
<span class="method-name">ole_obj_help</span><span
class="method-args">()</span>
</div>
<div class="method-description">
</div>
<div class="aliases">
Alias for: <a href="WIN32OLE.html#method-i-ole_type">ole_type</a>
</div>
</div>
<div id="method-i-ole_put_methods" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_put_methods
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the array of <a href="WIN32OLE_METHOD.html"><code>WIN32OLE_METHOD</code></a> object . The element of the array is property (settable) of <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">properties</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">ole_put_methods</span>
</pre>
<div class="method-source-code" id="ole_put_methods-source">
<pre>static VALUE
fole_put_methods(VALUE self)
{
return ole_methods( self, INVOKE_PROPERTYPUT|INVOKE_PROPERTYPUTREF);
}</pre>
</div>
</div>
</div>
<div id="method-i-ole_query_interface" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_query_interface(iid) → WIN32OLE object
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object for a specific dispatch or dual interface specified by iid.</p>
<pre class="ruby"><span class="ruby-identifier">ie</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'InternetExplorer.Application'</span>)
<span class="ruby-identifier">ie_web_app</span> = <span class="ruby-identifier">ie</span>.<span class="ruby-identifier">ole_query_interface</span>(<span class="ruby-string">'{0002DF05-0000-0000-C000-000000000046}'</span>) <span class="ruby-comment"># => WIN32OLE object for dispinterface IWebBrowserApp</span>
</pre>
<div class="method-source-code" id="ole_query_interface-source">
<pre>static VALUE
fole_query_interface(VALUE self, VALUE str_iid)
{
HRESULT hr;
OLECHAR *pBuf;
IID iid;
struct oledata *pole = NULL;
IDispatch *pDispatch;
void *p;
pBuf = ole_vstr2wc(str_iid);
hr = CLSIDFromString(pBuf, &iid);
SysFreeString(pBuf);
if(FAILED(hr)) {
ole_raise(hr, eWIN32OLERuntimeError,
"invalid iid: `%s'",
StringValuePtr(str_iid));
}
pole = oledata_get_struct(self);
if(!pole->pDispatch) {
rb_raise(rb_eRuntimeError, "failed to get dispatch interface");
}
hr = pole->pDispatch->lpVtbl->QueryInterface(pole->pDispatch, &iid,
&p);
if(FAILED(hr)) {
ole_raise(hr, eWIN32OLEQueryInterfaceError,
"failed to get interface `%s'",
StringValuePtr(str_iid));
}
pDispatch = p;
return create_win32ole_object(cWIN32OLE, pDispatch, 0, 0);
}</pre>
</div>
</div>
</div>
<div id="method-i-ole_respond_to-3F" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_respond_to?(method) → true or false
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns true when OLE object has OLE method, otherwise returns false.</p>
<pre>ie = WIN32OLE.new('InternetExplorer.Application')
ie.ole_respond_to?("gohome") => true</pre>
<div class="method-source-code" id="ole_respond_to-3F-source">
<pre>static VALUE
fole_respond_to(VALUE self, VALUE method)
{
struct oledata *pole = NULL;
BSTR wcmdname;
DISPID DispID;
HRESULT hr;
if(!RB_TYPE_P(method, T_STRING) && !RB_TYPE_P(method, T_SYMBOL)) {
rb_raise(rb_eTypeError, "wrong argument type (expected String or Symbol)");
}
if (RB_TYPE_P(method, T_SYMBOL)) {
method = rb_sym2str(method);
}
pole = oledata_get_struct(self);
wcmdname = ole_vstr2wc(method);
hr = pole->pDispatch->lpVtbl->GetIDsOfNames( pole->pDispatch, &IID_NULL,
&wcmdname, 1, cWIN32OLE_lcid, &DispID);
SysFreeString(wcmdname);
return SUCCEEDED(hr) ? Qtrue : Qfalse;
}</pre>
</div>
</div>
</div>
<div id="method-i-ole_type" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_type
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns <a href="WIN32OLE_TYPE.html"><code>WIN32OLE_TYPE</code></a> object.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">tobj</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">ole_type</span>
</pre>
<div class="method-source-code" id="ole_type-source">
<pre>static VALUE
fole_type(VALUE self)
{
ITypeInfo *pTypeInfo;
HRESULT hr;
struct oledata *pole = NULL;
LCID lcid = cWIN32OLE_lcid;
VALUE type = Qnil;
pole = oledata_get_struct(self);
hr = pole->pDispatch->lpVtbl->GetTypeInfo( pole->pDispatch, 0, lcid, &pTypeInfo );
if(FAILED(hr)) {
ole_raise(hr, eWIN32OLEQueryInterfaceError, "failed to GetTypeInfo");
}
type = ole_type_from_itypeinfo(pTypeInfo);
OLE_RELEASE(pTypeInfo);
if (type == Qnil) {
rb_raise(rb_eRuntimeError, "failed to create WIN32OLE_TYPE obj from ITypeInfo");
}
return type;
}</pre>
</div>
</div>
<div class="aliases">
Also aliased as: <a href="WIN32OLE.html#method-i-ole_obj_help">ole_obj_help</a>
</div>
</div>
<div id="method-i-ole_typelib" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE#ole_typelib → The WIN32OLE_TYPELIB object
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the <a href="WIN32OLE_TYPELIB.html"><code>WIN32OLE_TYPELIB</code></a> object. The object represents the type library which contains the <a href="WIN32OLE.html"><code>WIN32OLE</code></a> object.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">tlib</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">ole_typelib</span>
<span class="ruby-identifier">puts</span> <span class="ruby-identifier">tlib</span>.<span class="ruby-identifier">name</span> <span class="ruby-comment"># -> 'Microsoft Excel 9.0 Object Library'</span>
</pre>
<div class="method-source-code" id="ole_typelib-source">
<pre>static VALUE
fole_typelib(VALUE self)
{
struct oledata *pole = NULL;
HRESULT hr;
ITypeInfo *pTypeInfo;
LCID lcid = cWIN32OLE_lcid;
VALUE vtlib = Qnil;
pole = oledata_get_struct(self);
hr = pole->pDispatch->lpVtbl->GetTypeInfo(pole->pDispatch,
0, lcid, &pTypeInfo);
if(FAILED(hr)) {
ole_raise(hr, eWIN32OLEQueryInterfaceError, "failed to GetTypeInfo");
}
vtlib = ole_typelib_from_itypeinfo(pTypeInfo);
OLE_RELEASE(pTypeInfo);
if (vtlib == Qnil) {
rb_raise(rb_eRuntimeError, "failed to get type library info.");
}
return vtlib;
}</pre>
</div>
</div>
</div>
<div id="method-i-setproperty" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
setproperty('property', [arg1, arg2,...] val)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sets property of OLE object. When you want to set property with argument, you can use this method.</p>
<pre class="ruby"><span class="ruby-identifier">excel</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">'Excel.Application'</span>)
<span class="ruby-identifier">excel</span>.<span class="ruby-constant">Visible</span> = <span class="ruby-keyword">true</span>
<span class="ruby-identifier">book</span> = <span class="ruby-identifier">excel</span>.<span class="ruby-identifier">workbooks</span>.<span class="ruby-identifier">add</span>
<span class="ruby-identifier">sheet</span> = <span class="ruby-identifier">book</span>.<span class="ruby-identifier">worksheets</span>(<span class="ruby-value">1</span>)
<span class="ruby-identifier">sheet</span>.<span class="ruby-identifier">setproperty</span>(<span class="ruby-string">'Cells'</span>, <span class="ruby-value">1</span>, <span class="ruby-value">2</span>, <span class="ruby-value">10</span>) <span class="ruby-comment"># => The B1 cell value is 10.</span>
</pre>
<div class="method-source-code" id="setproperty-source">
<pre>static VALUE
fole_setproperty(int argc, VALUE *argv, VALUE self)
{
VALUE v = ole_invoke(argc, argv, self, DISPATCH_PROPERTYPUT, FALSE);
if (v == rb_eNoMethodError) {
return rb_call_super(argc, argv);
}
return v;
}</pre>
</div>
</div>
</div>
</section>
<section id="private-instance-5Buntitled-5D-method-details" class="method-section">
<header>
<h3>Private Instance Methods</h3>
</header>
<div id="method-i-ole_methods_safely" class="method-detail ">
<div class="method-heading">
<span class="method-name">ole_methods_safely</span><span
class="method-args">()</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<div class="method-source-code" id="ole_methods_safely-source">
<pre><span class="ruby-comment"># File ext/win32ole/lib/win32ole.rb, line 27</span>
<span class="ruby-keyword">def</span> <span class="ruby-identifier ruby-title">ole_methods_safely</span>
<span class="ruby-identifier">ole_methods</span>
<span class="ruby-keyword">rescue</span> <span class="ruby-constant">WIN32OLEQueryInterfaceError</span>
[]
<span class="ruby-keyword">end</span></pre>
</div>
</div>
</div>
</section>
</section>
</main>
<footer id="validator-badges" role="contentinfo">
<p><a href="https://validator.w3.org/check/referer">Validate</a>
<p>Generated by <a href="https://ruby.github.io/rdoc/">RDoc</a> 6.2.1.1.
<p>Based on <a href="http://deveiate.org/projects/Darkfish-RDoc/">Darkfish</a> by <a href="http://deveiate.org">Michael Granger</a>.
</footer>