diff --git a/collects/net/scribblings/base64.scrbl b/collects/net/scribblings/base64.scrbl new file mode 100644 index 0000000000..f052b24ade --- /dev/null +++ b/collects/net/scribblings/base64.scrbl @@ -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. diff --git a/collects/net/scribblings/cgi.scrbl b/collects/net/scribblings/cgi.scrbl index 915fbf4c67..abfb1795e2 100644 --- a/collects/net/scribblings/cgi.scrbl +++ b/collects/net/scribblings/cgi.scrbl @@ -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"].} diff --git a/collects/net/scribblings/cookie.scrbl b/collects/net/scribblings/cookie.scrbl new file mode 100644 index 0000000000..0cab806c86 --- /dev/null +++ b/collects/net/scribblings/cookie.scrbl @@ -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. diff --git a/collects/net/scribblings/dns.scrbl b/collects/net/scribblings/dns.scrbl index b586f983b2..8416e98d35 100644 --- a/collects/net/scribblings/dns.scrbl +++ b/collects/net/scribblings/dns.scrbl @@ -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 diff --git a/collects/net/scribblings/ftp.scrbl b/collects/net/scribblings/ftp.scrbl new file mode 100644 index 0000000000..1f0ee6b7af --- /dev/null +++ b/collects/net/scribblings/ftp.scrbl @@ -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. diff --git a/collects/net/scribblings/head.scrbl b/collects/net/scribblings/head.scrbl index 9a17add642..4b186161c7 100644 --- a/collects/net/scribblings/head.scrbl +++ b/collects/net/scribblings/head.scrbl @@ -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 diff --git a/collects/net/scribblings/imap.scrbl b/collects/net/scribblings/imap.scrbl index 1ffeee1ed1..cbce91ff14 100644 --- a/collects/net/scribblings/imap.scrbl +++ b/collects/net/scribblings/imap.scrbl @@ -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 diff --git a/collects/net/scribblings/mime.scrbl b/collects/net/scribblings/mime.scrbl index e355895701..44c265171e 100644 --- a/collects/net/scribblings/mime.scrbl +++ b/collects/net/scribblings/mime.scrbl @@ -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. diff --git a/collects/net/scribblings/net.scrbl b/collects/net/scribblings/net.scrbl index 759f1289f8..a2226e3c31 100644 --- a/collects/net/scribblings/net.scrbl +++ b/collects/net/scribblings/net.scrbl @@ -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" diff --git a/collects/net/scribblings/nntp.scrbl b/collects/net/scribblings/nntp.scrbl index 8f00cfa58e..8d02f619e3 100644 --- a/collects/net/scribblings/nntp.scrbl +++ b/collects/net/scribblings/nntp.scrbl @@ -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"].} diff --git a/collects/net/scribblings/pop3.scrbl b/collects/net/scribblings/pop3.scrbl index dc22d84281..b8c8555377 100644 --- a/collects/net/scribblings/pop3.scrbl +++ b/collects/net/scribblings/pop3.scrbl @@ -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"].} diff --git a/collects/net/scribblings/qp.scrbl b/collects/net/scribblings/qp.scrbl new file mode 100644 index 0000000000..000ab2c81c --- /dev/null +++ b/collects/net/scribblings/qp.scrbl @@ -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. diff --git a/collects/net/scribblings/sendmail.scrbl b/collects/net/scribblings/sendmail.scrbl index 0e41d4b644..cdb4be97a1 100644 --- a/collects/net/scribblings/sendmail.scrbl +++ b/collects/net/scribblings/sendmail.scrbl @@ -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 diff --git a/collects/net/scribblings/sendurl.scrbl b/collects/net/scribblings/sendurl.scrbl index bb3103b62b..96317df1fb 100644 --- a/collects/net/scribblings/sendurl.scrbl +++ b/collects/net/scribblings/sendurl.scrbl @@ -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.} diff --git a/collects/net/scribblings/smtp.scrbl b/collects/net/scribblings/smtp.scrbl index caeb880437..5c38d000bc 100644 --- a/collects/net/scribblings/smtp.scrbl +++ b/collects/net/scribblings/smtp.scrbl @@ -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 diff --git a/collects/net/scribblings/ssl-tcp-unit.scrbl b/collects/net/scribblings/ssl-tcp-unit.scrbl new file mode 100644 index 0000000000..c78ed27ec8 --- /dev/null +++ b/collects/net/scribblings/ssl-tcp-unit.scrbl @@ -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} + +]} \ No newline at end of file diff --git a/collects/net/scribblings/tcp-redirect.scrbl b/collects/net/scribblings/tcp-redirect.scrbl new file mode 100644 index 0000000000..4aa735aefb --- /dev/null +++ b/collects/net/scribblings/tcp-redirect.scrbl @@ -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.} diff --git a/collects/net/scribblings/tcp.scrbl b/collects/net/scribblings/tcp.scrbl new file mode 100644 index 0000000000..610ea9d28f --- /dev/null +++ b/collects/net/scribblings/tcp.scrbl @@ -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].} diff --git a/collects/net/scribblings/uri-codec.scrbl b/collects/net/scribblings/uri-codec.scrbl index a8a6b9a229..261301fef8 100644 --- a/collects/net/scribblings/uri-codec.scrbl +++ b/collects/net/scribblings/uri-codec.scrbl @@ -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 diff --git a/collects/net/scribblings/url.scrbl b/collects/net/scribblings/url.scrbl index 0317f38c0f..43fa60828c 100644 --- a/collects/net/scribblings/url.scrbl +++ b/collects/net/scribblings/url.scrbl @@ -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