🚀 go-pugleaf

Network Working Group                                         M. Lambert
Request for Comments: 1056                                           MIT
Obsoletes: RFC-993                                             June 1988

        PCMAIL: A Distributed Mail System for Personal Computers


                           Table of Contents

   1. Status of this Document                                      1
   2. Introduction                                                 2
   3. Repository architecture                                      4
        3.1. Management of user mail state                         5
        3.2. Repository-to-RFC-822 name translation                7
   4. Communication between repository and client: DMSP            8
        4.1. DMSP commands                                         8
        4.2. DMSP responses                                        8
        4.3. DMSP sessions                                        11
        4.4. General operations                                   11
        4.5. User operations                                      12
        4.6. Client operations                                    13
        4.7. Mailbox operations                                   14
        4.8. Address operations                                   15
        4.9. Subscription operations                              15
        4.10. Message operations                                  16
   5. Client Architecture                                         18
        5.1. Multiple clients                                     18
        5.2. Synchronization                                      18
        5.3. Batch operation versus interactive operation         20
        5.4. Message summaries                                    20
   6. Typical interactive-style client-repository interaction     21
   7. A current Pcmail implementation                             25
        7.1. IBM PC client code                                   25
        7.2. UNIX client code                                     26
        7.3. Repository code                                      26
   8. Conclusions                                                 26
   I. DMSP Protocol Specification                                 28
   II. Operations by name                                         37
   III. Responses by number                                       38

1. Status of this Memo

   This RFC is a discussion of the Pcmail workstation based distributed
   mail system.  It is identical to the discussion in RFC-993, save that
   a new, much simpler mail transport protocol is described.  The new
   transport protocol is the result of continued research into ease of
   protocol implementation and use issues.  Distribution of this memo is
   unlimited.



Lambert                                                         [Page 1]

RFC 1056                         PCMAIL                        June 1988


2. Introduction

   Pcmail is a distributed mail system providing mail service to an
   arbitrary number of users, each of whom owns one or more
   workstations.  Pcmail's motivation is to provide very flexible mail
   service to a wide variety of different workstations, ranging in power
   from small, resource-limited machines like IBM PCs to resource-rich
   (where "resources" are primarily processor speed and disk space)
   machines like Suns or Microvaxes.  It attempts to provide limited
   service to resource-limited workstations while still providing full
   service to resource-rich machines.  It is intended to work well with
   machines only infrequently connected to a network as well as machines
   permanently connected to a network.  It is also designed to offer
   diskless workstations full mail service.

   The system is divided into two halves.  The first consists of a
   single entity called the "repository".  The repository is a storage
   center for incoming mail.  Mail for a Pcmail user can arrive
   externally from the Internet or internally from other repository
   users.  The repository also maintains a stable copy of each user's
   mail state (this will hereafter be referred to as the user's "global
   mail state").  The repository is therefore typically a computer with
   a large amount of disk storage.

   The second half of Pcmail consists of one or more "clients".  Each
   Pcmail user may have an arbitrary number of clients, typically
   single-user workstations.  The clients provide a user with a friendly
   means of accessing the user's global mail state over a network.  In
   order to make the interaction between the repository and a user's
   clients more efficient, each client maintains a local copy of its
   user's global mail state, called the "local mail state".  It is
   assumed that clients, possibly being small personal computers, may
   not always have access to a network (and therefore to the global mail
   state in the repository).  This means that the local and global mail
   states may not be identical all the time, making synchronization
   between local and global mail states necessary.

   Clients communicate with the repository via the Distributed Mail
   System Protocol (DMSP); the specification for this protocol appears
   in appendix A. The repository is therefore a DMSP server in addition
   to a mail end-site and storage facility.  DMSP provides a complete
   set of mail manipulation operations ("send a message", "delete a
   message", "print a message", etc.).  DMSP also provides special
   operations to allow easy synchronization between a user's global mail
   state and his clients' local mail states.  Particular attention has
   been paid to the way in which DMSP operations act on a user's mail
   state.  All DMSP operations are failure-atomic (that is, they are
   guaranteed either to succeed completely, or leave the user's mail



Lambert                                                         [Page 2]

RFC 1056                         PCMAIL                        June 1988


   state unchanged ).  A client can be abruptly disconnected from the
   repository without leaving inconsistent or damaged mail states.

   Pcmail's design has been directed by the characteristics of currently
   available workstations.  Some workstations are fairly portable, and
   can be packed up and moved in the back seat of an automobile.  A few
   are truly portable--about the size of a briefcase--and battery-
   powered.  Some workstations have constant access to a high-speed
   local-area network; pcmail should allow for "on-line" mail delivery
   for these machines while at the same time providing "batch" mail
   delivery for other workstations that are not always connected to a
   network.  Portable and semi-portable workstations tend to be
   resource-poor.  A typical IBM PC has a small amount (typically less
   than one megabyte) of main memory and little in the way of mass
   storage (floppy-disk drives that can access perhaps 360 kilobytes of
   data).  Pcmail must be able to provide machines like this with
   adequate mail service without hampering its performance on more
   resource-rich workstations. Finally, all workstations have some
   common characteristics that Pcmail should take advantage of.  For
   instance, workstations are fairly inexpensive compared to the various
   time-shared systems that most people use for mail service.  This
   means that people may own more than one workstation, perhaps putting
   a Microvax in an office and an IBM PC at home.

   Pcmail's design reflects the differing characteristics of the various
   workstations.  Since one person can own several workstations, Pcmail
   allows users multiple access points to their mail state.  Each Pcmail
   user can have several client workstations, each of which can access
   the user's mail by communicating with the repository over a network.
   The clients all maintain local copies of the user's global mail
   state, and synchronize the local and global states using DMSP.

   It is also possible that some workstations will only infrequently be
   connected to a network (and thus be able to communicate with the
   repository).  The Pcmail design therefore allows two modes of
   communication between repository and client.  "Interactive mode" is
   used when the client is always connected to the network.  Any changes
   to the client's local mail state are immediately also made to the
   repository's global mail state, and any incoming mail is immediately
   transmitted from repository to client.  "Batch mode" is used by
   clients that have infrequent access to the repository.  Users
   manipulate the client's local mail state, queueing the changes
   locally.  When the client is next connected to the repository, the
   changes are executed, and the client's local mail state is
   synchronized with the repository's global mail state.

   Finally, the Pcmail design minimizes the effect of using a resource-
   poor workstation as a client.  Mail messages are split into two



Lambert                                                         [Page 3]

RFC 1056                         PCMAIL                        June 1988


   parts: a "descriptor" and a "body".  The descriptor is a capsule
   message summary whose length (typically about 100 bytes) is
   independent of the actual message length.  The body is the actual
   message text, including an RFC-822 standard message header.  While
   the client may not have enough storage to hold a complete set of
   messages, it can usually hold a complete set of descriptors, thus
   providing the user with at least a summary of his mail state.  For
   clients with extremely limited resources, Pcmail allows the storage
   of partial sets of descriptors.  Although this means the user does
   not have a complete local mail state, he can at least look at
   summaries of some messages.  In the cases where the client cannot
   immediately store message bodies, it can always pull them over from
   the repository as storage becomes available.

   The remainder of this document is broken up into sections discussing
   the following:

      - The repository architecture

      - DMSP, its operations, and motivation for its design

      - The client architecture

      - A typical DMSP session between the repository and a
        client

      - The current Pcmail implementation

      - Appendices describing the DMSP protocol in detail

3. Repository architecture

   A typical machine running repository code has a relatively powerful
   processor and a large amount of disk storage.  It must also be a
   permanent network site, for two reasons.  First, clients communicate
   with the repository over a network, and rely on the repository's
   being available at any time.  Second, people sending mail to
   repository users rely on the repository's being available to receive
   mail at any time.

   The repository must perform several tasks.  First, and most
   importantly, the repository must efficiently manage a potentially
   large number of users and their mail states.  Mail must be reliably
   stored in a manner that makes it easy for multiple clients to access
   the global mail state and synchronize their local mail states with
   the global state.  Since a large category of electronic mail is
   represented by bulletin boards (bboards), the repository should
   efficiently manage bboard mail, using a minimum of storage to store



Lambert                                                         [Page 4]

RFC 1056                         PCMAIL                        June 1988


   bboard messages in a manner that still allows any user subscribing to
   the bboard to read the mail.  Second, the repository must be able to
   communicate efficiently with its clients.  The protocol used to
   communicate between repository and client must be reliable and must
   provide operations that (1) allow typical mail manipulation, and (2)
   support Pcmail's distributed nature by allowing efficient
   synchronization between local and global mail states.  Third, the
   repository must be able to process mail from sources outside the
   repository's own user community (a primary outside source is the
   Internet).  Internet mail will arrive with a NIC RFC-822 standard
   message header; the recipient names in the message must be properly
   translated from the RFC-822 namespace into the repository's
   namespace.

3.1. Management of user mail state

   Pcmail divides the world into a community of users.  Each user is
   associated with a user object.  A user object consists of a unique
   name, a password (which the user's clients use to authenticate
   themselves to the repository before manipulating a global mail
   state), a list of "client objects" describing those clients belonging
   to the user, a list of "subscription objects", and a list of "mailbox
   objects".

   A client object consists of a unique name and a status.  A user has
   one client object for every client he owns; a client cannot
   communicate with the repository unless it has a corresponding client
   object in a user's client list.  Client objects therefore serve as a
   means of identifying valid clients to the repository.  Client objects
   also allow the repository to manage local and global mail state
   synchronization; the repository associates with every client an
   "update list" of message state changes which have occurred since the
   client's last synchronization.

   A client's status is either "active" or "inactive".  The repository
   defines inactive clients as those clients which have not connected to
   the repository within a set time period (one week in the current
   repository implementation).  When a previously-inactive client does
   connect to the repository, the repository notifies the client that it
   has been inactive for some time and should "reset" itself.  Resetting
   a client has the effect of placing every message in every mailbox
   onto the client's update list.  This allows the client to get a fresh
   global mail state from the repository when it next synchronizes (see
   synchronization discussion following).  The reset is performed on the
   assumption that enough global state changes occur in a week that the
   client would spend too much time performing an ordinary local state-
   global state synchronization.




Lambert                                                         [Page 5]

RFC 1056                         PCMAIL                        June 1988


   Messages are stored in mailboxes.  Users can have any number of
   mailboxes, which serve both to store and to categorize messages.  A
   mailbox object both names a mailbox and describes its contents.
   Mailboxes are identified by a unique name; their contents are
   described by three numeric values.  The first is the total number of
   messages in the mailbox, the second is the total number of unseen
   messages (messages that have never been seen by the user via any
   client) in the mailbox, and the third is the mailbox's next available
   message unique identifier (UID).  The above information is stored in
   the mailbox object to allow clients to get a summary of a mailbox's
   contents without having to read all the messages within the mailbox.

   Some mailboxes are special, in that other users may read the messages
   stored in them.  These mailboxes are called "bulletin board
   mailboxes" or "bboard mailboxes".  The repository uses bboard
   mailboxes to store bboard mail.  Bboard mailboxes differ from
   ordinary mailboxes in the following ways:

      - Their names are unique across the entire repository;
        for instance, only one bboard mailbox named "sf-lovers"
        may exist in the entire repository community.  This
        does not preclude other users from having an ordinary
        mailbox named "sf-lovers".

      - Subscribers to the bboard are granted read-only access
        to the messages in the bboard mailbox.  The bboard
        mailbox's owner (typically the system manager) has
        read/update/delete access to the mailbox.

   A bboard subscriber keeps track of the messages he has looked at via
   a subscription object.  The subscription object contains the name of
   the bboard, its owner (the user who owns the bboard mailbox where all
   the messages are stored), and the UID of the first message not yet
   seen by the subscriber.

   Users gain read-only access to a bboard by creating a subscription to
   it; they lose that access when they delete that subscription.  A list
   of all bboard mailboxes available for subscription can be transmitted
   to the user on demand.

   Associated with each mailbox are any number of message objects.  Each
   message is broken into two parts--a "descriptor", which contains a
   summary of useful information about the message, and a "body", which
   is the message text itself, including its NIC RFC-822 message header.
   Each message is assigned a monotonically increasing UID based on the
   owning mailbox's next available UID.  Each mailbox has its own set of
   UIDs which, together with the mailbox name and user name, uniquely
   identify the message within the repository.  A descriptor holds the



Lambert                                                         [Page 6]

RFC 1056                         PCMAIL                        June 1988


   following information:  the message UID, the message size in bytes
   and lines, four "useful" message header fields (the "date:", "to:",
   "from:", and "subject:" fields), and sixteen flags.  These flags are
   given identifying numbers 0 through 15.  Eight of these flags have
   well-known definitions and are reserved for the repository's use.
   The eight repository-defined flags mark:

      - (#0) whether the message has been deleted

      - (#1) whether it has been seen

      - (#2) whether it has been forwarded to the user

      - (#3) whether it has been forwarded by the user

      - (#4) whether it has been filed (written to a text file
        outside the repository)

      - (#5) whether it has been printed (locally or remotely)

      - (#6) whether it has been replied to

      - (#7) whether it has been copied to another mailbox



   The remaining eight flags are availble for user use.  Descriptors
   serve as an efficient means for clients to get message information
   without having to waste time retrieving the entire message from the
   repository.

3.2. Repository-to-RFC-822 name translation

   "Address objects" provide the repository with a means for translating
   the RFC-822-style mail addresses in Internet messages into repository
   names.  The repository provides its own namespace for message
   identification.  Any message is uniquely identified by the triple
   (user-name, mailbox-name, message-UID).  Any mailbox is uniquely
   identified by the pair (user-name, mailbox-name).  In order to
   translate between RFC-822-style mail addresses and repository names,
   the repository maintains a list of address objects.  Each address
   object is an association between an RFC-822-style address and a
   (user-name, mailbox-name) pair.  When mail arrives from the Internet,
   the repository can use the address object list to translate the
   recipients into (user-name, mailbox-name) pairs and route the message
   correctly.





Lambert                                                         [Page 7]

RFC 1056                         PCMAIL                        June 1988


4. Communication between repository and client: DMSP

   The Distributed Mail System Protocol (DMSP) defines and manipulates
   the objects mentioned in the previous section.  It has been designed
   to work with Pcmail's singlerepository/multiple-client model of the
   world.  In addition to providing typical mail manipulation functions,
   DMSP provides functions that allow easy synchronization of global and
   local mail states.

   DMSP has been completely re-specified in this version of Pcmail.
   Formerly, DMSP was implemented on top of the USP remote-procedure-
   call protocol.  Since this protocol is not fully unofficially
   specified (let alone officially specified) anywhere, implementation
   of USP is difficult for sites wishing to implement Pcmail on
   different systems.  We therefore have decided to completely redesign
   DMSP.  It is now a very simple request/response protocol similar to
   SMTP or NNTP, running directly on a reliable bidirectional byte-
   stream such as TCP.  The TCP contact port for DMSP has been
   designated 158.  Requests and responses consist of ASCII characters;
   on octet-based transmission streams, each character is transmitted
   rightjustified in an octet with the high-order bit cleared to zero.

4.1. DMSP commands

   DMSP operations consist of an operation name, followed by zero or
   more tab or space characters, followed by zero or more arguments,
   each of which is separated from the operation name and other
   arguments by one or more space or tab characters.  All operation
   requests, as well as all responses, must be terminated with a
   carriage-return plus line-feed (CR-LF) pair.  All operation names and
   arguments must be taken from the set of alphanumeric characters plus
   the characters dash ("-"), underscore ("_"), and period (".").

   DMSP operation names are case-insensitive; they may be transmitted in
   any combination of upper and lower case.  DMSP arguments are case-
   insensitive but case-preserving; in other words a mailbox named
   "MarkL" may be referred to by an operation argument "markl", but will
   always be stored, and transmitted in a repository response, as
   "MarkL"; furthermore, any attempt to create a new mailbox "MaRkL"
   will not be permitted.

   Each operation argument may contain no more than 64 characters.  No
   single request or response line may contain more than 512 characters,
   including all white space and the terminating CR-LF.

4.2. DMSP responses

   A DMSP operation always results in a response, which may be followed



Lambert                                                         [Page 8]

RFC 1056                         PCMAIL                        June 1988


   in turn by a list, consisting of zero or more lines of CR-LF-
   terminated text terminated by a single period (".") plus a CR-LF.  A
   response is always prefaced by a three-digit reply code; possible
   text following the response code can be in any format.  The response
   code is sufficient to determine whether the operation succeeded or
   failed, or whether more text is forthcoming following the response
   line.  Any text following the response code is for information only,
   and need not follow any particular format.

   The first digit indicates whether the operation succeeded or failed,
   and if it succeeded whether or not more text should be presented to
   the repository.  Definitions of the first digit are similar to those
   of NNTP:

   1XX             Informative message


   2XX             Operation completed successfully


   3XX             Operation completed successfully, present
                   remainder of text and terminate with a single
                   period plus CR-LF pair.


   4XX             Operation was performed and failed for some
                   reason.


   5XX             Operation could not be performed because of a
                   protocol syntax error of some sort.


   The second digit indicates the type of object referred to by the
   response.


   X0X             Miscellaneous


   X1X             User operation


   X2X             Client operation


   X3X             Mailbox operation




Lambert                                                         [Page 9]

RFC 1056                         PCMAIL                        June 1988


   X4X             Subscription operation


   X5X             Message operation


   X6X             Address operation


   In an error response, the final digit can describe the type of error
   that occurred.  Otherwise, it simply gives a response a unique
   number.  Numbers 0 through 3 are significant in 4XX-class (error)
   responses only.  Numbers 0-9 in all other responses serve only to
   differentiate responses dealing with the same type of object under
   different circumstances.

   4X0             Operation failed because object exists


   4X1             Operation failed because object does not exist


   4X2             Operation failed because of an internal error


   4X3             Operation failed because of an argument syntax
                   error


   Each operation generates one of a set of responses, detailed in the
   protocol specification appendix.

   List termination is determined solely by a well-known character
   sequence (CR-LF, period, CR-LF).  Since application data could well
   accidentally contain this termination sequence, the transmitting
   protocol module must modify application data so it contains no
   termination sequences.  The receiving module must similarly undo the
   modification before presenting the data to the application at the
   receiving end.

   The transmitting module modifies application data as follows:  If a
   line of application data begins with a period, that period is
   duplicated.  Since the termination sequence is a single period,
   accidental termination has now been prevented.

   The receiving protocol checks incoming all incoming data lines for a
   leading period.  A single period is a list terminator; a period
   followed by other text is removed before being presented to the



Lambert                                                        [Page 10]

RFC 1056                         PCMAIL                        June 1988


   receiving application.

4.3. DMSP sessions

   A DMSP session proceeds as follows: a client begins the session with
   the repository by opening a connection to the repository's machine.
   The client then authenticates both itself and its user to the
   repository with a "login" operation.  If the authentication is
   successful, the user performs an arbitrary number of DMSP operations
   before ending the session with a "logout" operation, at which time
   the connection is closed by the repository.

   Because DMSP can manipulate a pair of mail states (local and global)
   at once, it is extremely important that all DMSP operations are
   failure-atomic.  Failure of any DMSP operation must leave both states
   in a consistent, known state.  For this reason, a DMSP operation is
   defined to have failed unless an explicit acknowledgement is received
   by the operation initiator.  This acknowledgement consists of a
   response code possibly followed by information, as described above.

   Following is a general discussion of all the DMSP operations.  The
   operations are broken down by type: general operations, user
   operations, client operations, mailbox operations, address
   operations, subscription operations, and message operations.
   Detailed operation specifications appear at the end of this document.

4.4. General operations

   The first group of DMSP operations perform general functions that
   operate on no one particular class of object.  DMSP has three general
   operations which provide the following services:

   In order to prevent protocol version skew between clients and the
   repository, DMSP provides a "send-version" operation.  The client
   supplies its DMSP version number as an argument; the operation
   succeeds if the supplied version number matches the repository's DMSP
   version number.  It fails if the two version numbers do not match.
   The version number is a natural number like "100", "101", "200".  The
   "send-version" operation should be the first that a client sends to
   the repository, since no other operation may work correctly if the
   client and repository are using different versions of DMSP.

   Users can send mail to other users via the "send-message" operation.
   The message must have an Internet-style header as defined by NIC
   RFC-822.  The repository takes the message and distributes it to the
   mailboxes specified by the message header's destination fields.  If
   one or more of the mailboxes exists outside the repository's user
   community, the repository is responsible for handing the message to a



Lambert                                                        [Page 11]

RFC 1056                         PCMAIL                        June 1988


   local SMTP server.  The message envelope is generated by the
   repository from the message contents since it may be difficult for
   some clients to perform envelope-generation functions such as address
   verification and syntax checking.

   A success acknowledgement is sent from the repository only if (1) the
   entire message was successfully transmitted from client to
   repository, and (2) the message header was properly formatted.  Once
   the repository has successfully received the message from the client,
   any subsequent errors in queueing or delivery must be noted via
   return mail to the user.

   The last general operation is the "help" operation.  The repository
   responds to "help" by printing an acknowledgement followed by a list
   of supported commands, terminated with a period plus CR-LF.  The
   information is intended for display and can be in any format as long
   as the individual lines of text returned by the repository are CR-
   LF-terminated.

4.5. User operations

   The next series of DMSP operations manipulates user objects.  The
   most common of these operations are "login" and "logout".  A client
   must perform a login operation before being able to access a user's
   mail state.  A DMSP login operation takes five arguments: (1) the
   user's name, (2) the user's password, (3) the name of the client
   performing the login, (4) a flag set to 1 if the repository should
   create a client object for the client if one does not exist (0 else),
   and (5) a flag set to 1 if the client wishes to operate in "batch
   mode" and 0 if the client wishes to operate in "interactive" mode.
   The last flag value allows the repository to tune internal parameters
   for either mode of operation.

   The repository can make one of three responses.  First, it can make a
   success response, indicating successful authentication.  Second, it
   can make one of several failure responses, indicating failed
   authentication.  Finally, it can make a special response indicating
   that authentication was successful, but that the client has not been
   used in over a week.  This last response serves as a hint that the
   client should consider erasing its local mail state and pulling over
   a complete version of the repository's mail state.  This is done on
   the assumption that so many mail state changes have been made in a
   week that it would be inefficient to perform a normal
   synchronization.

   When a client has completed a session with the repository, it
   performs a logout operation.  This allows the repository to perform
   any necessary cleanup before closing the network connection.



Lambert                                                        [Page 12]

RFC 1056                         PCMAIL                        June 1988


   A user can change his password via the "set-password" operation.  The
   operation works much the same as the UNIX change-password operation,
   taking as arguments the user's current password and a desired new
   password.  If the current password given matches the user's current
   password, the user's current password is changed to the new password
   given.  Because encryption can be difficult to perform on some
   resource-poor clients, passwords are transmitted in clear text.
   Clearly this is not an acceptable long-term solution, and
   alternatives are welcomed.

4.6. Client operations

   DMSP provides four operations to manipulate client objects.  The
   first, "list-clients", tells the repository to send the user's client
   list to the requesting client.  The list is a series of lines, one
   per client, containing the client's name, followed by whitespace,
   followed by a status string.  The status is either "inactive" or
   "active".  As with all text responses, the list is terminated with a
   period plus CR-LF.

   The "create-client" operation allows a user to add a client object to
   his list of client objects.  Although the login operation duplicates
   this functionality via the "create-this- client?" flag, the create-
   client operation is a useful means of creating a number of new client
   objects while logged into the repository via an existing client.  The
   create-client operation requires as an argument the name of the
   client to create.

   The "delete-client" operation removes an existing client object from
   a user's client list.  The client being removed cannot be in use by
   anyone at the time.  Delete-client also requires as an argument the
   name of the client to delete.

   The last client operation, "reset-client", causes the repository to
   place all of the messages in all mailboxes onto the named client's
   update list.  When a client next synchronizes with the repository, it
   will end up receiving a list of all descriptors when it requests a
   list of changed message descriptors for a particular mailbox.  This
   is useful for two reasons.  First, a client's local mail state could
   easily become lost or damaged, especially if it is stored on a floppy
   disk.  Second, if a client has been marked as inactive by the
   repository, the reset-client operation provides a fast way of
   resynchronizing with the repository, assuming that so many
   differences exist between the local and global mail states that a
   normal synchronization would take far too much time.






Lambert                                                        [Page 13]

RFC 1056                         PCMAIL                        June 1988


4.7. Mailbox operations

   DMSP supports seven operations that manipulate mailbox objects.
   First, "list-mailboxes" has the repository send to the requesting
   client information on each mailbox.  The repository transmits one
   line of information per mailbox, terminating the list with a period
   plus CR-LF.  Each line contains, in order and separated by
   whitespace, the mailbox name, "next available UID", total message
   count, and unseen message count.  This operation is useful in
   synchronizing local and global mail states, since it allows a client
   to compare the user's global mailbox list with a client's local
   mailbox list.  The list of mailboxes also provides a quick summary of
   each mailbox's contents without having the contents present.

   The "create-mailbox" has the repository create a new mailbox and
   attach it to the user's list of mailboxes.  It takes as an argument
   the name of the mailbox to create.

   "Delete-mailbox" removes a mailbox from the user's list of mailboxes.
   All messages within the mailbox are also deleted and permanently
   removed from the system.  Any address objects binding the mailbox
   name to RFC-822-style mailbox addresses are also removed from the
   system.  Delete-mailbox takes as an argument the name of the mailbox
   to delete.

   "Create-bboard-mailbox" allows a user to create a bboard mailbox.
   The name given as an argument must be unique across the entire
   repository user community.  Once the bboard mailbox has been created,
   other users may subscribe to it, using subscription objects to keep
   track of which messages they have read on which bboard mailboxes.

   "Delete-bboard-mailbox" allows a bboard's owner to delete a bboard
   mailbox.  Subscribers who attempt to read from a bboard mailbox after
   it has been deleted are told that the bboard no longer exists.
   Again, the operation's argument is the name of the bboard mailbox to
   delete.

   "Reset-mailbox" causes the repository to place all of the messages in
   a named mailbox onto the current client's update list.  When the
   client next requests a list of changed message descriptors for this
   mailbox, it will receive a list of all message descriptors in the
   mailbox.  This operation is merely a more specific version of the
   reset-client operation (which allows the client to pull over a
   complete copy of the user's global mail state).  Its primary use is
   for mailboxes whose contents have accidentally been destroyed
   locally.

   Finally, DMSP has an "expunge-mailbox" operation.  Any message can be



Lambert                                                        [Page 14]

RFC 1056                         PCMAIL                        June 1988


   deleted and "undeleted" at will, since this simply changes the value
   of a flag attached to the message.  Deletions are made permanent by
   performing an expunge-mailbox operation.  The expunge operation
   causes the repository to look through a named mailbox, removing from
   the system any messages marked "deleted".  Expunge-mailbox takes as
   an argument the name of the mailbox to expunge.

4.8. Address operations

   DMSP provides three operations that allow users to manipulate address
   objects.  First, the "list-address" operation returns a list of
   address objects associated with a particular mailbox.  Each address
   is transmitted on a separate line terminated by a CR-LF; the list is
   terminated with a period plus CR-LF.

   The "create-address" operation adds a new address object that
   associates a (user-name, mailbox-name) pair with a given RFC-822-
   style mailbox address.  It takes as arguments the mailbox name and
   the address name.

   Finally, the "delete-address" operation destroys the address object
   binding the given RFC-822-style mail address and the given (user-
   name, mailbox-name) pair.  Arguments are the address to delete and
   the mailbox it belongs to.

4.9. Subscription operations

   DMSP provides five subscription operations.  The first, "list-
   subscriptions", gives the user a list of the bboards he is currently
   subscribing to.  The list consists of one line of information per
   subscription.  Each entry contains the following information, in
   order:

      - The bulletin board's name

      - The UID of the first message the subscriber has not yet
        seen

      - The number of messages the subscriber has not yet seen

      - The highest message UID in the bulletin board

   "List-available-subscriptions" gives the user a list of all bboards
   he can subscribe to.  The list consists of bboard names, one per
   line, terminated by a period plus CR-LF.  "Createsubscription" adds a
   subscription to the user's list of subscriptions; it takes as an
   argument the name of the bboard to subscribe to.  "Delete-
   subscription" removes a subscription from the list, and takes as an



Lambert                                                        [Page 15]

RFC 1056                         PCMAIL                        June 1988


   argument the name of the subscription to remove.  Note that this does
   not delete the associated bboard mailbox (obviously only the bboard's
   owner can do that).  It merely removes the user from the list of the
   bboard's subscribers.  Finally DMSP allows the user to tell the
   repository which messages in a bboard he has seen.  Every
   subscription object contains the UID of the first message the user
   has not yet seen; the "reset-subscription" operation updates that
   number, insuring that the user sees a given bboard message only once.
   Reset-subscription takes as arguments the name of the subscription
   and the new UID value.

4.10. Message operations

   The most commonly-manipulated Pcmail objects are messages; DMSP
   therefore provides special message operations to allow efficient
   synchronization, as well as a set of operations to perform standard
   message-manipulation functions.

   A user may request a series of descriptors with the "fetch-
   descriptors" operation.  The series is identified by a pair of
   message UIDs, representing the lower and upper bounds of the list.
   Since UIDs are defined to be monotonically increasing numbers, a pair
   of UIDs is sufficient to completely identify the series of
   descriptors.  If the lower bound UID does not exist, the repository
   starts the series with the first message with UID greater than the
   lower bound.  Similarly, if the upper bound does not exist, the
   repository ends the series with the last message with UID less than
   the upper bound.  If certain UIDs within the series no longer exist,
   the repository obviously does not send them.  The repository returns
   the descriptors in a list with the following format:

   If a descriptor has been expunged, the repository transmits two
   consecutive lines of information: the word "expunged" on one line,
   followed by the message UID on the next line.  "Expunged"
   notifications are only transmitted in response to a "fetch-changed-
   descriptors" command; they are an indication to the client that
   someone else has expunged the mailbox and that the client should
   remove the local copy of the expunged message.

   If a descriptor has not been expunged, it is presented as six
   consecutive lines of information: the word "descriptor" on the first
   line, followed by a second line containing the message UID, flag
   states (see examples following), message length in bytes, and message
   length in lines, followed by four lines containing in order the
   message "from:" field, "to:" field, "date:" field, and "subject:"
   field.  The entire list of descriptors is terminated by a period plus
   CR-LF; individual descriptors are not specially terminated since the
   first line ("expunged" or "descriptor") of a list entry determines



Lambert                                                        [Page 16]

RFC 1056                         PCMAIL                        June 1988


   the exact length of the entry (two lines or six lines).

   The "fetch-changed-descriptors" operation is intended for use during
   state synchronization.  Whenever a descriptor changes state (one of
   its flags is cleared, for example), the repository notes those
   clients which have not yet recorded the change locally.  Fetch-
   changed-descriptors has the repository send to the client a maximum
   of the first N descriptors which have changed since the client's last
   synchronization, where N is a number sent by the client.  The list
   sent begins with the descriptor with lowest UID.  Note that the list
   of descriptors is only guaranteed to be monotonically increasing for
   a given call to "fetch-changed-descriptors"; messages with lower UIDs
   may be changed by other clients in between calls to "fetch-
   changeddescriptors".  "Fetch-changed-descriptors" takes two
   arguments:  the name of the mailbox to search, and the maximum number
   of descriptors for the repository to return.

   Once the changed descriptors have been looked at, a user will want to
   inform the repository that the current client has recorded the change
   locally.  The "reset-descriptors" command causes the repository to
   mark as "recorded by current client" a given series of descriptors.
   The series is identified by a low UID and a high UID.  UIDs within
   the series that no longer exist are ignored.  Arguments are: mailbox
   name, low UID in range, and high UID in range.

   Whole messages are transmitted from repository to user with the
   "fetch-message" operation.  The separation of "fetchdescriptors" and
   "fetch-message" operations allows clients with small amounts of disk
   storage to obtain a small message summary (via "fetch-descriptors" or
   "fetch-changed-descriptors") without having to pull over the entire
   message.  Arguments are mailbox name, followed by message UID.

   Frequently, a message may be too large for some clients to store
   locally.  Users can still look at the message contents via the
   "print-message" operation.  This operation has the repository send a
   copy of the message to a named printer.  The printer name need only
   have meaning to the particular repository implementation; DMSP
   transmits the name only as a means of identification.  Arguments are:
   mailbox name, followed by message UID, followed by printer
   identification.

   Copying of one message into another mailbox is accomplished via the
   "copy-message" operation.  A descriptor list of length one,
   containing a descriptor for the copied message, is returned if the
   copy operation is successful.  This descriptor is required because
   the copied message acquires a UID different from the original
   message.  The client cannot be expected to know which UID has been
   assigned the copy, hence the repository's sending a descriptor



Lambert                                                        [Page 17]

RFC 1056                         PCMAIL                        June 1988


   containing the UID.  Arguments to copy-message are:  source mailbox
   name, target mailbox name, and source message UID.

   Each message has associated with it sixteen flags, as described
   earlier.  These flags can be set and cleared using the "set-message-
   flag" operation.  The first eight flags have special meaning to the
   repository as described above; the remaining eight are for user use.
   Set-message-flag takes four arguments: mailbox name, message UID,
   flag number (0 through 15), and desired flag state (0 or 1).

5. Client Architecture

   Clients can be any of a number of different workstations; Pcmail's
   architecture must therefore take into account the range of
   characteristics of these workstations.  First, most workstations are
   much more affordable than the large computers currently used for mail
   service.  It is therefore possible that a user may well have more
   than one.  Second, some workstations are portable and they are not
   expected to be constantly tied into a network.  Finally, many of the
   smaller workstations resource-poor, so they are not expected to be
   able to store a significant amount of state information locally.  The
   following subsections describe the particular parts of Pcmail's
   client architecture that address these different characteristics.

5.1. Multiple clients

   The fact that Pcmail users may own more than one workstation forms
   the rationale for the multiple client model that Pcmail uses.  A
   Pcmail user may have one client at home, another at an office, and
   maybe even a third portable client.  Each client maintains a separate
   copy of the user's mail state, hence Pcmail's distributed nature.
   The notion of separate clients allows Pcmail users to access mail
   state from several different locations.  Pcmail places no
   restrictions on a user's ability to communicate with the repository
   from several clients at the same time.  Instead, the decision to
   allow several clients concurrent access to a user's mail state is
   made by the repository implementation.

5.2. Synchronization

   Some workstations tend to be small and fairly portable; the
   likelihood of their always being connected to a network is relatively
   small.  This is another reason for each client's maintaining a local
   copy of a user's mail state.  The user can then manipulate the local
   mail state while not connected to the network (and the repository).
   This immediately brings up the problem of synchronization between
   local and global mail states.  The repository is continually in a
   position to receive global mail state updates, either in the form of



Lambert                                                        [Page 18]