Important:
This is retired content. This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This content may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.
A version of this page is also available for
4/8/2010

This interface allows any apartment in a process to get access to an interface implemented on an object in any other apartment in the process. The three methods allow you to do the following:

  • Register an interface as a global (process-wide) interface.

  • Get a pointer to that interface from any other apartment through a cookie.

  • Revoke the global registration of an interface.

The IGlobalInterfaceTableinterface is an efficient way for a process to store an interface pointer in a memory location that can be accessed from multiple apartments within the process, such as process-wide variables and agile (free-threaded marshaled) objects containing interface pointers to other objects.

An agile object is unaware of the underlying COM infrastructure in which it runs — in other words, what apartment, context, and thread it is executing on.

The object may be holding on to interfaces that are specific to an apartment or context. For this reason, calling these interfaces from wherever the agile component is executing may not always work properly.

The global interface table avoids this problem by guaranteeing that a valid proxy (or direct pointer) to the object is used, based on where the agile object is executing.

The global interface table is not portable across process or machine boundaries, so it cannot be used in place of the normal parameter-passing mechanism.

When to Implement

You should not implement this interface. The standard implementation provides complete thread-safe functionality.

When to Use

Use this interface when an interface implemented on an object in one apartment must be stored in memory accessible for use by other apartments. To create the global interface table object and get a pointer to this interface, make the following call.

Copy Code
CoCreateInstance(CLSID_StdGlobalInterfaceTable,
							NULL,
							CLSCTX_INPROC_SERVER,
							IID_IGlobalInterfaceTable,
							(void **)&gpGIT)
Note:
When creating the global interface table object using the above call, you must link to the library Uuid.lib. This will resolve the external symbols CLSID_StdGlobalInterfaceTable and IID_IGlobalInterfaceTable.

There is a single instance of the global interface table per process, so all calls to this function in a process return the same instance.

After calling the CoCreateInstancefunction, register the interface you want to make available process-wide from the apartment in which it resides with a call to the IGlobalInterfaceTable::RegisterInterfaceInGlobalmethod.

This supplies a pointer to a cookie (through the pdwCookieparameter) that identifies the interface and its location. An apartment that wants a pointer to this interface then calls the IGlobalInterfaceTable::GetInterfaceFromGlobalmethod with this cookie, and the implementation then supplies an interface pointer to the calling apartment.

To revoke the interface's global registration, any apartment may call the IGlobalInterfaceTable::RevokeInterfaceFromGlobalmethod.

A simple example of its use would be when you want to pass an interface pointer on an object in a single-threaded apartment (STA) to a worker thread in another apartment. Rather than having to marshal it into a stream and pass the stream to the worker thread as a thread parameter, this interface allows you simply to pass a cookie.

When you register the interface in the global interface table, you get a cookie that you can use instead of passing the actual pointer whenever you need to pass the pointer either to a non-method parameter that is going to another apartment (as a parameter to the ThreadProcfunction through the CreateThreadfunction) or to in-process memory accessible outside your apartment.

Care is required because using global interfaces places the extra burden on the programmer for managing problems such as race conditions and mutual exclusion, which are associated with accessing global state from multiple threads simultaneously.

Methods

The following table shows the methods for this interface in the order that the compiler calls the methods. Like all COM interfaces, this interface inherits the methods for the IUnknowninterface.

IUnknown method Description

QueryInterface

Returns pointers to supported interfaces.

AddRef

Increments reference count.

Release

Decrements reference count.

IGlobalInterfaceTable method Description

RegisterInterfaceInGlobal

Permits access to a given interface from any apartment in a process.

RevokeInterfaceFromGlobal

Revokes the registration of a global (process-wide) interface.

GetInterfaceFromGlobal

Gives the calling apartment access to an interface registered as global.

Remarks

To determine whether the platform supports this interface, see Determining Supported COM APIs.

Requirements

Header objidl.h, objidl.idl
Library ole32.lib, uuid.lib
Windows Embedded CE Windows CE 3.0 and later
Windows Mobile Windows Mobile Version 5.0 and later

See Also