<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) - S/E - Sylvestre Ledru
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xml:id="getURL" xml:lang="ru"
          xmlns="http://docbook.org/ns/docbook"
          xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg"
          xmlns:ns3="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML"
          xmlns:scilab="http://www.scilab.org"
          xmlns:db="http://docbook.org/ns/docbook">

    <refnamediv>
        <refname>getURL</refname>

        <refpurpose>Загрузка по URL (HTTP, HTTPS, FTP...) </refpurpose>
    </refnamediv>

    <refsynopsisdiv>
        <title>Синтаксис</title>

        <synopsis>filename = getURL(URL);
            [filename, [content]] = getURL(URL [, targetDir [, username [, password]]]]);
            [filename, [content]] = getURL(URL [, targetFile [, username [, password]]]]);
        </synopsis>
    </refsynopsisdiv>

    <refsection>
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>URL</term>
                <listitem>
                    <para>строка: ссылка URL. Поддерживаются и тестируются: HTTP, HTTPS, FTP (IPv4 и IPv6)</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>targetDir</term>
                <listitem>
                    <para>
                        Необязательный строковый параметр: указывает в какой директории будет
                        сохранён файл (если пустой, то текущая директория)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>targetFile</term>
                <listitem>
                    <para>
                        Необязательный строковый параметр: указывает где (и под каким именем)
                        данный файл будет сохранён (если пустой, то текущая директория)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>username</term>
                <listitem>
                    <para>
                        Необязательный строковый параметр: имя пользователя для вебсайтов,
                        которые запрашивают аутентификацию
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>password</term>
                <listitem>
                    <para>
                        Необязательный строковый параметр: пароль для вебсайтов,
                        которые запрашивают аутентификацию
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>filename</term>
                <listitem>
                    <para>строка: путь до загруженного файла</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>content</term>
                <listitem>
                    <para>строка: содержимое загруженного файла</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>

    <refsection>
        <title>Описание</title>

        <para>Загрузка файла по ссылке URL.</para>

        <para>
            Функция <literal>getURL</literal> загрузит файл по удалённой ссылке URL.
            Однако, в некоторых обстоятельствах (например,
            <emphasis role="italic">http://www.scilab.org/</emphasis>), имя файла
            не предоставляется самой ссылкой URL и <literal>getURL</literal>
            переименует файл в <emphasis role="italic">index.html</emphasis>.
        </para>

        <para>
            <varname>content</varname> содержит содержимое страницы, указанной в URL.
        </para>

        <para>
            Эта функция основана на <ulink url="http://curl.haxx.se/libcurl/">библиотеке curl</ulink>.
        </para>

        <para>
            <varname>username</varname> and <varname>password</varname> могут быть
            определены для тех вебсайтов, которые запрашивают аутентификацию.
            Используемый метод аутентификации <literal>CURLAUTH_ANY</literal>,
            указываемый параметром <literal>CURLOPT_HTTPAUTH</literal> библиотеки
            <literal>libcurl</literal>.
        </para>

        <para>
            <literal>getURL</literal> поддерживает IPv6 (и, очевидно, IPv4) по умолчанию.
        </para>

        <para>
            В этой версии доступна настройка прокси, она может быть изменена в настройках в
            разделе "Интернет".
        </para>

        <para>
            Опция curl <emphasis role="italic">CURLOPT_FOLLOWLOCATION</emphasis>
            активируется для того, чтобы убедиться в загрузке по ссылке URL.
        </para>

        <para>
            <literal>getURL</literal> основана на libcurl. Версия этой библиотеки в официальном двоичном файле Scilab, скомпилированным с поддержкой HTTP, HTTPS, FTP и FTPS. Если Scilab установлен через систему пакетов в дистрибутиве, вероятно, что будут работать <ulink url="http://curl.haxx.se/docs/features.html">и иные протоколы</ulink>, а не только HTTP, HTTPS и FTPS. Однако, они недостаточно протестированы.
        </para>

    </refsection>

    <refsection>
        <title>Примеры</title>

        <programlisting role="example">

            // Будет загружен URL с именем файла maths_simulation
            getURL("http://www.scilab.org/products/scilab/features/maths_simulation");

            // Сохранить домашнюю страницу Scilab в текущей директории (и переименуем файл)
            getURL("http://www.scilab.org","scilab_homepage.html");

            // Загрузка примера Scilab и исполнение его
            myFile = getURL("http://fileexchange.scilab.org/toolboxes/contour3d/10.03/files/contour3d.sci",TMPDIR)
            exec(myFile);
            contour3d();

            // Используем аутентификацию
            getURL("http://httpbin.org/basic-auth/user/passwd",TMPDIR+"/testfile.html","user","passwd")

            // Необходимо подключение IPv6
            getURL("http://ipv6.google.com/intl/en_com/images/srpr/logo3w.png")

            // Получение контента
            [myFile, content] = getURL("http://fileexchange.scilab.org/toolboxes/contour3d/10.03/files/contour3d.sci",TMPDIR)
        </programlisting>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="splitURL">splitURL</link>
            </member>
        </simplelist>
    </refsection>

    <refsection>
        <title>История</title>
        <revhistory>
            <revision>
                <revnumber>5.5.0</revnumber>
                <revremark>
                    Введена функция <literal>getURL()</literal>
                </revremark>
            </revision>
        </revhistory>
    </refsection>

</refentry>
