Interface IRunningObjects

This document covers the following topics:


Purpose

This interface is an iterator across the names of the objects that are contained in the running objects table (ROT). The ROT is a system table that is provided and maintained by Windows. It allows applications to make the objects or documents on which the user is currently working available to other applications.

Each object contained in this table is identified by a so-called "moniker". A moniker is a name that follows a specific syntax. For instance, there are file monikers that identify a file in the file system. A file moniker in its readable form is nothing else than a file name with full path name, like c:\MyDoc.doc. As another example, there are URL monikers that identify a resource in the internet and the protocol to be used to access it. A URL moniker in its readable form is just a common URL, like http://www.myorg.org/MyDoc.doc.

An application that wants to access an object in the ROT specifies the moniker that identifies the object and receives an interface pointer (an object handle) to the object.

Applications often enter the object or document on which the user is currently working in the ROT.

Example

If you open the document c:\MyDoc.doc in Microsoft Word, Microsoft Word will enter the name of this document (that is: c:\MyDoc.doc) and an interface pointer to this document into the ROT.

When a Natural Studio session is started, Natural Studio enters the Automation root interface INatAutoStudio of this session into the ROT. The interface is identified by a name built as follows:

NaturalStudio/<version>/<userid>/>processid>

Example

NaturalStudio/n.n/SCULLY/42

where n.n is the product version.

By specifying this name, other applications can retrieve the Automation root interface in the ROT and use it to access the Natural Studio session.

The interface IRunningObjects allows iterating across the names of all objects currently contained in the ROT. The found names can then be used in the method INaturalXUtilities::BindToObject to retrieve an interface pointer (object handle) to the corresponding object.

Example

In the following sample program, the characters n.n stand for the Natural product version. Please, replace these characters by the current Natural product version if you want to run the sample program.

define data
local
1 #util handle of object
1 #studio handle of object
1 #objects handle of object
1 #progs handle of object
1 #prog handle of object
1 #rot handle of object
1 #ro (a) dynamic
end-define
*
* Create an instance of the Utilities class.
create object #util of 'SoftwareAG.NaturalX.Utilities.5'
if #util eq null-handle
  escape routine
end-if
*
* Retrieve the running objects table.
send 'GetRunningObjects' to #util return #rot
if #rot eq null-handle
  escape routine
end-if
*
* Iterate across the running objects table.
repeat
  send 'Next' to #rot return #ro
  if #ro eq ' '
    escape bottom
  end-if
* If we hit a running Natural Studio session,...
  if substring(#ro,1,17) eq 'NaturalStudio/n.n'
*   ...we access it,...
    send 'BindToObject' to #util
    with #ro (ad=o) return #studio
*   ...open a Program Editor in that session...
    #objects := #studio.objects
    #progs := #objects.programs
    send 'Add' to #progs
    with 1009 return #prog
*   ...and display the identifier of this session in the editor.
    compress 'This is' #ro to #ro
    #prog.source := #ro
  end-if
end-repeat
*
end

Methods

The following methods are available:

Next

Returns the name of the next object in the ROT. The name can then be used in the method INaturalXUtilities::BindToObject to retrieve an interface pointer (object handle) to the corresponding object.

Parameters

Name Natural Type Variant Type Remark
Return value A VT_BSTR  
Return Value

The name of the next object in the ROT.

Reset

Resets the iterator to its initial state. After having called Reset, a subsequent call to Next returns the name of the first object in the ROT.