| % File src/library/base/man/curlGetHeaders.Rd |
| % Part of the R package, https://www.R-project.org |
| % Copyright 2015 R Core Team |
| % Distributed under GPL 2 or later |
| |
| \name{curlGetHeaders} |
| \alias{curlGetHeaders} |
| \title{ |
| Retrieve Headers from URLs |
| } |
| \description{ |
| Retrieve the headers for a URL for a supported protocol such as |
| \code{http://}, \code{ftp://}, \code{https://} and \code{ftps://}. |
| An optional function not supported on all platforms. |
| } |
| \usage{ |
| curlGetHeaders(url, redirect = TRUE, verify = TRUE) |
| } |
| |
| \arguments{ |
| \item{url}{character string specifying the URL.} |
| \item{redirect}{logical: should redirections be followed?} |
| \item{verify}{logical: should certificates be verified as valid |
| and applying to that host?} |
| } |
| |
| \details{ |
| This reports what \command{curl -I -L} or \command{curl -I} would |
| report. For a \code{ftp://} URL the \sQuote{headers} are a record of |
| the conversation between client and server before data transfer. |
| |
| Only 500 header lines will be reported: there is a limit of 20 |
| redirections so this should suffice (and even 20 would indicate |
| problems). |
| |
| It uses \code{\link{getOption}("timeout")} for the connection |
| timeout: that defaults to 60 seconds. As this cannot be interrupted |
| you may want to consider a shorter value. |
| |
| To see all the details of the interaction with the server(s) set |
| \code{\link{options}(internet.info = 1)}. |
| |
| HTTP[S] servers are allowed to refuse requests to read the headers and |
| some do: this will result in a \code{status} of \code{405}. |
| |
| For possible issues with secure URLs (especially on Windows) see |
| \code{\link{download.file}}. |
| |
| There is a security risk in not verifying certificates, but as only |
| the headers are captured it is slight. Usually looking at the URL in |
| a browser will reveal what the problem is (and it may well be |
| machine-specific). |
| } |
| \value{ |
| A character vector with integer attribute \code{"status"} (the |
| last-received \sQuote{status} code). If redirection occurs this will include |
| the headers for all the URLs visited. |
| |
| For the interpretation of \sQuote{status} codes see |
| \url{https://en.wikipedia.org/wiki/List_of_HTTP_status_codes} and |
| \url{https://en.wikipedia.org/wiki/List_of_FTP_server_return_codes}. |
| A successful FTP connection will usually have status 250 or 350. |
| } |
| |
| \seealso{ |
| \code{\link{capabilities}("libcurl")} to see if this is supported. |
| |
| \code{\link{options}} \code{HTTPUserAgent} and \code{timeout} are used. |
| } |
| |
| % http://forum.rebex.net/questions/1343/open-ftps-and-sftp-servers-for-testing-our-code-and-connectivity |
| \examples{\donttest{## needs Internet access, results vary |
| curlGetHeaders("http://bugs.r-project.org") ## this redirects to https:// |
| curlGetHeaders("https://httpbin.org/status/404") ## returns status |
| curlGetHeaders("ftp://cran.r-project.org") |
| } |
| \dontrun{ ## a not-always-available site: |
| curlGetHeaders("ftps://test.rebex.net/readme.txt") |
| }} |