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 [
nsp: NetworkStreamPair, -- streams 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, nsp: NetworkStreamPair, args:
ROPE, session: Session, close:
PROC [nsp: NetworkStreamPair]]
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. close is a top level proc called by DestroyInstance on nsp.
DestroyInstance:
PROC [session: Session, instance: Instance, clientData:
REF ¬
NIL];
Call the DestroyProc associated with cmdInstance, after deleting the instance from the session data structure, and closing the network stream. 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.