11 POP3: Reading Mail
struct
(struct communicator (sender receiver server port state) #:extra-constructor-name make-communicator) sender : output-port? receiver : input-port? server : string? port : (integer-in 0 65535) state : (or/c 'disconnected 'authorization 'transaction)
Once a connection to a POP-3 server has been established, its state is
stored in a communicator instance, and other procedures take
communicator instances as an argument.
procedure
(connect-to-server server [port-number]) → communicator?
server : string? port-number : (integer-in 0 65535) = 110
Connects to server at port-number.
procedure
(disconnect-from-server communicator) → void?
communicator : communicator?
Disconnects communicator from the server, and sets
communicator’s state to 'disconnected.
procedure
(authenticate/plain-text user passwd communicator) → void? user : string? passwd : string? communicator : communicator?
Authenticates using user and passwd. If
authentication is successful, communicator’s state is set to
'transaction.
procedure
(get-mailbox-status communicator) →
exact-nonnegative-integer? exact-nonnegative-integer? communicator : communicator?
Returns the number of messages and the number of octets in the
mailbox.
procedure
(get-message/complete communicator message-number)
→
(listof string?) (listof string?) communicator : communicator? message-number : exact-integer?
Given a message number, returns a list of message-header lines and
list of message-body lines.
procedure
(get-message/headers communicator message-number)
→
(listof string?) (listof string?) communicator : communicator? message-number : exact-integer?
Given a message number, returns a list of message-header lines.
procedure
(get-message/body communicator message-number)
→
(listof string?) (listof string?) communicator : communicator? message-number : exact-integer?
Given a message number, returns a list of message-body lines.
procedure
(delete-message communicator message-number) → void? communicator : communicator? message-number : exact-integer?
Deletes the specified message.
procedure
(get-unique-id/single communicator message-number) → string? communicator : communicator? message-number : exact-integer?
Gets the server’s unique id for a particular message.
procedure
(get-unique-id/all communicator)
→ (listof (cons/c exact-integer? string?)) communicator : communicator?
Gets a list of unique id’s from the server for all the messages in the
mailbox. The car of each item in the result list is the
message number, and the cdr of each item is the message’s
id.
procedure
(make-desired-header tag-string) → regexp?
tag-string : string?
Takes a header field’s tag and returns a regexp to match the field
procedure
(extract-desired-headers header desireds) → (listof string?)
header : (listof string?) desireds : (listof regexp?)
Given a list of header lines and of desired regexps, returns the
header lines that match any of the desireds.
11.1 Exceptions
The supertype of all POP3 exceptions.
struct
(struct cannot-connect pop3 () #:extra-constructor-name make-cannot-connect)
Raised when a connection to a server cannot be established.
struct
(struct username-rejected pop3 () #:extra-constructor-name make-username-rejected)
Raised if the username is rejected.
struct
(struct password-rejected pop3 () #:extra-constructor-name make-password-rejected)
Raised if the password is rejected.
struct
(struct not-ready-for-transaction pop3 (communicator) #:extra-constructor-name make-not-ready-for-transaction) communicator : communicator?
Raised when the communicator is not in transaction mode.
struct
(struct not-given-headers pop3 (communicator message) #:extra-constructor-name make-not-given-headers) communicator : communicator? message : exact-integer?
Raised when the server does not respond with headers for a message as
requested.
struct
(struct illegal-message-number pop3 (communicator message) #:extra-constructor-name make-illegal-message-number) communicator : communicator? message : exact-integer?
Raised when the client specifies an illegal message number.
struct
(struct cannot-delete-message exn (communicator message) #:extra-constructor-name make-cannot-delete-message) communicator : communicator? message : exact-integer?
Raised when the server is unable to delete a message.
struct
(struct disconnect-not-quiet pop3 (communicator) #:extra-constructor-name make-disconnect-not-quiet) communicator : communicator?
Raised when the server does not gracefully disconnect.
struct
(struct malformed-server-response pop3 (communicator) #:extra-constructor-name make-malformed-server-response) communicator : communicator?
Raised when the server produces a malformed response.
11.2 Example Session
> (require net/pop3) > (define c (connect-to-server "foo.bar.com")) > (authenticate/plain-text "bob" "********" c) > (get-mailbox-status c) 196 816400 > (get-message/headers c 100) ("Date: Thu, 6 Nov 1997 12:34:18 -0600 (CST)" "Message-Id: <199711061834.MAA11961@foo.bar.com>" "From: Alice <alice@foo.bar.com>" .... "Status: RO") > (get-message/complete c 100) ("Date: Thu, 6 Nov 1997 12:34:18 -0600 (CST)" "Message-Id: <199711061834.MAA11961@foo.bar.com>" "From: Alice <alice@foo.bar.com>" .... "Status: RO") ("some body" "text" "goes" "." "here" "." "") > (get-unique-id/single c 205) no message numbered 205 available for unique id > (list-tail (get-unique-id/all c) 194) ((195 . "e24d13c7ef050000") (196 . "3ad2767070050000")) > (get-unique-id/single c 196) "3ad2767070050000" > (disconnect-from-server c)
11.3 POP3 Unit
pop3@ and pop3^ are deprecated. They exist for backward-compatibility and will likely be removed in the future. New code should use the net/pop3 module.
| (require net/pop3-unit) | package: compatibility-lib |
Imports nothing, exports pop3^.
11.4 POP3 Signature
| (require net/pop3-sig) | package: compatibility-lib |
signature
pop3^ : signature
Includes everything exported by the net/pop3 module.