rfc984.txt

RFC 相关的技术文档

   message operations.

   Blocks marked "=>" flow from client to repository; blocks marked "<="
   flow from repository to client.  If more than one block can be sent,
   the choices are delimited by "or" ("|") characters.


Clark & Lambert                                                 [Page 6]



RFC 984                                                         May 1986
PCMAIL


   For clarity, each block type is put in a human-
   understandable form.  The block number is followed by an operation
   name; this name is never transmitted as part of a USP block.  Block
   arguments are identified by name and type, and enclosed in square
   brackets.  "Record" data types are described by a list of
   "field-name:field-type" pairs contained in square brackets.  "Choice"
   data types are described by a list of "tag:tag-name" pairs contained
   in square brackets.  USP data types are abbreviated as follows:

   Primitive data types:

      - string: str

      - cardinal: card

      - long-cardinal: Lcard

      - integer: int

      - long-integer: Lint

      - boolean: bool

   Compound data types:

      - sequence: SEQ

      - array: AR

      - record: REC

      - choice: CH

   4.1. General operations

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

      If either a client or the repository thinks the other is
      malfunctioning, they can send an "abort-request".  An
      abort-request is never acknowledged; after the request is sent,
      the sender immediately closes the USP connection and returns
      control to its application.

         => 503 (abort-request) [why:str]



Clark & Lambert                                                 [Page 7]



RFC 984                                                         May 1986
PCMAIL


      DMSP provides a limited remote debugging facility via the
      "start-debug" and "end-debug" operations.  When a client sends a
      "start-debug" request, the repository enables its idea of
      remote-debugging.  The exact definition of remote debugging is
      implementation dependent; the current repository implementation
      simply writes debugging information to a special file.  The
      "end-debug" request disables remote debugging.

         => 504 (start-debug) []

         <= 500 (ok) [] |
            501 (failure) [why:str]

         or

         => 505 (end-debug) []

         <= 500 (ok) []

      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.

         => 506 (send-version) [version-number:card]

         <= 500 (ok) [] |
            501 (failure) [why:str]

      DMSP also provides clients with the ability to send an arbitrary
      text message to the repository.  The "log-message" operation takes
      as an argument a string of arbitrary length; the repository
      accepts the string; what is done with the string is
      implementation-dependent.

         => 507 log-message[message:str]

         <= 500 (ok) [] |
            501 (failure) [why:str]

      Finally, 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 on the "to:", "cc:", and
      "bcc:" fields of the message header.  If one or more of the


Clark & Lambert                                                 [Page 8]



RFC 984                                                         May 1986
PCMAIL


      mailboxes exists outside the repository's user community, the
      repository is responsible for handing the message to a local SMTP
      server.

      An OK block is sent from the repository only if the entire message
      was successfully transmitted.  If the message was destined for the
      Internet, the send-message operation is successful if the message
      was successfully transmitted to the local SMTP server.

         => 508 (send-message) [message:SEQ[str]]

         <= 500 (ok) [] |
            501 (failure) [why:str]

   4.2. 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 block contains five items: (1)
      the user's name, (2) the user's password, (3) the name of the
      client performing the login, (4) a flag telling the repository to
      create a client object for the client if one does not exist, and
      (5) a flag set to TRUE if the client wishes to operate in "batch
      mode" and FALSE if the client wishes to operate in "interactive"
      mode.  The flag value allows the repository to tune internal
      parameters for either mode of operation.

      The repository can return either an OK block (indicating
      successful authentication), a FAILURE block (indicating failed
      authentication), or a FORCE-RESET block.  This last is sent if the
      client logging in has been marked as "inactive" by the repository
      (clients are marked inactive if they have not connected to the
      repository in over a week).  The FORCE-RESET block indicates that
      the client should erase its local mail state and pull 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.

         => 600 (login) [user:str, password:str, client:str,
                         create-client-object?:bool,
                         batch-mode-flag:bool]

         <= 500 (ok) [] |
            501 (failure) [why:str] |
            705 (force-client-reset) []


Clark & Lambert                                                 [Page 9]



RFC 984                                                         May 1986
PCMAIL


      When a client is finished interacting with the repository, it
      performs a logout operation.  This allows the repository to
      perform any necessary cleanup before closing the USP connection.

         => 601 (logout) []

         <= 500 (ok) []

      DMSP also provides "add-user" and "remove-user" operations, which
      allow system administrators to remotely add new users to, and
      remove users from, the repository.  These operations are
      privileged; the repository authenticates the user requesting the
      operation before performing an add-user or remove-user operation.
      Both operations require the name of the user to be added or
      removed; the add-user operation also requires a default password
      to assign the new user.

         => 602 (add-user) [user:str, password:str]

         <= 500 (ok) [] |
            501 (failure) [why:str]

         => 603 (remove-user) [user:str]

         <= 500 (ok) [] |
            501 (failure) [why:str]

      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.

         => 604 (set-password) [old-password:str,
                                new-password:str]

         <= 500 (ok) [] |
            501 (failure) [why:str]










Clark & Lambert                                                [Page 10]



RFC 984                                                         May 1986
PCMAIL


   4.3. 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 takes the form of
      a series of (name, status pairs).

         => 700 (list-clients) []

         <= 701 (client-list) [client-list:SEQ[
                               REC[name:str, status:card]]]

      The "add-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 add-client operation is a useful means of creating a number of
      new client objects while logged into the repository via an
      existing client.  The add-client operation requires the name of
      the client to add.

         => 702 (add-client) [client:str]

         <= 500 (ok) [] |
            501 (failure) [why:str]

      The most common failure mode for this operation is an attempt to
      add a client that already exists.

      The "remove-client" operation removes an existing client object
      from a user's client list.  The client being removed can be the
      client requesting the operation.  The remove-client operation
      requires the name of the client to remove.

         => 703 (remove-client) [client:str]

         <= 500 (ok) [] |
            501 (failure) [why:str]

      The most common failure mode here is an attempt to remove a
      non-existent client.  This is a typical failure mode for any DMSP
      operation which operates on a named object.

      The last client operation, "reset-client", causes the repository
      to mark all messages in the user's mail state as having changed
      since the client last logged in.  When a client next synchronizes
      with the repository, it will end up receiving a complete copy of
      the repository's global mail state.  This is useful for two


Clark & Lambert                                                [Page 11]



RFC 984                                                         May 1986
PCMAIL


      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.

         => 704 (reset-client) [client:str]

         <= 500 (ok) [] |
            501 (failure) [why:str]

   4.4. Mailbox operations

      DMSP supports five operations that manipulate mailbox objects.
      First, "list-mailboxes" has the repository send to the requesting
      client information on each mailbox.  This information consists of
      the mailbox name, total message count, unseen message count, and
      "next available UID".  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.

         => 800 (list-mailboxes) []

         <= 801 (mailbox-list) [mailbox-list:SEQ[
                                REC[mailbox:str,
                                    next-UID:Lcard,
                                    num-msgs:card,
                                    num-unseen-msgs:card]]]