Compartments
Compartment Types
There are several different types of compartments. There is a global compartment, and each thread manager, document manager, and context can contain a compartment.
The global compartment enables clients to share data across processes. To obtain the global compartment manager, call ITfThreadMgr::GetGlobalCompartment.
The thread manager contains a compartment manager that contains compartments on a per-thread basis. This allows data to be shared within a thread. To obtain a thread manager compartment manager, call ITfThreadMgr::QueryInterface with IID_ITfCompartmentMgr.
Each document manager created also contains a compartment manager. This allows data to be shared within a specific document manager. To obtain the document manager compartment manager, call ITfDocumentMgr::QueryInterface with IID_ITfCompartmentMgr.
Each context created also contains a compartment manager. This allows data to be shared within a specific context. To obtain a context compartment manager, call ITfContext::QueryInterface with IID_ITfCompartmentMgr.
Creating and Deleting a Compartment
A compartment is created the first time ITfCompartmentMgr::GetCompartment is called with the compartment GUID. The installing client should set the initial value of the compartment using ITfCompartment::SetValue. Until a value is set, the compartment value is empty. Because of this, there is no way to verify that the compartment existed before GetCompartment was called. To avoid this situation, the installing client should set the value to some initial value so that other clients can determine if the compartment already exists.
The ITfCompartmentMgr::ClearCompartment method is used to remove a compartment. Any existing references to the compartment are marked invalid.
Obtaining Compartments
Using the ITfCompartmentMgr interface, a client can enumerate compartments by calling ITfCompartmentMgr::EnumCompartments. This method provides an IEnumGUID object that contains the GUIDs of all of the installed compartments.
Using the compartment GUID , ITfCompartmentMgr::GetCompartment is used to obtain a specific compartment. This method provides the caller with an ITfCompartment object that can obtain and set the compartment data.
Receiving Compartment Change Notifications
When the value of a compartment changes, the TSF manager notifies any installed advise sinks that the compartment has changed. To install a compartment change advise sink, create an object that implements ITfCompartmentEventSink. Then call ITfCompartment::QueryInterface with IID_ITfSource on the compartment object to be monitored to obtain an ITfSource interface. Now call ITfSource::AdviseSink with IID_ITfCompartmentEventSink and the pointer to the ITfCompartmentEventSink object. When the value of the compartment changes, the advise sink's ITfCompartmentEventSink::OnChange is called with the GUID of the compartment. The advise sink can call ITfCompartment::GetValue to obtain the new value.
Related topics