The builtin server is built into the Hub. It provides administrative support, as well as an additional body of functionality the MIT group has found useful.
parameter | type | optional | depends on | description/constraints | |
IN: | :parse_frame | frame | the name of the frame is the action | ||
OUT: | :reply_frame | frame | the name of the frame is the return value of the action. If the :parse_frame contains a :domain key/value pair, the :reply_frame is also guaranteed to have the same value for :domain. If the return value of the action is NULL, then the :reply_frame is retrieved from the toplevel frame (the action will have set it). |
The actions are:
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default" |
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default" |
parameter | type | optional | depends on | description/constraints | |
OUT: | :close_off | integer | value is 1 |
parameter | type | optional | depends on | description/constraints | |
OUT: | :greetings | integer | value is 1 |
parameter | type | optional | depends on | description/constraints | |
OUT: | :praise | integer | value is 1 |
parameter | type | optional | depends on | description/constraints | |
OUT: | :vacuous | integer | value is 1 |
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default" | |
:parse_frame | frame | the :parse_frame should have the form
{... :topic {... :name "<name>" ... } ... } |
|||
OUT: | :new_domain | string | Domain being switched to. | ||
:reply_frame | frame | yes | If the domain being switched to was previously encountered, this value is set (a continuation?). | ||
:welcome_frame | frame | yes | If the domain being switched to was not previously encountered, this value is set. |
parameter | type | optional | depends on | description/constraints | |
OUT: | :reply_frame | frame | copies the value of :parse_frame |
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default" | |
OUT: | :reply_frame | frame | will be
{c rejection_<num> :no_parse 1 :domain <domain> } :domain will be set if the session has a domain specified; <num> is an internal index of failed parses. |
parameter | type | optional | depends on | description/constraints | |
IN: | :parse_frame | frame | the parse frame should have the form
... :topic {... :country_code "<country_code>" :area_code "<area_code>" :exchange "<exchange>" :core "<core>" } :calling_domain <optional string: provides domain for session> ... } where the phone number in the result will be <country_code>-<area_code>-<exchange>-<core>. |
||
OUT: | :callback_channel | string | value is "telephone" | ||
:callback_address | string | value is "<country_code>-<area_code>-<exchange>-<core>" |
dispatch_token handles the details of invoking the program named in the :program key (default is "main") using the current message. It creates a new message by changing the name of the frame to the program name and removing the internal Hub state information from the frame. It updates session information from :out_lang, :para_lang, :kv_lang and :domain. The dispatch function dispatch_to_main simply deletes its incoming :program key and calls dispatch_token.
These messages are special because
they will relay arbitrary keys to the new message, not just the keys which
are listed here.
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session | |
:program | string | yes | program name to dispatch to; default is main | ||
:server_id | frame | yes | absence of :session_id | should be {... :server_name <string> :host <string> :port <int> :sock <int> ...}. All keys are optional. Used to compute value of :session_id, which ultimately defaults to "Default" | |
:out_lang | string | yes | output language for the session | ||
:para_lang | string | yes | paraphrase language for the session | ||
:synth_lang | string | yes | synthesizer "language" for the session (that is, the name of the Genesis catalog for transduction from a string to a legal synthesizer input) | ||
:kv_lang | string | yes | key-value "language" for the session | ||
:domain | string | yes | name of the domain. | ||
:utterance_id | integer | yes | the utterance index | ||
:reply_clause_name | string | yes | for generating a :reply_frame for the "local" domain (that is, the builtin server) | ||
:no_abort | (not checked) | yes | value of :session_id and :utterance_id (after computation of output values) | blocks a previously-set abort for all utterances with this :utterance_id |
This message returns NULL.
call_program is a streamlined version of dispatch_token, which does not do any special processing on the current message beyond copying it, removing the Hub state information, and invoking the named program (default is "main"). It returns the final token state of the called program.
This message is special because
it relays arbitrary keys to the called program, and in fact does not pass
the :program key at all. It also returns arbitrary keys.
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session | |
:program | string | yes | program name to dispatch to; default is main |
This message returns a frame.
increment_utterance
increments the various indices for recording how many utterances have been
made.
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default" | |
:domain | string | yes | name of the domain. | ||
OUT: | :utterance_id | integer | new utterance index |
This message returns a frame.
abort_main
sets an abort for a specified utterance. This function returns NULL.
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default" | |
:server_id | frame | yes | absence of :session_id | should be {... :server_name <string> :host <string> :port <int> :sock <int> ...}. All keys are optional. Used to compute value of :session_id, which ultimately defaults to "Default" | |
:utterance_id | integer | yes | utterance index; defaults to the utterance index of the located session |
This message does not return a frame.
new_session
resets a session (opens a new logfile, resets utterance counter). If the
session does not exist, it will be created. To make sure that logfiles
are managed correctly when session IDs are reused, this function only opens
a new logfile the second time it's called and each subsequent time. See
the session
management documentation for details.
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default" |
This message returns a frame.
end_session
terminates the specified session. If a logfile is open, it will be closed.
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default" |
This message returns a frame.
This message returns a destroy token message reply. It does not return a normal reply.
nop is a no-op. It returns what is passed in.
reset_history
saves away the existing history when a domain switch happens, and restores
a previously stored history for the new domain (if it exists).
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default". If there's no session, returns without switching | |
:new_domain | string | name of the new domain |
This message returns a frame.
log_keys invokes the logger. This message is special because it logs whatever keys are in the frame passed to it. The keys will be logged under a timestamped instance of the log_keys operation. This message returns the frame passed to it.
modify_properties
updates properties in either the session or server Hub states. It deletes
before it sets.
parameter | type | optional | depends on | description/constraints | |
IN: | :namespace | string | identifies the Hub namespace to retrieve from (options are server or session) | ||
:properties_to_delete | list | yes | a list of keys to delete from the specified namespace | ||
:properties_to_set | frame | yes | a frame containing key-value pairs to add to the specified namespace (the name of the frame is ignored). |
This message returns NULL. See the Hub properties documentation.
get_properties
retrieves properties for either the session or server Hub states.
parameter | type | optional | depends on | description/constraints | |
IN: | :namespace | string | identifies the Hub namespace to retrieve from (options are server or session) | ||
:properties | list | a list of keys to retrieve from the specified namespace |
This message returns a frame containing the specified keys. See the Hub properties documentation.
set_session
possibly creates a new session, and optionally assigns some session locks
to it.
parameter | type | optional | depends on | description/constraints | |
IN: | :session_id | string | yes | string which identifies the session; defaults to "Default". | |
:lock_info | integer | yes | a logical OR of flags controlling how this session should be locked. See GalSS_EnvSetSession. If absent, the locks from the previous session will be used, if present. | ||
:previous_session_id | string | yes | a session to transfer locks from, if appropriate |
This message returns NULL.
hub_print
prints a message or the contents of a Hub namespace.
parameter | type | optional | depends on | description/constraints | |
IN: | :namespace | string | yes | identifies the Hub namespace to display the contents of | |
:message | string | yes | a string to display | ||
:verbosity | integer | yes | if present, restricts the printing to situations where GAL_VERBOSE exceeds the specified verbosity | ||
:session_locks | integer | yes | if nonzero, causes the Hub to print the status of all session locks | ||
:db | integer | yes | if nonzero, causes the Hub to print the contents of the current session utterance history DB |
This message returns NULL.
hub_break
enters a loop which allows the user to explore the current state of the
Hub.
parameter | type | optional | depends on | description/constraints | |
OUT: | :disable_break | integer | if 1, indicates that the user exited the loop requesting no further breaks |
This message returns a frame
hub_exit causes the Hub to exit gracefully. This message returns NULL.
hub_raise_error
raises an error using GalSS_EnvError.
This function can be useful if you've caught an error using the ERROR:
directive in a Hub program but you still want to raise an error for the
caller.
parameter | type | optional | depends on | description/constraints | |
IN: | :error_description | string | the description of the error to be passed to GalSS_EnvError. |
This message returns NULL.
hub_available_servers
returns the active service types in the Hub. This list may not match the
list of defined service types due to the use of the SERVERS:
directive in the program file.
parameter | type | optional | depends on | description/constraints | |
OUT: | :servers | list of strings | no | a list of names of active service types |
This message returns a frame.
hub_token_owner
returns the name of the service type of the provider originating the current
token.
parameter | type | optional | depends on | description/constraints | |
OUT: | :owner | string | The name of the service type for the provider originating the current token |
This message returns a frame.
hub_pause
sets a pause after each message dispatch. This can be useful for demoing
and debugging.
parameter | type | optional | depends on | description/constraints | |
IN: | :milliseconds | integer | yes | If present, the length of the pause in milliseconds |
This message returns NULL.
hub_set_verbosity
sets the verbosity level for the Hub, in addition to the command line argument
to the Hub and the GAL_VERBOSE environment variable.
parameter | type | optional | depends on | description/constraints | |
IN: | :verbosity | integer | Verbosity level (0 to 6) |
This message returns NULL.
hub_continue
listens for a new message of the specified form and treats it as a reply
or error. See the section on Hub
continuations for a discussion.
parameter | type | optional | depends on | description/constraints | |
IN: | :reply_matches | list of frames | yes | If present, a sequence of frames one of which should match an incoming new message, which will then be treated as a normal reply. Matching is done using Gal_MatchFrame. One of this and :error_matches must be specified. | |
:error_matches | list of frames | yes | If present, a sequence of frames one of which should match an incoming new message, which will then be treated as an error reply. Matching is done using Gal_MatchFrame. One of this and :reply_matches must be specified. | ||
:service_type | string | yes | If present, the name of a service type known to the Hub, which will serve as a filter on which providers will be monitored for new messages | ||
:service_provider | string | yes | If present, the identity or location of a service provider (e.g, audio@localhost:14000 or localhost:14000) which will server a s afilter on which providers will be monitored for new messages |
This message returns the frame which matches one of the elements in :reply_matches or :error_matches.
Copyright (c) 1998 - 2001
The MITRE
Corporation
ALL RIGHTS RESERVED