C3POServer

Used to initialize the C3PO. Every C3PO must support this interface.

Properties

The following table lists the properties for this class, along with access and descriptions.

Property

Access

Description

CommandFactory

R/O

CommandFactory object. Invoked to obtain the command source for the C3PO. The C3POServer may return NULL. If the C3POServer returns NULL (or returns an error), the C3POManager will skip the C3PO. That is, the Manager will consider the NULL (or error) to be a skip signal. Such a signal is not considered a system error by the Manager and will not propagate the error outside of the Manager.

Description

R/O

String. Returns a readable description of the C3POServer.

EventMonitor

R/O

EventMonitor object. Invoked to obtain the event monitor for the C3PO. If the C3POServer returns NULL (or an error), the C3POManager will skip the C3PO. Such a signal is not considered a system error and will not propagate the error outside of the C3POManager.

IconFactory

R/O

IconFactory object. Invoked to obtain the icon source for the C3PO. If the C3POServer returns NULL (or an error), the C3POManager will skip the C3PO. Such a signal is not considered a system error and will not propagate the error outside of the C3POManager.

Methods

Boolean CanShutdown( )
  • Invoked to query whether or not the C3POServer can shut down. Typically used when the C3POServer has a window open on the UI screen and shutdown is possible. Each C3POServer is guaranteed to have CanShutdown queried at least once before the C3PO system shuts down.
  • CanShutdown is a request from the C3POManager to a C3PO. It is not a request to shut down a C3PO, but to shut down the C3POManager and disconnect the C3PO. Typically a C3PO shuts down with the C3POManager.
  • No particular C3PO order can be relied on for querying the CanShutdown property.
  • A returned error is interpreted by the C3POManager to be a positive response (that is, the C3PO can be shut down). This prevents a an errant C3PO from causing an interference, making it impossible to exit the client.
DeInit( )
  • Terminates the relationship of the C3POManager with the C3POServer. This is a separate issue from the shutdown sequence (including shutdown events). For example, a C3PO can be unloaded from memory as a runtime optimization in which case the C3POServer first receives calls to CanShutdown followed by DeInit. The C3PO is unloaded, but the client application has not necessarily terminated.
  • The C3POManager pointer passed in to C3POServer::Init is still valid while calling DenInit. However, when DeInit returns, the C3POManager pointer is not guaranteed to be valid. The C3POServer must release all holds to the C3POManager during the DeInit( ) call.
  • One call to DeInit is issued to the C3POServer for each C3PO client using the C3PO system. C3PO software that wants to be capable of loading into multiple clients (irrespective of process boundaries) should be multiple-instance OLE servers. That is, a new C3POServer object should be created for each C3POManager that wants to use the services of the C3PO. By tracking the Manager pointer for each C3POServer, the C3PO can determine which requests are being issued from which clients.
  • Errors returned from this method are ignored by the C3POManager.
Init( C3POManager Manager )
  • The Manager object is valid until a future DeInit call is made. That is, the C3PO does not need to AddRef this object, but can simply store it for the life of the C3PO until DeInit is called.
  • This method is the first method invoked in the C3POServer object when loading a C3POServer. If the server fails this method (via HRESULT), the C3POServer is unloaded.
  • One call to Init is issued to the C3POServer for each C3PO client using the C3PO system. C3PO software that wants to be capable of loading into multiple clients (irrespective of process boundaries) should be multiple-instance OLE servers. That is, a new C3POServer object should be created for each C3POManager that wants to use the services of the C3PO. By tracking the Manager pointer for each C3POServer, the C3PO can determine which requests are being issued from which clients.
  • An error returned from this method will abort the loading of the C3POServer.

Remarks

None.