- Issue an http GET request to url.
-
url.
- - -headers specifies an ns_set of extra headers to send to the server when doing the request. - Some options exist that allow to avoid the need to specify headers manually, but headers will always take precedence over options. -
+ @param headers specifies an ns_set of extra headers to send + to the server when doing the request. Some options exist that + allow to avoid the need to specify headers manually, but headers + will always take precedence over options. -
- -gzip_response_p informs the server that we are capable of receiving gzipped responses. - If server complies to our indication, the result will be automatically decompressed. -
+ @param gzip_response_p informs the server that we are + capable of receiving gzipped responses. If server complies to our + indication, the result will be automatically decompressed. -- -force_ssl_p specifies wether we want to use SSL despite the url being in http:// form. - Default behavior is to use SSL on https:// urls only. -
+ @param force_ssl_p specifies wether we want to use SSL + despite the url being in http:// form. Default behavior is to use + SSL on https:// urls only. -- -spool_file enables file spooling of the request on the file specified. It is useful when we expect large responses from the server. -
+ @param spool_file enables file spooling of the request on + the file specified. It is useful when we expect large responses + from the server. -- -preference decides which available implementation prefer in respective order. Choice is between 'native', based on ns_ api, available for Naviserver - only and giving the best performances and 'curl', which wraps the command line utility (available on every system with curl installed). -
+ @param preference decides which available implementation prefer + in respective order. Choice is between 'native', based on ns_ api, + available for NaviServer only and giving the best performances and + 'curl', which wraps the command line utility (available on every + system with curl installed). - Returns the data in array get form with array elements page, status, and modified. + @return Returns the data as dict with elementspage,
+ status, and modified.
+
} {
return [util::http::request \
-url $url \
@@ -210,83 +209,93 @@
{-spool_file ""}
{-preference {native curl}}
} {
- Implement client-side HTTP POST request. -
-
- -body is the payload for the request and will be passed as is (useful for many purposes, such as webDav).
- A convenient way to specify form variables through this argument is passing a string obtained by export_vars -url.
-
export_vars -url.
-
- File upload can be specified using actual files on the filesystem or binary strings of data using the -files parameter.
- -files must be a list of array-lists in the form returned by array get.
+ @param files File upload can be specified using actual files on the
+ filesystem or binary strings of data using the -files
+ parameter. -files must be a dict (flat list of key value pairs).
Keys of -files parameter are:
+
-base64 flag is set, files will be base64 encoded (useful for some kind of form).
-
-
- Other form variables can be passes in-formvars easily by the use of export_vars -url and will be translated
- for the proper type of form. URL variables, as with GET requests, are also sent, but an error is thrown if URL variables conflict with those specified
- in other ways.
-
-base64 flag is set, files will be base64 encoded
+ (useful for some kind of form).
+
+ @param -formvars Other form variables can be passes in-formvars
+ easily by the use of export_vars -url and will be
+ translated for the proper type of form. URL variables, as with GET
+ requests, are also sent, but an error is thrown if URL variables
+ conflict with those specified in other ways.
-
- Default behavior is to build payload as an 'application/x-www-form-urlencoded' payload if no files are specified,
- and 'multipart/form-data' otherwise. If -multipart flag is set, format will be forced to multipart.
-
Default behavior is to build payload as an
+ 'application/x-www-form-urlencoded' payload if no files are
+ specified, and 'multipart/form-data' otherwise. If
+ -multipart flag is set, format will be forced to
+ multipart.
-
- -headers specifies an ns_set of extra headers to send to the server when doing the request. - Some options exist that allow to avoid the need to specify headers manually, but headers will always take precedence over options. -
+ @param headers specifies an ns_set of extra headers to send to the + server when doing the request. Some options exist that allow to + avoid the need to specify headers manually, but headers will + always take precedence over options. -- -gzip_request_p informs the server that we are sending data in gzip format. Data will be automatically compressed. - Notice that not all servers can treat gzipped requests properly, and in such cases response will likely be an error. -
+ @param gzip_request_p informs the server that we are sending data + in gzip format. Data will be automatically compressed. Notice + that not all servers can treat gzipped requests properly, and in + such cases response will likely be an error. -- -gzip_response_p informs the server that we are capable of receiving gzipped responses. - If server complies to our indication, the result will be automatically decompressed. -
+ @param gzip_response_p informs the server that we are capable of + receiving gzipped responses. If server complies to our + indication, the result will be automatically decompressed. -- -force_ssl_p specifies wether we want to use SSL despite the url being in http:// form. - Default behavior is to use SSL on https:// urls only. -
+ @param force_ssl_p specifies wether we want to use SSL despite the + url being in http:// form. Default behavior is to use SSL on + https:// urls only. -- -spool_file enables file spooling of the request on the file specified. It is useful when we expect large responses from the server. -
+ @param spool_file enables file spooling of the request on the file + specified. It is useful when we expect large responses from the + server. -- -post_redirect decides what happens when we are POSTing and server replies with 301, 302 or 303 redirects. RFC 2616/10.3.2 states that method - should not change when 301 or 302 are returned, and that GET should be used on a 303 response, but most HTTP clients fail in respecting this and switch - to a GET request independently. This options forces this kinds of redirect to conserve their original method. -
+ @param post_redirect decides what happens when we are POSTing and + server replies with 301, 302 or 303 redirects. RFC 2616/10.3.2 + states that method should not change when 301 or 302 are returned, + and that GET should be used on a 303 response, but most HTTP + clients fail in respecting this and switch to a GET request + independently. This options forces this kinds of redirect to + conserve their original method. -- -max_depth is the maximum number of redirects the proc is allowed to follow. Be aware that when following redirects, unless it is a code 303 - redirect, url and POST urlencoded variables will be sent again to the redirected host. Multipart variables won't be sent again. - Sending to the redirected host can be dangerous, if such host is not trusted or uses a lower level of secutiry. The default behavior is to not follow - redirects. -
+ @param max_depth is the maximum number of redirects the proc is + allowed to follow. Be aware that when following redirects, unless + it is a code 303 redirect, url and POST urlencoded variables will + be sent again to the redirected host. Multipart variables won't be + sent again. Sending to the redirected host can be dangerous, if + such host is not trusted or uses a lower level of secutiry. The + default behavior is to not follow redirects. -- -preference decides which available implementation prefer in respective order. Choice is between 'native', based on ns_ api, available for Naviserver - only and giving the best performances and 'curl', which wraps the command line utility (available on every system with curl installed). -
-} { + @param preference decides which available implementation prefer in + respective order. Choice is between 'native', based on ns_ api, + available for NaviServer only and giving the best performances and + 'curl', which wraps the command line utility (available on every + system with curl installed). + + @return Returns the data as dict with elementspage,
+ status, and modified.
+
+} {
set this_proc [lindex [info level 0] 0]
# Retrieve variables sent by the URL...
@@ -441,7 +450,7 @@
-preference $preference]
}
-ad_proc util::http::request {
+ad_proc -private util::http::request {
-url
{-method GET}
{-headers ""}
@@ -456,57 +465,63 @@
{-spool_file ""}
{-preference {native curl}}
} {
- Issue an HTTP request either GET or POST to the url specified. -
+ + @param headers specifies an ns_set of extra headers to send to the + server when doing the request. Some options exist that allow to + avoid the need to specify headers manually, but headers will + always take precedence over options. -- -headers specifies an ns_set of extra headers to send to the server when doing the request. - Some options exist that allow to avoid the need to specify headers manually, but headers will always take precedence over options. -
- -
- -body is the payload for the request and will be passed as is (useful for many purposes, such as webDav).
- A convenient way to specify form variables for POST payloads through this argument is passing a string obtained by export_vars -url.
-
export_vars -url.
- - -gzip_request_p informs the server that we are sending data in gzip format. Data will be automatically compressed. - Notice that not all servers can treat gzipped requests properly, and in such cases response will likely be an error. -
+ @param gzip_request_p informs the server that we are sending data + in gzip format. Data will be automatically compressed. Notice + that not all servers can treat gzipped requests properly, and in + such cases response will likely be an error. -- -gzip_response_p informs the server that we are capable of receiving gzipped responses. - If server complies to our indication, the result will be automatically decompressed. -
+ @param gzip_response_p informs the server that we are capable of + receiving gzipped responses. If server complies to our + indication, the result will be automatically decompressed. -- -force_ssl_p specifies wether we want to use SSL despite the url being in http:// form. Default behavior is to use SSL on https:// urls only. -
+ @param force_ssl_p specifies wether we want to use SSL despite the + url being in http:// form. Default behavior is to use SSL on + https:// urls only. -- -spool_file enables file spooling of the request on the file specified. It is useful when we expect large responses from the server. -
+ @param spool_file enables file spooling of the request on the file + specified. It is useful when we expect large responses from the + server. -- -post_redirect decides what happens when we are POSTing and server replies with 301, 302 or 303 redirects. RFC 2616/10.3.2 states that method - should not change when 301 or 302 are returned, and that GET should be used on a 303 response, but most HTTP clients fail in respecting this and switch - to a GET request independently. This options forces this kinds of redirect to conserve their original method. Notice that, as from RFC, a 303 redirect - won't send again any data to the server, as specification says we can assume variables to have been received. -
+ @param post_redirect decides what happens when we are POSTing and + server replies with 301, 302 or 303 redirects. RFC 2616/10.3.2 + states that method should not change when 301 or 302 are returned, + and that GET should be used on a 303 response, but most HTTP + clients fail in respecting this and switch to a GET request + independently. This options forces this kinds of redirect to + conserve their original method. Notice that, as from RFC, a 303 + redirect won't send again any data to the server, as specification + says we can assume variables to have been received. -- -max_depth is the maximum number of redirects the proc is allowed to follow. Be aware that when following redirects, unless it is a code 303 - redirect, url and POST urlencoded variables will be sent again to the redirected host. Multipart variables won't be sent again. - Sending to the redirected host can be dangerous, if such host is not trusted or uses a lower level of secutiry. The default behavior is to not follow - redirects. -
+ @param max_depth is the maximum number of redirects the proc is + allowed to follow. Be aware that when following redirects, unless + it is a code 303 redirect, url and POST urlencoded variables will + be sent again to the redirected host. Multipart variables won't be + sent again. Sending to the redirected host can be dangerous, if + such host is not trusted or uses a lower level of secutiry. The + default behavior is to not follow redirects. -- -preference decides which available implementation prefer in respective order. Choice is between 'native', based on ns_ api, available for Naviserver - only and giving the best performances and 'curl', which wraps the command line utility (available on every system with curl installed). -
-} { + @param preference decides which available implementation prefer + in respective order. Choice is between 'native', based on ns_ api, + available for NaviServer only and giving the best performances and + 'curl', which wraps the command line utility (available on every + system with curl installed). + + @return Returns the data as dict with elementspage,
+ status, and modified.
+
+} {
set this_proc [lindex [info level 0] 0]
if {$force_ssl_p || [string match "https://*" $url]} {
@@ -541,7 +556,7 @@
#
-## Native Naviserver implementation
+## Native NaviServer implementation
#
namespace eval util::http::native {}
@@ -560,53 +575,58 @@
-post_redirect:boolean
{-spool_file ""}
} {
- + Issue an HTTP request either GET or POST to the url specified. -
+ This is the native implementation based on NaviServer HTTP api. -- -headers specifies an ns_set of extra headers to send to the server when doing the request. - Some options exist that allow to avoid the need to specify headers manually, but headers will always take precedence over options. -
+ @param headers specifies an ns_set of extra headers to send to the + server when doing the request. Some options exist that allow to + avoid the need to specify headers manually, but headers will + always take precedence over options. -
- -body is the payload for the request and will be passed as is (useful for many purposes, such as webDav).
- A convenient way to specify form variables for POST payloads through this argument is passing a string obtained by export_vars -url.
-
export_vars -url.
- - -gzip_request_p informs the server that we are sending data in gzip format. Data will be automatically compressed. - Notice that not all servers can treat gzipped requests properly, and in such cases response will likely be an error. -
+ @param gzip_request_p informs the server that we are sending data + in gzip format. Data will be automatically compressed. Notice + that not all servers can treat gzipped requests properly, and in + such cases response will likely be an error. -- -gzip_response_p informs the server that we are capable of receiving gzipped responses. - If server complies to our indication, the result will be automatically decompressed. -
+ @param gzip_response_p informs the server that we are capable of + receiving gzipped responses. If server complies to our + indication, the result will be automatically decompressed. -- -force_ssl_p specifies wether we want to use SSL despite the url being in http:// form. Default behavior is to use SSL on https:// urls only. -
+ @param force_ssl_p specifies wether we want to use SSL despite the + url being in http:// form. Default behavior is to use SSL on + https:// urls only. -- -spool_file enables file spooling of the request on the file specified. It is useful when we expect large responses from the server. -
+ @param spool_file enables file spooling of the request on the file + specified. It is useful when we expect large responses from the + server. -- -post_redirect decides what happens when we are POSTing and server replies with 301, 302 or 303 redirects. RFC 2616/10.3.2 states that method - should not change when 301 or 302 are returned, and that GET should be used on a 303 response, but most HTTP clients fail in respecting this and switch - to a GET request independently. This options forces this kinds of redirect to conserve their original method. Notice that, as from RFC, a 303 redirect - won't send again any data to the server, as specification says we can assume variables to have been received. -
+ @param post_redirect decides what happens when we are POSTing and + server replies with 301, 302 or 303 redirects. RFC 2616/10.3.2 + states that method should not change when 301 or 302 are returned, + and that GET should be used on a 303 response, but most HTTP + clients fail in respecting this and switch to a GET request + independently. This options forces this kinds of redirect to + conserve their original method. Notice that, as from RFC, a 303 + redirect won't send again any data to the server, as specification + says we can assume variables to have been received. -- -max_depth is the maximum number of redirects the proc is allowed to follow. Be aware that when following redirects, unless it is a code 303 - redirect, url and POST urlencoded variables will be sent again to the redirected host. Multipart variables won't be sent again. - Sending to the redirected host can be dangerous, if such host is not trusted or uses a lower level of secutiry. The default behavior is to not follow - redirects. -
-page,
+ status, and modified.
+
} {
set this_proc [lindex [info level 0] 0]
@@ -701,7 +721,7 @@
}
if {$gzip_response_p} {
- # Naviserver since 4.99.6 can decompress response transparently
+ # NaviServer since 4.99.6 can decompress response transparently
if {[apm_version_names_compare [ns_info patchlevel] "4.99.5"] == 1} {
lappend wait_cmd -decompress
}
@@ -795,7 +815,7 @@
## Decoding of the response
- # If response was compressed and our Naviserver
+ # If response was compressed and our NaviServer
# is prior 4.99.6, we have to decompress on our own.
if {$content_encoding eq "gzip"} {
if {[apm_version_names_compare [ns_info patchlevel] "4.99.5"] == 1} {
@@ -839,52 +859,56 @@
-post_redirect:boolean
{-spool_file ""}
} {
- + Issue an HTTP request either GET or POST to the url specified. -
+ This is the curl wrapper implementation, used on Aolserver and + when ssl native capabilities are not available. -- -headers specifies an ns_set of extra headers to send to the server when doing the request. - Some options exist that allow to avoid the need to specify headers manually, but headers will always take precedence over options. -
+ @param headers specifies an ns_set of extra headers to send to the + server when doing the request. Some options exist that allow to + avoid the need to specify headers manually, but headers will + always take precedence over options. -
- -body is the payload for the request and will be passed as is (useful for many purposes, such as webDav).
- A convenient way to specify form variables for POST payloads through this argument is passing a string obtained by export_vars -url.
-
export_vars -url.
- - -gzip_request_p informs the server that we are sending data in gzip format. Data will be automatically compressed. - Notice that not all servers can treat gzipped requests properly, and in such cases response will likely be an error. -
+ @param gzip_request_p informs the server that we are sending data + in gzip format. Data will be automatically compressed. Notice + that not all servers can treat gzipped requests properly, and in + such cases response will likely be an error. -- -gzip_response_p informs the server that we are capable of receiving gzipped responses. - If server complies to our indication, the result will be automatically decompressed. -
+ @param gzip_response_p informs the server that we are + capable of receiving gzipped responses. If server complies to our + indication, the result will be automatically decompressed. -- -force_ssl_p is ignored when using curl http client implementation and is only kept for cross compatibility -
+ @param force_ssl_p is ignored when using curl http client + implementation and is only kept for cross compatibility. -- -spool_file enables file spooling of the request on the file specified. It is useful when we expect large responses from the server. -
+ @param spool_file enables file spooling of the request on the file + specified. It is useful when we expect large responses from the + server. -- -post_redirect decides what happens when we are POSTing and server replies with 301, 302 or 303 redirects. RFC 2616/10.3.2 states that method - should not change when 301 or 302 are returned, and that GET should be used on a 303 response, but most HTTP clients fail in respecting this and switch - to a GET request independently. This options forces this kinds of redirect to conserve their original method. -
+ @param post_redirect decides what happens when we are POSTing and + server replies with 301, 302 or 303 redirects. RFC 2616/10.3.2 + states that method should not change when 301 or 302 are returned, + and that GET should be used on a 303 response, but most HTTP + clients fail in respecting this and switch to a GET request + independently. This options forces this kinds of redirect to + conserve their original method. -- -max_depth is the maximum number of redirects the proc is allowed to follow. Be aware that when following redirects, unless it is a code 303 - redirect, url and POST urlencoded variables will be sent again to the redirected host. Multipart variables won't be sent again. - Sending to the redirected host can be dangerous, if such host is not trusted or uses a lower level of secutiry. The default behavior is to not follow - redirects. -
-page,
+ status, and modified.
+
} {
set this_proc [lindex [info level 0] 0]
@@ -1265,12 +1289,12 @@
- The switches -file /path/to/file and -data $raw_data - are mutually exclusive. You can specify one or the other, but not - both. NOTE: it is perfectly valid to not specify either, in which - case no file is uploaded, but form variables are encoded using - multipart/form-data instead of the usual encoding (as - noted aboved). + The switches -file /path/to/file and -data + $raw_data are mutually exclusive. You can specify one or the + other, but not both. NOTE: it is perfectly valid to not specify + either, in which case no file is uploaded, but form variables are + encoded using multipart/form-data instead of the usual + encoding (as noted aboved).