The participant record consists of a participant identifier, a user record, a terminal name and a timestamp taken at the moment when the user joined the session. The session description finally consists of the session address, the application name, the optional title name, the session state, the session start time and a list of participant records:
struct SessionDescription{
PoolName pn;
SessionId id;
ApplicationName an;
TitleNameF tn;
SessionState state;
ParticipantRecords prs;
Typ::Date start;
};
The session description is available to every session participant, i.e., it can be accessed inde-pendently from the application via the control panel. Applications are likely to supplement the APMT session description with application and session specific information that can only be accessed via the application itself.
7.5 Terminal Control Interfaces
This section presents the various interfaces of the terminal control. It starts with a description of the principal interfaces visible to control panels and application pools, and continues with a description of the interfaces of the user session object. The interfaces of the terminal control are depicted in Figure 6.5 on page 112.
7.5.1 Interface Tc::Terminal
Tc::Terminal is the public interface of the terminal. It contains attributes that describe ter-minal characteristics, the operationfinger() that allows other users to find out about who is currently logged, and the operation knock() via which a textual message can be communi-cated to the currently logged user. The most important operation it defines is the operation invite() that allows an application to invite a user to its session:
void invite(in Atyp::User user, in Pac::Participant sc,
in Typ::InfIdents termobjects, in Atyp::InvitationInfo info)
raises (NobodyThere,
Ex::NotCompatible, Ex::NoSuchUser);
The parameteruser is the identifier of the invited user. The terminal control checks this iden-tifier against the one of the user that is currently logged. If there is a mismatch, it will raise the exception Ex::NoSuchUser. If there is currently nobody logged it will raise the exception NobodyThere. The parameter termobjects is the minimal list of interfaces that the termi-nal needs to implement in order to be able to participate in the application. If the termitermi-nal does not support all of the interfaces mentioned in the list it will raise the exception Ex::NotCom-patible. The parameterinfo contains a session description that helps the user in his deci-sion whether to accept the invitation or not. The parametersc is a reference to an interface of the participation control that the terminal control will use to asynchronously respond to the invitation. The response to an invitation is asynchronous because it is assumed that the caller of theinvite() operation does not want to block for the time it takes the user to decide upon an invitation. The caller of theinvite() operation will typically release the binding to theTc::
Terminal interface right after the call completes.
7.5.2 Interface Tc::PanelTerminalControl
Tc::PanelTerminalControl is the interface of the terminal control towards a control panel. Every terminal has a generic control panel, and allows users to import a private control panel from an application pool. A user that wants to log to a terminal first starts the generic control panel. The generic control panel contacts his user agent in order to retrieve the user record, and registers him with the terminal control:
void register(in Atyp::UserRecord user) raises (RegistrationError);
If the user does not have a user agent he is asked by the control panel to provide the informa-tion that is contained in the user record. Once a user is registered he can access the services of the terminal control. A user terminates a terminal session by deregistering from the terminal control with a call toderegister(). Deregistration causes the termination of all applications started by the user. The terminal will also quit all application sessions in which the terminal participates.
After successful registration of the user the control panel may retrieve a stringified reference to theTc::Terminal interface and send it to the user agent. This allows the user agent to for-ward invitations to the terminal. Applications will normally send invitations to user agents, and not directly to terminals. The control panel may also retrieve a reference to an application con-trol interface via which applications can be started:
ApplicationControl get_application_control();
This interface allows for instance to import control panels. An imported control panel gets a reference to the Tc::PanelTerminalControl interface from the terminal control. It does not need to register with the terminal control, and has immediately the same access rights to the terminal control as the generic control panel. Once the imported control panel is running the user will stop to use the generic control panel. However, he will be able to resort to it at any time if the imported control panel does not work satisfactory.
The terminal control communicates with its control panels via events. Control panels regis-ter for regis-terminal control events with the following operation:
CosEventChannelAdmin::ConsumerAdmin register_terminal_events();
The CosEventChannelAdmin::ConsumerAdmin interface allows a control panel to con-nect a CosEventComm::PushConsumer or CosEventComm::PullConsumer interface to the event channel. The terminal control maintains a single event channel for control panels, which means that all control panels see exactly the same events. The terminal control generates for instance events when applications are started by other applications, when applications are ready, and when a message arrived via the knock() operation in the interface Tc::Termi-nal. An important event is the invitation event:
const string InvitationEventK =
"Tc:PanelTerminalControl:Invitation";
struct InvitationEventD { Atyp::InvitationInfo info;
InvitationKey key;
boolean rejected;
};
The event data contains the invitation information that was communicated to the terminal con-trol via theinvite() operation in theTc::Terminal interface, a flag indicating if the termi-nal control already rejected the invitation due to compatibility problems, and an invitation key that the control panel uses in its response to identify the previous invitation:
UserSession invite_accept(in InvitationKey key) raises (Ex::NoSuchKey,
Ex::ResourceProblem,
Atyp::SessionAccessDenied);
oneway void invite_reject(in InvitationKey key);
If the user accepts the invitation, the terminal control contacts the participation control of the application, which may actually reject the terminal, for instance due to resource problems that did not exist at the time the invitation was sent, or because the invitation was cancelled by the application. The invite_accept() operation blocks until the remote participation control accepts or rejects the terminal. In case the terminal is accepted, a reference to a new instance of aTc::UserSession interface is returned to the control panel.
The control panel may get references to all user session objects, including those that were started by yellow page applications. The Tc::UserSession interface allows the control panel to discover and access all objects that the respective application has created on the termi-nal, and to call compound operations on all terminal servers owned by an application.
7.5.3 Interface Tc::ApplicationControl
Tc::ApplicationControl is the interface via which a control panel or an application may start an application or join a session on an application pool. The most important operation in this interface isstart():
UserSession start(in Atyp::PoolName pool,
in Atyp::ApplicationNameF application, in Atyp::TitleNameF title,
in Atyp::SessionId reserved) raises (PoolNameError,
Atyp::NoSuchApplication, Atyp::NoSuchTitle,
Atyp::ApplicationStartupDenied, Atyp::ApplicationStartupFailed, Ex::NotCompatible,
Ex::ResourceProblem);
This operation starts an application in an application pool. The application pool is identified by thepool parameter, and the application by the combination of an application and a title name.
The caller may either give a title name, an application name, or both. The parameter reserved indicates with a non-zero value a previously reserved session identifier that is to be used for the session. The call blocks until the application runs and is initialized, i.e., until there is a certain level of confidence that the application will successfully run on the terminal. A ref-erence to aTc::UserSession interface is returned to the caller via which the application can be monitored and controlled.
The start() operation may already fail locally, for instance if the terminal is unable to construct an IIOP IOR for thePc::Pool interface of the given application pool, or if the ter-minal does not have enough resources to support a new application. It may then fail in an early phase if the contacted application pool does not support the given application or title, or if the user is not authorized to start it. It may further fail because the terminal finds out by itself that it is not compatible with the application. The application pool control allows terminals to test their compatibility before they actually start an application. Application startup may then fail because the application crashes right after startup, or because it cannot serve the requested title to the user. The exceptions that thestart() operation may raise take account of all the men-tioned failure scenarios.
The second important operation inTc::ApplicationControl is join() which allows to join an ongoing application session:
UserSession join(in Atyp::SessionAddress aaddr) raises (Atyp::SessionAccessDenied,....);
The only information needed to join a session is the session address consisting of the applica-tion pool name and a local session identifier. The terminal control first accesses thePc::Pool interface of the application pool where it can get a reference to the Pac::SessionAccess interface of the respective participation control. It then issues a join request to the participation control. This join request returns immediately because it is processed asynchronously. The ter-minal control receives a callback from the participation control once the application or one of the session participants has decided about the request. In case the terminal and its user are accepted, the operationjoin() returns a reference to theTc::UserSession interface of the user session object. It raises the exceptionAtyp::SessionAccessDenied if the application denied session access.
The interface Tc::ApplicationControl further contains a couple of operations that allow to start special applications. The control panel of a user is started with the following operation:
UserSession start_panel(in Atyp::PoolName pool,
in Atyp::TitleName paneluser) raises (....);
A special operation is necessary for this because the control panel has, unlike other applica-tions, the right to retrieve a reference to the Tc::PanelTerminalControl interface. The control panel is identified by a title name, which may for instance be identical with the user name.
Terminal applications are also started via theTc::ApplicationControl interface. The only argument needed for this is an application name:
UserSession start_term_app(in Atyp::ApplicationName application) raises (....);
It can also be imagined to provide a special interface for already running terminal applications that allows them to directly access the terminal control services.
7.5.4 Interface Tc::UserSession
Every application running on the terminal is represented by a user session object in the termi-nal control. TheTc::UserSession interface of the user session object allows a control panel to control an application. Terminal applications and remote applications are handled via differ-ent interfaces that both inherit fromTc::UserSession:
module Tc { ....
interface UserSession {...};
interface RemoteUserSession : UserSession {...};
interface LocalUserSession : UserSession {...};
};
Every running application has a user session identifier that is unique within the terminal:
typedef unsigned long UserSessionId;
A user session is associated with a state:
enum UserSessionState{RUNNING,PAUSED,HIDDEN, HIDDEN_PAUSED,EXITING};
A user may locally pause an application, which means that the terminal servers of the applica-tion stop processing. This does not concern applet handlers, and it also does not concern the processing of control operation requests. A user may further hide an application, in which case it unmaps its graphical user interface and stops all output. An application may also be paused and hidden at the same time, in which case it does not consume any resources and is invisible to the user. The operations inTc::UserSession that influence the user session state are:
void hide();
void show();
void pause();
void continue();
These operations can also be found in the interfaceTs::TerminalServer. The user session object may therefore simply repeat their invocation on every terminal server owned by the application. Since these operations only have a limited effect on the application it is assumed that they do not fail under normal conditions. An eventual failure indicates a major problem that is fatal to the user session as a whole.
A user may also kill the applications that he started, quit the applications that he joined, and remove the user session object:
void kill();
void quit();
void remove();
The kill() operation blocks until the application has terminated. Similarly, the quit() operation blocks until the application has removed all of its terminal servers. Applications will normally provide proprietary ways to quit or kill the application session. It can therefore be assumed that users will rarely need to resort tokill() orquit().
The moduleTc defines the typeRemoteSessionDescription for the description of an application running in an application pool:
struct RemoteSessionDescription { UserSessionId id;
UserSessionState state;
Atyp::SessionDescription globdesc;
Ts::TermServDescriptions terservs;
};
The memberterservs is a list of terminal server descriptions. A terminal server description contains a reference to aTs::TerminalServer interface that allows a control panel to con-tact the respective terminal server and to find out about the objects that it instantiated. The ses-sion description can be retrieved via an operation in theTc::RemoteUserSession interface:
RemoteSessionDescription get_description();
An operation has been chosen rather than an attribute because the terminal control may need to contact the participation control in the application pool in order to get an up-to-date session membership list.
7.5.5 Interface Tc::TerminalControl
Tc::TerminalControl is the interface of running applications to the terminal control. It offers more functionality than any other terminal control interface. The terminal control gives the reference to the Tc::TerminalControl interface not only to terminal applications and remote applications, but also to every terminal server that is activated by an application. Before an application activates a terminal server it may find out what kinds of terminal servers are available:
readonly attribute Typ::InfIdents termservers;
It may also find out what interfaces are supported by the terminal:
Typ::InfIdents challenge(in Typ::InfIdents termobjects);
The parameter termobjects is the list of interfaces in which the application is interested.
The terminal control compares this with the list of available interfaces, and returns the subset
of interfaces that is not supported by the terminal. The challenge() operation is a conve-nient way for applications to find out if a terminal supports certain sets of interfaces. It is not thought to be a compatibility test. The compatibility of the terminal with respect to the applica-tion is tested as part of the startup procedure, i.e., before the applicaapplica-tion even sees a reference to theTc::TerminalControl interface.
The application may activate terminal servers with the following operation:
Ts::TerminalServer get_terminal_server(in Ftyp::NameF name, in Typ::InfIdent server)
raises (....);
The parameterserver is the name of the terminal server that is to be activated. The parameter name allows the application to assign a name to the newly created instance of the terminal server. The terminal control will then register this name and the object reference of the termi-nal server with the local naming service.
Yellow page applications or application pool browsers may want to start other applications on behalf of the user. They may retrieve a reference to the Tc::ApplicationControl interface via the following operation:
ApplicationControl get_application_control();
Imported control panels need to get access to theTc::PanelTerminalControl interface of the terminal control:
PanelTerminalControl get_terminal_control();
This operation will raise the standard security exceptionNO_PERMISSION if it is called by an application that was not started as a control panel.
The application may retrieve a reference to a branch in the naming tree of the local name service that it may freely use for its purposes:
CosNaming::NamingContext get_name_service();
This branch is deleted when the application terminates. It would also be possible to provide a branch in the naming tree that is shared among applications on the terminal and that allows them to discover each other.
Many of the objects that an application owns on a terminal are in fact created by one of its application pool utilities. This means that the application and its applets on the terminal do not automatically have object references to them. An application may get the object references it is interested in from the utilities that created the respective objects, and communicate these refer-ences to its applets, but this is awkward and should be avoided because it puts an unnecessary load on the application. It makes more sense to communicate object references locally to the applets that are interested in them. The application and its utilities may assign a name to every object that they create, as could be seen in the case of terminal servers. If an object is created with a name, the terminal control will advertise its object reference via an entry in the naming tree branch of the application. Most applications will need in addition to that a real handshake procedure that allows them to synchronize with the life-cycle of an object. The interfaceTc::
TerminalControl supports this with four operations and two events. The following two operations are called by factories within terminal servers to indicate the creation or deletion of a named object:
oneway void create_indication(in CosNaming::Name obj_name, in Typ::StringRef obj_ref);
oneway void delete_indication(in CosNaming::Name obj_name);
Applets that want to synchronize with the creation or deletion of named objects call the follow-ing two operations:
boolean create_event(in CosNaming::Name objname, out Typ::StringRef obj_ref);
boolean delete_event(in CosNaming::Name objname);
The operation create_event() returns TRUE if the object exists already, in which case it returns the object reference in the obj_ref parameter. The operation delete_event() returnsTRUE if the object has already been deleted. The following events are issued by the ter-minal control when a named object is created or deleted:
const string CreationEvent = "Tc:TerminalControl:Creation";
struct CreateEventD {
CosNaming::Name obj_name;
Typ::StringRef obj_ref;
};
const string DeleteEventK = "Tc:TerminalControl:Deletion";
typedef CosNaming::Name DeleteEventD;
Applets must separately register for the events in which they are interested:
CosEventChannelAdmin::ConsumerAdmin register_event(in Typ::EventKey key) raises (Ex::NoSuchEvent);
The user session object maintains one event channel per event. This means that an applet must filter the create and delete events that it receives. This is acceptable because it can be assumed that there will be rarely more than one applet per application on the terminal. If this assumption should turn out to be wrong it would be necessary to add functionality to Tc::TerminalCon-trol that allows applets to maintain their own event channels, in which case the user session
The user session object maintains one event channel per event. This means that an applet must filter the create and delete events that it receives. This is acceptable because it can be assumed that there will be rarely more than one applet per application on the terminal. If this assumption should turn out to be wrong it would be necessary to add functionality to Tc::TerminalCon-trol that allows applets to maintain their own event channels, in which case the user session