diff --git a/collects/net/doc/cgi.scrbl b/collects/net/doc/cgi.scrbl new file mode 100644 index 0000000000..915fbf4c67 --- /dev/null +++ b/collects/net/doc/cgi.scrbl @@ -0,0 +1,156 @@ +#lang scribble/doc +@(require "common.ss" + (for-label net/cgi + net/cgi-unit + net/cgi-sig)) + +@title{CGI Scripts} + +@defmodule[net/cgi]{The @schememodname[net/cgi] module provides tools +for scripts that follow the Common Gateway Interface @cite["CGI"].} + +The @schememodname[net/cgi] library expects to be run in a certain +context as defined by the CGI standard. This means, for instance, +that certain environment variables will be bound. + +Unfortunately, not all CGI environments provide this. For instance, +the FastCGI library, despite its name, does not bind the environment +variables required of the standard. Users of FastCGI will need to +bind @envvar{REQUEST_METHOD} and possibly also @envvar{QUERY_STRING} +to successfully employ the CGI library. The FastCGI library ought to +provide a way to extract the values bound to these variables; the user +can then put these into the CGI program's environment using the +@scheme[putenv] function. + +A CGI @deftech{binding} is an association of a form item with its +value. Some form items, such as checkboxes, may correspond to +multiple bindings. A binding is a tag-string pair, where a tag is a +symbol or a string. + +@; ---------------------------------------- + +@section{CGI Functions} + +@deftogether[( +@defproc[(get-bindings) (listof (cons/c (or/c symbol? string?) string?))] +@defproc[(get-bindings/post) (listof (cons/c (or/c symbol? string?) string?))] +@defproc[(get-bindings/get) (listof (cons/c (or/c symbol? string?) string?))] +)]{ + +Returns the bindings that corresponding to the options specified by +the user. The @scheme[get-bindings/post] and +@scheme[get-bindings/get] variants work only when POST and GET forms +are used, respectively, while @scheme[get-bindings] determines the +kind of form that was used and invokes the appropriate function.} + + +@defproc[(extract-bindings [key? (or/c symbol? string?)] + [bindings (listof (cons/c (or/c symbol? string?) string?))]) + (listof string?)]{ + +Given a key and a set of bindings, determines which ones correspond to +a given key. There may be zero, one, or many associations for a given +key.} + + +@defproc[(extract-binding/single [key? (or/c symbol? string?)] + [bindings (listof (cons/c (or/c symbol? string?) string?))]) + string?]{ + +Like @scheme[extract-bindings], but for a key that has exactly one +association.} + + +@defproc[(output-http-headers) void?]{ + +Outputs all the HTTP headers needed for a normal response. Only +call this function if you are not using @scheme[generate-html-output] or +@scheme[generate-error-output].} + + +@defproc[(generate-html-output [title string?] + [body (listof string?)] + [text-color string? "#000000"] + [bg-color string? "#ffffff"] + [link-color string? "#cc2200"] + [vlink-color string? "#882200"] + [alink-color string? "#444444"]) + void?]{ + +Outputs an response: a title and a list of strings for the body. + +The last five arguments are each strings representing a HTML color; in +order, they represent the color of the text, the background, +un-visited links, visited links, and a link being selected.} + + +@defproc[(string->html [str string?]) string?]{ + +Converts a string into an HTML string by applying the appropriate HTML +quoting conventions.} + + +@defproc[(generate-link-text [str string?] [html-str string?]) string?]{ + +Takes a string representing a URL, a HTML string for the anchor +text, and generates HTML corresponding to an anchor.} + + +@defproc[(generate-error-output [strs (listof string?)]) any]{ + +The procedure takes a list of HTML strings representing the body, +prints them with the subject line "Internal error", and exits via +@scheme[exit].} + + +@defproc[(get-cgi-method) (one-of/c "GET" "POST")]{ + +Returns either @scheme["GET"] or @scheme["POST"] when invoked inside a +CGI script, unpredictable otherwise.} + + +@defproc[(bindings-as-html (listof (cons/c (or/c symbol? string?) string?))) + (listof string?)]{ + +Converts a set of bindings into a list of HTML strings, which is +useful for debugging.} + + +@defstruct[cgi-error ()]{ + +A supertype for all exceptions thrown by the @schememodname[net/cgi] +library.} + + +@defstruct[(incomplete-%-suffix cgi-error) ([chars (listof char?)])]{ + +Raised when a @litchar{%} in a query is followed by an incomplete +suffix. The characters of the suffix---excluding the +@litchar{%}---are provided by the exception.} + + +@defstruct[(invalid-%-suffix cgi-error) ([char char?])]{ + +Raised when the character immediately following a @litchar{%} in a +query is invalid.} + + +@; ---------------------------------------- + +@section{CGI Unit} + +@defmodule[net/cgi-unit] + +@defthing[cgi@ unit?]{ + +Imports nothing, exports @scheme[cgi^].} + +@; ---------------------------------------- + +@section{CGI Signature} + +@defmodule[net/cgi-sig] + +@defsignature[cgi^ ()]{} + +Includes everything exported by the @schememodname[net/cgi] module. diff --git a/collects/net/doc/common.ss b/collects/net/doc/common.ss new file mode 100644 index 0000000000..7b1497d834 --- /dev/null +++ b/collects/net/doc/common.ss @@ -0,0 +1,9 @@ +#lang scheme/base + +(require scribble/manual + (for-label scheme/base + scheme/contract)) + +(provide (all-from-out scribble/manual) + (for-label (all-from-out scheme/base + scheme/contract))) diff --git a/collects/net/doc/info.ss b/collects/net/doc/info.ss new file mode 100644 index 0000000000..3cbc2bca08 --- /dev/null +++ b/collects/net/doc/info.ss @@ -0,0 +1,3 @@ +(module info setup/infotab + (define name "Net documentation") + (define scribblings '(("net.scrbl" (multi-page main-doc))))) diff --git a/collects/net/doc/net.scrbl b/collects/net/doc/net.scrbl new file mode 100644 index 0000000000..694460d437 --- /dev/null +++ b/collects/net/doc/net.scrbl @@ -0,0 +1,36 @@ +#lang scribble/doc +@(require "common.ss") + +@title{@bold{Net}: PLT Networking Libraries} + +@table-of-contents[] + +@include-section["url.scrbl"] +@include-section["sendurl.scrbl"] +@include-section["smtp.scrbl"] +@include-section["cgi.scrbl"] +@include-section["sendmail.scrbl"] + +@(bibliography + + (bib-entry #:key "CGI" + #:title "Common Gateway Interface (CGI/1.1)" + #:url "http://hoohoo.ncsa.uiuc.edu/cgi/") + + (bib-entry #:key "RFC2396" + #:title "Uniform Resource Identifiers (URI): Generic Syntax" + #:author "T. Berners-Lee, R. Fielding, and L. Masinter" + #:location "RFC" + #:url "http://www.ietf.org/rfc/rfc2396.txt" + #:date "1998") + + (bib-entry #:key "RFC3986" + #:title "Uniform Resource Identifier (URI): Generic Syntax" + #:author "T. Berners-Lee, R. Fielding, and L. Masinter" + #:location "RFC" + #:url "http://www.ietf.org/rfc/rfc3986.txt" + #:date "2005") + +) + +@index-section[] diff --git a/collects/net/doc/sendmail.scrbl b/collects/net/doc/sendmail.scrbl new file mode 100644 index 0000000000..9317719593 --- /dev/null +++ b/collects/net/doc/sendmail.scrbl @@ -0,0 +1,82 @@ +#lang scribble/doc +@(require "common.ss" + (for-label net/sendmail + net/sendmail-unit + net/sendmail-sig)) + +@title{Sending E-Mail via @exec{sendmail}} + +@defmodule[net/sendmail]{The @schememodname[net/sendmail] module +provides tools for sending electronic mail messages using a +@exec{sendmail} program on the local system. See also the +@scheme[net/smtp] package, which sends mail via SMTP.} + +All strings used in mail messages are assumed to conform to their +corresponding SMTP specifications, except as noted otherwise. + +@section{Sendmail Functions} + +@defproc[(send-mail-message/port [from string?] + [subject string?] + [to (listof string?)] + [cc (listof string?)] + [bcc (listof string?)] + [extra-header string?] ...) + output-port?]{ + +The first argument is the header for the sender, the second is the +subject line, the third a list of ``To:'' recipients, the fourth a +list of ``CC:'' recipients, and the fifth a list of ``BCC:'' +recipients. Additional arguments argument supply other mail headers, +which must be provided as lines (not terminated by a linefeed or +carriage return) to include verbatim in the header. + +The return value is an output port into which the client must write +the message. Clients are urged to use @scheme[close-output-port] on +the return value as soon as the necessary text has been written, so +that the sendmail process can complete. + +The @scheme[from] argument can be any value; of course, spoofing +should be used with care.} + +@defproc[(send-mail-message/port [from string?] + [subject string?] + [to (listof string?)] + [cc (listof string?)] + [bcc (listof string?)] + [body (listof string?)] + [extra-header string?] ...) + void?]{ + +Like @scheme[send-mail-message/port], but with @scheme[body] as a list +of strings, each providing a line of the message body. + +Lines that contain a single period do not need to be quoted.} + + +@defstruct[(no-mail-recipients exn) ()]{ + +Raised when no mail recipients were specified for +@scheme[send-mail-message/port].} + + + +@; ---------------------------------------- + +@section{Sendmail Unit} + +@defmodule[net/sendmail-unit] + +@defthing[sendmail@ unit?]{ + +Imports nothing, exports @scheme[sendmail^].} + +@; ---------------------------------------- + +@section{Sendmail Signature} + +@defmodule[net/sendmail-sig] + +@defsignature[sendmail^ ()]{} + +Includes everything exported by the @schememodname[net/sendmail] module. diff --git a/collects/net/doc/sendurl.scrbl b/collects/net/doc/sendurl.scrbl new file mode 100644 index 0000000000..b1ed47e493 --- /dev/null +++ b/collects/net/doc/sendurl.scrbl @@ -0,0 +1,69 @@ +#lang scribble/doc +@(require "common.ss" + (for-label net/sendurl + scheme/file)) + +@title{Opening a Web Browser} + +@defmodule[net/sendurl]{Provides @scheme[send-url] for opening a URL +in the user's chosen web browser.} + +See also @schememodname[browser/external], which requires +@scheme[scheme/gui], but can prompt the user for a browser if no +browser preference is set. + + +@defproc[(send-url [str string?] [separate-window? any/c #t]) + void?]{ + +Opens @scheme[str], which represents a URL, in a platform-specific +manner. For some platforms and configurations, the +@scheme[separate-window?] parameter determines if the browser creates +a new window to display the URL or not. + +Under Windows, @scheme[send-url] normally uses @scheme[shell-execute] +to launch a browser. If the URL appears to contain a fragment, it may +instead use @exec{ftype htmlfile} to obtain a command-line to run, +since @scheme[shell-execute] drops a fragment. + +Under Mac OS X, @scheme[send-url] runs @exec{osascript} to start the +user's chosen browser. + +Under Unix, @scheme[send-url] uses the value of the +@scheme[external-browser] parameter to select a browser.} + + +@defparam[external-browser cmd browser-preference?]{ + +A parameter that, under Unix, determines the browser started +@scheme[send-url]. + +The parameter is initialized to the value of the +@scheme['external-browser] preference. + +The parameter value can be any of the symbols in +@scheme[unix-browser-list], @scheme[#f] to indicate that the +preference is under, or a pair of strings. If the preference is +unset, @scheme[send-url] uses the first of the browsers from +@scheme[unix-browser-list] for which the executable is found. If the +parameter is a pair of strings, then a command line is constructed by +concatenating in order the first string, the URL string, and the +second string. + +If the preferred or default browser can't be launched, +@scheme[send-url] fails. See @scheme[get-preference] and +@scheme[put-preferences] for details on setting preferences.} + +@defproc[(browser-preference? [a any/c]) boolean?]{ + +Returns @scheme[#t] if @scheme[v] is a valid browser preference, +@scheme[#f] otherwise. See @scheme[external-browser] for more +information.} + +@defthing[unix-browser-list (listof symbol?)]{ + +A list of symbols representing Unix executable names that may be tried +in order by @scheme[send-url]. The @scheme[send-url] function +internally includes information on how to launch each executable with +a URL.} + diff --git a/collects/net/doc/smtp.scrbl b/collects/net/doc/smtp.scrbl new file mode 100644 index 0000000000..43f523b97c --- /dev/null +++ b/collects/net/doc/smtp.scrbl @@ -0,0 +1,123 @@ +#lang scribble/doc +@(require "common.ss" + (for-label net/smtp + net/smtp-unit + net/smtp-sig + scheme/tcp + openssl)) + +@title{Sending E-Mail via SMTP} + +@defmodule[net/smtp]{The @schememodname[net/smtp] module provides +tools for sending electronic mail messages using SMTP. The client must +provide the address of an SMTP server; in contrast, the +@schememodname[net/sendmail] module uses a pre-configured +@exec{sendmail} on the local system.} + +The @schememodname[net/head] library defines the format of a +@tech{header} string, which is used by @scheme[send-smtp-message]. The +@schememodname[net/head] module also provides utilities to verify the +formatting of a mail address. The procedures of the @scheme[net/smtp] +module assume that the given string arguments are well-formed. + + +@section{SMTP Functions} + +@defproc[(smtp-send-message [server-address string?] + [from string?] + [to (listof string?)] + [header string?] + [message (listof (or/c string? bytes?))] + [#:port-no port-no/k (integer-in 0 65535) 25] + [#:auth-user user (or/c string? false/c) #f] + [#:auth-passwd pw (or/c string? false/c) #f] + [#:tcp-connect connect + ((string? (integer-in 0 65535)) + . ->* . (input-port? output-port?)) + tcp-connect] + [#:tls-encode encode + (or/c false/c + ((input-port? output-port? + #:mode (one-of/c 'connect) + #:encrypt (one-of/c 'tls) + #:close-original? (one-of/c #t)) + . ->* . (input-port? output-port?))) + #f] + [port-no (integer-in 0 65535) port-no/k]) + void?]{ + +Connects to the server at @scheme[server-address] and @scheme[port-no] +to send a message. The @scheme[from] argument specifies the mail +address of the sender, and @scheme[to] is a list of recipient +addresses (including ``To:'', ``CC'', and ``BCC'' recipients). + +The @scheme[header] argument is the complete message header, which +should already include ``From:'', ``To:'', and ``CC:'' fields +consistent with the given sender and recipients. See also the +@schememodname[net/head] library for header-creating utilities. + +The @scheme[message] argument is the body of the message, where each +string or byte string in the list corresponds to a single line of +message text. No string in @scheme[message] should contain a carriage +return or linefeed character. + +The optional @scheme[port-no] argument---which can be specified either +with the @scheme[#:port-no] keyword or, for backward compatibility, as +an extra argument after keywords---specifies the IP port to use in +contacting the SMTP server. + +The optional @scheme[#:auth-user] and @scheme[#:auth-passwd] keyword +argument supply a username and password for authenticated SMTP (using +the AUTH PLAIN protocol). + +The optional @scheme[#:tcp-connect] keyword argument supplies a +connection procedure to be used in place of @scheme[tcp-connect]. For +example, use @scheme[ssl-connect] to connect to the server via SSL. + +If the optional @scheme[#:tls-encode] keyword argument supplies a +procedure instead of #f, then the ESMTP STARTTLS protocol is used to +initiate SSL communication with the server. The procedure given as the +#:tls-encode argument should be like @scheme[ports->ssl-ports]; it +will be called as + +@schemeblock[ +(encode r w #:mode 'connect #:encrypt 'tls #:close-original? #t) +] + +and it should return two values: an input port and an export port. +All further SMTP communication uses the returned ports. + +For encrypted communication, normally either @scheme[ssl-connect] +should be supplied for @scheme[#:tcp-connect], or +@scheme[ports->ssl-ports] should be supplied for +@scheme[#:tls-encode]---one or the other (depending on what the server +expects), rather than both.} + +@defparam[smtp-sending-end-of-message proc (-> any)]{ + +A parameter that determines a send-done procedure to be called after +@scheme[smtp-send-message] has completely sent the message. Before the +send-done procedure is called, breaking the thread that is executing +@scheme[smtp-send-message] cancels the send. After the send-done +procedure is called, breaking may or may not cancel the send (and +probably will not).} + +@; ---------------------------------------- + +@section{SMTP Unit} + +@defmodule[net/SMTP-unit] + +@defthing[smtp@ unit?]{ + +Imports nothing, exports @scheme[smtp^].} + +@; ---------------------------------------- + +@section{SMTP Signature} + +@defmodule[net/smtp-sig] + +@defsignature[smtp^ ()]{} + +Includes everything exported by the @schememodname[net/smtp] module. diff --git a/collects/net/doc/url.scrbl b/collects/net/doc/url.scrbl new file mode 100644 index 0000000000..f806a6a09a --- /dev/null +++ b/collects/net/doc/url.scrbl @@ -0,0 +1,304 @@ +#lang scribble/doc +@(require "common.ss" + scribble/bnf + (for-label net/url + net/url-unit + net/url-sig + net/head + net/uri-codec)) + +@title{URLs and HTTP} + +@defmodule[net/url]{The @schememodname[net/url] library provides +utilities to parse and manipulate URIs, as specified in RFC 2396 +@cite["RFC2396"], and to use the HTTP protocol.} + +To access the text of a document from the web, first obtain its URL as +a string. Convert the address into a @scheme[url] structure using +@scheme[string->url]. Then, open the document using +@scheme[get-pure-port] or @scheme[get-impure-port], depending on +whether or not you wish to examine its MIME headers. At this point, +you have a regular input port with which to process the document, as with +any other file. + +Currently the only supported protocols are @scheme["http"] and +sometimes @scheme["file"]. See also the @schememodname[net/news] +library. + +@section{URL Structure} + +@declare-exporting[net/url-struct net/url] + +@defmodule*/no-declare[(net/url-struct)]{The URL structure types are +provided by the @schememodname[net/url-struct] library, and +re-exported by @schememodname[net/url].} + +@; ---------------------------------------- + + +@defstruct[url ([scheme (or/c false/c string?)] + [user (or/c false/c string?)] + [host (or/c false/c string?)] + [port (or/c false/c exact-nonnegative-integer?)] + [path-absolute? boolean?] + [path (listof path/param?)] + [query (listof (cons/c symbol? (or/c false/c string?)))] + [fragment (union false/c string?)])]{ + +The basic structure for all URLs, hich is explained in RFC 3986 +@cite["RFC3986"]. The following diagram illustrates the parts: + +@verbatim[#<url] and @scheme[url->string] translate encodings such +as @litchar{%20} into spaces and back again. + +By default, query associations are parsed with either @litchar{;} or +@litchar{&} as a separator, and they are generated with @litchar{&} as +a separator. The @scheme[current-alist-separator-mode] parameter +adjusts the behavior. + +An empty string at the end of the @scheme[path] list corresponds to a +URL that ends in a slash. For example, the result of +@scheme[(string->url "http://www.drscheme.org/a/")] has a +@scheme[path] field with strings @scheme["a"] and @scheme[""], while +the result of @scheme[(string->url "http://www.drscheme.org/a")] has a +@scheme[path] field with only the string @scheme["a"].} + +@defstruct[path/param ([path (or/c string? (one-of/c 'up 'same))] + [param (listof string?)])]{ + +A pair that joins a path segment with its params in a URL.} + +@; ---------------------------------------- + +@section{URL Functions} + +An HTTP connection is created as a @deftech{pure port} or a +@deftech{impure port}. A pure port is one from which the MIME headers +have been removed, so that what remains is purely the first content +fragment. An impure port is one that still has its MIME headers. + +@defproc[(string->url [str string?]) url?]{ + +Parses the URL specified by @scheme[str] into a @scheme[url] +struct. The @scheme[string->url] procedure uses +@scheme[form-urlencoded->alist] when parsing the query, so it is +sensitive to the @scheme[current-alist-separator-mode] parameter for +determining the association separator.} + + +@defproc[(combine-url/relative [base url?] [relative string?]) url?]{ + +Given a base URL and a relative path, combines the two and returns a +new URL as per the URL combination specification. They are combined +according to the rules in RFC 3986 @cite["RFC3986"]. + +This function does not raise any exceptions.} + + +@defproc[(netscape/string->url [str string?]) url?]{ + +Turns a string into a URL, applying (what appear to be) Netscape's +conventions on automatically specifying the scheme: a string starting +with a slash gets the scheme @scheme["file"], while all others get the +scheme @scheme["http"].} + + +@defproc[(url->string [URL url?]) string?]{ + +Generates a string corresponding to the contents of a @scheme[url] struct. +For a @scheme["file:"] URL, empty strings in the path list are treated as +@scheme['same] for @scheme[build-path]. + +The @scheme[url->string] procedure uses +@scheme[alist->form-urlencoded] when formatting the query, so it it +sensitive to the @scheme[current-alist-separator-mode] parameter for +determining the association separator. The default is to separate +associations with a @litchar{&}.} + + + +@deftogether[( +@defproc[(get-pure-port [URL url?] + [header (listof string?) null]) + input-port?] +@defproc[(head-pure-port [URL url?] + [header (listof string?) null]) + input-port?] +@defproc[(delete-pure-port [URL url?] + [header (listof string?) null]) + input-port?] +)]{ + +Initiates a GET/HEAD/DELETE request for @scheme[URL] and returns a +@tech{pure port} corresponding to the body of the response. The +optional list of strings can be used to send header lines to the +server. + +The GET method is used to retrieve whatever information is identified +by @scheme[URL]. + +The HEAD method is identical to GET, except the server must not return +a message body. The meta-information returned in a response to a HEAD +request should be identical to the information in a response to a GET +request. + +The DELETE method is used to delete the entity identified by +@scheme[URL]. + +The @scheme["file"] scheme for URLs is handled only by +@scheme[get-pure-port], which uses @scheme[open-input-file], does not +handle exceptions, and ignores the optional strings.} + +@deftogether[( +@defproc[(get-impure-port [URL url?] + [header (listof string?) null]) + input-port?] +@defproc[(head-impure-port [URL url?] + [header (listof string?) null]) + input-port?] +@defproc[(delete-impure-port [URL url?] + [header (listof string?) null]) + input-port?] +)]{ + +Like @scheme[get-pure-port], etc., but the resulting @tech{impure +port} contains both the returned headers and the body. The +@scheme["file"] URL scheme is not handled by these functions.} + +@deftogether[( +@defproc[(post-pure-port [URL url?] + [post bytes?] + [header (listof string?) null]) + input-port?] +@defproc[(put-pure-port [URL url?] + [post bytes?] + [header (listof string?) null]) + input-port?] +)]{ + +Initiates a POST/PUT request for @scheme[URL] and sends the +@scheme[post] byte string. The result is a @tech{pure port}, which +contains the body of the response is returned. The optional list of +strings can be used to send header lines to the server.} + +@deftogether[( +@defproc[(post-impure-port [URL url?] + [post bytes?] + [header (listof string?) null]) + input-port?] +@defproc[(put-impure-port [URL url?] + [post bytes?] + [header (listof string?) null]) + input-port?] +)]{ + +Like @scheme[post-pure-port] and @scheme[put-pure-port], but the +resulting @tech{impure port} contains both the returned headers and +body.} + + +@defproc[(display-pure-port [in input-port?]) void?]{ + +Writes the output of a pure port, which is useful for debugging purposes.} + + +@defproc[(purify-port [in input-port?]) string?]{ + +Purifies a port, returning the MIME headers, plus a leading line for +the form @litchar{HTTP/}@nonterm{vers}@litchar{ +}@nonterm{code}@litchar{ }@nonterm{message}, where @nonterm{vers} is +something like @litchar{1.0} or @litchar{1.1}, @nonterm{code} is an +exact integer for the response code, and @nonterm{message} is +arbitrary text without a return or newline. + +The @schememodname[net/head.ss] library provides procedures, such as +@scheme[extract-field] for manipulating the header. + +Since web servers sometimes return mis-formatted replies, +@scheme[purify-port] is liberal in what it accepts as a header. as a +result, the result string may be ill formed, but it will either be the +empty string, or it will be a string matching the following regexp: + +@schemeblock[ +#rx"^HTTP/.*?(\r\n\r\n|\n\n|\r\r)" +]} + + +@defproc*[([(call/input-url [URL url?] + [connect (url? . -> . input-port?)] + [handle (input-port? . -> . any)]) + any] + [(call/input-url [URL url?] + [connect (url? (listof string?) . -> . input-port?)] + [handle (input-port? . -> . any)] + [header (listof string?)]) + any])]{ + +Given a URL and a @scheme[connect] procedure like +@scheme[get-pure-port] to convert the URL to an input port (either a +@tech{pure port} or @tech{impure port}), calls the @scheme[handle] +procedure on the port and closes the port on return. The result of the +@scheme[handle] procedure is the result of @scheme[call/input-url]. + +When a @scheme[header] argument is supplied, it is passed along to the +@scheme[connect] procedure. + +The connection is made in such a way that the port is closed before +@scheme[call/input-url] returns, no matter how it returns. In +particular, it is closed if @scheme[handle] raises an exception, or if +the connection process is interruped by an asynchronous break +exception.} + + +@defparam[current-proxy-servers mapping (listof (list/c string? string? (integer-in 0 65535)))]{ + +A parameter that determines a mapping of proxy servers used for +connections. Each mapping is a list of three elements: + +@itemize{ + + @item{the URL scheme, such as @scheme["http"];} + + @item{the proxy server address; and} + + @item{the proxy server port number.} + +} + +Currently, the only proxiable scheme is @scheme["http"]. The default +mapping is the empty list (i.e., no proxies).} + +@; ---------------------------------------- + +@section{URL Unit} + +@defmodule[net/url-unit] + +@defthing[url@ unit?]{ + +Imports @scheme[tcp^], exports @scheme[url^].} + +@; ---------------------------------------- + +@section{URL Signature} + +@defmodule[net/url-sig] + +@defsignature[url^ ()]{ + +Includes everything exported by the @schememodname[net/url] module.} +