R COM Client Interface and internal COM Server

R COM Client Interface and internal COM Server [R logo]

Help pages for package ‘rcom’ version 2.2-1

$.COMObject | Invoke a function (method) an a COM Object
comCreateObject | Create COM Objects
comGetObject | Get Access to Existing COM Objects
comGetObjectInfo | Get Information about a COM Objects
comGetPicture | Get the clipboard contents as IPictureDisp Object
comGetProperty | Read One of a COM Object's Properties
comGetVersion | Get rcom version information
comInvoke | Invoke a function (method) on a COM Object
comIsValidHandle | Check if the COM object is valid
comRegisterRegistry | Register the COM server in the registry
comRegisterServer | Initialize the COM server
comSetProperty | Set One of the COM Object's Properties
comThis | Return the COM Object for this \R Instance
comTrace | Trace information about SEXP
comTraceObject | Trace information about the passed object
comUnregisterRegistry | Deregister the COM server from the registry
comUnregisterServer | Terminate the COM server
installstatconnDCOM | install statconnDCOM
[[.COMObject | Read One of a COM Object's Properties
[[<-.COMObject | Write One of a COM Object's Properties


Create COM Objects

Description

Creates a new COM object specified by its program identifier.

The object will be released automatically when the last reference to the object is removed. To speed up this process, assign some NULL value as soon as you don't need the object any more.

Usage

comCreateObject(progid)

Arguments

progid ProgId of COM object to create, e.g. "Excel.Application"

Value

comCreateObject returns an object of class "COMObject".

Author(s)

Thomas Baier

Examples

# start up excel
## Not run: x<-comCreateObject("Excel.Application")

# and make it visible
## Not run: comSetProperty(x,"Visible",TRUE)

# do something now...
[Package rcom version 2.2-1 Index]


Get Access to Existing COM Objects

Description

Tries to find a running instance of the specified progid and returns this object.

Use this function to use services provided by an already running application, e.g. the currently visible instance of Microsoft Excel.

The object will be released automatically when the last reference to the object is removed. To speed up this process, assign some NULL value as soon as you don't need the object any more.

Usage

comGetObject(progid)

Arguments

progid ProgId of COM object to get access to, e.g. "Excel.Application"

Value

comGetObject returns an object of class "COMObject".

Author(s)

Thomas Baier

Examples

# get access to excel
## Not run: x<-comGetObject("Excel.Application")

# and make it visible
## Not run: comSetProperty(x,"Visible",TRUE);

# do something now...


Get Information about a COM Objects

Description

This function will return information about the COM object passed as parameter.

Use this function to find out what rcom thinks about the object.

Use this function for debugging purposes to find out why rcom fails.

Not yet implemented!

Usage

comGetObjectInfo(handle)

Arguments

handle COM object (class "COMObject") as returned by e.g. comCreateObject

Value

comGetObject will return a list of all functions and their descriptions

Author(s)

Thomas Baier


Get the clipboard contents as IPictureDisp Object

Description

This function checks the contents of the (local) clipboard for an enhanced metafile object. If found, a COM object implementing the standard COM interface IPictureDisp is created from the clipboard contents.

Enhanced metafiles in the clipboard are created using R's graphics functions if the device win.metafile with an empty filename is used.

You have to close the device before retrieving the picture object.

Does not work at the moment due to problems in Microsoft's IPictureDisp.

Usage

comGetPicture()

Value

comGetObject returns an object of class "COMObject".

Author(s)

Thomas Baier

Examples

## Not run: win.metafile()
## Not run: plot(sin(1:100))
## Not run: dev.off()
## Not run: pic<-comGetPicture()


Read One of a COM Object's Properties

Description

Reads one of the COM object's properties.

Usage

comGetProperty(handle,property,...)

Arguments

handle | COM object (class "COMObject") as returned by e.g. comCreateObject
property | name of property to get as a character string
... | optional additional arguments for property specification (e.g. index for an array)

Value

The return value depends on the (data) type of the property to read.

Author(s)

Thomas Baier

See Also

comInvoke, comSetProperty

Examples

# start up excel
## Not run: x<-comCreateObject("Excel.Application")

# retrieve the "Visible" property
## Not run: v <- comGetProperty(x,"Visible")

# add a new workbook to Excel and gain access to the first worksheet
## Not run: newwb <- comInvoke(comGetProperty(x,"Workbooks"),"Add")
## Not run: ws <- comGetProperty(newwb,"Worksheets",1)

# get a specific range
## Not run: r <- comGetProperty(ws,"Range","A1","B4")

# do something now...


Get rcom version information

Description

This function returns the version of the currently installed rcom package as a floating point number.

Use this function to find out which version you are using. The version must be specified when reporting problems.

Usage

comGetVersion()

Value

comGetVersion returns the version number in format major.minor.

Author(s)

Thomas Baier


Invoke a function (method) on a COM Object

Description

Invokes a function (method) on a COM object.

Usage

comInvoke(handle,method,...)

Arguments

handle | COM object (class "COMObject") as returned by e.g. comCreateObject
method | name of method to call as a character string
... | parameters passed when calling the method

Value

The return value of comInvoke depends on the function (method) called.

Author(s)

Thomas Baier

See Also

comSetProperty, comGetProperty


Check if the COM object is valid

Description

Check if the passed object is a valid COM object

Usage

comIsValidHandle(handle)

Arguments

handle COM object (class "COMObject") as returned by e.g. comCreateObject

Value

com.isvalid returns TRUE if the object is valid, FALSE otherwise.

Author(s)

Thomas Baier

See Also

comCreateObject, comGetObject


Register the COM server in the registry

Description

This function will register the COM server and its associated type library with the system (registry).

Technically, this will register the type library and add local-server entries for the prog and class ids.

This function has to be called when installing the package. Otherwise, neither the type library will be available (automation clients cannot use the server) nor a mapping from version independent and version-dependant prog-id will be available.

Usage

comRegisterRegistry()

Author(s)

Thomas Baier

See Also

comUnregisterRegistry


Initialize the COM server

Description

This function registers the COM server at runtime. It is called automatically when the package rcom is loaded.

Technically, this will register the class factory in the system, so calls to CoCreateInstance() from client applications will succeed.

Remark: The type library will be loaded on demand later on

comUnregisterServer() is used to unregister the class object (class factory) again.

Usage

comRegisterServer()

Author(s)

Thomas Baier

See Also

comUnregisterServer, comRegisterRegistry


Set One of the COM Object's Properties

Description

Set one of the COM object's properties.

In case the property is an indexed property, pass the index value before the property value.

Usage

comSetProperty(handle,property,...)

Arguments

handle | COM object (class "COMObject") as returned by e.g. comCreateObject
property | name of property to get as a character string
... | the value the property should be set to

Author(s)

Thomas Baier

See Also

comInvoke, comGetProperty

Examples

# start up excel
## Not run: x<-comCreateObject("Excel.Application")

# and make it visible
## Not run: comSetProperty(x,"Visible",TRUE);

# set the value of index 3 of the indexed property ArrayProperty
## Not run: comSetProperty(x,"ArrayProperty",3,TRUE);

# do something now...


Return the COM Object for this R Instance

Description

Returns the COM object for this R Instance.

Use this function to e.g. pass a handle to the running R COM server to another COM obejct.

The object will be released automatically when the last reference to the object is removed. To speed up this process, assign some NULL value as soon as you don't need the object any more.

Usage

comThis()

Value

comThis returns an object of class "COMObject" representing the IStatConnector/IDispatch of the current R.

Author(s)

Thomas Baier

Examples

# get access to R
## Not run: x<-comThis();

# do something with R
## Not run: comInvoke(x,"SetSymbol","abc",1);


Trace information about SEXP

Description

This function will trace all passed parameters (variables, constants etc) to the R console.

Use this function to find out what rcom thinks about the parameters (e.g. which data types are recognized).

Use this function for debugging purposes to find out why rcom fails.

Usage

comTrace(x)

Arguments

x expression (variable, constant) to trace

Author(s)

Thomas Baier


Trace information about the passed object

Description

This function will trace information about the COM object passed as parameter.

Use this function to find out what rcom thinks about the object.

Use this function for debugging purposes to find out why rcom fails.

Usage

comTraceObject(handle)

Arguments

handle COM object (class "COMObject") as returned by e.g. comCreateObject

Author(s)

Thomas Baier


Deregister the COM server from the registry

Description

This function will deregister the COM server and its associated type library from the registry/system.

Call this function before uninstalling the package to clean-up the registry.

Usage

comUnregisterRegistry()

Author(s)

Thomas Baier

See Also

comRegisterRegistry


Terminate the COM server

Description

This function will deregister the COM server at runtime.

Technically, this will unregister the class factory in the system, so future calls to CoCreateInstance() from client applications will fail.

Usage

comUnregisterServer()

Author(s)

Thomas Baier

See Also

comRegisterServer, comUnregisterRegistry


install statconnDCOM

Description

Installs RExcel, an Excel add-in connecting R and Excel on Windows, by running a Windows installer progam creating its own uninstaller.

Usage

installstatconnDCOM()

Details

rcom requires an installation of statconnDCOM to work. installstatconnDCOM() downloads a binary installer statconnDCOM.latest.exe from its web site, http://rcom.univie.ac.at/.

It is possible to install (or update) statconnDCOM on a machine without Internet access. To accomplish this, download the current version from http://rcom.univie.ac.at/, transfer it to the machine without Internet access and run in on this machine. Administrator privileges are needed to run this installer.


Invoke a function (method) an a COM Object

Description

Invokes a function (method) on a COM object.

Usage

## S3 method for class 'COMObject':
handle$method,...

Arguments

handle | COM object (class "COMObject") as returned by e.g. comCreateObject
method | name of method to call as a character string
... | parameters passed when calling the method

Value

The return value of $.COMObject depends on the function (method) called.

Author(s)

Gabor Grothendieck

See Also

comInvoke, [[.COMObject, [[<-.COMObject


Read One of a COM Object's Properties

Description

Reads one of the COM object's properties.

Usage

## S3 method for class 'COMObject':
handle[[property,...]]

Arguments

handle | COM object (class "COMObject") as returned by e.g. comCreateObject
property | name of property to get as a character string
... | optional additional arguments for property specification (e.g. index for an array)

Value

When reading a property, the return value depends on the (data) type of the property to read.

Author(s)

Gabor Grothendieck

See Also

comGetProperty, $.COMObject

Examples

# start up excel
## Not run: x<-comCreateObject("Excel.Application")

# retrieve the "Visible" property
## Not run: v <- x[["Visible"]]


Write One of a COM Object's Properties

Description

Writes one of the COM object's properties.

Usage

## S3 method for class 'COMObject':
handle[[property,...]]<-value

Arguments

handle | COM object (class "COMObject") as returned by e.g. comCreateObject
property | name of property to get as a character string
... | optional additional arguments for property specification (e.g. index for an array)
value | the value the property should be set to

Value

The return value is the object handle.

Author(s)

Gabor Grothendieck

See Also

comSetProperty, $.COMObject

Examples

# start up excel
## Not run: x<-comCreateObject("Excel.Application")

# and make it visible
## Not run: x[["Visible"]] <- TRUE;