[ ActionReport, ConversationID, ConvEventBody, InterfaceSpec, NB, nullConvID, nullID, PartyID, Reason, ROPE, SHHH, SmartsID, StateInConv ],

nullConvID: ConversationID = Thrush.nullConvID;

doReports: BOOL¬FALSE,

doPollingTimeouts: BOOL¬TRUE,

pollDefault: INT ¬ 300, -- 5 minutes minimum between probes when disconnected

timeoutInitiating: NAT ¬ 11,

jayTimeout: NAT ¬ 1,

encryptionRequested: BOOLEAN¬TRUE,

waitsForConnect: NAT¬5,

maxProseLength: INT¬1000,

requests: MBQueue.Queue -- requests to report; must be serialized across all instances

];

smartsID: Thrush.SmartsID¬nullID,

partyID: PartyID ¬ nullID,

shh: SHHH¬NIL,

conversations: LIST OF ConvDesc -- of ConvDescs --,

stateChange: CONDITION,

myName: ThSmartsRpcControl.InterfaceName ¬ [],

myRName: ROPE ¬ NIL,

myPassword: RPC.EncryptionKey ¬ NULL,

prevThrushInstance: ROPE ¬ NIL,

pollCondition: CONDITION,

nextScheduledCheck: INT¬0,

lastRemoteRemark: ROPE ¬ NIL, -- print each remote remark once only

voicePath: BOOL ¬ FALSE, -- adjacent Lark is connected

These values are derived from lower-level values.

enabled: BOOL¬FALSE, -- all levels are willing for connection to be maintained.

connected: BOOL ¬ FALSE -- connection is established, and we're registered with Thrush

];

Switching data

situation: Thrush.ConvEventBody, -- amalgam of useful info from last-reported event

previousSituation: Thrush.ConvEventBody, -- helps with hold/active state transitions

Data of use to clients, maintained by FinchSmarts

ultimateState: Thrush.StateInConv ¬ idle, -- last state reached (except for idle)

startTime: BasicTime.GMT¬NULL,

subject: ROPE¬NIL,

numParties: NAT¬0,

numActive: NAT¬0,

numIdle: NAT¬0,

partyInfo: ThParty.PartyInfo¬NIL, -- Complete description as of some recent time

feepInterfaceSpec: Thrush.InterfaceSpec,

feepInterface: LarkFeepRpcControl.InterfaceRecord,

feepShhh: Thrush.SHHH,

Client-maintained data

clientData: REF ¬ NIL,

props: Atom.PropList ¬ NIL,

firstReport: BOOL¬TRUE,

originatorRecorded: BOOL¬FALSE,

reportComplete: BOOL¬FALSE

];

Initialize, then register the specified procedures via RegisterForReports. Solves a mutual dependency: the completion of InitFinchSmarts wants to call ReportSystemState via the registry, but the registry is maintained by a data structure that this procedure creates.

RETURNS [finchIsEnabled: BOOL, finchIsRunning: BOOL, voicePath: BOOL];

finchIsEnabled means InitFinchSmarts has been called more frequently than UninitFinchSmarts; finchIsRunning means Finch and the server are in contact; if false, the next call will attempt to reestablish, but it might fail. voicePath means that the adjacent Lark is registered.

If enabled but not connected, tries to get connected, best way.

convID: Thrush.ConversationID ¬ nullConvID,

rName: ROPE¬NIL,

number: ROPE¬NIL,

useNumber: BOOL¬FALSE];

Uses specified conversation, creates a new one or uses one that's in a sufficiently idle state.

Interpretation of rName and number -- evaluate until action can be taken:

convID: ConversationID,

reason: Thrush.Reason¬$terminating,

comment: ROPE¬NIL,

newState: Thrush.StateInConv ¬ $idle -- Can also be $failed, to terminate with fast-busy and such.

];

Alphabetic characters in feepString are translated to their corresponding digits, based ont he mapping found on most telephone touchpads and dials.

RETURNS [fullRName: ROPE, number: ROPE, homeNumber: ROPE];

Currently-known conversations

RETURNS [value: ROPE, valueLoc: ThParty.Attributes¬NIL];

serviceName: ROPE,

convID: Thrush.ConversationID ¬ nullConvID,

createOK: BOOL¬TRUE,

addOK: BOOL ¬ FALSE

] RETURNS [

nb: NB¬$success,

cDesc: ConvDesc¬NIL

];

Establishes an active conversation with the named voice service, e.g. "recording". Uses specified conversation, creates a new one, or uses one that's in a sufficiently idle state.

If serviceName is NIL, this is a request to establish as innocuous a one-party conversation as possible—preferably in the state $inactive—so that we can talk with our poachee.

If supplied conversation or (if none supplied) is active and addOK, and service is not already a party, bring it in (!)

serviceName: ROPE,

interfaceName: ROPE,

cDesc: ConvDesc¬NIL

] RETURNS [

nb: NB¬$success,

interfaceSpec: Thrush.InterfaceSpec

];

Looks up the interface for the named voice service, e.g. the "VoiceRopeServer" interface for the "recording" service. Clients can then import this interface directly.

If serviceName is NIL, this is a request to obtain the service from our own party, or (more likely, since that's the whole idea) that of its poachee.

IF cDesc#NIL, this is a request to obtain the service from the "other party" in the present conversation; a bit flakey since there could be more than one, in which case it makes an arbitrary choice.

RETURNS [nb: NB¬$success];

Will complain about invalid passwords iff complain=TRUE.

nb: NB¬NIL,

remark: Rope.ROPE,

connected: BOOL,

enabled: BOOL,

voicePath: BOOL,

remoteRemark: Rope.ROPE

]

RETURNS[echoNB: NB] -- A convenience for callers -- ;

Records that Finch is connected or disconnected, enabled or disabled, logs the remark(s) if given, reports new system state to registered clients, returns its NB argument. See FinchSmartsImpl, ThPartyClientImpl.

Used as Key and UserData in the report tree

Call backs

key: ATOM, -- identifies the purpose of this group of procedures

position: INT ¬ 0, -- ordinal within reporting structure; see FinchSmartsImpl

reportSystemState: ReportSystemStateProc,

reportConversationState: ReportConversationStateProc,

reportRequestState: ReportRequestStateProc,

enabled: BOOL¬TRUE -- disable, don't delete

];

enabled is made true through calls to InitFinchSmarts; connected is true only when a server connection has been established. voicePath is true only when the adjacent Lark is connected.

Client-relevant changes in conversation state are reported in gory detail; FinchSmarts is allowed to invent parts of it (e.g., reason and remark fields)

ThSmarts.ReportAction was called; we are willing to pass the report on to this routine. FinchSmarts implementation will locate the relevant action request (e.g., an IntervalSpec) and pass it on with the action report.

N.B.!!! Each registered ReportRequestStateProc must either return actionReport, or return a better value for it. The intended use is for an upstream registered proc. to compute the request value as a function of actionReport and some local state. Downstream procedures get the augmented report. Care must be taken to register these procedures (with the help of the before hint (see RegisterForReports), so that the right thing happens.

If before is true, procs go at front of other, else they go after it.

If other is $all, places this set of procs at head or tail of reporting order (one only each)

Key must be a unique id for an "appearance" of a proc set in the list. It is used to permit new versions to overlay old ones during system development. The "before"-ness cannot change from one version to another within the same virtual memory.

Remove procs from the list of report subscribers. (Actually merely invalidates them, so that their beforeness will not be disturbed.

Distributes a report to all subscribers.