Registration
Register:
PROC [
name: ROPE, -- name under which command is registered.
createProc: CreateProc, -- proc invoked to instantiate.
clientData: REF, -- passed to cmdProc to instantiate.
destroyProc: DestroyProc -- proc invoked to act on instances.
];
Register a command, whose CreateProc can then be invoked using CreateInstance. To unregister a command, use createProc = NIL.
Session Management
CreateSession:
PROC [sessionName:
ROPE]
RETURNS [newSession: Session];
Create a new session. There may be multiple sessions with the same name.
DestroySession:
PROC [session: Session];
Destroy the session and all command instances associated with it. Destroying a session more than once is okay.
SessionNameFromSession: PROC [session: Session] RETURNS [sessionName: ROPE];
SessionIsDead: PROC [session: Session] RETURNS [dead: BOOL];
Instance Management
Instance: TYPE ~ REF; -- identifies instance; opaque to BridgeExec package.
Session: TYPE ~ REF SessionObject;
SessionObject: TYPE; -- identifies session to BridgeExec package; opaque to clients.
CreateProc:
TYPE ~
PROC [
s: NetworkStream, -- stream for communication with host.
args: ROPE, -- as sent from host, with leading blanks stripped but no other processing performed. The command name is not included. By convention, args are terminated (rather than separated) by CRs.
session: Session, -- session in which this instance is being created.
clientData: REF -- the clientData that was passed to AddCommand.
]
RETURNS [
instance: Instance -- newly-created instance, or NIL.
];
DestroyProc:
TYPE ~
PROC [
instance: Instance, -- instance to be killed.
clientData: REF -- NIL if called by BridgeExec package.
];
CreateInstance:
PROC[cmdName:
ROPE, s: NetworkStream, args:
ROPE, session: Session]
RETURNS [instance: Instance];
Create a command instance by calling the CreateProc for the named command with the given parameters. Fails if the session is dead, returning NIL.
DestroyInstance:
PROC [session: Session, instance: Instance, clientData:
REF];
Call the DestroyProc associated with cmdInstance, after deleting the instance from the session data structure. If the instance isn't there, do nothing. This is the only way for a client to destroy a command instance. Succeeds even if the session is dead.