File: C:/Ruby27-x64/share/doc/ruby/html/WIN32OLE_VARIANT.html
<!DOCTYPE html>
<html>
<head>
<meta charset="UTF-8">
<title>class WIN32OLE_VARIANT - 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-array">::array</a>
<li ><a href="#method-c-new">::new</a>
<li ><a href="#method-i-5B-5D">#[]</a>
<li ><a href="#method-i-5B-5D-3D">#[]=</a>
<li ><a href="#method-i-value">#value</a>
<li ><a href="#method-i-value-3D">#value=</a>
<li ><a href="#method-i-vartype">#vartype</a>
</ul>
</div>
</div>
</nav>
<main role="main" aria-labelledby="class-WIN32OLE_VARIANT">
<h1 id="class-WIN32OLE_VARIANT" class="class">
class WIN32OLE_VARIANT
</h1>
<section class="description">
<p><code>WIN32OLE_VARIANT</code> objects represents OLE variant.</p>
<p>Win32OLE converts Ruby object into OLE variant automatically when invoking OLE methods. If OLE method requires the argument which is different from the variant by automatic conversion of Win32OLE, you can convert the specfied variant type by using <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> class.</p>
<pre class="ruby"><span class="ruby-identifier">param</span> = <span class="ruby-constant">WIN32OLE_VARIANT</span>.<span class="ruby-identifier">new</span>(<span class="ruby-value">10</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_R4</span>)
<span class="ruby-identifier">oleobj</span>.<span class="ruby-identifier">method</span>(<span class="ruby-identifier">param</span>)
</pre>
<p><a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> does not support VT_RECORD variant. Use <a href="WIN32OLE_RECORD.html"><code>WIN32OLE_RECORD</code></a> class instead of <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> if the VT_RECORD variant is needed.</p>
</section>
<section id="5Buntitled-5D" class="documentation-section">
<section class="constants-list">
<header>
<h3>Constants</h3>
</header>
<dl>
<dt id="Empty">Empty
<dd><p>represents VT_EMPTY OLE object.</p>
<dt id="NoParam">NoParam
<dd><p>represents VT_ERROR variant with DISP_E_PARAMNOTFOUND. This constants is used for not specified parameter.</p>
<pre class="ruby"><span class="ruby-identifier">fso</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"Scripting.FileSystemObject"</span>)
<span class="ruby-identifier">fso</span>.<span class="ruby-identifier">openTextFile</span>(<span class="ruby-identifier">filename</span>, <span class="ruby-constant">WIN32OLE_VARIANT</span><span class="ruby-operator">::</span><span class="ruby-constant">NoParam</span>, <span class="ruby-keyword">false</span>)
</pre>
<dt id="Nothing">Nothing
<dd><p>represents <a href="WIN32OLE_VARIANT.html#Nothing"><code>Nothing</code></a> of VB.NET or VB.</p>
<dt id="Null">Null
<dd><p>represents VT_NULL OLE object.</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-array" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
array(ary, vt)
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns Ruby object wrapping OLE variant whose variant type is VT_ARRAY. The first argument should be <a href="Array.html"><code>Array</code></a> object which specifies dimensions and each size of dimensions of OLE array. The second argument specifies variant type of the element of OLE array.</p>
<p>The following create 2 dimensions OLE array. The first dimensions size is 3, and the second is 4.</p>
<pre class="ruby"><span class="ruby-identifier">ole_ary</span> = <span class="ruby-constant">WIN32OLE_VARIANT</span>.<span class="ruby-identifier">array</span>([<span class="ruby-value">3</span>,<span class="ruby-value">4</span>], <span class="ruby-constant">VT_I4</span>)
<span class="ruby-identifier">ruby_ary</span> = <span class="ruby-identifier">ole_ary</span>.<span class="ruby-identifier">value</span> <span class="ruby-comment"># => [[0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]]</span>
</pre>
<div class="method-source-code" id="array-source">
<pre>static VALUE
folevariant_s_array(VALUE klass, VALUE elems, VALUE vvt)
{
VALUE obj = Qnil;
VARTYPE vt;
struct olevariantdata *pvar;
SAFEARRAYBOUND *psab = NULL;
SAFEARRAY *psa = NULL;
UINT dim = 0;
UINT i = 0;
ole_initialize();
vt = RB_NUM2UINT(vvt);
vt = (vt | VT_ARRAY);
Check_Type(elems, T_ARRAY);
obj = folevariant_s_allocate(klass);
TypedData_Get_Struct(obj, struct olevariantdata, &olevariant_datatype, pvar);
dim = RARRAY_LEN(elems);
psab = ALLOC_N(SAFEARRAYBOUND, dim);
if(!psab) {
rb_raise(rb_eRuntimeError, "memory allocation error");
}
for (i = 0; i < dim; i++) {
psab[i].cElements = RB_FIX2INT(rb_ary_entry(elems, i));
psab[i].lLbound = 0;
}
psa = SafeArrayCreate((VARTYPE)(vt & VT_TYPEMASK), dim, psab);
if (psa == NULL) {
if (psab) free(psab);
rb_raise(rb_eRuntimeError, "memory allocation error(SafeArrayCreate)");
}
V_VT(&(pvar->var)) = vt;
if (vt & VT_BYREF) {
V_VT(&(pvar->realvar)) = (vt & ~VT_BYREF);
V_ARRAY(&(pvar->realvar)) = psa;
V_ARRAYREF(&(pvar->var)) = &(V_ARRAY(&(pvar->realvar)));
} else {
V_ARRAY(&(pvar->var)) = psa;
}
if (psab) free(psab);
return obj;
}</pre>
</div>
</div>
</div>
<div id="method-c-new" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
new(val, vartype) #→ WIN32OLE_VARIANT object.
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns Ruby object wrapping OLE variant. The first argument specifies Ruby object to convert OLE variant variable. The second argument specifies VARIANT type. In some situation, you need the <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> object to pass OLE method</p>
<pre class="ruby"><span class="ruby-identifier">shell</span> = <span class="ruby-constant">WIN32OLE</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"Shell.Application"</span>)
<span class="ruby-identifier">folder</span> = <span class="ruby-identifier">shell</span>.<span class="ruby-constant">NameSpace</span>(<span class="ruby-string">"C:\\Windows"</span>)
<span class="ruby-identifier">item</span> = <span class="ruby-identifier">folder</span>.<span class="ruby-constant">ParseName</span>(<span class="ruby-string">"tmp.txt"</span>)
<span class="ruby-comment"># You can't use Ruby String object to call FolderItem.InvokeVerb.</span>
<span class="ruby-comment"># Instead, you have to use WIN32OLE_VARIANT object to call the method.</span>
<span class="ruby-identifier">shortcut</span> = <span class="ruby-constant">WIN32OLE_VARIANT</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"Create Shortcut(\&S)"</span>)
<span class="ruby-identifier">item</span>.<span class="ruby-identifier">invokeVerb</span>(<span class="ruby-identifier">shortcut</span>)
</pre>
<div class="method-source-code" id="new-source">
<pre>static VALUE
folevariant_initialize(VALUE self, VALUE args)
{
int len = 0;
VARIANT var;
VALUE val;
VALUE vvt;
VARTYPE vt;
struct olevariantdata *pvar;
len = RARRAY_LEN(args);
rb_check_arity(len, 1, 3);
VariantInit(&var);
val = rb_ary_entry(args, 0);
check_type_val2variant(val);
TypedData_Get_Struct(self, struct olevariantdata, &olevariant_datatype, pvar);
if (len == 1) {
ole_val2variant(val, &(pvar->var));
} else {
vvt = rb_ary_entry(args, 1);
vt = RB_NUM2INT(vvt);
if ((vt & VT_TYPEMASK) == VT_RECORD) {
rb_raise(rb_eArgError, "not supported VT_RECORD WIN32OLE_VARIANT object");
}
ole_val2olevariantdata(val, vt, pvar);
}
return self;
}</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_VARIANT[i,j,...] #→ element of OLE array.
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns the element of <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> object(OLE array). This method is available only when the variant type of <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> object is VT_ARRAY.</p>
<p>REMARK:</p>
<pre>The all indices should be 0 or natural number and
lower than or equal to max indices.
(This point is different with Ruby Array indices.)
obj = WIN32OLE_VARIANT.new([[1,2,3],[4,5,6]])
p obj[0,0] # => 1
p obj[1,0] # => 4
p obj[2,0] # => WIN32OLERuntimeError
p obj[0, -1] # => WIN32OLERuntimeError</pre>
<div class="method-source-code" id="5B-5D-source">
<pre>static VALUE
folevariant_ary_aref(int argc, VALUE *argv, VALUE self)
{
struct olevariantdata *pvar;
SAFEARRAY *psa;
VALUE val = Qnil;
VARIANT variant;
LONG *pid;
HRESULT hr;
TypedData_Get_Struct(self, struct olevariantdata, &olevariant_datatype, pvar);
if (!V_ISARRAY(&(pvar->var))) {
rb_raise(eWIN32OLERuntimeError,
"`[]' is not available for this variant type object");
}
psa = get_locked_safe_array(self);
if (psa == NULL) {
return val;
}
pid = ary2safe_array_index(argc, argv, psa);
VariantInit(&variant);
V_VT(&variant) = (V_VT(&(pvar->var)) & ~VT_ARRAY) | VT_BYREF;
hr = SafeArrayPtrOfIndex(psa, pid, &V_BYREF(&variant));
if (FAILED(hr)) {
ole_raise(hr, eWIN32OLERuntimeError, "failed to SafeArrayPtrOfIndex");
}
val = ole_variant2val(&variant);
unlock_safe_array(psa);
if (pid) free(pid);
return val;
}</pre>
</div>
</div>
</div>
<div id="method-i-5B-5D-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
WIN32OLE_VARIANT[i,j,...] = val #→ set the element of OLE array
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p><a href="Set.html"><code>Set</code></a> the element of <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> object(OLE array) to val. This method is available only when the variant type of <a href="WIN32OLE_VARIANT.html"><code>WIN32OLE_VARIANT</code></a> object is VT_ARRAY.</p>
<p>REMARK:</p>
<pre>The all indices should be 0 or natural number and
lower than or equal to max indices.
(This point is different with Ruby Array indices.)
obj = WIN32OLE_VARIANT.new([[1,2,3],[4,5,6]])
obj[0,0] = 7
obj[1,0] = 8
p obj.value # => [[7,2,3], [8,5,6]]
obj[2,0] = 9 # => WIN32OLERuntimeError
obj[0, -1] = 9 # => WIN32OLERuntimeError</pre>
<div class="method-source-code" id="5B-5D-3D-source">
<pre>static VALUE
folevariant_ary_aset(int argc, VALUE *argv, VALUE self)
{
struct olevariantdata *pvar;
SAFEARRAY *psa;
VARIANT var;
VARTYPE vt;
LONG *pid;
HRESULT hr;
VOID *p = NULL;
TypedData_Get_Struct(self, struct olevariantdata, &olevariant_datatype, pvar);
if (!V_ISARRAY(&(pvar->var))) {
rb_raise(eWIN32OLERuntimeError,
"`[]' is not available for this variant type object");
}
psa = get_locked_safe_array(self);
if (psa == NULL) {
rb_raise(rb_eRuntimeError, "failed to get SafeArray pointer");
}
pid = ary2safe_array_index(argc-1, argv, psa);
VariantInit(&var);
vt = (V_VT(&(pvar->var)) & ~VT_ARRAY);
p = val2variant_ptr(argv[argc-1], &var, vt);
if ((V_VT(&var) == VT_DISPATCH && V_DISPATCH(&var) == NULL) ||
(V_VT(&var) == VT_UNKNOWN && V_UNKNOWN(&var) == NULL)) {
rb_raise(eWIN32OLERuntimeError, "argument does not have IDispatch or IUnknown Interface");
}
hr = SafeArrayPutElement(psa, pid, p);
if (FAILED(hr)) {
ole_raise(hr, eWIN32OLERuntimeError, "failed to SafeArrayPutElement");
}
unlock_safe_array(psa);
if (pid) free(pid);
return argv[argc-1];
}</pre>
</div>
</div>
</div>
<div id="method-i-value" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
value #→ Ruby object.
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns Ruby object value from OLE variant.</p>
<pre class="ruby"><span class="ruby-identifier">obj</span> = <span class="ruby-constant">WIN32OLE_VARIANT</span>.<span class="ruby-identifier">new</span>(<span class="ruby-value">1</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_BSTR</span>)
<span class="ruby-identifier">obj</span>.<span class="ruby-identifier">value</span> <span class="ruby-comment"># => "1" (not Integer object, but String object "1")</span>
</pre>
<div class="method-source-code" id="value-source">
<pre>static VALUE
folevariant_value(VALUE self)
{
struct olevariantdata *pvar;
VALUE val = Qnil;
VARTYPE vt;
int dim;
SAFEARRAY *psa;
TypedData_Get_Struct(self, struct olevariantdata, &olevariant_datatype, pvar);
val = ole_variant2val(&(pvar->var));
vt = V_VT(&(pvar->var));
if ((vt & ~VT_BYREF) == (VT_UI1|VT_ARRAY)) {
if (vt & VT_BYREF) {
psa = *V_ARRAYREF(&(pvar->var));
} else {
psa = V_ARRAY(&(pvar->var));
}
if (!psa) {
return val;
}
dim = SafeArrayGetDim(psa);
if (dim == 1) {
val = rb_funcall(val, rb_intern("pack"), 1, rb_str_new2("C*"));
}
}
return val;
}</pre>
</div>
</div>
</div>
<div id="method-i-value-3D" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
value = val #→ set WIN32OLE_VARIANT value to val.
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Sets variant value to val. If the val type does not match variant value type(vartype), then val is changed to match variant value type(vartype) before setting val. This method is not available when vartype is VT_ARRAY(except VT_UI1|VT_ARRAY). If the vartype is VT_UI1|VT_ARRAY, the val should be <a href="String.html"><code>String</code></a> object.</p>
<pre class="ruby"><span class="ruby-identifier">obj</span> = <span class="ruby-constant">WIN32OLE_VARIANT</span>.<span class="ruby-identifier">new</span>(<span class="ruby-value">1</span>) <span class="ruby-comment"># obj.vartype is WIN32OLE::VARIANT::VT_I4</span>
<span class="ruby-identifier">obj</span>.<span class="ruby-identifier">value</span> = <span class="ruby-value">3.2</span> <span class="ruby-comment"># 3.2 is changed to 3 when setting value.</span>
<span class="ruby-identifier">p</span> <span class="ruby-identifier">obj</span>.<span class="ruby-identifier">value</span> <span class="ruby-comment"># => 3</span>
</pre>
<div class="method-source-code" id="value-3D-source">
<pre>static VALUE
folevariant_set_value(VALUE self, VALUE val)
{
struct olevariantdata *pvar;
VARTYPE vt;
TypedData_Get_Struct(self, struct olevariantdata, &olevariant_datatype, pvar);
vt = V_VT(&(pvar->var));
if (V_ISARRAY(&(pvar->var)) && ((vt & ~VT_BYREF) != (VT_UI1|VT_ARRAY) || !RB_TYPE_P(val, T_STRING))) {
rb_raise(eWIN32OLERuntimeError,
"`value=' is not available for this variant type object");
}
ole_val2olevariantdata(val, vt, pvar);
return Qnil;
}</pre>
</div>
</div>
</div>
<div id="method-i-vartype" class="method-detail ">
<div class="method-heading">
<span class="method-callseq">
vartype #→ OLE variant type.
</span>
<span class="method-click-advice">click to toggle source</span>
</div>
<div class="method-description">
<p>Returns OLE variant type.</p>
<pre class="ruby"><span class="ruby-identifier">obj</span> = <span class="ruby-constant">WIN32OLE_VARIANT</span>.<span class="ruby-identifier">new</span>(<span class="ruby-string">"string"</span>)
<span class="ruby-identifier">obj</span>.<span class="ruby-identifier">vartype</span> <span class="ruby-comment"># => WIN32OLE::VARIANT::VT_BSTR</span>
</pre>
<div class="method-source-code" id="vartype-source">
<pre>static VALUE
folevariant_vartype(VALUE self)
{
struct olevariantdata *pvar;
TypedData_Get_Struct(self, struct olevariantdata, &olevariant_datatype, pvar);
return RB_INT2FIX(V_VT(&pvar->var));
}</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>