VoiceRopeDB.mesa
Copyright © 1986 by Xerox Corporation. All rights reserved.
Doug Terry, July 28, 1987 9:58:49 pm PDT
Routines for storing voice ropes in a database and manipulating their structure. This interface is internal to the voice rope package.
DIRECTORY
BasicTime USING [GMT, nullGMT],
LoganBerry USING [Entry, OpenDB],
RefID USING [nullID],
Rope USING [ROPE],
Thrush USING [EncryptionKey];
VoiceRopeDB:
CEDAR
DEFINITIONS = {
Handle: TYPE = REF HandleRec;
HandleRec:
TYPE =
RECORD [
voiceRopeDB: LoganBerry.OpenDB ← RefID.nullID,
voiceInterestDB: LoganBerry.OpenDB ← RefID.nullID,
voiceRopeDBName: Rope.ROPE,
voiceInterestDBName: Rope.ROPE
];
TuneID: TYPE = INT;
TuneList: TYPE = LoganBerry.Entry;
Header: TYPE = LoganBerry.Entry;
Interest: TYPE = LoganBerry.Entry;
ID: TYPE = Rope.ROPE;
VoiceRopeInfo:
TYPE ~
RECORD[
vrID: ID ← NIL, -- unique ID of the voice rope
length: INT ← -1, -- length of the voice rope (-1 denotes the whole thing)
creator: Rope.ROPE ← NIL, -- an RName, e.g. "Terry.pa"
timestamp: BasicTime.GMT ← BasicTime.nullGMT, -- time of creation
playAccess: LIST OF Rope.ROPE ← NIL, -- access control list for Play operation
editAccess: LIST OF Rope.ROPE ← NIL, -- access control list for Cat, Substr, Replace
struct: TuneList ← NIL -- the actual voice rope components
];
InterestInfo:
TYPE ~
RECORD[
interestID: ID ← NIL, -- unique ID of the interest
vrID: ID, -- unique ID of a voice rope
class: Rope.ROPE, -- e.g. "TiogaVoice"
refID: Rope.ROPE, -- e.g. "[Ivy]<>User>FileWithVoice.tioga"
creator: Rope.ROPE ← NIL, -- actually an RName, e.g. "Terry.pa"
timestamp: BasicTime.GMT ← BasicTime.nullGMT, -- time interest was registered
data: Rope.ROPE ← NIL -- class-specific data
];
Basic database operations
Error:
ERROR [ec:
ATOM, explanation: Rope.
ROPE ←
NIL];
Most of the errors raised are identical to LoganBerry.Errors.
Open:
PROC [dbName: Rope.
ROPE]
RETURNS [handle: Handle ←
NIL];
Prepares the given database for service.
ReadVoiceRope:
PROC [handle: Handle, ropeID: ID]
RETURNS [header: Header, struct: TuneList];
Returns the structure of the given voice rope.
WriteVoiceRope:
PROC [handle: Handle, vr: VoiceRopeInfo, replace:
BOOLEAN ←
FALSE]
RETURNS [info: VoiceRopeInfo];
Writes the voice rope information into the database. If vr.vrID = NIL then a unique ID will be generated and returned as info.vrID.
DeleteVoiceRope:
PROC [handle: Handle, ropeID: ID];
Deletes the given voice rope (regardless of what interests may exist).
AddInterest:
PROC [handle: Handle, interest: InterestInfo]
RETURNS [info: InterestInfo];
Adds an entry to the interest database if a similar entry does not already exist.
DropInterest:
PROC [handle: Handle, interest: InterestInfo];
Removes an entry from the interest database.
Queries and enumerations
VoiceRopeContainingTune:
PROC [handle: Handle, tune:
INT]
RETURNS [header: Header];
Returns a voice rope containing the given tune, if one exists.
InterestInVoiceRope:
PROC [handle: Handle, ropeID:
ID]
RETURNS [interest: Interest];
Returns an interest for the voice rope, if one exists.
InterestForRef:
PROC [handle: Handle, class: Rope.
ROPE, refID: Rope.
ROPE]
RETURNS [interest: Interest];
Returns an interest with the given class and refID, if one exists.
EnumProc: TYPE = PROC [info: VoiceRopeInfo] RETURNS [continue: BOOLEAN ← TRUE];
EnumerateVoiceRopes:
PROC [handle: Handle, start:
ID ←
NIL, proc: EnumProc];
Calls the enumeration procedure for every voice rope with id greater than start; start=NIL represents the first element of the database. Stops when proc returns FALSE or the end of the database is encountered.
InterestProc: TYPE = PROC [info: InterestInfo] RETURNS [continue: BOOLEAN ← TRUE];
EnumerateInterestClass:
PROC [handle: Handle, class: Rope.
ROPE, proc: InterestProc];
Calls the enumeration procedure for every interest of the given class. Stops when proc returns FALSE or the end of the database is encountered.
Obtaining information
Clients of this interface should never attempt to directly access information in a Header or Interest entry. These routines are used to parse this information and return it in a client-usable form.
UnpackHeader:
PROC [header: Header]
RETURNS [info: VoiceRopeInfo];
Returns the information associated with a voice rope header.
UnpackInterest:
PROC [interest: Interest]
RETURNS [info: InterestInfo];
Returns the information associated with an interest entry.
Voice rope structure
The following routines allow clients to manipulate TuneLists without having to understand their internal representations.
SimpleTuneList:
PROC [tune: TuneID, start:
INT, length:
INT, key: Thrush.EncryptionKey]
RETURNS [list: TuneList];
Builds a tune list with a single tune's information.
NextTuneOnList:
PROC [list: TuneList]
RETURNS [tune: TuneID, start:
INT, length:
INT, key: Thrush.EncryptionKey, rest: TuneList];
Returns information about the next tune on the list; assumes that list really points to a properly structured TuneList so doesn't bother to check attribute types. The rest of the list is returned so this routine can be repetitively called to get all the tunes on the list.
TuneListInterval:
PROC [list: TuneList, start:
INT ← 0, length:
INT ← -1]
RETURNS [new: TuneList];
Returns the tune list representing the structure of the voice rope interval. If the list contains intervals of unspecified length (-1) then the desired voice rope interval may not be determinable and an Error[$UnspecifiedInterval] is raised.
Warning: this operation modifies the original list!
}.
Doug Terry, June 3, 1986 3:30:54 pm PDT
Created internal DB interface.
changes to: DIRECTORY, VoiceRopeDB, OpenDB, ReadVoiceRope, WriteVoiceRope, SimpleTuneList, NextTuneOnList, TuneListInterval
Doug Terry, June 12, 1986 2:32:49 pm PDT
Clarified the distinction between packed entries, such as Headers, and unpacked records, such as VocieRopeInfo.
changes to: DIRECTORY, VoiceRopeDB, ReadVoiceRope, WriteVoiceRope, DeleteVoiceRope, AddInterest, DropInterest, VoiceRopeContainingTune, InterestInVoiceRope, InterestForRef, EnumProc, EnumerateVoiceRopes, EnumerateInterestClass, UnpackHeader, UnpackInterest, TuneListInterval
Doug Terry, August 18, 1986 5:09:02 pm PDT
Minor modifications to some procedure arguments and their types.
changes to: DIRECTORY, VoiceRopeDB, SimpleTuneList, NextTuneOnList, TuneListInterval, WriteVoiceRope, AddInterest
Doug Terry, August 22, 1986 2:33:43 pm PDT
Changes to comments to clarify treatment of length = -1.
changes to: , VoiceRopeDB, Error, WriteVoiceRope, TuneListInterval