IRunningObjectTable Interface

IID_IRunningObjectTable

{00000010-0000-0000-C000-000000000046}

The IRunningObjectTable interface manages access to the Running Object Table (ROT), a globally accessible look-up table on each workstation. A workstation's ROT keeps track of those objects that can be identified by a moniker and that are currently running on the workstation. When a client tries to bind a moniker to an object, the moniker checks the ROT to see if the object is already running; this allows the moniker to bind to the current instance instead of loading a new one.

The ROT contains entries of the form:

(pmkObjectName, pUnkObject)

The pmkObjectName element is a pointer to the moniker that identifies the running object. The pUnkObject element is a pointer to the running object itself. During the binding process, monikers consult the pmkObjectName entries in the Running Object Table to see if an object is already running.

Objects that can be named by monikers must be registered with the ROT when they are loaded and their registration must be revoked when they are no longer running.

You typically use the ROT if you're a moniker provider (that is, you hand out monikers identifying your objects to make them accessible to others) or if you're writing your own moniker class (that is, implementing the IMoniker interface).

If you are a moniker provider, you register your objects with the ROT when they begin running and revoke their registrations when they are no longer running. This enables the monikers that you hand out to be bound to running objects. You should also use the ROT to record the object's last modification time. You can get an IRunningObjectTable interface pointer to the local ROT by calling the GetRunningObjectTable function.

The most common type of moniker provider is a compound-document link source. This includes server applications that support linking to their documents (or portions of a document) and container applications that support linking to embeddings within their documents. Server applications that do not support linking can also use the ROT to cooperate with container applications that support linking to embeddings.

If you are writing your own moniker class, you use the ROT to determine whether a object is running and to retrieve the object's last modification time. You can get an IRunningObjectTable interface pointer to the local ROT by calling the IBindCtx::GetRunningObjectTable method on the bind context for the current binding operation. Moniker implementations should always use the bind context to acquire a pointer to the ROT; this allows future implementations of IBindCtx to modify binding behavior. Note that you must also implement the IROTData interface on your moniker class in order to allow your monikers to be registered with the ROT.

Methods in VTable order

IUnknown Methods

Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IRunningObjectTable Methods

Description

Register

Registers an object with the ROT.

Revoke

Revokes an object's registration with the ROT.

IsRunning

Checks whether an object is running.

GetObject

Returns a pointer to an object given its moniker.

NoteChangeTime

Notifies the ROT that an object has changed.

GetTimeOfLastChange

Returns the time an object was last changed.

EnumRunning

Returns an enumerator for the ROT.

Register

FUNCTION IRunningObjectTable_Register ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL grfFlags AS DWORD _

, BYVAL pUnkObject AS DWORD _

, BYVAL pmkObjectName AS DWORD _

, BYREF pdwRegister AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[3] USING IRunningObjectTable_Register (pthis, grfFlags, pUnkObject, pmkObjectName, pdwRegister) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

FUNCTION IRunningObjectTable_Register ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL grfFlags AS DWORD _

, BYVAL pUnkObject AS DWORD _

, BYVAL pmkObjectName AS DWORD _

, BYREF pdwRegister AS DWORD _

  ) AS LONG

  ! push pdwRegister

  ! push pmkObjectName
  ! push pUnkObject
  ! push grfFlags
  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+12]
  ! mov  FUNCTION, eax

END FUNCTION

Revoke

FUNCTION IRunningObjectTable_Revoke ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwRegister AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[4] USING IRunningObjectTable_Revoke (pthis, dwRegister) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

FUNCTION IRunningObjectTable_Revoke ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwRegister AS DWORD _

  ) AS LONG

  ! push dwRegister

  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+16]
  ! mov  FUNCTION, eax

END FUNCTION
 

IsRunning

FUNCTION IRunningObjectTable_IsRunning ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pmkObjectName AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[5] USING IRunningObjectTable_IsRunning (pthis, pmkObjectName) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

FUNCTION IRunningObjectTable_IsRunning ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pmkObjectName AS DWORD _

  ) AS LONG
 

  ! push pmkObjectName

  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+20]
  ! mov  FUNCTION, eax

END FUNCTION

GetObject

FUNCTION IRunningObjectTable_GetObject ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pmkObjectName AS DWORD _

, BYREF ppunkObject AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[6] USING IRunningObjectTable_GetObject (pthis, pmkObjectName, ppunkObject) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

FUNCTION IRunningObjectTable_GetObject ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pmkObjectName AS DWORD _

, BYREF ppunkObject AS DWORD _

  ) AS LONG

  ! push ppunkObject

  ! push pmkObjectName
  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+24]
  ! mov  FUNCTION, eax

END FUNCTION

NoteChangeTime

FUNCTION IRunningObjectTable_NoteChangeTime ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwRegister AS DWORD _

, BYREF pfileTime AS FILETIME _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[7] USING IRunningObjectTable_NoteChangeTime (pthis, dwRegister, pfileTime) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

FUNCTION IRunningObjectTable_NoteChangeTime ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL dwRegister AS DWORD _

, BYREF pfileTime AS FILETIME _

  ) AS LONG

  ! mov  eax, pfileTime

  ! push eax
  ! push dwRegister
  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+28]
  ! mov  FUNCTION, eax

END FUNCTION

GetTimeOfLastChange

FUNCTION IRunningObjectTable_GetTimeOfLastChange ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pmkObjectName AS DWORD _

, BYREF pfileTime AS FILETIME _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[8] USING IRunningObjectTable_GetTimeOfLastChange (pthis, pmkObjectName, pfileTime) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION
 

FUNCTION IRunningObjectTable_GetTimeOfLastChange ( _

  BYVAL pthis AS DWORD PTR _

, BYVAL pmkObjectName AS DWORD _

, BYREF pfileTime AS FILETIME _

  ) AS LONG
 

  ! mov  eax, pfileTime

  ! push eax
  ! push pmkObjectName
  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+32]
  ! mov  FUNCTION, eax

END FUNCTION
 

EnumRunning

FUNCTION IRunningObjectTable_EnumRunning ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppenumMoniker AS DWORD _

  ) AS LONG

  LOCAL HRESULT AS LONG
  CALL DWORD @@pthis[9] USING IRunningObjectTable_EnumRunning (pthis, ppenumMoniker) TO HRESULT
  FUNCTION = HRESULT

END FUNCTION

FUNCTION IRunningObjectTable_EnumRunning ( _

  BYVAL pthis AS DWORD PTR _

, BYREF ppenumMoniker AS DWORD _

  ) AS LONG

  ! push ppnumMoniker
  ! mov  eax, pthis
  ! push eax
  ! mov  eax, dword ptr[eax]
  ! call dword ptr[eax+36]
  ! mov  FUNCTION, eax

END FUNCTION

Example

The following example shows the display names of all the objects currently registered in the Running Object Table (ROT)

#COMPILE EXE
#DIM ALL
#INCLUDE "Win32Api.inc"
 

FUNCTION PBMAIN

   LOCAL hr AS LONG
   LOCAL ppbc AS DWORD
   LOCAL pprot AS DWORD
   LOCAL ppenumMoniker AS DWORD
   LOCAL ppMoniker AS DWORD
   LOCAL pceltFetched AS DWORD
   LOCAL strDisplayName AS STRING

   ' Get a pointer to the Running Object Table (ROT)
   hr = CreateBindCtx(0, ppbc)
   IF hr <> %S_OK OR ppbc = %NULL THEN GOTO Terminate
   hr = IBindCtx_GetRunningObjectTable(ppbc, pprot)
   IF hr <> %S_OK OR pprot = %NULL THEN GOTO Terminate
 

   ' Get a pointer to the moniker enumerator
   hr = IRunningObjectTable_EnumRunning(pprot, ppenumMoniker)
   IF hr <> %S_OK OR ppenumMoniker = %NULL THEN GOTO Terminate

   ' Enumerate the monikers and retrieve the display name
   ppMoniker = 0
   DO
      hr = IEnumMoniker_Next(ppenumMoniker, 1, VARPTR(ppMoniker), pceltFetched)
      IF hr <> %S_OK OR ppMoniker = 0 OR pceltFetched = 0 THEN EXIT DO
      hr = IMoniker_GetDisplayName(ppMoniker, ppbc, %NULL, strDisplayName)
      IF ppMoniker THEN IUnknown_Release ppMoniker
      IF hr <> %S_OK THEN EXIT DO
      MSGBOX strDisplayName
   LOOP

   ' Release the enumerator
   IF ppenumMoniker THEN IUnknown_Release ppenumMoniker

Terminate:

   ' Cleanup
   IF ppbc THEN IUnknown_Release ppbc
   IF pprot THEN IUnknown_Release pprot

END FUNCTION