summaryrefslogtreecommitdiffstats
path: root/doc/http.n
diff options
context:
space:
mode:
Diffstat (limited to 'doc/http.n')
-rw-r--r--doc/http.n37
1 files changed, 17 insertions, 20 deletions
diff --git a/doc/http.n b/doc/http.n
index 0b3e2c1..15fd250 100644
--- a/doc/http.n
+++ b/doc/http.n
@@ -6,7 +6,7 @@
'\" See the file "license.terms" for information on usage and redistribution
'\" of this file, and for a DISCLAIMER OF ALL WARRANTIES.
'\"
-'\" RCS: @(#) $Id: http.n,v 1.28 2007/10/28 14:17:40 dkf Exp $
+'\" RCS: @(#) $Id: http.n,v 1.29 2007/10/29 01:42:18 dkf Exp $
'\"
.so man.macros
.TH "http" n 2.5 http "Tcl Bundled Packages"
@@ -16,6 +16,7 @@
http \- Client-side implementation of the HTTP/1.0 protocol
.SH SYNOPSIS
\fBpackage require http ?2.5?\fR
+.\" See Also -useragent option documentation in body!
.sp
\fB::http::config \fI?options?\fR
.sp
@@ -45,7 +46,6 @@ http \- Client-side implementation of the HTTP/1.0 protocol
.sp
\fB::http::unregister \fIproto\fR
.BE
-
.SH DESCRIPTION
.PP
The \fBhttp\fR package provides the client side of the HTTP/1.0
@@ -89,7 +89,8 @@ flags and values that define the configuration:
The Accept header of the request. The default is */*, which means that
all types of documents are accepted. Otherwise you can supply a
comma-separated list of mime type patterns that you are
-willing to receive. For example, "image/gif, image/jpeg, text/*".
+willing to receive. For example,
+.QW "image/gif, image/jpeg, text/*" .
.TP
\fB\-proxyhost\fR \fIhostname\fR
The name of the proxy host, if any. If this value is the
@@ -119,8 +120,8 @@ returned by specifying the empty string (\fB{}\fR), although
characters.
.TP
\fB\-useragent\fR \fIstring\fR
-The value of the User-Agent header in the HTTP request. The default
-is \fB"Tcl http client package 2.4."\fR
+The value of the User-Agent header in the HTTP request. The default is
+.QW "\fBTcl http client package 2.5\fR" .
.RE
.TP
\fB::http::geturl\fR \fIurl\fR ?\fIoptions\fR?
@@ -281,10 +282,10 @@ any. This sets the \fBstate(status)\fR value to \fIwhy\fR, which defaults to \f
\fB::http::wait\fR \fItoken\fR
This is a convenience procedure that blocks and waits for the
transaction to complete. This only works in trusted code because it
-uses \fBvwait\fR. Also, it's not useful for the case where
+uses \fBvwait\fR. Also, it is not useful for the case where
\fB::http::geturl\fR is called \fIwithout\fR the \fB-command\fR option
-because in this case the \fB::http::geturl\fR call doesn't return
-until the HTTP transaction is complete, and thus there's nothing to
+because in this case the \fB::http::geturl\fR call does not return
+until the HTTP transaction is complete, and thus there is nothing to
wait for.
.TP
\fB::http::data\fR \fItoken\fR
@@ -317,7 +318,7 @@ This procedure cleans up the state associated with the connection
identified by \fItoken\fR. After this call, the procedures
like \fB::http::data\fR cannot be used to get information
about the operation. It is \fIstrongly\fR recommended that you call
-this function after you're done with a given HTTP request. Not doing
+this function after you are done with a given HTTP request. Not doing
so will result in memory not being freed, and if your app calls
\fB::http::geturl\fR enough times, the memory leak could cause a
performance hit...or worse.
@@ -340,8 +341,7 @@ set token [::http::geturl https://my.secure.site/]
\fB::http::unregister\fR \fIproto\fR
This procedure unregisters a protocol handler that was previously
registered via \fB::http::register\fR.
-
-.SH "ERRORS"
+.SH ERRORS
The \fB::http::geturl\fR procedure will raise errors in the following cases:
invalid command line options,
an invalid URL,
@@ -354,13 +354,12 @@ writing out the HTTP request header.
For synchronous \fB::http::geturl\fR calls (where \fB-command\fR is
not specified), it will raise an error if it gets an I/O error while
reading the HTTP reply headers or data. Because \fB::http::geturl\fR
-doesn't return a token in these cases, it does all the required
-cleanup and there's no issue of your app having to call
+does not return a token in these cases, it does all the required
+cleanup and there is no issue of your app having to call
\fB::http::cleanup\fR.
.PP
For asynchronous \fB::http::geturl\fR calls, all of the above error
-situations apply, except that if there's any error while
-reading the
+situations apply, except that if there is any error while reading the
HTTP reply headers or data, no exception is thrown. This is because
after writing the HTTP headers, \fB::http::geturl\fR returns, and the
rest of the HTTP transaction occurs in the background. The command
@@ -374,7 +373,7 @@ to know the result of the asynchronous HTTP request, it can call
callback does.
.PP
In any case, you must still call
-\fB::http::cleanup\fR to delete the state array when you're done.
+\fB::http::cleanup\fR to delete the state array when you are done.
.PP
There are other possible results of the HTTP transaction
determined by examining the status from \fB::http::status\fR.
@@ -385,7 +384,8 @@ If the HTTP transaction completes entirely, then status will be \fBok\fR.
However, you should still check the \fB::http::code\fR value to get
the HTTP status. The \fB::http::ncode\fR procedure provides just
the numeric error (e.g., 200, 404 or 500) while the \fB::http::code\fR
-procedure returns a value like "HTTP 404 File not found".
+procedure returns a value like
+.QW "HTTP 404 File not found" .
.TP
eof
If the server closes the socket without replying, then no error
@@ -404,7 +404,6 @@ transaction.
If it can read the server's response
it will end up with an \fBok\fR status, otherwise it will have
an \fBeof\fR status.
-
.SH "STATE ARRAY"
The \fB::http::geturl\fR procedure returns a \fItoken\fR that can be used to
get to the state of the HTTP transaction in the form of a Tcl array.
@@ -534,9 +533,7 @@ proc httpCopyProgress {args} {
flush stderr
}
.CE
-
.SH "SEE ALSO"
safe(n), socket(n), safesock(n)
-
.SH KEYWORDS
security policy, socket