Time-stamp: <98/03/17 20:22:37 shriram>

Package: pop3
Collection: net
Files: pop3.ss, pop3r.ss, pop3s.ss, pop3u.ss

ABSTRACT -------------------------------------------------------------

Implements RFC 1939, Post Office Protocol - Version 3, Myers & Rose.

TYPES ----------------------------------------------------------------

communicator:
struct communicator (sender receiver server port state)
sender : oport
receiver : iport
server : string
port : number
state : symbol = (disconnected, authorization, transaction)

  Once a connection to a POP-3 server has been established, its state
  is stored in a communicator, and other procedures take communicators
  as an argument.

desired:

  A regular expression that matches against a mail header.

EXCEPTIONS -----------------------------------------------------------

struct (pop3 exn) ()

  The super-struct used for all other package exceptions.

struct (cannot-connect pop3) ()

  When a connection to a server cannot be established.

struct (username-rejected pop3) ()

  If the username is rejected.

struct (password-rejected pop3) ()

  If the password is rejected.

struct (not-ready-for-transaction pop3) (communicator)
communicator : communicator

  When the communicator is not in transaction mode.

struct (not-given-headers pop3) (communicator message)
communicator : communicator
message : number

  When the server does not respond with headers for a message as
  requested.

struct (not-given-message pop3) (communicator message)
communicator : communicator
message : number

  When the server does not respond with the contents of a message as
  requested.

struct (cannot-delete-message exn) (communicator message)
communicator : communicator
message : number

  When the server is unable to delete a message.

struct (disconnect-not-quiet pop3) (communicator)
communicator : communicator

  When the server does not gracefully disconnect.

struct (malformed-server-response pop3) (communicator)
communicator : communicator

  When the server produces a mal-formed response.

PROCEDURES -----------------------------------------------------------

connect-to-server :
string [x number] -> communicator

  Connects to a server.  Uses the default port number if none is
  provided.

disconnect-from-server :
communicator -> ()

  Disconnects from as server.  Sets the communicator state to
  disconnected.

authenticate/plain-text :
string x string x communicator -> ()

  Takes a username and password string and, if successful, changes the
  communicator's state to transaction.

get-mailbox-status :
communicator -> number x number

  Returns the number of messages and the number of octets.

get-message/complete :
communicator x number -> list (string) x list (string)

  Given a message number, returns a list of headers and list of
  strings for the body.

get-message/headers :
communicator x number -> list (string)

  Given a message number, returns the list of headers.

get-message/body :
communicator x number -> list (string)

  Given a message number, returns the list of strings for the body.

delete-message :
communicator x number -> ()

  Deletes the specified message.

make-desired-header :
string -> desired

  Takes the header's tag and returns a desired regexp for that header.

extract-desired-headers :
list (string) x list (desired) -> list (string)

  Given a list of headers and of desired's, returns the header lines
  that match any of the desired's.

EXAMPLE --------------------------------------------------------------

> (reference-library "pop3.ss" "net")
> (define c (pop3:connect-to-server "cs.rice.edu"))
> (pop3:authenticate/plain-text "scheme" "********" c)
> (pop3:get-mailbox-status c)
100
177824
> (pop3:get-message/headers c 100)
("Date: Thu, 6 Nov 1997 12:34:18 -0600 (CST)"
 "Message-Id: <199711061834.MAA11961@new-world.cs.rice.edu>"
 "From: Shriram Krishnamurthi <shriram@cs.rice.edu>"
 ...
 "Status: RO")
> (pop3:get-message/complete  c 100)
("Date: Thu, 6 Nov 1997 12:34:18 -0600 (CST)"
 "Message-Id: <199711061834.MAA11961@new-world.cs.rice.edu>"
 "From: Shriram Krishnamurthi <shriram@cs.rice.edu>"
 ...
 "Status: RO")
("some body" "text" "goes" "." "here" "." "")
> (pop3:disconnect-from-server c)
