.. highlightlang:: us

.. index:: curl_download

.. _curl_download:

curl_download
=============

.. us.tag  curl_download ENGLISH Curl New5700

:ref:`curl_download` loads data from the Internet, using HTTP, HTTPS, FTP, 
SFTP and other protocols.

.. function::  
    data = curl_download(ssURL)
    data = curl_download(ssURL, oOptions)

.. us.return

**Return Value**

In case of an error, an *error* object (see :ref:`error_create`) is returned,
otherwise an object with data is returned.. 

The number of data blocks is returned in ``data.cnt``.

``data[1]`` to ``data[cnt]`` contains the data blocks as strings in a packed
form. Each character is two bytes long. The last character contains one or two
bytes. The bytes can contain zero bytes. See :ref:`mem_len` and
:ref:`mem_unpack`.

Convert *data* to an string::

    s = "";
    if (data.cnt != 0) {
        for (i in 1:data.cnt) {
            s = s + mem_unpack(data.data[i]);
        }
        s = utf8_decode(s); 
    }

.. us.params

**Parameters**

.. uparam:: ssURL

   *ssURL* is the URL.

.. uparam:: oOptions

   *oOptions* is an object with options or 0, see :ref:`curl_easy_setopt`.

.. us.example

**Example**

::

   def curl_download_text(ssURL, _oOptions)
   {
       nArgs = nargsin();
       if (nArgs == 1) {
           o = curl_download(ssURL)
       } else if (nArgs == 2) {
           o = curl_download(ssURL, _oOptions);
       } else {
           error();
       }
       if (type(o) == "error") {
           return o;
       }

       s = "";
       if (o.cnt == 0) {
           return s;
       }
       for (i in 1:o.cnt) {
           s = s + mem_unpack(o.data[i]);
       }
       return utf8_decode(s);
   }

   s = curl_download_text("www.uniplot.de")

Save the download in a file:

.. index:: curl_download_binary

::

   ssBinary = curl_download_binary(ssURL, _oOptions)
   ssOK = curl_download_binary(ssURL, _oOptions, ssSaveFileName)

Example: 

::

   if (curl_download_binary("https://www.uniplot.de/_images/monitor.png", 0, "d:/a.png") == "OK") {
      print "success";
   }

.. us.history

**History**

.. list-table::
   :header-rows: 1

   * - Version
     - Description
   * - R2015.0
     - New.

.. seealso::
   :ref:`overview-curl`,
   :ref:`curl_easy_perform`,
   :ref:`mem_len`,
   :ref:`mem_unpack`

:sub:`id-930757`