Function: url-retrieve

url-retrieve is an autoloaded and byte-compiled function defined in url.el.gz.

Signature

(url-retrieve URL CALLBACK &optional CBARGS SILENT INHIBIT-COOKIES)

Documentation

Retrieve URL asynchronously and call CALLBACK with CBARGS when finished.

URL is either a string or a parsed URL. If it is a string containing characters that are not valid in a URI, those characters are percent-encoded; see url-encode-url.

CALLBACK is called when the object has been completely retrieved, with the current buffer containing the object, and any MIME headers associated with it. It is called as (apply CALLBACK STATUS CBARGS). STATUS is a plist representing what happened during the request, with most recent events first, or an empty list if no events have occurred. Each pair is one of:

(:redirect REDIRECTED-TO) - the request was redirected to this URL.

(:error (error type . DATA)) - an error occurred. TYPE is a
symbol that says something about where the error occurred, and DATA is a list (possibly nil) that describes the error further.

Return the buffer URL will load into, or nil if the process has already completed (i.e. URL was a mailto URL or similar; in this case the callback is not called).

The variables url-request-data, url-request-method and url-request-extra-headers can be dynamically bound around the request; dynamic binding of other variables doesn't necessarily take effect.

If SILENT, then don't message progress reports and the like. If INHIBIT-COOKIES, cookies will neither be stored nor sent to the server. If URL is a multibyte string, it will be encoded as utf-8 and URL-encoded before it's used.

Probably introduced at or before Emacs version 24.1.

Source Code

;; Defined in /usr/src/emacs/lisp/url/url.el.gz
;;;###autoload
(defun url-retrieve (url callback &optional cbargs silent inhibit-cookies)
  "Retrieve URL asynchronously and call CALLBACK with CBARGS when finished.
URL is either a string or a parsed URL.  If it is a string
containing characters that are not valid in a URI, those
characters are percent-encoded; see `url-encode-url'.

CALLBACK is called when the object has been completely retrieved, with
the current buffer containing the object, and any MIME headers associated
with it.  It is called as (apply CALLBACK STATUS CBARGS).
STATUS is a plist representing what happened during the request,
with most recent events first, or an empty list if no events have
occurred.  Each pair is one of:

\(:redirect REDIRECTED-TO) - the request was redirected to this URL.

\(:error (error type . DATA)) - an error occurred.  TYPE is a
symbol that says something about where the error occurred, and
DATA is a list (possibly nil) that describes the error further.

Return the buffer URL will load into, or nil if the process has
already completed (i.e. URL was a mailto URL or similar; in this case
the callback is not called).

The variables `url-request-data', `url-request-method' and
`url-request-extra-headers' can be dynamically bound around the
request; dynamic binding of other variables doesn't necessarily
take effect.

If SILENT, then don't message progress reports and the like.
If INHIBIT-COOKIES, cookies will neither be stored nor sent to
the server.
If URL is a multibyte string, it will be encoded as utf-8 and
URL-encoded before it's used."
  ;; XXX: There is code in Emacs that does dynamic binding
  ;; of the following variables around url-retrieve:
  ;; url-standalone-mode, url-gateway-unplugged,
  ;; url-confirmation-func, url-cookie-multiple-line,
  ;; url-cookie-{{,secure-}storage,confirmation}
  ;; url-standalone-mode and url-gateway-unplugged should work as
  ;; usual.  url-confirmation-func is only used in nnwarchive.el and
  ;; webmail.el; the latter should be updated.  Is
  ;; url-cookie-multiple-line needed anymore?  The other url-cookie-*
  ;; are (for now) only used in synchronous retrievals.
  (url-retrieve-internal url callback (cons nil cbargs) silent
			 inhibit-cookies))