home *** CD-ROM | disk | FTP | other *** search
/ Unix System Administration Handbook 1997 October / usah_oct97.iso / rfc / 900s / rfc984.txt < prev    next >
Text File  |  1986-05-01  |  68KB  |  1,768 lines
  1.  
  2.  
  3. Network Working Group                                     David D. Clark
  4. Request for Comments: 984                                Mark L. Lambert
  5.                                 M. I. T. Laboratory for Computer Science
  6.                                                                 May 1986
  7.  
  8.         PCMAIL: A Distributed Mail System for Personal Computers
  9.  
  10.  
  11. 1. Status of this Document
  12.  
  13.    This document is a preliminary discussion of the design of a
  14.    personal-computer-based distributed mail system.  It is published for
  15.    discussion and comment, and does not constitute a standard.  As the
  16.    proposal may change, implementation of this document is not advised.
  17.    Distribution of this memo is unlimited.
  18.  
  19. 2. Introduction
  20.  
  21.    Pcmail is a distributed mail system that provides mail service to an
  22.    arbitrary number of users, each of which owns one or more personal
  23.    computers (PCs).  The system is divided into two halves.  The first
  24.    consists of a single entity called the "repository".  The repository
  25.    is a storage center for incoming mail.  Mail for a Pcmail user can
  26.    arrive externally from the Internet or internally from other
  27.    repository users.  The repository also maintains a stable copy of
  28.    each user's mail state (this will hereafter be referred to as the
  29.    user's "global mail state").  The repository is therefore typically a
  30.    computer with a large amount of disk storage.
  31.  
  32.    The second half of Pcmail consists of one or more "clients". Each
  33.    Pcmail user may have an arbitrary number of clients, which are
  34.    typically PCs.  The clients provide a user with a friendly means of
  35.    accessing the user's global mail state over a network. In order to
  36.    make the interaction between the repository and a user's clients more
  37.    efficient, each client maintains a local copy of its user's global
  38.    mail state, called the "local mail state". Since clients are PCs,
  39.    they may not always have access to a network (and therefore to the
  40.    global mail state in the repository).  This means that the local and
  41.    global mail states may not be identical all the time, making
  42.    synchronization between local and global mail states necessary.
  43.  
  44.    Clients communicate with the repository via the Distributed Mail
  45.    System Protocol (DMSP); the specification for this protocol appears
  46.    in appendix A. The repository is therefore a DMSP server in addition
  47.    to a mail end-site and storage facility.  DMSP provides a complete
  48.    set of mail manipulation operations ("send a message", "delete a
  49.    message", "print a message", etc.).  DMSP also provides special
  50.    operations to allow easy synchronization between a user's global mail
  51.    state and his clients' local mail states.  Particular attention has
  52.    been paid to the way in which DMSP operations act on a user's mail
  53.    state.  All DMSP operations are atomic (that is, they are guaranteed
  54.  
  55.  
  56. Clark & Lambert                                                 [Page 1]
  57.  
  58.  
  59.  
  60. RFC 984                                                         May 1986
  61. PCMAIL
  62.  
  63.  
  64.    either to succeed completely, or fail completely).  A client can be
  65.    abruptly disconnected from the repository without leaving
  66.    inconsistent or damaged mail states.
  67.  
  68.    Pcmail is a mail system for PCs.  Its design has therefore been
  69.    heavily influenced by several characteristics unique to PCs. First,
  70.    PCs are relatively inexpensive.  This means that people may own more
  71.    than one PC, perhaps putting one in an office and one at home.
  72.    Second, PCs are portable.  Most PCs can be packed up and moved in the
  73.    back seat of an automobile, and a few are truly portable--about the
  74.    size of a briefcase--and battery-powered.  Finally, PCs are
  75.    resource-poor.  A typical PC has a small amount (typically less than
  76.    one megabyte) of main memory and little in the way of mass storage
  77.    (floppy-disk drives that can access perhaps 360 kilobytes of data).
  78.  
  79.    Because PCs are relatively inexpensive and people may own more than
  80.    one, Pcmail has been designed to allow users multiple access points
  81.    to their mail state.  Each Pcmail user can have several client PCs,
  82.    each of which can access the user's mail by communicating with the
  83.    repository over a network.  The client PCs all maintain local copies
  84.    of the user's global mail state, and synchronize the local and global
  85.    states using DMSP.
  86.  
  87.    It is possible, even likely, that many PCs will only infrequently be
  88.    connected to a network (and thus be able to communicate with the
  89.    repository).  The Pcmail design therefore allows two modes of
  90.    communication between repository and client. "Interactive mode" is
  91.    used when the client PC is always connected to the network.  Any
  92.    changes to the client's local mail state are immediately also made to
  93.    the repository's global mail state, and any incoming mail is
  94.    immediately transmitted from repository to client.  "Batch mode" is
  95.    used by clients that have infrequent access to the repository.  Users
  96.    manipulate the client's local mail state, queueing the changes as
  97.    "actions".  When next connected to the repository, the actions are
  98.    transmitted, and the client's local mail state is synchronized with
  99.    the repository's global mail state.
  100.  
  101.    Finally, the Pcmail design minimizes the effect of using a
  102.    resource-poor PC as a client.  Mail messages are split into two
  103.    parts:  a "descriptor" and a "body".  The descriptor is a capsule
  104.    message summary whose length (typically about 100 bytes) is
  105.    independent of the actual message length.  The body is the actual
  106.    message text, including an RFC-822 standard message header. While the
  107.    client may not have enough storage to hold a complete set of
  108.    messages, it can always hold a complete set of descriptors, thus
  109.  
  110.  
  111.  
  112.  
  113. Clark & Lambert                                                 [Page 2]
  114.  
  115.  
  116.  
  117. RFC 984                                                         May 1986
  118. PCMAIL
  119.  
  120.  
  121.    providing the user with at least a summary of his mail state.
  122.    Message bodies can be pulled over from the repository as client
  123.    storage becomes available.
  124.  
  125.    The remainder of this document is broken up into the following
  126.    sections: first, there is a detailed description of the repository
  127.    architecture.  This is followed by a description of DMSP, its
  128.    operations, and motivation for its design.  A third section describes
  129.    client architecture.  Another section describes a typical DMSP
  130.    session between the repository and a client.  The final section
  131.    discusses the current Pcmail implementation.
  132.  
  133. 3. Repository Architecture
  134.  
  135.    A machine running repository code is typically a medium-to-large size
  136.    computer with a large amount of disk storage.  It must also be a
  137.    permanent network site, since client PCs communicate with the
  138.    repository over a network, and rely on the repository's being
  139.    available at any time.
  140.  
  141.    The repository must perform several tasks.  First, and most
  142.    importantly, the repository must efficiently manage a potentially
  143.    large number of users and their mail states.  Mail must be reliably
  144.    stored in a manner that makes it easy for multiple clients to access
  145.    the global mail state and synchronize their local mail states with
  146.    the global state.  Second, the repository must be able to communicate
  147.    efficiently with its clients.  The protocol used to communicate
  148.    between repository and client must be reliable and must provide
  149.    operations that (1) allow typical mail manipulation, and (2) support
  150.    Pcmail's distributed nature by allowing efficient synchronization
  151.    between local and global mail states.  Third, the repository must be
  152.    able to process mail from sources outside the repository's own user
  153.    community (a primary outside source is the Internet).  Internet mail
  154.    will arrive with a NIC RFC-822 standard message header; the recipient
  155.    names in the message must be properly translated from the RFC-822
  156.    namespace into the repository's namespace.
  157.  
  158.    3.1. Management of user mail state
  159.  
  160.       Pcmail divides the world into a community of users.  Each user is
  161.       referred to by a user object.  A user object consists of a unique
  162.       name, a password (which the user's clients use to authenticate
  163.       themselves to the repository before manipulating a global mail
  164.       state), a list of "client objects" describing those clients
  165.       belonging to the user, and a list of "mailbox objects".
  166.  
  167.       A client object consists of a unique name and a status.  A user
  168.  
  169.  
  170. Clark & Lambert                                                 [Page 3]
  171.  
  172.  
  173.  
  174. RFC 984                                                         May 1986
  175. PCMAIL
  176.  
  177.  
  178.       has one client object for every client he owns; a client cannot
  179.       communicate with the repository unless it has a corresponding
  180.       client object in a user's client list.  Client objects therefore
  181.       serve as a means of identifying valid clients to the repository.
  182.       Client objects also allow the repository to manage local and
  183.       global mail state synchronization; the repository associates with
  184.       every global state change a list of client objects corresponding
  185.       to those clients which have not recorded the global change
  186.       locally.
  187.  
  188.       A client's status is either "active" or "inactive".  The
  189.       repository defines inactive clients as those clients which have
  190.       not connected to the repository within a set time period (one week
  191.       in the current Pcmail implementation).  When an inactive client
  192.       does connect to the repository, the repository notifies the client
  193.       that it has been "reset".  The repository resets a client by
  194.       marking all messages in the user's mail state as having changed
  195.       since the client last logged in.  When the client next
  196.       synchronizes with the repository, it will receive a complete copy
  197.       of the repository's global mail state.  A forced reset is
  198.       performed on the assumption that enough global state changes occur
  199.       in a week that the client would spend too much time performing an
  200.       ordinary local state-global state synchronization.
  201.  
  202.       Messages are stored in mailboxes.  Users can have an arbitrary
  203.       number of mailboxes, which serve both to store and to categorize
  204.       messages.  Since there can be any number of mailboxes, messages
  205.       can be categorized to an arbitrarily fine degree.  A mailbox
  206.       object both names a mailbox and describes its contents. Mailboxes
  207.       are identified by a unique name; their contents are described by
  208.       three numeric values.  The first is the total number of messages
  209.       in the mailbox, the second is the total number of unseen messages
  210.       (messages that have never been seen by the user via any client) in
  211.       the mailbox, and the third is the next available message unique
  212.       identifier (UID).  This information is stored in the mailbox
  213.       object to allow clients to get a summary of a mailbox's contents
  214.       without having to read all the messages within the mailbox.
  215.  
  216.       Associated with each mailbox are an arbitrary number of message
  217.       objects.  Each message is broken into two parts--a "descriptor",
  218.       which contains a summary of useful information about the message,
  219.       and a "body", which is the message text itself, including NIC
  220.       RFC-822 message header.  Each message is assigned a monotonically
  221.       increasing UID based on the owning mailbox's next available UID.
  222.       Each mailbox has its own set of UIDs which, together with the
  223.       mailbox name and user name, uniquely identify the message within
  224.       the repository.
  225.  
  226.  
  227. Clark & Lambert                                                 [Page 4]
  228.  
  229.  
  230.  
  231. RFC 984                                                         May 1986
  232. PCMAIL
  233.  
  234.  
  235.       A descriptor holds the following information: the message UID, the
  236.       message size in bytes and lines, four "useful" message header
  237.       fields (the "date:", "to:", "from:", and "subject:" fields), and
  238.       two groups of eight flags each.  The first group of flags is
  239.       system defined.  These flags mark whether the message has never
  240.       been seen, whether it has been deleted, whether it is a forwarded
  241.       message, and whether the message has been expunged. The remaining
  242.       four flags are reserved for future use.  The second group of flags
  243.       is user defined.  The repository never examines these flags
  244.       internally; instead they can be used by application programs
  245.       running on the clients.  Descriptors serve as an efficient means
  246.       for clients to get message information without having to waste
  247.       time retrieving the message from the repository.
  248.  
  249.    3.2. Repository-to-RFC-822 name translation
  250.  
  251.       "Address objects" provide the repository with a means for
  252.       translating the RFC-822-style mail addresses in Internet messages
  253.       into repository names.  The repository provides its own namespace
  254.       for message identification.  Any message is uniquely identified by
  255.       the triple (user-name, mailbox-name, message-UID).  Any mailbox is
  256.       uniquely identified by the pair (user-name, mailbox-name).  Thus
  257.       to send a message between two repository users, a user would
  258.       address the message to (user-name, mailbox-name).  The repository
  259.       would deliver the message to the named user and mailbox, and
  260.       assign it a UID based on the requested mailbox's next available
  261.       UID.
  262.  
  263.       In order to translate between RFC-822-style mail addresses and
  264.       repository names, the repository maintains a list of address
  265.       objects.  Each address object is an association between an
  266.       RFC-822-style address and a (user-name, mailbox-name) pair.  When
  267.       mail arrives from the Internet, the repository can use the address
  268.       object list to translate the recipients into (user-name,
  269.       mailbox-name) pairs and route the message correctly.
  270.  
  271. 4. Communication Between Repository and Client: DMSP
  272.  
  273.    The Distributed Mail System Protocol (DMSP) is a block-stream
  274.    protocol that defines and manipulates the objects mentioned in the
  275.    previous section.  It has been designed to work with Pcmail's
  276.    single-repository/multiple-client model of the world.  In addition to
  277.    providing typical mail manipulation functions, DMSP provides
  278.    functions that allow easy synchronization of global and local mail
  279.    states.
  280.  
  281.    DMSP is implemented on top of the Unified Stream Protocol (USP),
  282.  
  283.  
  284. Clark & Lambert                                                 [Page 5]
  285.  
  286.  
  287.  
  288. RFC 984                                                         May 1986
  289. PCMAIL
  290.  
  291.  
  292.    specified in MIT-LCS Technical Memo 255.  USP provides a reliable
  293.    virtual circuit block-stream connection between two machines.  USP
  294.    defines a basic set of data types ("strings", "integers", "booleans",
  295.    etc.).  Instances of these data types are grouped in an
  296.    application-defined order to form USP blocks.  Each USP block is
  297.    defined by a numeric "block type"; a USP application can thus
  298.    interpret a block's contents based on knowledge of the block's type.
  299.    DMSP consists of a set of operations, each of which is comprised of
  300.    one or more different USP blocks that are sent between repository and
  301.    client.
  302.  
  303.    A DMSP session proceeds as follows: a client begins the session with
  304.    the repository by opening a USP connection to the repository's
  305.    machine.  The client then authenticates both itself and its user to
  306.    the repository with a "login" operation.  If the authentication is
  307.    successful, the user performs an arbitrary number of DMSP operations
  308.    before ending the session with a "logout" operation (at which time
  309.    the connection is closed by the repository).
  310.  
  311.    Because DMSP can manipulate a pair of mail states (local and global)
  312.    at once, it is extremely important that all DMSP operations are
  313.    atomic.  Failure of any DMSP operation must leave both states in a
  314.    consistent, known state.  For this reason, a DMSP operation is
  315.    defined to have failed unless an explicit acknowledgement is received
  316.    by the operation initiator.  This acknowledgement can take one of two
  317.    basic forms, based on two broad categories that all DMSP operations
  318.    fall into.  First, an operation can be a request to perform some mail
  319.    state modification, in which case the repository will acknowledge the
  320.    request with either an "ok" or a "failure" (in which case the reason
  321.    for the failure is also returned).  Second, an operation can be a
  322.    request for information, in which case the request is acknowledged by
  323.    the repository's providing the information to the client.  Operations
  324.    such as "delete a message" fall into the first category; operations
  325.    like "send a list of mailboxes" fall into the second category.
  326.  
  327.    Following are a list of DMSP operations by object type, their block
  328.    types and arguments, and their expected acknowledgement block types.
  329.    Each DMSP block has a different number; the first digit of each block
  330.    type defines the object being manipulated: Operations numbered 5xx
  331.    are general, operations numbered 6xx are user operations, operations
  332.    numbered 7xx are client operations, operations numbered 8xx are
  333.    mailbox and address operations, and operations numbered 11xx are
  334.    message operations.
  335.  
  336.    Blocks marked "=>" flow from client to repository; blocks marked "<="
  337.    flow from repository to client.  If more than one block can be sent,
  338.    the choices are delimited by "or" ("|") characters.
  339.  
  340.  
  341. Clark & Lambert                                                 [Page 6]
  342.  
  343.  
  344.  
  345. RFC 984                                                         May 1986
  346. PCMAIL
  347.  
  348.  
  349.    For clarity, each block type is put in a human-
  350.    understandable form.  The block number is followed by an operation
  351.    name; this name is never transmitted as part of a USP block.  Block
  352.    arguments are identified by name and type, and enclosed in square
  353.    brackets.  "Record" data types are described by a list of
  354.    "field-name:field-type" pairs contained in square brackets.  "Choice"
  355.    data types are described by a list of "tag:tag-name" pairs contained
  356.    in square brackets.  USP data types are abbreviated as follows:
  357.  
  358.    Primitive data types:
  359.  
  360.       - string: str
  361.  
  362.       - cardinal: card
  363.  
  364.       - long-cardinal: Lcard
  365.  
  366.       - integer: int
  367.  
  368.       - long-integer: Lint
  369.  
  370.       - boolean: bool
  371.  
  372.    Compound data types:
  373.  
  374.       - sequence: SEQ
  375.  
  376.       - array: AR
  377.  
  378.       - record: REC
  379.  
  380.       - choice: CH
  381.  
  382.    4.1. General operations
  383.  
  384.       The first group of DMSP operations perform general functions that
  385.       operate on no one particular class of object.  DMSP has six
  386.       general operations, which provide the following services:
  387.  
  388.       If either a client or the repository thinks the other is
  389.       malfunctioning, they can send an "abort-request".  An
  390.       abort-request is never acknowledged; after the request is sent,
  391.       the sender immediately closes the USP connection and returns
  392.       control to its application.
  393.  
  394.          => 503 (abort-request) [why:str]
  395.  
  396.  
  397.  
  398. Clark & Lambert                                                 [Page 7]
  399.  
  400.  
  401.  
  402. RFC 984                                                         May 1986
  403. PCMAIL
  404.  
  405.  
  406.       DMSP provides a limited remote debugging facility via the
  407.       "start-debug" and "end-debug" operations.  When a client sends a
  408.       "start-debug" request, the repository enables its idea of
  409.       remote-debugging.  The exact definition of remote debugging is
  410.       implementation dependent; the current repository implementation
  411.       simply writes debugging information to a special file.  The
  412.       "end-debug" request disables remote debugging.
  413.  
  414.          => 504 (start-debug) []
  415.  
  416.          <= 500 (ok) [] |
  417.             501 (failure) [why:str]
  418.  
  419.          or
  420.  
  421.          => 505 (end-debug) []
  422.  
  423.          <= 500 (ok) []
  424.  
  425.       In order to prevent protocol version skew between clients and the
  426.       repository, DMSP provides a "send-version" operation.  The client
  427.       supplies its DMSP version number as an argument; the operation
  428.       succeeds if the supplied version number matches the repository's
  429.       DMSP version number.  It fails if the two version numbers do not
  430.       match.
  431.  
  432.          => 506 (send-version) [version-number:card]
  433.  
  434.          <= 500 (ok) [] |
  435.             501 (failure) [why:str]
  436.  
  437.       DMSP also provides clients with the ability to send an arbitrary
  438.       text message to the repository.  The "log-message" operation takes
  439.       as an argument a string of arbitrary length; the repository
  440.       accepts the string; what is done with the string is
  441.       implementation-dependent.
  442.  
  443.          => 507 log-message[message:str]
  444.  
  445.          <= 500 (ok) [] |
  446.             501 (failure) [why:str]
  447.  
  448.       Finally, users can send mail to other users via the "send-message"
  449.       operation.  The message must have an Internet-style header as
  450.       defined by NIC RFC-822.  The repository takes the message and
  451.       distributes it to the mailboxes specified on the "to:", "cc:", and
  452.       "bcc:" fields of the message header.  If one or more of the
  453.  
  454.  
  455. Clark & Lambert                                                 [Page 8]
  456.  
  457.  
  458.  
  459. RFC 984                                                         May 1986
  460. PCMAIL
  461.  
  462.  
  463.       mailboxes exists outside the repository's user community, the
  464.       repository is responsible for handing the message to a local SMTP
  465.       server.
  466.  
  467.       An OK block is sent from the repository only if the entire message
  468.       was successfully transmitted.  If the message was destined for the
  469.       Internet, the send-message operation is successful if the message
  470.       was successfully transmitted to the local SMTP server.
  471.  
  472.          => 508 (send-message) [message:SEQ[str]]
  473.  
  474.          <= 500 (ok) [] |
  475.             501 (failure) [why:str]
  476.  
  477.    4.2. User operations
  478.  
  479.       The next series of DMSP operations manipulates user objects. The
  480.       most common of these operations are "login" and "logout".  A
  481.       client must perform a login operation before being able to access
  482.       a user's mail state.  A DMSP login block contains five items: (1)
  483.       the user's name, (2) the user's password, (3) the name of the
  484.       client performing the login, (4) a flag telling the repository to
  485.       create a client object for the client if one does not exist, and
  486.       (5) a flag set to TRUE if the client wishes to operate in "batch
  487.       mode" and FALSE if the client wishes to operate in "interactive"
  488.       mode.  The flag value allows the repository to tune internal
  489.       parameters for either mode of operation.
  490.  
  491.       The repository can return either an OK block (indicating
  492.       successful authentication), a FAILURE block (indicating failed
  493.       authentication), or a FORCE-RESET block.  This last is sent if the
  494.       client logging in has been marked as "inactive" by the repository
  495.       (clients are marked inactive if they have not connected to the
  496.       repository in over a week).  The FORCE-RESET block indicates that
  497.       the client should erase its local mail state and pull over a
  498.       complete version of the repository's mail state. This is done on
  499.       the assumption that so many mail state changes have been made in a
  500.       week that it would be inefficient to perform a normal
  501.       synchronization.
  502.  
  503.          => 600 (login) [user:str, password:str, client:str,
  504.                          create-client-object?:bool,
  505.                          batch-mode-flag:bool]
  506.  
  507.          <= 500 (ok) [] |
  508.             501 (failure) [why:str] |
  509.             705 (force-client-reset) []
  510.  
  511.  
  512. Clark & Lambert                                                 [Page 9]
  513.  
  514.  
  515.  
  516. RFC 984                                                         May 1986
  517. PCMAIL
  518.  
  519.  
  520.       When a client is finished interacting with the repository, it
  521.       performs a logout operation.  This allows the repository to
  522.       perform any necessary cleanup before closing the USP connection.
  523.  
  524.          => 601 (logout) []
  525.  
  526.          <= 500 (ok) []
  527.  
  528.       DMSP also provides "add-user" and "remove-user" operations, which
  529.       allow system administrators to remotely add new users to, and
  530.       remove users from, the repository.  These operations are
  531.       privileged; the repository authenticates the user requesting the
  532.       operation before performing an add-user or remove-user operation.
  533.       Both operations require the name of the user to be added or
  534.       removed; the add-user operation also requires a default password
  535.       to assign the new user.
  536.  
  537.          => 602 (add-user) [user:str, password:str]
  538.  
  539.          <= 500 (ok) [] |
  540.             501 (failure) [why:str]
  541.  
  542.          => 603 (remove-user) [user:str]
  543.  
  544.          <= 500 (ok) [] |
  545.             501 (failure) [why:str]
  546.  
  547.       A user can change his password via the "set-password" operation.
  548.       The operation works much the same as the UNIX change-password
  549.       operation, taking as arguments the user's current password and a
  550.       desired new password.  If the current password given matches the
  551.       user's current password, the user's current password is changed to
  552.       the new password given.
  553.  
  554.          => 604 (set-password) [old-password:str,
  555.                                 new-password:str]
  556.  
  557.          <= 500 (ok) [] |
  558.             501 (failure) [why:str]
  559.  
  560.  
  561.  
  562.  
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569. Clark & Lambert                                                [Page 10]
  570.  
  571.  
  572.  
  573. RFC 984                                                         May 1986
  574. PCMAIL
  575.  
  576.  
  577.    4.3. Client operations
  578.  
  579.       DMSP provides four operations to manipulate client objects. The
  580.       first, "list-clients", tells the repository to send the user's
  581.       client list to the requesting client.  The list takes the form of
  582.       a series of (name, status pairs).
  583.  
  584.          => 700 (list-clients) []
  585.  
  586.          <= 701 (client-list) [client-list:SEQ[
  587.                                REC[name:str, status:card]]]
  588.  
  589.       The "add-client" operation allows a user to add a client object to
  590.       his list of client objects.  Although the login operation
  591.       duplicates this functionality via the "create-this-client?" flag,
  592.       the add-client operation is a useful means of creating a number of
  593.       new client objects while logged into the repository via an
  594.       existing client.  The add-client operation requires the name of
  595.       the client to add.
  596.  
  597.          => 702 (add-client) [client:str]
  598.  
  599.          <= 500 (ok) [] |
  600.             501 (failure) [why:str]
  601.  
  602.       The most common failure mode for this operation is an attempt to
  603.       add a client that already exists.
  604.  
  605.       The "remove-client" operation removes an existing client object
  606.       from a user's client list.  The client being removed can be the
  607.       client requesting the operation.  The remove-client operation
  608.       requires the name of the client to remove.
  609.  
  610.          => 703 (remove-client) [client:str]
  611.  
  612.          <= 500 (ok) [] |
  613.             501 (failure) [why:str]
  614.  
  615.       The most common failure mode here is an attempt to remove a
  616.       non-existent client.  This is a typical failure mode for any DMSP
  617.       operation which operates on a named object.
  618.  
  619.       The last client operation, "reset-client", causes the repository
  620.       to mark all messages in the user's mail state as having changed
  621.       since the client last logged in.  When a client next synchronizes
  622.       with the repository, it will end up receiving a complete copy of
  623.       the repository's global mail state.  This is useful for two
  624.  
  625.  
  626. Clark & Lambert                                                [Page 11]
  627.  
  628.  
  629.  
  630. RFC 984                                                         May 1986
  631. PCMAIL
  632.  
  633.  
  634.       reasons.  First, a client's local mail state could easily become
  635.       lost or damaged, especially if it is stored on a floppy disk.
  636.       Second, if a client has been marked as inactive by the repository,
  637.       the reset-client operation provides a fast way of resynchronizing
  638.       with the repository, assuming that so many differences exist
  639.       between the local and global mail states that a normal
  640.       synchronization would take far too much time.
  641.  
  642.          => 704 (reset-client) [client:str]
  643.  
  644.          <= 500 (ok) [] |
  645.             501 (failure) [why:str]
  646.  
  647.    4.4. Mailbox operations
  648.  
  649.       DMSP supports five operations that manipulate mailbox objects.
  650.       First, "list-mailboxes" has the repository send to the requesting
  651.       client information on each mailbox.  This information consists of
  652.       the mailbox name, total message count, unseen message count, and
  653.       "next available UID".  This operation is useful in synchronizing
  654.       local and global mail states, since it allows a client to compare
  655.       the user's global mailbox list with a client's local mailbox list.
  656.       The list of mailboxes also provides a quick summary of each
  657.       mailbox's contents without having the contents present.
  658.  
  659.          => 800 (list-mailboxes) []
  660.  
  661.          <= 801 (mailbox-list) [mailbox-list:SEQ[
  662.                                 REC[mailbox:str,
  663.                                     next-UID:Lcard,
  664.                                     num-msgs:card,
  665.                                     num-unseen-msgs:card]]]
  666.  
  667.       The "add-mailbox" has the repository create a new mailbox and
  668.       attach it to the user's list of mailboxes.  An address object
  669.       binding the (user-name, mailbox-name) pair to an RFC-822-style
  670.       address is automatically created and placed in the repository's
  671.       list of address objects.  This allows mail coming from the
  672.       Internet to be correctly routed to the new mailbox.
  673.  
  674.          => 802 (add-mailbox) [mailbox:str]
  675.  
  676.          <= 500 (ok) [] |
  677.             501 (failure) [why:str]
  678.  
  679.       "Remove-mailbox" removes a mailbox from the user's list of
  680.       mailboxes.  All messages within the mailbox are also deleted and
  681.  
  682.  
  683. Clark & Lambert                                                [Page 12]
  684.  
  685.  
  686.  
  687. RFC 984                                                         May 1986
  688. PCMAIL
  689.  
  690.  
  691.       permanently removed from the system.  Any address objects binding
  692.       the mailbox name to RFC-822-style mailbox addresses are also
  693.       removed from the system.
  694.  
  695.          => 803 (remove-mailbox) [mailbox:str]
  696.  
  697.          <= 500 (ok) [] |
  698.             501 (failure) [why:str]
  699.  
  700.       DMSP also has an "expunge-mailbox" operation.  Any message can be
  701.       deleted and "undeleted" at will.  Deletions are made permanent by
  702.       performing an expunge-mailbox operation.  The expunge operation
  703.       causes the repository to look through a named mailbox, removing
  704.       from the system any messages marked "deleted".
  705.  
  706.          => 808 expunge-mailbox[mailbox:str]
  707.  
  708.          <= 500 (ok) [] |
  709.             501 (failure) [why:str]
  710.  
  711.       Finally, "reset-mailbox" causes the repository to mark all the
  712.       messages in a named mailbox as having changed since the current
  713.       client last logged in.  When the client next synchronizes with the
  714.       repository, it will receive a complete copy of the named mailbox's
  715.       mail state.  This operation is merely a more specific version of
  716.       the reset-client operation (which allows the client to pull over a
  717.       complete copy of the user's global mail state).  Its primary use
  718.       is for mailboxes whose contents have accidentally been destroyed
  719.       locally.
  720.  
  721.          => 809 (reset-mailbox) [mailbox:str]
  722.  
  723.          <= 500 (ok) [] |
  724.             501 (failure) [why:str]
  725.  
  726.    4.5. Address operations
  727.  
  728.       DMSP provides three operations that allow users to manipulate
  729.       address objects.  First, the "list-address" operation returns a
  730.       list of address objects associated with a particular (user-name,
  731.       mailbox-name) pair.
  732.  
  733.          => 804 (list-addresses) [mailbox:str]
  734.  
  735.          <= 501 (failure) [why:str] |
  736.             805 (address-list) [address-list:SEQ[str]]
  737.  
  738.  
  739.  
  740. Clark & Lambert                                                [Page 13]
  741.  
  742.  
  743.  
  744. RFC 984                                                         May 1986
  745. PCMAIL
  746.  
  747.  
  748.       The "add-address" operation adds a new address object that
  749.       associates a (user-name, mailbox-name) pair with a given
  750.       RFC-822-style mailbox address.
  751.  
  752.          => 806 (add-address) [mailbox:str,
  753.                                RFC-822-mail-address:str]
  754.  
  755.          <= 500 (ok) [] |
  756.             501 (failure) [why:str]
  757.  
  758.       Finally, the "remove-address" operation destroys the address
  759.       object binding the given RFC-822-style mail address and the given
  760.       (user-name, mailbox-name) pair.
  761.  
  762.          => 807 (remove-address) [mailbox:str,
  763.                                   RFC-822-mail-address:str]
  764.  
  765.          <= 500 (ok) [] |
  766.             501 (failure) [why:str]
  767.  
  768.    4.6. Message operations
  769.  
  770.       The most commonly-manipulated Pcmail objects are messages; DMSP
  771.       therefore provides special message operations to allow efficient
  772.       synchronization, as well as a set of operations to perform
  773.       standard message-manipulation functions.  In the following
  774.       paragraphs, the terms "message" and "descriptor" will be used
  775.       interchangeably.
  776.  
  777.       A client can request a particular message's flag values with the
  778.       "get-descriptor-flags" operation.  The repository sends over an
  779.       array of boolean values, eight of which are system defined, and
  780.       eight of which are user defined and ignored by the repository.
  781.  
  782.          => 1100 (get-descriptor-flags) [mailbox:str,
  783.                                          uid:Lcard]
  784.  
  785.          <= 1101 (descriptor-flags) [flags:SEQ[bool]] |
  786.             501 (failure) [why:str]
  787.  
  788.       A user may request a series of descriptors with the
  789.       "get-descriptors" operation.  The series is identified by a pair
  790.       of message UIDs, representing the lower and upper bounds of the
  791.       list.  Since UIDs are defined to be monotonically increasing
  792.       numbers, a pair of UIDs is sufficient to completely identify the
  793.       series of descriptors.  The repository returns a sequence of
  794.       "choices".  Elements of the sequence can either be descriptors, in
  795.  
  796.  
  797. Clark & Lambert                                                [Page 14]
  798.  
  799.  
  800.  
  801. RFC 984                                                         May 1986
  802. PCMAIL
  803.  
  804.  
  805.       which case the choice is tagged as a descriptor, or they can be
  806.       notification that the requested message has been expunged
  807.       subsequent to the client's last connection to the repository.
  808.  
  809.          => 1102 (get-descriptors) [mailbox:str,
  810.                                     low-UID:Lcard,
  811.                                     high-UID:Lcard]
  812.  
  813.          <= 501 (failure) [why:str] |
  814.             1103 (descriptor-list) [descriptor-list:SEQ[ CH[
  815.                                     expunged[uid:Lcard]
  816.                                     descriptor[REC[UID:Lcard,
  817.                                                    flags:SEQ[bool],
  818.                                                    from-field:str,
  819.                                                    to-field:str,
  820.                                                    date-field:str,
  821.                                                    subject-field:str,
  822.                                                    num-bytes:Lcard,
  823.                                                    num-lines:Lcard]
  824.                                                 ]]]]
  825.  
  826.       The "get-changed-descriptors" operation is intended for use during
  827.       state synchronization.  Whenever a descriptor changes state (is
  828.       deleted, for example), the repository notes those clients which
  829.       have not yet recorded the change locally. Get-changed-descriptors
  830.       has the repository send to the client a given number of
  831.       descriptors which have changed since the client's last
  832.       synchronization.  The list sent begins with the earliest-changed
  833.       descriptor.
  834.  
  835.          => 1105 (get-changed-descriptors) [mailbox:str,
  836.                                             max-to-send:card]
  837.  
  838.          <= 501 (failure) why:str] |
  839.             1103 (descriptor-list) [descriptor-list:SEQ[
  840.                   CH[
  841.                     expunged[uid:Lcard]
  842.                     descriptor[REC[UID:Lcard,
  843.                                    flags:SEQ[bool],
  844.                                    from-field:str,
  845.                                    to-field:str,
  846.                                    date-field:str,
  847.                                    subject-field:str,
  848.                                    num-bytes:Lcard,
  849.                                    num-lines:Lcard]
  850.                                 ]]]]
  851.  
  852.  
  853.  
  854. Clark & Lambert                                                [Page 15]
  855.  
  856.  
  857.  
  858. RFC 984                                                         May 1986
  859. PCMAIL
  860.  
  861.  
  862.       Once the changed descriptors have been looked at, a user will want
  863.       to inform the repository that the current client has recorded the
  864.       change locally.  The "reset-changed-descriptors" causes the
  865.       repository to mark as "seen by current client" a given number of
  866.       changed descriptors, starting with the changed descriptor with
  867.       lowest UID.
  868.  
  869.          => 1106 (reset-changed-descriptors) [
  870.                   mailbox:str,
  871.                   number-to-reset:card]
  872.  
  873.          <= 500 (ok) [] |
  874.             501 (failure) [why:str]
  875.  
  876.       Message bodies are transmitted from repository to user with the
  877.       "get-message-text" operation.  The separation of "get-descriptors"
  878.       and "get-message-text" operations allows clients with small
  879.       amounts of disk storage to obtain a small message summary (via
  880.       "get-descriptors" or "get-changed-descriptors") without having to
  881.       pull over the entire message.
  882.  
  883.          => 1107 (get-message-text)[mailbox:str,
  884.                                     uid:Lcard]
  885.  
  886.          <= 501 (failure) [why:str] |
  887.             1110 (message) [message:SEQ[str]]
  888.  
  889.       Frequently, a message may be too large for some clients to store
  890.       locally.  Users can still look at the message contents via the
  891.       "print-message" operation.  This operation has the repository send
  892.       a copy of the message to a named printer.  The printer name need
  893.       only have meaning to the particular repository implementation;
  894.       DMSP transmits the name only as a means of identification.
  895.  
  896.          => 1108 (print-message) [mailbox:str,
  897.                                   uid:Lcard,
  898.                                   printer-name:str]
  899.  
  900.          <= 500 (ok) [] |
  901.             501 (failure) [why:str]
  902.  
  903.       The user can set and clear any of the 16 descriptor flags with the
  904.       "set-flag" operation.  The desired flag is set or cleared
  905.       according to the operation arguments.
  906.  
  907.  
  908.  
  909.  
  910.  
  911. Clark & Lambert                                                [Page 16]
  912.  
  913.  
  914.  
  915. RFC 984                                                         May 1986
  916. PCMAIL
  917.  
  918.  
  919.          => 1109 (set-flag) [mailbox:str,
  920.                              uid:Lcard,
  921.                              flag-number:card,
  922.                              flag-setting:bool]
  923.  
  924.          <= 500 (ok) [] |
  925.             501 (failure) [why:str]
  926.  
  927.       Copying of one message into another mailbox is accomplished via
  928.       the "copy-message" operation.
  929.  
  930.          => 1111 (copy-message) [source-mailbox:str,
  931.                                  target-mailbox:str,
  932.                                  source-uid:Lcard]
  933.  
  934.          <= 500 (ok) [] |
  935.             501 (failure) [why:str]
  936.  
  937. 5. Client Architecture
  938.  
  939.    Clients are typically PCs; Pcmail's architecture must therefore take
  940.    into account several characteristics common to PCs.  First, PCs are
  941.    cheap, therefore a user may well have more than one.  Second, they
  942.    are portable, therefore they are not expected to be constantly tied
  943.    into a network.  Finally, they are resource-poor, so they are not
  944.    expected to be able to store a significant amount of state
  945.    information locally.  The following subsections describe the
  946.    particular parts of Pcmail's client architecture that address these
  947.    three characteristics.
  948.  
  949.    5.1. Multiple clients
  950.  
  951.       The fact that Pcmail users may own more than one PC forms the
  952.       rationalization for the multiple client model that Pcmail uses.  A
  953.       Pcmail user may have a PC client at home, a PC at an office, and
  954.       maybe even a third portable PC.  Each client maintains a separate
  955.       copy of the user's mail state, hence Pcmail's distributed nature.
  956.       The notion of separate clients allows Pcmail users to access mail
  957.       state from several different locations.
  958.  
  959.  
  960.  
  961.  
  962.  
  963.  
  964.  
  965.  
  966.  
  967.  
  968. Clark & Lambert                                                [Page 17]
  969.  
  970.  
  971.  
  972. RFC 984                                                         May 1986
  973. PCMAIL
  974.  
  975.  
  976.    5.2. Synchronization
  977.  
  978.       Since PCs are fairly portable, the likelihood of a PC's being
  979.       always connected to a network is relatively small.  This is
  980.       another reason for each client's maintaining a local copy of a
  981.       user's mail state.  The user can then manipulate the local mail
  982.       state while not connected to the network (and the repository).
  983.       This immediately brings up the problem of synchronization between
  984.       local and global mail states.  The repository is continually in a
  985.       position to receive global mail state updates, either in the form
  986.       of incoming mail, or in the form of changes from other clients. A
  987.       client that is not always connected to the net cannot immediately
  988.       receive the global changes.  In addition, the client's user can
  989.       make his own changes on the local mail state.
  990.  
  991.       Pcmail's architecture permits efficient synchronization between
  992.       client local mail states and the repository's global mail state.
  993.       Each client is identified in the repository by a client object
  994.       attached to the user.  This object forms the basis for
  995.       synchronization between local and global mail states.  Some of the
  996.       less common state changes include the adding and deleting of user
  997.       mailboxes and the adding and deleting of address objects.
  998.       Synchronization of these changes is performed via DMSP list
  999.       operations, which allow clients to compare their local versions of
  1000.       mailbox and address object lists with the repository's global
  1001.       version and make any appropriate changes.  The majority of
  1002.       possible changes to a user's mail state are in the form of changed
  1003.       descriptors.  Since most users will have a large number of
  1004.       messages, and message states will change relatively often, special
  1005.       attention needs to be paid to message synchronization.
  1006.  
  1007.       An existing descriptor can be changed in one of two ways: first,
  1008.       one of its sixteen flags values can be changed (this encompasses
  1009.       reading an unseen message, deleting a message, and expunging a
  1010.       message).  The second way to change a descriptor is via the
  1011.       arrival of incoming mail or the copying of a message from one
  1012.       mailbox to another.  Both result in a new message being added to a
  1013.       mailbox.
  1014.  
  1015.       In both the above cases, synchronization is required between the
  1016.       repository and every client that has not previously noted a
  1017.       change.  To keep track of which clients have noticed a global mail
  1018.       state change and changed their local states accordingly, each
  1019.       descriptor has associated with it a (potentially empty) "update
  1020.       list" of client objects.  The list identifies those clients which
  1021.       have not yet recorded a change to that descriptor's state.
  1022.  
  1023.  
  1024.  
  1025. Clark & Lambert                                                [Page 18]
  1026.  
  1027.  
  1028.  
  1029. RFC 984                                                         May 1986
  1030. PCMAIL
  1031.  
  1032.  
  1033.       When a client connects to the repository, it executes a DMSP
  1034.       "get-changed-descriptors" operation.  This causes the repository
  1035.       to return a list of all descriptor objects that have the
  1036.       requesting client on their update list.  As the client receives
  1037.       the changed descriptors, it can store them locally, thus updating
  1038.       the local mail state.  After a changed descriptor has been
  1039.       recorded, the client uses the DMSP "reset-descriptors" operation
  1040.       to remove itself from the descriptor's update list.  That
  1041.       descriptor will now not be sent to the client unless (1) it is
  1042.       explicitly requested, or (2) it changes again.
  1043.  
  1044.       In this manner, a client can run through its user's mailboxes,
  1045.       getting all changed descriptors, incorporating them into the local
  1046.       mail state, and marking the change as recorded.
  1047.  
  1048.    5.3. Batch operation versus interactive operation
  1049.  
  1050.       Because of the portable nature of most PCs, they may not always be
  1051.       connected to the repository.  Since each client maintains a local
  1052.       mail state, Pcmail users can manipulate the local state while not
  1053.       connected to the repository.  This is known as "batch" operation,
  1054.       since all changes are recorded by the client and made to the
  1055.       repository's global state in a batch, when the client next
  1056.       connects to the repository.  Interactive operation occurs when a
  1057.       client is always connected to the repository.  In interactive
  1058.       mode, changes made to the local mail state are immediately
  1059.       propagated to the global state via DMSP operations.
  1060.  
  1061.       In batch mode, interaction between client and repository takes the
  1062.       following form:  the client connects to the repository and sends
  1063.       over all the changes made by the user to the local mail state.
  1064.       The repository changes its global mail state accordingly. When all
  1065.       changes have been processed, the client begins synchronization, to
  1066.       incorporate newly-arrived mail, as well as mail state changes by
  1067.       other clients, into the local state.
  1068.  
  1069.       In interactive mode, since local changes are immediately
  1070.       propagated to the repository, the first part of batch-type
  1071.       operation is eliminated.  The synchronization process also
  1072.       changes; interactive clients can periodically poll the repository
  1073.       for a list of changes, synchronizing a small amount at a time.
  1074.  
  1075.  
  1076.  
  1077.  
  1078.  
  1079.  
  1080.  
  1081.  
  1082. Clark & Lambert                                                [Page 19]
  1083.  
  1084.  
  1085.  
  1086. RFC 984                                                         May 1986
  1087. PCMAIL
  1088.  
  1089.  
  1090.    5.4. Message summaries
  1091.  
  1092.       Since PCs are assumed to have little in the way of disk storage, a
  1093.       given client may never have enough room for a complete local copy
  1094.       of a user's global mail state.  This means that Pcmail's client
  1095.       architecture must allow user's to obtain a clear picture of their
  1096.       mail state without having all their messages present.
  1097.  
  1098.       Descriptors provide message information without taking up large
  1099.       amounts of storage.  Each descriptor contains a summary of
  1100.       information on a message.  This information includes the message
  1101.       UID, its length in bytes and lines, its status (encoded in the
  1102.       eight system-defined and eight user-defined flags), and portions
  1103.       of its RFC-822 header (the "to:", "from:", "subject:" and "date:"
  1104.       fields).  All of this information can be encoded in a small
  1105.       (around 100 bytes) data structure whose length is independent of
  1106.       the size of the message it describes.
  1107.  
  1108.       Any client should be able to store a complete list of message
  1109.       descriptors with little problem.  This allows a user to get a
  1110.       complete picture of his mail state without having all his messages
  1111.       present locally.  Short messages can reside on the client, along
  1112.       with the descriptors, and long messages can either be printed via
  1113.       the DMSP print-message operation, or specially pulled over via the
  1114.       fetch-message-text operation.
  1115.  
  1116. 6. Typical Client-Repository Interaction
  1117.  
  1118.    The following example describes a typical communication session
  1119.    between the repository and a client.  The client is one of three
  1120.    belonging to user "Fred".  Its name is "office-client", and since
  1121.    Fred uses the client regularly to access his mail, the client is
  1122.    marked as "active".  Fred has two mailboxes: "main" is where all of
  1123.    his current mail is stored; "archive" is where messages of lasting
  1124.    importance are kept.  The example will run through a simple
  1125.    synchronization operation followed by a series of typical mail state
  1126.    manipulations.  Typically, the synchronization will be performed by
  1127.    an application program that connects to the repository, logs in,
  1128.    synchronizes, and logs out.
  1129.  
  1130.    For the example, all DMSP operations will be shown in a user-readable
  1131.    format.  In reality, the operations would be sent as a stream of USP
  1132.    blocks consisting of a block-type number followed by a stream of
  1133.    bytes representing the block's arguments. Both the block name and its
  1134.    number are included for convenience.
  1135.  
  1136.  
  1137.  
  1138.  
  1139. Clark & Lambert                                                [Page 20]
  1140.  
  1141.  
  1142.  
  1143. RFC 984                                                         May 1986
  1144. PCMAIL
  1145.  
  1146.  
  1147.    In order to access his global mail state, the client software must
  1148.    authenticate Fred to the repository; this is done via the DMSP login
  1149.    operation:
  1150.  
  1151.       600 (login) ["fred", "ajyr63ywg", "office-client",
  1152.                    FALSE, FALSE]
  1153.  
  1154.    This tells the repository that Fred is logging in via
  1155.    "office-client", and that "office-client" is identified by an
  1156.    existing client object attached to Fred's user object.  The second
  1157.    login block argument in an encrypted version of Fred's password.  The
  1158.    final argument tells the repository that Fred's client is not
  1159.    operating in batch mode but rather in interactive mode.
  1160.  
  1161.    Fred's authentication checks out, so the repository logs him in,
  1162.    acknowledging the login request with an OK block.
  1163.  
  1164.    Now that Fred is logged in, he wants to bring
  1165.    "office-client"'s local mail state up to date.  To do this, the
  1166.    client program asks for an up-to-date list of mailboxes:
  1167.  
  1168.       800 (list-mailboxes) []
  1169.  
  1170.    The repository replies with:
  1171.  
  1172.       801 (mailbox-list) [["main", 10, 1, 253],
  1173.                           ["archive", 100, 0, 101]]
  1174.  
  1175.    This tells the client that there are two mailboxes, "main" and
  1176.    "archive".  "Main" has 10 messages, one of which is unseen. The next
  1177.    incoming message will be assigned a UID of 253. "Archive", on the
  1178.    other hand, has 100 message, none of which are unseen.  The next
  1179.    message sent to "archive" will be assigned the UID 101.  There are no
  1180.    new mailboxes in the list (if there were, the client program would
  1181.    create them.  On the other hand, if some mailboxes in the client's
  1182.    local list were not in the repository's list, the program would
  1183.    assume them deleted by another client and delete them locally as
  1184.    well).
  1185.  
  1186.    To synchronize the client need only look at each mailbox's contents
  1187.    to see if (1) any new mail has arrived, or (2) if Fred changed any
  1188.    messages on one of his other two clients subsequent to
  1189.    "office-client"'s last connection to the repository.
  1190.  
  1191.    The client asks for any changed descriptors via the
  1192.    "get-changed-descriptors" operation.  It requests at most ten changed
  1193.    descriptors since storage is very tight on "office-client".
  1194.  
  1195.  
  1196. Clark & Lambert                                                [Page 21]
  1197.  
  1198.  
  1199.  
  1200. RFC 984                                                         May 1986
  1201. PCMAIL
  1202.  
  1203.  
  1204.       1105 (get-changed-descriptors) ["main", 10]
  1205.  
  1206.    The repository responds with:
  1207.  
  1208.       1103 (descriptor-list) [[descriptor[
  1209.                                6,
  1210.                                [T T F F F F F F F F F F F F F F],
  1211.                                "Fred@borax",
  1212.                                "Joe@fab",
  1213.                                "Wed, 23 Jan 86 11:11 EST",
  1214.                                "tomorrow's meeting",
  1215.                                621,
  1216.                                10]]
  1217.                               [descriptor[
  1218.                                10,
  1219.                                [F T F F F F F F F F F F F F F F],
  1220.                                "Fred",
  1221.                                "Freds-secretary",
  1222.                                "Fri, 25 Jan 86 11:11 EST",
  1223.                                "Monthly progress report",
  1224.                                13211,
  1225.                                350]]
  1226.                            ]
  1227.  
  1228.    The first descriptor in the list is one which Fred deleted on another
  1229.    client yesterday.  "Office-client" marks the local version of the
  1230.    message as deleted.  The second descriptor in the list is a new one.
  1231.    "Office-client" adds the descriptor to its local list.  Since both
  1232.    changes have now been recorded locally, the descriptors can be reset:
  1233.  
  1234.       1106 (reset-descriptors) ["main", 2]
  1235.  
  1236.    The repository clears each descriptor's update vector bit
  1237.    corresponding to "office-client"'s client object.  "Main" has now
  1238.    been synchronized.  The client now turns to Fred's "archive" mailbox
  1239.    and asks for the first ten changed descriptors.
  1240.  
  1241.       1105 (get-changed-descriptors) ["archive", 10]
  1242.  
  1243.    The repository responds with
  1244.  
  1245.       1103 (descriptor-list) []
  1246.  
  1247.    The zero-length list tells "office-client" that no descriptors have
  1248.    been changed in "archive" since its last synchronization.  No new
  1249.    synchronization needs to be performed.
  1250.  
  1251.  
  1252.  
  1253. Clark & Lambert                                                [Page 22]
  1254.  
  1255.  
  1256.  
  1257. RFC 984                                                         May 1986
  1258. PCMAIL
  1259.  
  1260.  
  1261.    Fred's client is now ready to pull over the new message so Fred can
  1262.    read it.  The message is 320 lines long; there might not be
  1263.    sufficient storage on "office-client" to hold the new message. The
  1264.    client tries anyway:
  1265.  
  1266.       1107 (fetch-message-text) ["main", 10]
  1267.  
  1268.    The repository begins transmitting the message:
  1269.  
  1270.       1110 (message) ["From: Fred's-secretary",
  1271.                       "To: Fred",
  1272.                       "Subject: Monthly progress report",
  1273.                       "Date: Fri, 25 Jan 86 11:11 EST",
  1274.                       "",
  1275.                       "Dear Fred,",
  1276.                       "Here is this month's progress report",
  1277.                       ...
  1278.                       ]
  1279.  
  1280.    Halfway through the message transmission, "office-client" runs out of
  1281.    disk space.  Because all DMSP operations are defined to be atomic,
  1282.    the portion of the message already transmitted is destroyed locally
  1283.    and the operation fails.  "Office-client" informs Fred that the
  1284.    message cannot be pulled over because of a lack of disk space.  The
  1285.    synchronization process is now finished and Fred's client logs out.
  1286.  
  1287.       601 (logout) []
  1288.  
  1289.    The repository does any housecleaning it needs to do, acknowledges
  1290.    the logout request, and closes the USP connection.
  1291.  
  1292. 7. A Current Pcmail Implementation
  1293.  
  1294.    The following section briefly describes a current implementation of
  1295.    Pcmail that services a small community of users.  The Pcmail
  1296.    repository runs under UNIX on a DEC VAX-750 connected to the
  1297.    Internet.  The clients are IBM PCs, XTs, and ATs.  The network
  1298.    software that communicates with the repository allows only
  1299.    "batch-mode" operation.  Users make local state changes, which are
  1300.    queued until the client connects to the repository.  At that time,
  1301.    the changes are performed and the local and global states
  1302.    synchronized.  The client then disconnects from the repository.
  1303.  
  1304.    Users access and modify their local mail state via a user interface
  1305.    program.  The program uses windows and a full-screen mode of
  1306.    operation.  Users are given a rich variety of commands to operate on
  1307.  
  1308.  
  1309.  
  1310. Clark & Lambert                                                [Page 23]
  1311.  
  1312.  
  1313.  
  1314. RFC 984                                                         May 1986
  1315. PCMAIL
  1316.  
  1317.  
  1318.    individual messages as well as mailboxes.  The interface allows use
  1319.    of any text editor to compose messages, and adds features of its own
  1320.    to make RFC-822-style header composition easier.
  1321.  
  1322.    Synchronization and the processing of queued changes is performed by
  1323.    a separate program, which the user runs whenever he wishes.  The
  1324.    program takes any actions queued while operating the user interface,
  1325.    and converts them into DMSP operations.  All queued changes are made
  1326.    before any synchronization is performed.
  1327.  
  1328.    The limitation of client operation to batch mode was made for the
  1329.    following reasons: first, the implementation is slanted toward use of
  1330.    portable computers as clients.  These computers are rarely connected
  1331.    to the network, making interactive mode unnecessary.  Those clients
  1332.    that are constantly connected to the network run slightly less
  1333.    efficiently than they could (since users must make changes locally
  1334.    and then run the action-processing/synchronization program, rather
  1335.    than simply making changes interactively).
  1336.  
  1337.    Another important reason for limiting operation to batch mode is that
  1338.    it allows a very simple locking scheme to prevent problems raised by
  1339.    concurrent state updates.  A user may have several clients; it is
  1340.    therefore likely that the repository could get into a variety of
  1341.    inconsistent states as different clients try to change the
  1342.    repository's global mail state at the same time.  To prevent these
  1343.    inconsistencies, a user's mail state is locked as soon as a client
  1344.    connects to the repository.  The lock is released when the client
  1345.    disconnects from the repository. This locking scheme is simple to
  1346.    implement, but makes interactive-mode operation very cumbersome: if a
  1347.    user remains constantly connected to the network (i.e. in interactive
  1348.    mode), the repository would be unavailable to any of the user's other
  1349.    clients for an unacceptable length of time.
  1350.  
  1351. 8. Conclusions
  1352.  
  1353.    Pcmail is now used by a small community of people at the MIT
  1354.    Laboratory for Computer Science.  The repository design works well,
  1355.    providing a fairly efficient means of storing and maintaining mail
  1356.    state for several users.  Members of another research group at LCS
  1357.    are currently working on a replicated, scaleable version of the
  1358.    repository designed to support a very large community of users with
  1359.    high availability.  This repository also uses DMSP and has
  1360.    successfully communicated with clients that use the current
  1361.    repository implementation.  DMSP therefore seems to be useable over
  1362.    several flavors of repository design. The clients, being PCs, are
  1363.    unfortunately very limited in the way of resources, making local mail
  1364.    state manipulation difficult at times.  Synchronization is also
  1365.  
  1366.  
  1367. Clark & Lambert                                                [Page 24]
  1368.  
  1369.  
  1370.  
  1371. RFC 984                                                         May 1986
  1372. PCMAIL
  1373.  
  1374.  
  1375.    relatively time consuming due to the low performance of the PCs.  The
  1376.    "batch-mode" of client operation is very useful for portable
  1377.    computers that spend a large percentage of their time unplugged and
  1378.    away from a network. It is somewhat less useful for the majority of
  1379.    the clients, which are always connected to the network and could make
  1380.    good use of an "interactive-mode" state manipulation.
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.  
  1395.  
  1396.  
  1397.  
  1398.  
  1399.  
  1400.  
  1401.  
  1402.  
  1403.  
  1404.  
  1405.  
  1406.  
  1407.  
  1408.  
  1409.  
  1410.  
  1411.  
  1412.  
  1413.  
  1414.  
  1415.  
  1416.  
  1417.  
  1418.  
  1419.  
  1420.  
  1421.  
  1422.  
  1423.  
  1424. Clark & Lambert                                                [Page 25]
  1425.  
  1426.  
  1427.  
  1428. RFC 984                                                         May 1986
  1429. PCMAIL
  1430.  
  1431.  
  1432. I. DMSP Protocol Specification
  1433.  
  1434.    Following is a list of DMSP block types and DMSP operations by object
  1435.    type.  Again, "=>" marks blocks flowing from client to repository;
  1436.    "<=" marks blocks flowing from repository to client.
  1437.  
  1438.       General operations:
  1439.  
  1440.          => or <= 503 (abort-request) [why:str]
  1441.          (no acknowledgement)
  1442.  
  1443.          => 504 (start-debug) []
  1444.          <= 500 (ok) [] |
  1445.             501 (failure) [why:str]
  1446.  
  1447.          => 505 (end-debug) []
  1448.          <= 500 (ok) []
  1449.  
  1450.          => 506 (send-version) [version:card]
  1451.          <= 500 (ok) [] |
  1452.             501 (failure) [why:str]
  1453.  
  1454.          => 507 (log-message) [message:str]
  1455.          <= 500 (ok) [] |
  1456.             501 (failure) [why:str]
  1457.  
  1458.          => 508 (send-message) [message:seq[str]]
  1459.          <= 500 (ok) [] |
  1460.             501 (failure) [why:str]
  1461.  
  1462.       User operations:
  1463.  
  1464.          => 600 (login) [name:str, password:str,
  1465.                          client:str, create-client-object?:bool
  1466.                          batch-mode-flag:bool]
  1467.          <= 500 (ok) [] |
  1468.             501 (failure) [why:str] |
  1469.             705 (force-client-reset) []
  1470.  
  1471.          => 601 (logout) []
  1472.          <= 500 (ok) []
  1473.  
  1474.          => 602 (add-user) [name:str, password:str]
  1475.          <= 500 (ok) [] |
  1476.             501 (failure) [why:str]
  1477.  
  1478.  
  1479.  
  1480.  
  1481. Clark & Lambert                                                [Page 26]
  1482.  
  1483.  
  1484.  
  1485. RFC 984                                                         May 1986
  1486. PCMAIL
  1487.  
  1488.  
  1489.          => 603 (remove-user) [user:str]
  1490.          <= 500 (ok) [] |
  1491.             501 (failure) [why:str]
  1492.  
  1493.          => 604 (set-password) [old:str, new:str]
  1494.          <= 500 (ok) [] |
  1495.             501 (failure) [why:str]
  1496.  
  1497.       Client operations:
  1498.  
  1499.          => 700 (list-clients) []
  1500.          <= 701 (client-list) [client-list:seq[
  1501.                                rec[name:str], status:card]]
  1502.  
  1503.          => 702 (add-client) [client:str]
  1504.          <= 500 (ok) [] |
  1505.             501 (failure) [why:str]
  1506.  
  1507.          => 703 (remove-client) [client:str]
  1508.          <= 500 (ok) [] |
  1509.             501 (failure) [why:str]
  1510.  
  1511.          => 704 (reset-client) [client:str]
  1512.          <= 500 (ok) [] |
  1513.             501 (failure) [why:str]
  1514.  
  1515.       Mailbox operations:
  1516.  
  1517.          => 800 (list-mailboxes) []
  1518.          <= 801 (mailbox-list) [mailbox-list:seq[
  1519.                                 rec[mailbox:str,
  1520.                                     next-uid:lcard,
  1521.                                     num-msgs:card,
  1522.                                     num-unseen-msgs:card]]]
  1523.  
  1524.          => 802 (add-mailbox) [mailbox:str]
  1525.          <= 500 (ok) [] |
  1526.             501 (failure) [why:str]
  1527.  
  1528.          => 803 (remove-mailbox) [mailbox:str]
  1529.          <= 500 (ok) [] |
  1530.             501 (failure) [why:str]
  1531.  
  1532.          => 808 (expunge-mailbox) [mailbox:str]
  1533.          <= 500 (ok) [] |
  1534.             501 (failure) [why:str]
  1535.  
  1536.  
  1537.  
  1538. Clark & Lambert                                                [Page 27]
  1539.  
  1540.  
  1541.  
  1542. RFC 984                                                         May 1986
  1543. PCMAIL
  1544.  
  1545.  
  1546.          => 809 (reset-mailbox) [mailbox:str]
  1547.          <= 500 (ok) [] |
  1548.             501 (failure) [why:str]
  1549.  
  1550.       Address operations:
  1551.  
  1552.          => 804 (list-addresses) [mailbox:str]
  1553.          <= 501 (failure) [why:str] |
  1554.             805 (address-list) [address-list:seq[str]]
  1555.  
  1556.          => 806 (add-address) [mailbox:str, address:str]
  1557.          <= 500 (ok) [] |
  1558.             501 (failure) [why:str]
  1559.  
  1560.          => 807 (remove-address) [mailbox:str, address:str]
  1561.          <= 500 (ok) [] |
  1562.             501 (failure) [why:str]
  1563.  
  1564.       Message operations:
  1565.  
  1566.          => 1100 (get-descriptor-flags) [mailbox:str, uid:lcard]
  1567.          <= 1101 (descriptor-flags) [flags:seq[bool]] |
  1568.             501 (failure) [why:str]
  1569.  
  1570.          => 1102 (get-descriptors) [mailbox:str,
  1571.                                     low-uid:lcard,
  1572.                                     high-uid:lcard]
  1573.          <= 501 (failure) [why:str] |
  1574.             1103 (descriptor-list) [descriptor-list:seq[
  1575.                    ch[
  1576.                      expunged[uid:lcard],
  1577.                      descriptor[rec[uid:lcard,
  1578.                                     flags:seq[bool],
  1579.                                     from-field:str,
  1580.                                     to-field:str,
  1581.                                     date-field:str,
  1582.                                     subject-field:str,
  1583.                                     nun-bytes:lcard,
  1584.                                     num-lines:lcard]
  1585.                           ]]]]
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.  
  1593.  
  1594.  
  1595. Clark & Lambert                                                [Page 28]
  1596.  
  1597.  
  1598.  
  1599. RFC 984                                                         May 1986
  1600. PCMAIL
  1601.  
  1602.  
  1603.          => 1105 (get-changed-descriptors) [mailbox:str,
  1604.                                             max-to-send:card]
  1605.          <= 501 (failure) [why:str] |
  1606.             1103 (descriptor-list) [descriptor-list:seq[
  1607.                    ch[
  1608.                      expunged[uid:lcard],
  1609.                      descriptor[rec[uid:lcard,
  1610.                                     flags:seq[bool],
  1611.                                     from-field:str,
  1612.                                     to-field:str,
  1613.                                     date-field:str,
  1614.                                     subject-field:str,
  1615.                                     num-bytes:lcard,
  1616.                                     num-lines:lcard]
  1617.                          ]]]]
  1618.  
  1619.          => 1106 (reset-changed-descriptors) [
  1620.                          mailbox:str,
  1621.                          start-uid:lcard,
  1622.                          end-uid:lcard]
  1623.          <= 500 (ok) [] |
  1624.             501 (failure) [why:str]
  1625.  
  1626.          => 1107 (get-message-text) [mailbox:str,
  1627.                                      uid:lcard]
  1628.          <= 501 (failure) [why:str] |
  1629.             1110 (message) [message:seq[str]]
  1630.  
  1631.          => 1108 (print-message) [mailbox:str,
  1632.                                   uid:lcard,
  1633.                                   printer-name:str]
  1634.          <= 500 (ok) [] |
  1635.             501 (failure) [why:str]
  1636.  
  1637.          => 1109 (set-flag) [mailbox:str,
  1638.                              uid:lcard,
  1639.                              flag-number:card,
  1640.                              flag-setting:bool]
  1641.          <= 500 (ok) [] |
  1642.             501 (failure) [why:str]
  1643.  
  1644.          => 1111 copy-message[source-mailbox:str,
  1645.                               target-mailbox:str,
  1646.                               source-uid:lcard]
  1647.          <= 500 (ok) [] |
  1648.             501 (failure) [why:str]
  1649.  
  1650.  
  1651.  
  1652. Clark & Lambert                                                [Page 29]
  1653.  
  1654.  
  1655.  
  1656. RFC 984                                                         May 1986
  1657. PCMAIL
  1658.  
  1659.  
  1660.    DMSP block types by number
  1661.  
  1662.       General block types
  1663.  
  1664.          ok                        500
  1665.          failure                   501
  1666.          abort-request             503
  1667.          start-debug               504
  1668.          end-debug                 505
  1669.          send-version              506
  1670.          log-message               507
  1671.          send-message              508
  1672.  
  1673.       User operation block types
  1674.  
  1675.          login                     600
  1676.          logout                    601
  1677.          add-user                  602
  1678.          remove-user               603
  1679.          set-password              604
  1680.  
  1681.       Client operation block types
  1682.  
  1683.          list-clients              700
  1684.          client-list               701
  1685.          add-clien                 702
  1686.          remove-client             703
  1687.          reset-client              704
  1688.          force-client-reset        705
  1689.  
  1690.       Mailbox operation block types
  1691.  
  1692.          list-mailboxes            800
  1693.          mailbox-list              801
  1694.          add-mailbox               802
  1695.          remove-mailbox            803
  1696.          expunge-mailbox           808
  1697.          reset-mailbox             809
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709. Clark & Lambert                                                [Page 30]
  1710.  
  1711.  
  1712.  
  1713. RFC 984                                                         May 1986
  1714. PCMAIL
  1715.  
  1716.  
  1717.       Address operation block types
  1718.  
  1719.          list-addresses            804
  1720.          address-list              805
  1721.          add-address               806
  1722.          remove-address            807
  1723.  
  1724.       Message operation block types
  1725.  
  1726.          get-descriptor-flags      1100
  1727.          descriptor-flags          1101
  1728.          get-descriptors           1102
  1729.          descriptor-list           1103
  1730.          get-changed-descriptors   1105
  1731.          reset-changed-descriptors 1106
  1732.          get-message-text          1107
  1733.          print-message             1108
  1734.          set-flag                  1109
  1735.          message                   1110
  1736.          copy-message              1111
  1737.  
  1738.  
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766. Clark & Lambert                                                [Page 31]
  1767.  
  1768.