Description
This interface provides the procedures for managing recorded voice utterances. See /Indigo/Voice/®/Top/Bluejay for a discussion of tunes, the unit of allocation for voice utterances. VoiceDB supplies a database for associating a unique voiceFileID representing a single use of a tune (tunes are re-usable) with additional information, including speaker, create time, and encryption key.
In addition, one can record references to a voiceFileID as additional unique refIDs associated with the name of the user requesting the reference, the kind of reference, and arbitrary additional information. A voiceFileID for which one or more references exists will not be garbage collected.
This package is implemented as LoganBerry databases, local and/or remote.
Interface procedures
Open:
PROC[ dbName, instance, localName: Rope.
ROPE←
NIL ]
RETURNS [ handle: VoiceDBHandle, openEc: ErrorCode←NIL, expl: Rope.ROPE ];
This needs to be done only once per session per chosen database configuration. VoiceDB is responsible for re-establishing communications and so on when the handle is presented in one of the following operations and something goes wrong.
dbName is the prefix for the primary voice database being opened.
///Strowger/tunes => ///Strowger/Tunes.df and ///Strowger.TunesRefs.df.
If instance is non-nil, it represents the RPC instance of Loganberry to import. Otherwise dbName is taken to define a local Loganberry file.
localName is the prefix for a local backup copy of the database, using the same rules as above. Useful only when dbName is remote, created when the remote db becomes unavailable. Writes occur here; reads try here first, then the main db if available. It is the option of this package to decide when to copy local entries to the database. (What to do when consistency errors occur in that case?)
The resulting handle contains the open-file designators of the two related voice databases.
Open does not raise any interface errors; if an anticipated error occurs, ec and expl contain the error parameters. This allows Open to return a handle in the event that the Open failed but the problem may not persist.
N.B. Open is idempotent; it is always permissible to Open the database again. Any client that wishes to deal with this database can Open it independently.
Create:
PROC[
handle: VoiceDBHandle,
tune: INT,
creator: Rope.ROPE←NIL, -- default is credentials of this machine.
interval: Thrush.VoiceInterval←[],
key: Thrush.EncryptionKey←NULL,
otherAttributes: LoganBerry.Entry←NIL
]
RETURNS [voiceFileID: Rope.ROPE, entry: LoganBerry.Entry];
Returns entire entry as entered in TuneDB.
Creator of a tune must call Create to record tune's existence permanently and to provide a storage place (insecure, at present) for its encryption key.
Retain:
PROC[
handle: VoiceDBHandle,
voiceFileID: Rope.ROPE,
refID: Rope.ROPE,
refIDType: Rope.ROPE, -- provides interpretation for meaning of refID
creator: Rope.ROPE←NIL, -- Default is this machine's credentials
otherAttributes: LoganBerry.Entry ← NIL -- other things to store with this value
]
RETURNS [entry: LoganBerry.Entry]; -- entire entry as entered in TuneRefDB
refID is a unique value representing caller's interest in the voiceFileID. refIDType not only defines the semantics of refID (if any), but also protects against inadvertent identical refID entries. Two refID's are in fact equal iff refID and refIDType match. The caller can associate any other desired attributes with the reference (see LoganBerry for format). Retain can be called more than once with different voiceFileID values, since a refID may refer to more than one utterance.
Forget:
PROC[
handle: VoiceDBHandle,
refID: Rope.ROPE,
refIDType: Rope.ROPE
];
This reference is no longer of interest.
Query:
PROC [
handle: VoiceDBHandle,
voiceFileID: Rope.ROPE←NIL,
refID: Rope.ROPE←NIL,
refIDType: Rope.ROPE←NIL
] RETURNS [
tune: Thrush.Tune,
interval: Thrush.VoiceInterval,
key: Thrush.EncryptionKey,
voiceEntry: LoganBerry.Entry,
refEntry: LoganBerry.Entry
];
Either voiceFileID or (refID and refIDType) must be non-NIL. If all three are present, it's a programming error.
Returns both entries (only voiceEntry, if the reference information is not provided), breaking out the more useful typed information as a convenience.
voiceEntry is NIL if no matching value is found.
Error:
ERROR[ec: ErrorCode, explanation: Rope.
ROPE←
NIL];
Can be raised by any VoiceDB procedure. Errors we have not contemplated will propogate.
ErrorCode:
TYPE =
ATOM;
-- {
$dbNotFound, -- A problem requiring administrative assistance.
$invalid, -- A problem requiring administrative assistance.
Either discovered at open time or during normal operations.
$notAvailable, -- Can occur at any time. Explanation may say why and how long.
$communications, -- Can occur at any time. Attempt to reach data base failed due to communications problems. Should not occur when a local backup is specified.
$voiceIDNotUnique, -- Each should be created but once
$refIDNotFound, -- in a Forget operation.
$clientError, -- Caller supplied a meaningless value or is executing an invalid or disallowed operation (writing a read-only Database, for instance).
};