diff options
Diffstat (limited to 'doc/http.n')
| -rw-r--r-- | doc/http.n | 37 |
1 files changed, 17 insertions, 20 deletions
@@ -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 |