net docs finished

svn: r9317
This commit is contained in:
Matthew Flatt 2008-04-15 14:13:10 +00:00
parent f3e2e2c566
commit 8284b3ab15
25 changed files with 690 additions and 2539 deletions

View File

@ -1,5 +1,6 @@
#lang scheme/signature
cookie?
set-cookie
cookie:add-comment
cookie:add-domain

File diff suppressed because it is too large Load Diff

View File

@ -1,5 +1,6 @@
#lang scheme/signature
ftp-connection?
ftp-cd
ftp-establish-connection ftp-establish-connection*
ftp-close-connection

View File

@ -9,7 +9,7 @@
(export ftp^)
;; opqaue record to represent an FTP connection:
(define-struct tcp-connection (in out))
(define-struct ftp-connection (in out))
(define tzoffset (date-time-zone-offset (seconds->date (current-seconds))))
@ -94,10 +94,10 @@
(define re:passive #rx#"\\((.*),(.*),(.*),(.*),(.*),(.*)\\)")
(define (establish-data-connection tcp-ports)
(fprintf (tcp-connection-out tcp-ports) "PASV\n")
(fprintf (ftp-connection-out tcp-ports) "PASV\n")
(let ([response (ftp-check-response
(tcp-connection-in tcp-ports)
(tcp-connection-out tcp-ports)
(ftp-connection-in tcp-ports)
(ftp-connection-out tcp-ports)
#"227"
(lambda (s ignore) s) ; should be the only response
(void))])
@ -114,9 +114,9 @@
(list-ref reg-list 3)
(list-ref reg-list 4))
(+ (* 256 pn1) pn2))])
(fprintf (tcp-connection-out tcp-ports) "TYPE I\n")
(ftp-check-response (tcp-connection-in tcp-ports)
(tcp-connection-out tcp-ports)
(fprintf (ftp-connection-out tcp-ports) "TYPE I\n")
(ftp-check-response (ftp-connection-in tcp-ports)
(ftp-connection-out tcp-ports)
#"200" void (void))
(close-output-port tcp-data-out)
tcp-data))))
@ -138,19 +138,19 @@
(display (bytes-append #"PASS " (string->bytes/locale password) #"\n")
out)
(ftp-check-response in out #"230" void (void))))
(make-tcp-connection in out))
(make-ftp-connection in out))
(define (ftp-establish-connection server-address server-port username password)
(let-values ([(tcpin tcpout) (tcp-connect server-address server-port)])
(ftp-establish-connection* tcpin tcpout username password)))
(define (ftp-close-connection tcp-ports)
(fprintf (tcp-connection-out tcp-ports) "QUIT\n")
(ftp-check-response (tcp-connection-in tcp-ports)
(tcp-connection-out tcp-ports)
(fprintf (ftp-connection-out tcp-ports) "QUIT\n")
(ftp-check-response (ftp-connection-in tcp-ports)
(ftp-connection-out tcp-ports)
#"221" void (void))
(close-input-port (tcp-connection-in tcp-ports))
(close-output-port (tcp-connection-out tcp-ports)))
(close-input-port (ftp-connection-in tcp-ports))
(close-output-port (ftp-connection-out tcp-ports)))
(define (filter-tcp-data tcp-data-port regular-exp)
(let loop ()
@ -165,9 +165,9 @@
(define (ftp-cd ftp-ports new-dir)
(display (bytes-append #"CWD " (string->bytes/locale new-dir) #"\n")
(tcp-connection-out ftp-ports))
(ftp-check-response (tcp-connection-in ftp-ports)
(tcp-connection-out ftp-ports)
(ftp-connection-out ftp-ports))
(ftp-check-response (ftp-connection-in ftp-ports)
(ftp-connection-out ftp-ports)
#"250" void (void)))
(define re:dir-line
@ -175,14 +175,14 @@
(define (ftp-directory-list tcp-ports)
(let ([tcp-data (establish-data-connection tcp-ports)])
(fprintf (tcp-connection-out tcp-ports) "LIST\n")
(ftp-check-response (tcp-connection-in tcp-ports)
(tcp-connection-out tcp-ports)
(fprintf (ftp-connection-out tcp-ports) "LIST\n")
(ftp-check-response (ftp-connection-in tcp-ports)
(ftp-connection-out tcp-ports)
#"150" void (void))
(let ([dir-list (filter-tcp-data tcp-data re:dir-line)])
(close-input-port tcp-data)
(ftp-check-response (tcp-connection-in tcp-ports)
(tcp-connection-out tcp-ports)
(ftp-check-response (ftp-connection-in tcp-ports)
(ftp-connection-out tcp-ports)
#"226" print-msg (void))
(map (lambda (l) (map bytes->string/locale l)) dir-list))))
@ -202,15 +202,15 @@
(string->bytes/locale filename)
#"\n")]
[tcp-data (establish-data-connection tcp-ports)])
(display tcpstring (tcp-connection-out tcp-ports))
(ftp-check-response (tcp-connection-in tcp-ports)
(tcp-connection-out tcp-ports)
(display tcpstring (ftp-connection-out tcp-ports))
(ftp-check-response (ftp-connection-in tcp-ports)
(ftp-connection-out tcp-ports)
#"150" print-msg (void))
(copy-port tcp-data new-file)
(close-output-port new-file)
(close-input-port tcp-data)
(ftp-check-response (tcp-connection-in tcp-ports)
(tcp-connection-out tcp-ports)
(ftp-check-response (ftp-connection-in tcp-ports)
(ftp-connection-out tcp-ports)
#"226" print-msg (void))
(rename-file-or-directory tmpfile (build-path folder filename) #t)))

View File

@ -0,0 +1,66 @@
#lang scribble/doc
@(require "common.ss"
(for-label net/base64
net/base64-unit
net/base64-sig))
@title[#:tag "base64"]{Base 64: Encoding and Decoding}
@defmodule[net/base64]{The @schememodname[net/base64] library provides
utilities for Base 64 (mime-standard) encoding and decoding.}
@section[#:tag "base64-procs"]{Functions}
@defproc[(base64-encode [bstr bytes?]) bytes?]{
Consumes a byte string and returns its Base 64 encoding as a new byte
string. The returned string is broken into 72-byte lines separated by
CRLF combinations, and always ends with a CRLF combination unless the
input is empty.}
@defproc[(base64-decode [bstr bytes?]) bytes?]{
Consumes a byte string and returns its Base 64 decoding as a new byte
string.}
@defproc[(base64-encode-stream [in input-port?]
[out output-port?]
[newline-bstr bytes? #"\n"])
void?]{
Reads bytes from @scheme[in] and writes the encoded result to
@scheme[out], breaking the output into 72-character lines separated by
@scheme[newline-bstr], and ending with @scheme[newline-bstr] unless
the input stream is empty. Note that the default @scheme[newline-bstr]
is just @scheme[#"\n"], not @scheme[#"\r\n"]. The procedure returns when
it encounters an end-of-file from @scheme[in].}
@defproc[(base64-decode-stream [in input-port?]
[out output-port?])
void?]{
Reads a Base 64 encoding from @scheme[in] and writes the decoded
result to @scheme[out]. The procedure returns when it encounters an
end-of-file or Base 64 terminator @litchar{=} from @scheme[in].}
@; ----------------------------------------
@section{Base64 Unit}
@defmodule[net/base64-unit]
@defthing[base64@ unit?]{
Imports nothing, exports @scheme[base64^].}
@; ----------------------------------------
@section{Base64 Signature}
@defmodule[net/base64-sig]
@defsignature[base64^ ()]{}
Includes everything exported by the @schememodname[net/base64] module.

View File

@ -4,7 +4,7 @@
net/cgi-unit
net/cgi-sig))
@title{CGI Scripts}
@title[#:tag "cgi"]{CGI Scripts}
@defmodule[net/cgi]{The @schememodname[net/cgi] module provides tools
for scripts that follow the Common Gateway Interface @cite["CGI"].}

View File

@ -0,0 +1,176 @@
#lang scribble/doc
@(require "common.ss"
scribble/eval
(for-label net/cookie
net/cookie-unit
net/cookie-sig))
@(define cookie-eval (make-base-eval))
@interaction-eval[#:eval cookie-eval (require net/cookie)]
@title[#:tag "cookie"]{Cookie: HTTP Client Storage}
@defmodule[net/cookie]{The @schememodname[net/cookie] library provides
utilities for using cookies as specified in RFC 2109 @cite["RFC2109"].}
@section[#:tag "cookie-procs"]{Functions}
@defproc[(cookie? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] represents a cookie, @scheme[#f]
otherwise.}
@defproc[(set-cookie [name string?] [value string?]) cookie?]{
Creates a new cookie, with default values for required fields.}
@defproc[(cookie:add-comment [cookie cookie?] [comment string?])
cookie?]{
Modifies @scheme[cookie] with a comment, and also returns
@scheme[cookie].}
@defproc[(cookie:add-domain [cookie cookie?] [domain string?])
cookie?]{
Modifies @scheme[cookie] with a domain, and also returns
@scheme[cookie]. The @scheme[domain] must match a prefix of the
request URI.}
@defproc[(cookie:add-max-age [cookie cookie?] [seconds exact-nonnegative-integer?])
cookie?]{
Modifies @scheme[cookie] with a maximum age, and also returns
@scheme[cookie]. The @scheme[seconds] argument is number of seconds
that a client should retain the cookie.}
@defproc[(cookie:add-path [cookie cookie?] [path string?])
cookie?]{
Modifies @scheme[cookie] with a path, and also returns
@scheme[cookie].}
@defproc[(cookie:secure [cookie cookie?] [secure boolean?])
cookie?]{
Modifies @scheme[cookie] with a security flag, and also returns
@scheme[cookie].}
@defproc[(cookie:version [cookie cookie?] [version exact-nonnegative-integer?])
cookie?]{
Modifies @scheme[cookie] with a version, and also returns
@scheme[cookie]. The default is the only known incarnation of HTTP
cookies: @scheme[1].}
@defproc[(print-cookie [cookie cookie?]) string?]{
Prints @scheme[cookie] to a string. Empty fields do not appear in the
output except when there is a required default.}
@defproc[(get-cookie [name string?] [cookies string?]) (listof string?)]{
Returns a list with all the values (strings) associated with @scheme[name].
The method used to obtain the @scheme["Cookie"] header depends on the
web server. It may be an environment variable (CGI), or you may have
to read it from the input port (FastCGI), or maybe it comes in an
initial-request structure, etc. The @scheme[get-cookie] and
@scheme[get-cookie/single] procedure can be used to extract fields
from a @scheme["Cookie"] field value.}
@defproc[(get-cookie/single [name string?] [cookies string?]) (or/c string? false/c)]{
Like @scheme[get-cookie], but returns the just first value string
associated to @scheme[name], or #f if no association is found.}
@defstruct[(cookie-error exn:fail) ()]{
Raised for errors when handling cookies.}
@section[#:tag "cookie-examples"]{Examples}
@subsection{Creating a cookie}
@schemeblock[
(let ((c (cookie:add-max-age
(cookie:add-path
(set-cookie "foo" "bar")
"/servlets")
3600)))
(print-cookie c))
]
Produces
@schemeblock[
#, @schemeresultfont{"foo=bar; Max-Age=3600; Path=/servlets; Version=1"}
]
To use this output in a ``regular'' CGI, instead of the last line use:
@schemeblock[
(display (format "Set-Cookie: ~a" (print-cookie c)))
]
and to use with the PLT Web Server, use:
@schemeblock[
(make-response/full code message (current-seconds) mime
`((Set-Cookie . ,(print-cookie c)))
body)
]
@subsection{Parsing a cookie}
Imagine your Cookie header looks like this:
@interaction[
#:eval cookie-eval
(define cookies
"test2=2; test3=3; xfcTheme=theme6; xfcTheme=theme2")
]
Then, to get the values of the xfcTheme cookie, use
@interaction[
#:eval cookie-eval
(get-cookie "xfcTheme" cookies)
(get-cookie/single "xfcTheme" cookies)
]
If you try to get a cookie that simply is not there:
@interaction[
#:eval cookie-eval
(get-cookie/single "foo" cookies)
(get-cookie "foo" cookies)
]
Note that not having a cookie is normally not an error. Most clients
won't have a cookie set then first arrive at your site.
@; ----------------------------------------
@section{Cookie Unit}
@defmodule[net/cookie-unit]
@defthing[cookie@ unit?]{
Imports nothing, exports @scheme[cookie^].}
@; ----------------------------------------
@section{Cookie Signature}
@defmodule[net/cookie-sig]
@defsignature[cookie^ ()]{}
Includes everything exported by the @schememodname[net/cookie] module.

View File

@ -4,9 +4,9 @@
net/dns-unit
net/dns-sig))
@title{DNS: Domain Name Service Queries}
@title[#:tag "dns"]{DNS: Domain Name Service Queries}
@defmodule[net/dns]{The @schememodname[net/dns] module provides
@defmodule[net/dns]{The @schememodname[net/dns] library provides
utilities for looking up hostnames.
Thanks to Eduardo Cavazos and Jason Crowe for repairs and

View File

@ -0,0 +1,103 @@
#lang scribble/doc
@(require "common.ss"
(for-label net/ftp
net/ftp-unit
net/ftp-sig))
@title[#:tag "ftp"]{FTP: Client Downloading}
@defmodule[net/ftp]{The @schememodname[net/ftp] library provides
utilities for FTP client operations.
The library was written by Micah Flatt.}
@section[#:tag "ftp-procs"]{Functions}
@defproc[(ftp-connection? [v any/c]) boolean?]{
Returns @scheme[#t] if @scheme[v] represents an FTP connection as
returned by @scheme[ftp-establish-connection], @scheme[#f] otherwise.}
@defproc[(ftp-establish-connection [server string?]
[port-no (integer-in 0 65535)]
[user string?]
[passwd string?])
ftp-connection?]{
Establishes an FTP connection with the given server using the
supplied username and password.
The username and password strings are encoded to bytes using the
current locale's encoding.}
@defproc[(ftp-close-connection [ftp-conn ftp-connection?]) void?]{
Closes an FTP connection.}
@defproc[(ftp-cd [ftp-conn ftp-connection?][new-dir string?]) void?]{
Changes the current directory on the FTP server to @scheme[new-dir].
The @scheme[new-dir] argument is not interpreted at all, but simply
passed on to the server (encoded using the current locale's
encoding); it must not contain a newline.}
@defproc[(ftp-directory-list [ftp-conn ftp-connection?])
(listof (list/c (one-of/c "-" "d" "l")
string?
string?))]{
Returns a list of files and directories in the current directory of
the server, assuming that the server provides directory information in
the quasi-standard Unix format.
Each file or directory is represented by a list of three strings. The
first string is either @scheme["-"], @scheme["d"], or @scheme["l"],
depending on whether the items is a file, directory, or link,
respectively. The second item is the file's date; to convert this
value to seconds consistent with @scheme[file-seconds], pass the date
string to @scheme[ftp-make-file-seconds], below. The third string is
the name of the file or directory.
All strings are decoded from bytes using the current locale's
encoding.}
@defproc[(ftp-make-file-seconds [ftp-date string?]) exact-integer?]{
Takes a date string produced by @scheme[ftp-directory-list] and
converts it to seconds (which can be used with
@scheme[seconds->date]).}
@defproc[(ftp-download-file [ftp-conn ftp-connection?]
[local-dir path-string?]
[file string?]) void?]{
Downloads @scheme[file] from the server's current directory and puts
it in @scheme[local-dir] using the same name. If the file already
exists in the local directory, it is replaced, but only after the
transfer succeeds (i.e., the file is first downloaded to a temporary
file, then moved into place on success).}
@; ----------------------------------------
@section{FTP Unit}
@defmodule[net/ftp-unit]
@defthing[ftp@ unit?]{
Imports nothing, exports @scheme[ftp^].}
@; ----------------------------------------
@section{FTP Signature}
@defmodule[net/ftp-sig]
@defsignature[ftp^ ()]{}
Includes everything exported by the @schememodname[net/ftp] module.

View File

@ -3,7 +3,7 @@
scribble/extract
(for-label net/gifwrite))
@title{GIF: Writing Image Files}
@title[#:tag "gifwrite"]{GIF: Writing Image Files}
@defmodule[net/gifwrite]

View File

@ -9,7 +9,7 @@
@(define head-eval (make-base-eval))
@interaction-eval[#:eval head-eval (require net/head)]
@title{headers: Parsing and Constructing}
@title[#:tag "head"]{Headers: Parsing and Constructing}
@defmodule[net/head]{The @schememodname[net/head] module provides
utilities for parsing and constructing RFC 822 headers

View File

@ -41,7 +41,7 @@
...))
...))))
@title{IMAP: Reading Mail}
@title[#:tag "imap"]{IMAP: Reading Mail}
@defmodule[net/imap]{The @schememodname[net/imap] module provides
utilities for the client side of Internet Message Access Protocol

View File

@ -26,9 +26,9 @@
...)
...))))
@title{MIME: Decoding Internet Data}
@title[#:tag "mime"]{MIME: Decoding Internet Data}
@defmodule[net/mime]{The @schememodname[net/mime] module provides
@defmodule[net/mime]{The @schememodname[net/mime] library provides
utilities for parsing and creating MIME encodings as described in RFC
2045 through RFC 2049.
@ -235,3 +235,22 @@ when the specification is incorrectly formatted.}
Raised when type specified for the @scheme["Content-Disposition"]
field, or when the specification is incorrectly formatted.}
@; ----------------------------------------
@section{MIME Unit}
@defmodule[net/mime-unit]
@defthing[mime@ unit?]{
Imports nothing, exports @scheme[mime^].}
@; ----------------------------------------
@section{MIME Signature}
@defmodule[net/mime-sig]
@defsignature[mime^ ()]{}
Includes everything exported by the @schememodname[net/mime] module.

View File

@ -7,6 +7,7 @@
@include-section["url.scrbl"]
@include-section["uri-codec.scrbl"]
@include-section["ftp.scrbl"]
@include-section["sendurl.scrbl"]
@include-section["smtp.scrbl"]
@include-section["sendmail.scrbl"]
@ -14,9 +15,15 @@
@include-section["imap.scrbl"]
@include-section["pop3.scrbl"]
@include-section["mime.scrbl"]
@include-section["base64.scrbl"]
@include-section["qp.scrbl"]
@include-section["dns.scrbl"]
@include-section["nntp.scrbl"]
@include-section["tcp.scrbl"]
@include-section["tcp-redirect.scrbl"]
@include-section["ssl-tcp-unit.scrbl"]
@include-section["cgi.scrbl"]
@include-section["cookie.scrbl"]
@include-section["gifwrite.scrbl"]
@(bibliography
@ -60,6 +67,13 @@
#:url "http://www.ietf.org/rfc/rfc2060.txt"
#:date "1996")
(bib-entry #:key "RFC2109"
#:title "HTTP State Management Mechanism"
#:author "D. Kristol and L. Montulli"
#:location "RFC"
#:url "http://www.ietf.org/rfc/rfc2109.txt"
#:date "1997")
(bib-entry #:key "RFC2396"
#:title "Uniform Resource Identifiers (URI): Generic Syntax"
#:author "T. Berners-Lee, R. Fielding, and L. Masinter"

View File

@ -4,7 +4,7 @@
net/nntp-unit
net/nntp-sig))
@title{NNTP: Newsgroup Protocol}
@title[#:tag "nntp"]{NNTP: Newsgroup Protocol}
@defmodule[net/nntp]{The @schememodname[net/nntp] module provides
tools to access Usenet group via NNTP @cite["RFC977"].}

View File

@ -6,7 +6,7 @@
@(define pt (tt ">"))
@title{POP3: Reading Mail}
@title[#:tag "pop3"]{POP3: Reading Mail}
@defmodule[net/pop3]{The @schememodname[net/pop3] module provides
tools for the Post Office Protocol version 3 @cite["RFC977"].}

View File

@ -0,0 +1,86 @@
#lang scribble/doc
@(require "common.ss"
(for-label net/qp
net/qp-unit
net/qp-sig))
@title[#:tag "qp"]{Quoted-Printable: Encoding and Decoding}
@defmodule[net/qp]{The @schememodname[net/qp] library provides
utilities for quoted-printable (mime-standard) encoding and decoding
from RFC 2045 section 6.7.
The library was written by Francisco Solsona.}
@section[#:tag "qp-procs"]{Functions}
@defproc[(qp-encode [bstr bytes?]) bytes?]{
Consumes a byte string and returns its quoted printable representation
as a new string. The encoded string uses @scheme[#"\r\n"] where
necessary to create shorter lines.}
@defproc[(qp-decode [bstr bytes?]) bytes?]{
Consumes a byte string and returns its un-quoted printable
representation as a new string. Non-soft line breaks are preserved in
whatever form they exist (CR, LR, or CRLF) in the input string.}
@defproc[(qp-encode-stream [in input-port?]
[out output-port?]
[newline-bstr bytes? #"\n"])
void?]{
Reads characters from @scheme[in] and writes the quoted printable
encoded result to @scheme[out].
The @scheme[newline-bstr] argument is used for soft line-breaks (after
@litchar{=}). Note that the default @scheme[newline-bstr] is just
@scheme[#"\n"], not @scheme[#"\r\n"].
Other line breaks are preserved in whatever form they exist (CR, LR,
or CRLF) in the input stream.}
@defproc[(qp-decode-stream [in input-port?]
[out output-port?])
void?]{
Reads characters from @scheme[in] and writes de-quoted-printable
result to @scheme[out]. Non-soft line breaks are preserved in
whatever form they exist (CR, LR, or CRLF) in the input stream.}
@; ----------------------------------------
@section[#:tag "qp-exn"]{Exceptions}
@deftogether[(
@defstruct[qp-error ()]
@defstruct[(qp-wrong-input qp-error) ()]
@defstruct[(qp-wrong-line-size qp-error) ()]
)]{
None of these are used anymore, but the bindings are preserved for
backward compatibility.}
@; ----------------------------------------
@section{Quoted-Printable Unit}
@defmodule[net/qp-unit]
@defthing[qp@ unit?]{
Imports nothing, exports @scheme[qp^].}
@; ----------------------------------------
@section{-Printable Signature}
@defmodule[net/qp-sig]
@defsignature[qp^ ()]{}
Includes everything exported by the @schememodname[net/qp] module.

View File

@ -4,7 +4,7 @@
net/sendmail-unit
net/sendmail-sig))
@title{@exec{sendmail}: Sending E-Mail}
@title[#:tag "sendmail"]{@exec{sendmail}: Sending E-Mail}
@defmodule[net/sendmail]{The @schememodname[net/sendmail] module
provides tools for sending electronic mail messages using a

View File

@ -3,7 +3,7 @@
(for-label net/sendurl
scheme/file))
@title{Send URL: Opening a Web Browser}
@title[#:tag "sendurl"]{Send URL: Opening a Web Browser}
@defmodule[net/sendurl]{Provides @scheme[send-url] for opening a URL
in the user's chosen web browser.}

View File

@ -6,7 +6,7 @@
scheme/tcp
openssl))
@title{SMTP: Sending E-Mail}
@title[#:tag "smtp"]{SMTP: Sending E-Mail}
@defmodule[net/smtp]{The @schememodname[net/smtp] module provides
tools for sending electronic mail messages using SMTP. The client must

View File

@ -0,0 +1,56 @@
#lang scribble/doc
@(require "common.ss"
(for-label net/ssl-tcp-unit
net/tcp-sig))
@title[#:tag "ssl-tcp-unit"]{SSL Unit: @scheme[tcp^] via SSL}
@defmodule[net/ssl-tcp-unit]{The @schememodname[net/ssl-tcp-unit]
library provides a function for creating a @scheme[tcp^]
implementation with @schememodname[openssl] functionality.}
@defproc[(make-ssl-tcp@ [server-cert-file (or/c path-string? false/c)]
[server-key-file (or/c path-string? false/c)]
[server-root-cert-files (or/c (listof path-string?) false/c)]
[server-suggest-auth-file path-string?]
[client-cert-file (or/c path-string? false/c)]
[client-key-file (or/c path-string? false/c)]
[client-root-cert-files (listof path-string?)])
unit?]{
Returns a unit that implements @scheme[tcp^] using the SSL functions
from @schememodname[openssl]. The arguments to @scheme[make-ssl-tcp@]
control the certificates and keys uses by server and client
connections:
@itemize[
@item{@scheme[server-cert-file] --- a PEM file for a server's
certificate; @scheme[#f] means no certificate (which is unlikely
to work with any SSL client)}
@item{@scheme[server-key-file] --- a private key PEM to go with
@scheme[server-cert-file]; @scheme[#f] means no key (which is likely
renders a certificate useless)}
@item{@scheme[server-root-cert-files] --- a list of PEM files for
trusted root certificates; @scheme[#f] disables verification of
peer client certificates}
@item{@scheme[server-suggest-auth-file] --- PEM file for root
certificates to be suggested to peer clients that must supply
certificates}
@item{@scheme[client-cert-file] --- a PEM file for a client's
certificate; @scheme[#f] means no certificate (which is usually
fine)}
@item{@scheme[client-key-file] --- a private key PEM to go with
@scheme[client-cert-file]; @scheme[#f] means no key (which is likely
renders a certificate useless)}
@item{@scheme[client-root-cert-files] --- a list of PEM files for
trusted root certificates; @scheme[#f] disables verification of
peer server certificates}
]}

View File

@ -0,0 +1,23 @@
#lang scribble/doc
@(require "common.ss"
(for-label net/tcp-redirect
net/tcp-sig))
@title[#:tag "tcp-redirect"]{TCP Redirect: @scheme[tcp^] via Channels}
@defmodule[net/tcp-redirect]{The @schememodname[net/tcp-redirect]
library provides a function for directing some TCP port numbers to use
buffered channels instead of the TCP support from
@schememodname[scheme/tcp].}
@defproc[(tcp-redirect [port-numbers (listof (integer-in 0 65535))])
unit?]{
Returns a unit that implements @scheme[tcp^]. For port numbers not
listed in @scheme[port-numbers], the unit's implementations are the
@schememodname[scheme/tcp] implementations.
For the port numbers listed in @scheme[port-numbers] and for
connections to @scheme["127.0.0.1"], the unit's implementation does
not use TCP connections, but instead uses internal buffered
channels. Such channels behave exactly as TCP listeners and ports.}

View File

@ -0,0 +1,104 @@
#lang scribble/doc
@(require "common.ss"
(for-label net/tcp-sig
net/tcp-unit
net/url-unit
net/tcp-redirect
net/ssl-tcp-unit
scheme/tcp))
@title[#:tag "tcp"]{TCP: Unit and Signature}
The @schememodname[net/tcp-sig] and @schememodname[net/tcp-unit]
libraries define a @scheme[tcp^] signature and @scheme[tcp@]
implementation, where the implementation uses
@schememodname[scheme/tcp].
Some units in the @filepath{net} collection import @scheme[tcp^], so
that they can be used with transports other than plain TCP. For
example, @scheme[url@] imports @scheme[tcp^].
See also @scheme[tcp-redirect] and @scheme[make-ssl-tcp@].
@section{TCP Signature}
@defmodule[net/tcp-sig]
@defsignature[tcp^ ()]{
@defproc[(tcp-listen [port-no (and/c nonnegative-exact-integer?
(integer-in 1 65535))]
[max-allow-wait nonnegative-exact-integer? 4]
[reuse? any/c #f]
[hostname (or/c string? false/c) #f])
#, @sigelem[tcp^ tcp-listener?]]{
Like @scheme[tcp-listen] from @schememodname[scheme/tcp].}
@defproc[(tcp-connect [hostname string?]
[port-no (and/c nonnegative-exact-integer?
(integer-in 1 65535))]
[local-hostname (or/c string? false/c) #f]
[local-port-no (or/c (and/c nonnegative-exact-integer?
(integer-in 1 65535))
false/c)
#f])
(values input-port? output-port?)]{
Like @scheme[tcp-connect] from @schememodname[scheme/tcp].}
@defproc[(tcp-connect/enable-break [hostname string?]
[port-no (and/c nonnegative-exact-integer?
(integer-in 1 65535))]
[local-hostname (or/c string? false/c) #f]
[local-port-no (or/c (and/c nonnegative-exact-integer?
(integer-in 1 65535))
false/c)])
(values input-port? output-port?)]{
Like @scheme[tcp-connect/enable-break] from @schememodname[scheme/tcp].}
@defproc[(tcp-accept [listener #, @sigelem[tcp^ tcp-listener?]])
(values input-port? output-port?)]{
Like @scheme[tcp-accept] from @schememodname[scheme/tcp].}
@defproc[(tcp-accept/enable-break [listener #, @sigelem[tcp^ tcp-listener?]])
(values input-port? output-port?)]{
Like @scheme[tcp-accept/enable-break] from @schememodname[scheme/tcp].}
@defproc[(tcp-accept-ready? [listener #, @sigelem[tcp^ tcp-listener?]]) boolean?]{
Like @scheme[tcp-accept-ready?] from @schememodname[scheme/tcp].}
@defproc[(tcp-close [listener #, @sigelem[tcp^ tcp-listener?]]) void?]{
Like @scheme[tcp-close] from @schememodname[scheme/tcp].}
@defproc[(tcp-listener? [v any/c]) boolean?]{
Like @scheme[tcp-listener?] from @schememodname[scheme/tcp].}
@defproc[(tcp-abandon-port [tcp-port port?]) void?]{
Like @scheme[tcp-abandon-port] from @schememodname[scheme/tcp].}
@defproc[(tcp-addresses [tcp-port port?]
[port-numbers? any/c #f])
(or/c (values string? string?)
(values string? (integer-in 1 65535)
string? (integer-in 1 65535)))]{
Like @scheme[tcp-addresses] from @schememodname[scheme/tcp].}
}
@section{TCP Unit}
@defmodule[net/tcp-unit]
@defthing[tcp@ unit?]{
Imports nothing and exports @scheme[tcp^], implemented using
@schememodname[scheme/tcp].}

View File

@ -10,7 +10,7 @@
@(define uri-codec-eval (make-base-eval))
@interaction-eval[#:eval uri-codec-eval (require net/uri-codec)]
@title{URI Codec: Encoding and Decoding URIs}
@title[#:tag "uri-codec"]{URI Codec: Encoding and Decoding URIs}
@defmodule[net/uri-codec]{The @schememodname[net/uri-codec] module
provides utilities for encoding and decoding strings using the URI

View File

@ -7,7 +7,7 @@
net/head
net/uri-codec))
@title{URLs and HTTP}
@title[#:tag "url"]{URLs and HTTP}
@defmodule[net/url]{The @schememodname[net/url] library provides
utilities to parse and manipulate URIs, as specified in RFC 2396