IGlobalInterfaceTable

[New for Windows NT 4.0 Service Pack 3.]

Allows any apartment (either single- or multi-threaded) in a process to get access to an interface implemented on an object in any other apartment in the process. There are three methods, which allow you to register an interface as global (process-wide), to get a pointer to that interface from any other apartment through a "cookie", and to revoke the global registration.

This interface can be an efficient way for a process to store an interface pointer in a memory that may be accessed from multiple apartments within the process, such as process global variables and free-threaded objects containing interface pointers to non-free-threading objects. This mechanism is not portable across process or machine boundaries, so cannot be use in place of the normal parameter passing mechanism.

Note  This is available only on Windows NT 4.0, Service Pack 3 and later. It is not available on Windows95.

When to Implement

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

When to Use

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

CoCreateInstance(CLSID_StdGlobalInterfaceTable,
                            NULL,
                            CLSCTX_INPROC_SERVER,
                            IID_IGlobalInterfaceTable,
                            (void **)&gpGIT)
 

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 the call to the CoCreateInstance, register the interface of interest from the apartment in which it resides with a call to the RegisterInterfaceInGlobal method. This supplies a "cookie" that identifies the interface and its location. An apartment that wants a pointer to this interface then calls the GetInterfaceFromGlobal method with this cookie, and the implementation then supplies an interface pointer to the calling apartment in the proper way. To revoke the global registration, any apartment may call the RevokeInterfaceFromGlobal method.

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 to simply 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 ThreadProc via CreateThread), or to in-process memory accessible outside your apartment.

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

This interface also makes another previously difficult problem simpler for the programmer to deal with. This occurs when an in-process free-threaded object aggregates the free-threaded marshaler and also holds (as member variables) interface pointers to other objects which themselves are not free-threaded and do not aggregate the free-threaded marshaler. If the outer object gets marshaled to another apartment and the application calls on it, and the object tries to call on any of its member variable interface pointers that are not free-threaded or are proxies to objects in other apartments, it may get incorrect results or the error RPC_E_WRONG_THREAD, since the inner interface is only designed to be callable from the apartment in which it was first stored in the member variable.

To solve this problem, the outer object aggregating the free-threaded marshaler should call the RegisterInterfaceInGlobal method on the inner interface and store the resulting cookie in its member variable instead of storing the actual interface pointer. When the outer object wants to call on an inner object's interface pointer, it should call GetInterfaceFromGlobal, use the returned interface pointer, then Release it. When the outer object goes away, it should call RevokeInterfaceFromGlobal to remove the interface from the global interface table.

Methods in Vtable Order

QuickInfo

  Windows NT: Use version 5.0 or later.
  Windows: Unsupported.
  Windows CE: Unsupported.
  Header: Declared in objidl.h.