diff --git a/collects/net/scribblings/imap.scrbl b/collects/net/scribblings/imap.scrbl new file mode 100644 index 0000000000..9e2c24acc4 --- /dev/null +++ b/collects/net/scribblings/imap.scrbl @@ -0,0 +1,499 @@ +#lang scribble/doc +@(require "common.ss" + scribble/eval + scribble/struct + (for-label net/imap + net/imap-unit + net/imap-sig)) + +@(define (just-report) + @elem{This operation does not communicate with the server. It merely reports + the result of previous communication.}) + +@(define-syntax-rule (flag-table (section [sym0 flag0] [sym flag] ...) ...) + (let ([spacer (hspace 1)] + [to-flow (lambda (e) + (make-flow (list (make-paragraph (list e)))))]) + (make-table + #f + (append + (list + (list (to-flow spacer) + (to-flow spacer) + (to-flow spacer) + (to-flow (italic "symbol")) + (to-flow spacer) + (to-flow (italic "IMAP flag")))) + (let ([sec section]) + (list + (list (to-flow spacer) + (to-flow sec) + (to-flow spacer) + (to-flow (scheme sym0)) + (to-flow spacer) + (to-flow (scheme flag0))) + (list (to-flow spacer) + (to-flow spacer) + (to-flow spacer) + (to-flow (scheme sym)) + (to-flow spacer) + (to-flow (scheme flag))) + ...)) + ...)))) + +@title{IMAP: Reading Mail} + +@defmodule[net/imap]{The @schememodname[net/imap] module provides for +the client side of Internet Message Access Protocol version 4rev1 +@cite["RFC2060"].} + +@; ---------------------------------------- + +@section{Connecting and Selecting Mailboxes} + +@defproc[(imap-connection? [v any/c]) boolean?]{ + +Return @scheme[#t] if @scheme[v] is a IMAP-connection value (which is +opaque), @scheme[#f] otherwise.} + +@defproc[(imap-connect [server string?] + [username (or/c string? bytes?)] + [password (or/c string? bytes?)] + [mailbox (or/c string? bytes?)]) + (values imap-connection? exact-nonnegative-integer? exact-nonnegative-integer?)]{ + +Establishes an IMAP connection to the given server using the given +username and password, and selects the specified mailbox. The first +result value reprsents the connection. + +The second and third return values indicate the total number of +messages in the mailbox and the number of recent messages (i.e., +messages received since the mailbox was last selected), respectively. + +See also @scheme[imap-port-number]. + +A user's primary mailbox is always called +@scheme["INBOX"]. (Capitalization doesn't matter for that mailbox +name.) + +Updated message-count and recent-count values are available through +@scheme[imap-messages] and @scheme[imap-recent]. See also @scheme[imap-new?] and +@scheme[imap-reset-new!].} + + +@defparam[imap-port-number k (integer-in 0 65535)]{ + +A parameter that determines the server port number. The initial value +is @scheme[143].} + + +@defproc[(imap-connect* [in input-port?] + [out output-port?] + [username (or/c string? bytes?)] + [password (or/c string? bytes?)] + [mailbox (or/c string? bytes?)]) + (values imap-connection? exact-nonnegative-integer? exact-nonnegative-integer?)]{ + +Like @scheme[imap-connect], but given input and output ports (e.g., +ports for an SSL session) instead of a server address.} + + +@defproc[(imap-disconnect [imap imap-connection?]) void?]{ + +Closes an IMAP connection. The close may fail due to a communication +error.} + + +@defproc[(imap-force-disconnect [imap imap-connection?]) void?]{ + +Closes an IMAP connection forcefully (i.e., without send a close +message to the server). A forced disconnect never fails.} + + +@defproc[(imap-reselect [imap imap-connection?] + [mailbox (or/c string? bytes?)]) + (values exact-nonnegative-integer? exact-nonnegative-integer?)]{ + +De-selects the mailbox currently selected by the connection and +selects the specified mailbox, returning the total and recent message +counts for the new mailbox. Expunge and message-state information is +removed. + +Do not use this procedure to poll a mailbox to see whether there are +any new messages. Use @scheme[imap-noop], @scheme[imap-new?], and +@scheme[imap-reset-new!] instead.} + + +@defproc[(imap-examine [imap imap-connection?] + [mailbox (or/c string? bytes?)]) + (values exact-nonnegative-integer? exact-nonnegative-integer?)]{ + +Like @scheme[imap-reselect], but the mailbox is selected as read-only.} + +@; ---------------------------------------- + +@section{Selected Mailbox State} + +@defproc[(imap-noop [imap imap-connection?]) + (values exact-nonnegative-integer? exact-nonnegative-integer?)]{ + +Sends a ``no-op'' message to the server, typically to keep the session +alive. As for many commands, the server may report message-state +updates or expunges, which are recorded in @scheme[imap]. + +The return information is the same as for @scheme[imap-reselect].} + + +@defproc[(imap-poll [imap imap-connection?]) void?]{ + +Does not send a request to the server, but checks for asynchronous +messages from the server that update the message count, to report +expunges, etc.} + + +@defproc[(imap-messages [imap imap-connection?]) exact-nonnegative-integer?]{ + +Returns the number of messages in the selected mailbox. The server can +update this count during most any interaction. + +@just-report[]} + + +@defproc[(imap-recent [imap imap-connection?]) exact-nonnegative-integer?]{ + +Returns the number of ``recent'' messages in the currently selected +mailbox, as most recently reported by the server. The server can +update this count during most any interaction. + +@just-report[]} + + +@defproc[(imap-unseen [imap imap-connection?]) (or/c exact-nonnegative-integer? false/c)]{ + +Returns the number of ``unseen'' messages in the currently selected +mailbox, as most recently reported by the server. The server can +update this count during most any interaction. Old IMAP servers might +not report this value, in which case the result is @scheme[#f]. + +@just-report[]} + + +@defproc[(imap-uidnext [imap imap-connection?]) (or/c exact-nonnegative-integer? false/c)]{ + +Returns the predicted next uid for a message in the currently selected +mailbox, as most recently reported by the server. The server can +update this count during most any interaction. Old IMAP servers might +not report this value, in which case the result is @scheme[#f]. + +@just-report[]} + + +@defproc[(imap-uidvalidity [imap imap-connection?]) (or/c exact-nonnegative-integer? false/c)]{ + +Returns an id number that changes when all uids become invalid. The +server @emph{cannot} update this number during a session. Old IMAP +servers might not report this value, in which case the result is +@scheme[#f]. + +@just-report[]} + + +@defproc[(imap-new? [imap imap-connection?]) boolean?]{ + +Returns @scheme[#t] if the server has reported an increase in the +message count for the currently mailbox since the last call to +@scheme[imap-reset-new!]. Selecting a mailbox implicitly calls +@scheme[imap-reset-new!]. + +@just-report[]} + + +@defproc[(imap-reset-new! [imap imap-connection?]) void?]{ + +Resets the new flag for the session; see @scheme[imap-new?]. +This operation does not communicate with the server.} + + +@defproc[(imap-get-expunges [imap imap-connection?]) (listof exact-nonnegative-integer?)]{ + +Returns pending expunge notifications from the server for the selected +mailbox in terms of message positions (not uids), and clears the +pending notifications. The result list is sorted, ascending. + +@just-report[] + +The server can notify the client of newly deleted messages during most +other commands, but not asynchronously between commands. Furthermore, +the server cannot report new deletions during @scheme[imap-get-messages] or +@scheme[imap-store] operations. + +Before calling any IMAP operation that works in terms of message +numbers, pending expunge notifications must be handled by calling +@scheme[imap-get-expunges].} + + +@defproc[(imap-pending-expunges? [imap imap-connection?]) boolean?]{ + +Returns @scheme[#f] if @scheme[imap-get-expunges] would return an +empty list, @scheme[#t] otherwise.} + + +@defproc[(imap-get-updates [imap imap-connection?]) + (listof (cons/c exact-nonnegative-integer? + (listof pair?)))]{ + +Returns information must like @scheme[imap-get-messages], but includes +information reported asynchronously by the server (e.g., to notify a +client with some other client changes a message attribute). Instead +of reporting specific requested information for specific messages, the +result is associates message positions to field-value association +lists. The result list is sorted by message position, ascending. + +@just-report[] It also clears the update information from the +connection after reporting it. + +When a server reports information that supersedes old reported +information for a message, or if the server reports that a message has +been deleted, then old information for the message is +dropped. Similarly, if @scheme[imap-get-messages] is used to +explicitly obtain information, any redundant (or out-of-date) +information is dropped. + +A client need not use @scheme[imap-get-updates] ever, but accumulated +information for the connection consumes space.} + + +@defproc[(imap-pending-updates? [imap imap-connection?]) boolean?]{ + +Returns @scheme[#f] if @scheme[imap-get-updates] would return an +list, @scheme[#t] otherwise.} + + +@; ---------------------------------------- + +@section{Manipulating Messages} + +@defproc[(imap-get-messages [imap imap-connection?] + [msg-nums (listof exact-nonnegative-integer?)] + [fields (listof (one-of/c 'uid + 'header + 'body + 'flags))]) + (listof list?)]{ + +Downloads information for a set of messages. The @scheme[msg-nums] +argument specifies a set of messages by their message positions (not +their uids). The @scheme[fields] argument specifies the type of +information to download for each message. The available fields are: + +@itemize[ + + @item{@scheme['uid] --- the value is an integer} + + @item{@scheme['header] --- the value is a header (a string, but see + @schememodname[net/head])} + + @item{@scheme['body] --- the value is a byte string, with + CRLF-separated lines} + + @item{@scheme['flags] --- the value is a list of symbols that + correspond to IMAP flags; see @scheme[imap-flag->symbol]} + +] + +The return value is a list of entry items in parallel to +@scheme[msg-nums]. Each entry is itself a list containing value items +in parallel to @scheme[fields]. + +Pending expunges must be handled before calling this function; see +@scheme[imap-get-expunges]. + +@examples[ +(eval:alts (imap-get-message imap '(1 3 5) '(uid header)) + '((107 #"From: larry@stooges.com ...") + (110 #"From: moe@stooges.com ...") + (112 #"From: curly@stooges.com ..."))) +]} + +@deftogether[( +@defproc[(imap-flag->symbol [flag symbol?]) symbol?] +@defproc[(symbol->imap-flag [sym symbol?]) symbol?] +)]{ + +An IMAP flag is a symbol, but it is generally not a convenient one to +use within a Scheme program, because it usually starts with a +backslash. The @scheme[imap-flag->symbol] and +@scheme[symbol->imap-flag] procedures convert IMAP flags to convenient +symbols and vice-versa: + +@flag-table[ +("message flags:" + ['seen '|\Seen|] + ['answered '|\Answered|] + ['flagged '|\Flagged|] + ['deleted '|\Deleted|] + ['draft '|\Draft|] + ['recent '|\Recent|] +) +("mailbox flags:" + ['noinferiors '|\Noinferiors|] + ['noselect '|\Noselect|] + ['marked '|\Marked|] + ['unmarked '|\Unmarked|] + ['hasnochildren '|\HasNoChildren|] + ['haschildren '|\HasChildren|] +) +] + +The @scheme[imap-flag->symbol] and @scheme[symbol->imap-flag] +functions act like the identity function when any other symbol is +provided.} + + +@defproc[(imap-store [imap imap-connection?] + [mode (one-of/c '+ '- '!)] + [msg-nums (listof exact-nonnegative-integer?)] + [imap-flags (listof symbol?)]) + void?]{ + +Sets flags for a set of messages. The mode argument specifies how +flags are set: + +@itemize[ + + @item{@scheme['+] --- add the given flags to each message} + + @item{@scheme['-] --- remove the given flags from each message} + + @item{@scheme['!] --- set each message's flags to the given set} + +] + +The @scheme[msg-nums] argument specifies a set of messages by their +message positions (not their uids). The @scheme[flags] argument +specifies the imap flags to add/remove/install. + +Pending expunges must be handled before calling this function; see +@scheme[imap-get-expunges]. The server will not report back +message-state changes (so they will not show up through +@scheme[imap-get-updates]). + +@examples[ +(eval:alts (imap-store imap '+ '(1 2 3) (list (symbol->imap-flag 'deleted))) + (void)) +(code:comment #, @t{marks the first three messages to be deleted}) +(eval:alts (imap-expunge imap) (void)) +(code:comment #, @t{permanently removes the first three messages (and possibly}) +(code:comment #, @t{others) from the currently-selected mailbox}) +]} + + +@defproc[(imap-expunge [imap imap-connection?]) void?]{ + +Purges every message currently marked with the @scheme['|\Deleted|] +flag from the mailbox.} + +@; ---------------------------------------- + +@section{Querying and Changing (Other) Mailboxes} + +@defproc[(imap-copy [imap imap-connection?] + [msg-nums (listof exact-nonnegative-integer?)] + [dest-mailbox (or/c string? bytes?)]) + void?]{ + +Copies the specified messages from the currently selected mailbox to +the specified mailbox. + +Pending expunges must be handled before calling this function; see +@scheme[imap-get-expunges].} + + +@defproc[(imap-append [imap imap-connection?] + [mailbox string?] + [message (or/c string? bytes?)]) + void?]{ + +Adds a new message (containing @scheme[message]) to the given +mailbox.} + + +@defproc[(imap-status [imap imap-connection?] + [mailbox (or/c string? bytes?)] + [statuses (listof symbol?)]) + list?]{ + +Requests information about a mailbox from the server, typically +@emph{not} the currently selected mailbox. + +The @scheme[statuses] list specifies the request, and the return value +includes one value for each symbol in @scheme[statuses]. The allowed +status symbols are: + +@itemize[ + + @item{@scheme['messages] --- number of messages} + @item{@scheme['recent] --- number of recent messages} + @item{@scheme['unseen] --- number of unseen messages} + @item{@scheme['uidnext] --- uid for next received message} + @item{@scheme['uidvalidity] --- id that changes when all uids are changed} + +] + +Use @scheme[imap-messages] to get the message count for the currently +selected mailbox, etc. Use @scheme[imap-new?] and +@scheme[imap-reset-new!] to detect when new messages are available in +the currently selected mailbox.} + + +@defproc[(imap-mailbox-exists? [imap imap-connection?] + [mailbox (or/c string? bytes?)]) + boolean?]{ + +Returns @scheme[#t] if @scheme[mailbox] exists, @scheme[#f] +otherwise.} + + +@defproc[(imap-create-mailbox [imap imap-connection?] + [mailbox (or/c string? bytes?)]) + void?]{ + +Creates @scheme[mailbox]. (It must not exist already.)} + + +@defproc[(imap-list-child-mailboxes [imap imap-connection?] + [mailbox (or/c string? bytes? false/c)] + [delimiter (or/c string? bytes?) + (imap-get-hierarchy-delimiter)]) + (listof (list/c (listof symbol?) bytes?))]{ + +Returns information about sub-mailboxes of @scheme[mailbox]; if +@scheme[mailbox] is @scheme[#f], information about all top-level +mailboxes is returned. The @scheme[delimiter] is used to parse mailbox +names from the server to detect hierarchy. + +The return value is a list of mailbox-information lists. Each +mailbox-information list contains two items: + +@itemize[ + + @item{a list of imap flags for the mailbox} + + @item{the mailbox's name} + +]} + + +@defproc[(imap-get-hierarchy-delimiter [imap imap-connection?]) bytes?]{ + +Returns the server-specific string that is used as a separator in +mailbox path names.} + + +@defproc[(imap-mailbox-flags [imap imap-connection?] + [mailbox (or/c string? bytes?)]) + (listof symbol?)]{ + +Returns a list of IMAP flags for the given mailbox. See also +@scheme[imap-flag->symbol].} + diff --git a/collects/net/scribblings/net.scrbl b/collects/net/scribblings/net.scrbl index ba8a705555..4262bebaec 100644 --- a/collects/net/scribblings/net.scrbl +++ b/collects/net/scribblings/net.scrbl @@ -10,6 +10,9 @@ @include-section["smtp.scrbl"] @include-section["cgi.scrbl"] @include-section["sendmail.scrbl"] +@include-section["nntp.scrbl"] +@include-section["pop3.scrbl"] +@include-section["imap.scrbl"] @include-section["gifwrite.scrbl"] @(bibliography @@ -18,6 +21,27 @@ #:title "Common Gateway Interface (CGI/1.1)" #:url "http://hoohoo.ncsa.uiuc.edu/cgi/") + (bib-entry #:key "RFC977" + #:title "Network News Transfer Protocol" + #:author "Brian Kantor and Phil Lapsley" + #:location "RFC" + #:url "http://www.ietf.org/rfc/rfc0977.txt" + #:date "1986") + + (bib-entry #:key "RFC1939" + #:title "Post Office Protocol - Version 3" + #:author "J. Myers and M. Rose" + #:location "RFC" + #:url "http://www.ietf.org/rfc/rfc1939.txt" + #:date "1996") + + (bib-entry #:key "RFC2060" + #:title "Internet Message Access Protocol - Version 4rev1" + #:author "M. Crispin" + #:location "RFC" + #:url "http://www.ietf.org/rfc/rfc2060.txt" + #:date "1996") + (bib-entry #:key "RFC2396" #:title "Uniform Resource Identifiers (URI): Generic Syntax" #:author "T. Berners-Lee, R. Fielding, and L. Masinter" diff --git a/collects/net/scribblings/nntp.scrbl b/collects/net/scribblings/nntp.scrbl new file mode 100644 index 0000000000..8f00cfa58e --- /dev/null +++ b/collects/net/scribblings/nntp.scrbl @@ -0,0 +1,155 @@ +#lang scribble/doc +@(require "common.ss" + (for-label net/nntp + net/nntp-unit + net/nntp-sig)) + +@title{NNTP: Newsgroup Protocol} + +@defmodule[net/nntp]{The @schememodname[net/nntp] module provides +tools to access Usenet group via NNTP @cite["RFC977"].} + +@section{Connection and Operations} + +@defstruct[communicator ([sender output-port?] + [receiver input-port?] + [server string?] + [port (integer-in 0 65535)])]{ + +Once a connection to a Usenet server has been established, its state +is stored in a @scheme[communicator], and other procedures take +communicators as an argument.} + +@defproc[(connect-to-server [server string?] [port-number (integer-in 0 65535) 119]) + communicator?]{ + +Connects to @scheme[server] at @scheme[port-number].} + +@defproc[(disconnect-from-server [communicator communicator?]) void?]{ + +Disconnects an NNTP communicator.} + +@defproc[(open-news-group [communicator communicator?] + [newsgroup string?]) + (values exact-nonnegative-integer? + exact-nonnegative-integer? + exact-nonnegative-integer?)]{ + +Selects the newsgroup of an NNTP connection. The returned values are +the total number of articles in the group, the first available +article, and the last available article.} + +@defproc[(authenticate-user [communicator communicator?] + [username string?] + [password string?]) + void?]{ + +Tries to authenticate a user with the original authinfo command (uses +cleartext). The @scheme[password] argument is ignored if the server +does not ask for it.} + +@defproc[(head-of-message [communicator communicator?] + [message-index exact-nonnegative-integer?]) + (listof string?)]{ + +Given a message number, returns its header lines.} + +@defproc[(body-of-message [communicator communicator?] + [message-index exact-nonnegative-integer?]) + (listof string?)]{ + +Given a message number, returns the body of the message.} + +@defproc[(newnews-since [communicator communicator?] + [message-index exact-nonnegative-integer?]) + (listof string?)]{ + +Implements the @tt{NEWNEWS} command (often disabled on servers).} + +@defproc[((generic-message-command [command string?] + [ok-code exact-integer?]) + [communicator communicator?] + [message-index exact-nonnegative-integer?]) + (listof string?)]{ + +Useful primitive for implementing @scheme[head-of-message], +@scheme[body-of-message] and other similar commands.} + +@defproc[(make-desired-header [tag-string string?]) + regexp?]{ + +Takes a header field's tag and returns a regexp to match the field} + +@defproc[(extract-desired-headers [header (listof string?)] + [desireds (listof regexp?)]) + (listof string?)]{ + +Given a list of header lines and of desired regexps, returns the +header lines that match any of the @scheme[desireds].} + + +@section{Exceptions} + +@defstruct[(nntp exn) ()]{ + +The supertype of all NNTP exceptions.} + +@defstruct[(unexpected-response nntp) ([code exact-integer?] + [text string?])]{ + +Raised whenever an unexpected response code is received. The +@scheme[text] field holds the response text sent by the server.} + +@defstruct[(bad-status-line nntp) ([line string?])]{ + +Raised for mal-formed status lines.} + +@defstruct[(premature-close nntp) ([communicator communicator?])]{ + +Raised when a remote server closes its connection unexpectedly.} + +@defstruct[(bad-newsgroup-line nntp) ([line string?])]{ + +Raised when the newsgroup line is improperly formatted.} + +@defstruct[(non-existent-group nntp) ([group string?])]{ + +Raised when the server does not recognize the name of the requested +group.} + +@defstruct[(article-not-in-group nntp) ([article exact-integer?])]{ + +Raised when an article is outside the server's range for that group.} + +@defstruct[(no-group-selected nntp) ()]{ + +Raised when an article operation is used before a group has been +selected.} + +@defstruct[(article-not-found nntp) ([article exact-integer?])]{ + +Raised when the server is unable to locate the article.} + +@defstruct[(authentication-rejected nntp) ()]{ + +Raised when the server reject an authentication attempt.} + +@; ---------------------------------------- + +@section{NNTP Unit} + +@defmodule[net/nntp-unit] + +@defthing[nntp@ unit?]{ + +Imports nothing, exports @scheme[nntp^].} + +@; ---------------------------------------- + +@section{NNTP Signature} + +@defmodule[net/nntp-sig] + +@defsignature[nntp^ ()]{} + +Includes everything exported by the @schememodname[net/nntp] module. diff --git a/collects/net/scribblings/pop3.scrbl b/collects/net/scribblings/pop3.scrbl new file mode 100644 index 0000000000..dc22d84281 --- /dev/null +++ b/collects/net/scribblings/pop3.scrbl @@ -0,0 +1,204 @@ +#lang scribble/doc +@(require "common.ss" + (for-label net/pop3 + net/pop3-unit + net/pop3-sig)) + +@(define pt (tt ">")) + +@title{POP3: Reading Mail} + +@defmodule[net/pop3]{The @schememodname[net/pop3] module provides +tools for the Post Office Protocol version 3 @cite["RFC977"].} + +@defstruct[communicator ([sender output-port?] + [receiver input-port?] + [server string?] + [port (integer-in 0 65535)] + [state (one-of/c 'disconnected 'authorization 'transaction)])]{ + +Once a connection to a POP-3 server has been established, its state is +stored in a @scheme[communicator] instance, and other procedures take +@scheme[communicator] instances as an argument.} + + +@defproc[(connect-to-server [server string?] + [port-number (integer-in 0 65535) 110]) + communicator?]{ + +Connects to @scheme[server] at @scheme[port-number].} + + +@defproc[(disconnect-from-server [communicator communicator?]) + void?]{ + +Disconnects @scheme[communicator] from the server, and sets +@scheme[communicator]'s state to @scheme['disconnected].} + + +@defproc[(authenticate/plain-text [user string?] [passwd string?] + [communicator communicator?]) + void?]{ + +Authenticates using @scheme[user] and @scheme[passwd]. If +authentication is successful, @scheme[communicator]'s state is set to +@scheme['transaction].} + +@defproc[(get-mailbox-status [communicator communicator?]) + (values exact-nonnegative-integer? exact-nonnegative-integer?)]{ + +Returns the number of messages and the number of octets in the +mailbox.} + +@defproc[(get-message/complete [communicator communicator?] + [message-number exact-integer?]) + (values (listof string?) (listof string?))]{ + +Given a message number, returns a list of message-header lines and +list of message-body lines.} + +@defproc[(get-message/headers [communicator communicator?] + [message-number exact-integer?]) + (values (listof string?) (listof string?))]{ + +Given a message number, returns a list of message-header lines.} + +@defproc[(get-message/body [communicator communicator?] + [message-number exact-integer?]) + (values (listof string?) (listof string?))]{ + +Given a message number, returns a list of message-body lines.} + +@defproc[(delete-message [communicator communicator?] + [message-number exact-integer?]) + void?]{ + +Deletes the specified message.} + +@defproc[(get-unique-id/single [communicator communicator?] + [message-number exact-integer?]) + string?]{ + +Gets the server's unique id for a particular message.} + + +@defproc[(get-unique-id/all [communicator communicator?]) + (listof (cons/c exact-integer? string?))]{ + +Gets a list of unique id's from the server for all the messages in the +mailbox. The @scheme[car] of each item in the result list is the +message number, and the @scheme[cdr] of each item is the message's +id.} + +@defproc[(make-desired-header [tag-string string?]) + regexp?]{ + +Takes a header field's tag and returns a regexp to match the field} + +@defproc[(extract-desired-headers [header (listof string?)] + [desireds (listof regexp?)]) + (listof string?)]{ + +Given a list of header lines and of desired regexps, returns the +header lines that match any of the @scheme[desireds].} + +@; ---------------------------------------- + +@section[#:tag "pop3-exns"]{Exceptions} + +@defstruct[(pop3 exn) ()]{ + +The supertype of all POP3 exceptions.} + +@defstruct[(cannot-connect pop3) ()]{ + +Raised when a connection to a server cannot be established.} + +@defstruct[(username-rejected pop3) ()]{ + +Raised if the username is rejected.} + +@defstruct[(password-rejected pop3) ()]{ + +Raised if the password is rejected.} + +@defstruct[(not-ready-for-transaction pop3) ([communicator communicator?])]{ + +Raised when the communicator is not in transaction mode.} + +@defstruct[(not-given-headers pop3) ([communicator communicator?] + [message exact-integer?])]{ + +Raised when the server does not respond with headers for a message as +requested.} + +@defstruct[(illegal-message-number pop3) ([communicator communicator?] + [message exact-integer?])]{ + +Raised when the client specifies an illegal message number.} + + +@defstruct[(cannot-delete-message exn) ([communicator communicator?] + [message exact-integer?])]{ + +Raised when the server is unable to delete a message.} + +@defstruct[(disconnect-not-quiet pop3) ([communicator communicator?])]{ + +Raised when the server does not gracefully disconnect.} + + +@defstruct[(malformed-server-response pop3) ([communicator communicator?])]{ + +Raised when the server produces a mal-formed response.} + +@section{Example Session} + +@schemeblock[ + #,pt (require net/pop3) + #,pt (define c (connect-to-server "cs.rice.edu")) + #,pt (authenticate/plain-text "scheme" "********" c) + #,pt (get-mailbox-status c) + 196 + 816400 + #,pt (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 " + .... + "Status: RO") + #,pt (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 " + .... + "Status: RO") + ("some body" "text" "goes" "." "here" "." "") + #,pt (get-unique-id/single c 205) + #, @schemeerror{no message numbered 205 available for unique id} + #,pt (list-tail (get-unique-id/all c) 194) + ((195 . "e24d13c7ef050000") (196 . "3ad2767070050000")) + #,pt (get-unique-id/single c 196) + "3ad2767070050000" + #,pt (disconnect-from-server c) +] + +@; ---------------------------------------- + +@section{POP3 Unit} + +@defmodule[net/pop3-unit] + +@defthing[pop3@ unit?]{ + +Imports nothing, exports @scheme[pop3^].} + +@; ---------------------------------------- + +@section{POP3 Signature} + +@defmodule[net/pop3-sig] + +@defsignature[pop3^ ()]{} + +Includes everything exported by the @schememodname[net/pop3] module. diff --git a/collects/net/scribblings/sendmail.scrbl b/collects/net/scribblings/sendmail.scrbl index 42ffaafd2d..0e41d4b644 100644 --- a/collects/net/scribblings/sendmail.scrbl +++ b/collects/net/scribblings/sendmail.scrbl @@ -4,7 +4,7 @@ net/sendmail-unit net/sendmail-sig)) -@title{Sending E-Mail via @exec{sendmail}} +@title{@exec{sendmail}: Sending E-Mail} @defmodule[net/sendmail]{The @schememodname[net/sendmail] module provides tools for sending electronic mail messages using a diff --git a/collects/net/scribblings/sendurl.scrbl b/collects/net/scribblings/sendurl.scrbl index 80e9ae063e..bb3103b62b 100644 --- a/collects/net/scribblings/sendurl.scrbl +++ b/collects/net/scribblings/sendurl.scrbl @@ -3,7 +3,7 @@ (for-label net/sendurl scheme/file)) -@title{Opening a Web Browser} +@title{Send URL: Opening a Web Browser} @defmodule[net/sendurl]{Provides @scheme[send-url] for opening a URL in the user's chosen web browser.} diff --git a/collects/net/scribblings/smtp.scrbl b/collects/net/scribblings/smtp.scrbl index 6307155d13..caeb880437 100644 --- a/collects/net/scribblings/smtp.scrbl +++ b/collects/net/scribblings/smtp.scrbl @@ -6,7 +6,7 @@ scheme/tcp openssl)) -@title{Sending E-Mail via SMTP} +@title{SMTP: Sending E-Mail} @defmodule[net/smtp]{The @schememodname[net/smtp] module provides tools for sending electronic mail messages using SMTP. The client must