--- title: "URLSaveAsynchronous" language: "en" type: "Symbol" summary: "URLSaveAsynchronous is being phased out in favor of URLDownloadSubmit, which was introduced experimentally in Version 11.2." canonical_url: "https://reference.wolfram.com/language/ref/URLSaveAsynchronous.html" source: "Wolfram Language Documentation" related_functions: - title: "URLDownload" link: "https://reference.wolfram.com/language/ref/URLDownload.en.md" - title: "URLRead" link: "https://reference.wolfram.com/language/ref/URLRead.en.md" - title: "URLSubmit" link: "https://reference.wolfram.com/language/ref/URLSubmit.en.md" --- # URLSaveAsynchronous ⚠ ``URLSaveAsynchronous`` is being phased out in favor of ``URLDownloadSubmit``, which was introduced experimentally in Version 11.2. URLSaveAsynchronous["url", "file", func] performs a download to "file" in the background, calling func when an event is raised. ## Details and Options * Types of events that may be raised: | | | | ------------ | --------------------------------------------------------------------------------------------- | | "data" | returns an empty list; can be used to indicate the connection has completed | | "progress" | returns information about the current connection of the form {dlnow, dltotal, ulnow, ultotal} | | "error" | indicates that an error occurred while attempting to connect to the URL | | "headers" | headers received from the web server | | "cookies" | a list of all known cookies | | "statuscode" | the status code returned by the server | * The following options can be given: | | | | | --- | --- | --- | | Method | "GET" | method to use for request | | "Parameters" | {} | parameters to be sent for the request | | "Body" | "" | contents of message body to be sent | | "MultipartElements" | {} | list of multipart data elements to send | | "Username" | "" | username to use for the request | | "Password" | "" | password to use for the request | | "Headers" | {} | headers to be manually sent to the HTTP server | | "Cookies" | Automatic | cookies to pass to the server | | "StoreCookies" | True | whether to store received cookies | | "VerifyPeer" | True | verify authenticity using SSL certificates | | "UserAgent" | Automatic | user agent string to send | | "ReadTimeout" | 0 | time to allow for uploading or downloading data | | "ConnectTimeout" | 0 | time to allow for connecting to the server | | "Progress" | False | whether to raise a "progress" event | | "Transfer" | Automatic | if Automatic, the "data" event returns once and returns all the data downloaded; if "Chunks", the "data" event is raised multiple times with the data downloaded since the last event was raised | | "UserData" | None | any expression passed to this option will be stored for use of the AsynchronousTaskObject inside t ... data can be found by checking the options of AsynchronousTaskObject passed to the event function | | BinaryFormat | True | whether to avoid textual interpretation of newlines or other data | | "FollowRedirects" | True | whether to follow redirects | * When an event is raised, the event function passed to ``URLSaveAsynchronous`` will be executed. The event functions will be passed three arguments, the ``AsynchronousTaskObject``, the event name, and the data received from the event. Event functions are the only method for handling data received from ``URLSaveAsynchronous``. --- ## Examples (17) ### Basic Examples (1) Monitor progress while downloading the contents of a URL to a file: ```wl In[1]:= url = "http://exampledata.wolfram.com/10mb.dat"; progress = 0.; progFunction[_, "progress", {dlnow_, dltotal_, _, _}] := Quiet[progress = dlnow / dltotal] In[2]:= Dynamic[ProgressIndicator[progress]] Out[2]= ProgressIndicator[0.8] In[3]:= URLSaveAsynchronous[url, FileNameJoin[{$TemporaryDirectory, "10mb.dat"}], progFunction, "Progress" -> True] Out[3]= AsynchronousTaskObject["http://exampledata.wolfram.com/10mb.dat", 21, 28150430734831193724] ``` ### Options (15) #### "Method" (1) ``"Method"`` can be used to specify the HTTP method used by the connection: ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://wolfram.com", tmpFile, Null, "Method" -> "HEAD"] Out[1]= AsynchronousTaskObject["http://wolfram.com", 22, 28150430734831193724] In[2]:= FilePrint[tmpFile] Accept: */* Host: exampledata.wolfram.com MyHeader: 42 User-Agent: Mathematica HTTPClient 9. ``` #### "Parameters" (1) Specify the parameters that should be sent to the server: ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/httpget.php", tmpFile, Null, "Parameters" -> {"name" -> "Joe", "age" -> "30"}] Out[1]= AsynchronousTaskObject["http://exampledata.wolfram.com/httpget.php", 23, 28150430734831193724] In[2]:= FilePrint[tmpFile] Joe is 30 years old. ``` #### "VerifyPeer" (1) Verify that the SSL certificate used by the server is valid: ```wl In[1]:= statusData; tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; eventFunction[_, "statuscode", status_] := statusData = status; URLSaveAsynchronous["https://wolfram.com", tmpFile, eventFunction, "VerifyPeer" -> True] Out[1]= AsynchronousTaskObject["https://wolfram.com", 24, 28150430734831193724] In[2]:= statusData Out[2]= {200} ``` #### "Username" (1) Specify the username that should be sent to the server: ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/authentication.php", tmpFile, Null, "Username" -> "Joe", "Password" -> ""] Out[1]= AsynchronousTaskObject["http://exampledata.wolfram.com/authentication.php", 25, 28150430734831193724] In[2]:= FilePrint[tmpFile] Hello Joe.You entered as your password. ``` #### "Password" (1) Specify the password that should be sent to the server: ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/authentication.php", tmpFile, Null, "Username" -> "Joe", "Password" -> "topsecret"] Out[1]= AsynchronousTaskObject["http://exampledata.wolfram.com/authentication.php", 26, 28150430734831193724] In[2]:= FilePrint[tmpFile] Hello Joe.You entered topsecret as your password. ``` #### "UserAgent" (1) Specify the user agent that should be sent to the server: ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/useragent.php", tmpFile, Null, "UserAgent" -> "Web Browser"] Out[1]= AsynchronousTaskObject["http://exampledata.wolfram.com/useragent.php", 27, 28150430734831193724] In[2]:= FilePrint[tmpFile] Web Browser ``` #### "Cookies" (1) Manually control the cookies used by ``URLSaveAsynchronous`` : ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/cookies.php", tmpFile, Null, "Cookies" -> {{"Domain" -> ".exampledata.wolfram.com", "Path" -> "/", "Secure" -> "FALSE", "Expires" -> DateString[{2020, 1, 1, 0, 0, 0}], "Name" -> "MyCookie", "Value" -> "CookieData"}}] Out[1]= AsynchronousTaskObject["http://exampledata.wolfram.com/cookies.php", 28, 28150430734831193724] In[2]:= FilePrint[tmpFile] MyCookie--> CookieData ``` #### "StoreCookies" (1) If ``False``, ``"StoreCookies"`` will not place any new cookies found while connecting to the site in the global cookie share: ```wl In[1]:= cookiesData; tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; eventFunction[_, "cookies", cookies_] := cookiesData = cookies URLSaveAsynchronous["http://wolfram.com/", tmpFile, eventFunction, "StoreCookies" -> False] Out[1]= AsynchronousTaskObject["http://wolfram.com/", 29, 28150430734831193724] In[2]:= cookiesData Out[2]= {{"Domain" -> ".wolfram.com", "Path" -> "/", "Secure" -> "FALSE", "Expires" -> "Thu 29 Sep 2022 20:58:08", "Name" -> "WR_SID", "Value" -> "8cb1c8fe2265506a03e081d"}} In[3]:= $HTTPCookies Out[3]= {} ``` #### "Headers" (1) Specify headers to be sent to the server: ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/headers.php", tmpFile, Null, "Headers" -> {"MyHeader" -> "42"}] Out[1]= AsynchronousTaskObject["http://exampledata.wolfram.com/headers.php", 30, 28150430734831193724] In[2]:= FilePrint[tmpFile] Accept: */* Host: exampledata.wolfram.com MyHeader: 42 User-Agent: Mathematica HTTPClient 9. ``` #### "BodyData" (1) Specify the message body that should be sent when connecting to the server: ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/bodydata.php", tmpFile, Null, "BodyData" -> "Message body data sent to server."] Out[1]= AsynchronousTaskObject["http://exampledata.wolfram.com/bodydata.php", 31, 28150430734831193724] In[2]:= FilePrint[tmpFile] Message body data sent to server. ``` #### "MultipartData" (1) Specify the contents of a multipart message body: ```wl In[1]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/multipartdata.php", tmpFile, Null, "MultipartData" -> {{"partName", "mime/type", {1, 2, 3, 4, 5}}}]; In[2]:= FilePrint[tmpFile] 7cfdd07889b3295d6a550914ab35e068 ``` #### "ReadTimeout" (1) Specify the maximum allotted time in seconds to finish downloading data from the server: ```wl In[1]:= errorString; eventFunction[_, "error", error_] := errorString = error tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://exampledata.wolfram.com/50mb.dat", tmpFile, eventFunction, "ReadTimeout" -> 1]; In[2]:= errorString Out[2]= {"Timeout was reached"} ``` #### "ConnectTimeout" (1) Specify the maximum allotted time in seconds to establish a connection to the server: ```wl In[1]:= errorString; eventFunction[_, "error", error_] := errorString = error tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; URLSaveAsynchronous["http://127.0.0.1", tmpFile, eventFunction, "ConnectTimeout" -> 1]; In[2]:= errorString Out[2]= {"Timeout was reached"} ``` #### "Progress" (1) If ``True``, the ``"progress"`` event will be raised, returning information downloaded and uploaded about in-progress downloads: ```wl In[1]:= progressData = {}; In[2]:= tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; progressFunction[_, "progress", progress_] := progressData = progress URLSaveAsynchronous["http://exampledata.wolfram.com/5mb.dat", tmpFile, progressFunction, "Progress" -> True]; Dynamic[progressData] Out[2]= {} ``` #### "UserData" (1) ``"UserData"`` is any expression containing information to be made available when an event is called: ```wl In[1]:= dataString; tmpFile = FileNameJoin[{$TemporaryDirectory, "tmp.txt"}]; eventFunction[async_, "statuscode", data_] := dataString = "UserData" /. Options[async] URLSaveAsynchronous["http://wolfram.com", tmpFile, eventFunction, "UserData" -> "stored data"]; In[2]:= dataString Out[2]= "stored data" ``` ### Properties & Relations (1) Use ``URLFetchAsynchronous`` to load the content directly into the Wolfram Language: ```wl In[1]:= constitution; f[_, "data", document_] := constitution = FromCharacterCode[document] URLFetchAsynchronous["http://exampledata.wolfram.com/USConstitution.txt", f]; In[2]:= Short[constitution] Out[2]//Short= {"\r We the People of the United States, in Orde"…"f Representatives shall\r have intervened.\r \r "} ``` ## See Also * [`URLDownload`](https://reference.wolfram.com/language/ref/URLDownload.en.md) * [`URLRead`](https://reference.wolfram.com/language/ref/URLRead.en.md) * [`URLSubmit`](https://reference.wolfram.com/language/ref/URLSubmit.en.md) ## History * [Introduced in 2012 (9.0)](https://reference.wolfram.com/language/guide/SummaryOfNewFeaturesIn90.en.md)