The <C>Download</C> operation has been written by Thomas Breuer,
incorporating a number of suggestions from Max Horn,
for version 0.77 of <Package>Utils</Package>.
It implements downloading a file from within &GAP;.
It can use the <Package>IO</Package> or <Package>curlInterface</Package>
packages, or <E>wget</E> or <E>curl</E>, if installed,
and it can be extended with other download methods quite easily.
It is envisaged that, once other packages have started to use it,
and any problems have been addressed, that the functions will be transferred
to the main &GAP; library.
<Section Label="sec-download">
<Heading>Functions for downloading files from the web</Heading>
<Description>
This function downloads the file with the web address <A>url</A>,
which must be a string.
<P/>
The result is a record which has at least the component <C>success</C>,
with value <K>true</K> if the download was successful and <K>false</K>
otherwise.
In the former case, the component <C>result</C> is bound,
whose value is a string that contains the contents of the downloaded file.
In the latter case, the component <C>error</C> is bound,
whose value is a string that describes the problem.
<P/>
The function calls the methods stored in the global list
<C>Download_Methods</C> until one of them is successful.
Currently there are methods based on the &GAP; functions
<Ref Func="DownloadURL" BookName="curl"/> and
<Ref Func="SingleHTTPRequest" BookName="io"/>,
and methods based on the external programs <C>wget</C> and <C>curl</C>.
<P/>
An optional record <A>opt</A> can be given.
The following components are supported.
<P/>
<List>
<Mark><C>maxTime</C></Mark>
<Item>
If this component is bound then its value must be a nonnegative integer
<M>n</M>, meaning that the function gives up after <M>n</M> seconds.
<P/>
A zero value of <M>n</M> means that no timeout is set, the method will
never give up in this case.
<P/>
The default for <M>n</M> is given by the value of the user preference
<C>DownloadMaxTime</C> (see <Ref Subsect="subsec-DownloadMaxTime"/>).
</Item>
<Mark><C>target</C></Mark>
<Item>
If this component is bound then its value must be a string
that is a local filename,
and the function writes the downloaded contents to this file;
the returned record does not have a <C>result</C> component in this case.
</Item>
<Mark><C>verifyCert</C></Mark>
<Item>
If this component is bound and has the value <K>false</K>
then those download methods that are based on <C>curl</C> or <C>wget</C>
will omit the check of the server's certificate.
<P/>
The same effect is achieved for all <Ref Func="Download"/> calls
by setting the user preference <C>DownloadVerifyCertificate</C>
(see <Ref Subsect="subsec-DownloadVerifyCertificate"/>) to <K>false</K>
and omitting the <C>verifyCert</C> component from <A>opt</A>.
</Item>
</List>
<P/>
<Example>
<![CDATA[
gap> url:= "https://www.gap-system.org/index.html";;
gap> res1:= Download( url );;
gap> res1.success;
true
gap> IsBound( res1.result ) and IsString( res1.result );
true
gap> res2:= Download( Concatenation( url, "xxx" ) );;
gap> res2.success;
false
gap> IsBound( res2.error ) and IsString( res2.error );
true
]]>
</Example>
</Description>
</ManSection>
The value <K>true</K> (the default) means that the server's certificate
is checked in calls of <Ref Func="Download"/>,
such that nothing gets downloaded if the certificate is invalid.
<P/>
If the value is <K>false</K> then download methods are supposed to omit
the check of the server's certificate (this may not be supported by all
download methods).
<P/>
One can set the value of the preference to be <C>val</C> via
<Ref Func="SetUserPreference" BookName="ref"/>, by calling
<C>SetUserPreference( "utils", "DownloadVerifyCertificate", val )</C>,
and access the current value via
<Ref Func="UserPreference" BookName="ref"/>, by calling
<C>UserPreference( "utils", "DownloadVerifyCertificate" )</C>.
<P/>
We recommend leaving this preference at its default value <K>true</K>.
Sometimes it can be necessary to change it, e.g. to work around issues
with old operating systems which may not be able to correctly verify new
certificates. In general it is better to update such a system, but if that is
not an option, then disabling certificate checks may be a good last resort.
The value <C>0</C> (the default) means that no timeout is set
in calls of <Ref Func="Download"/>.
If the value is a positive integer <M>n</M> then those download methods that
support a timeout will give up after <M>n</M> seconds.
<P/>
One can set the value of the preference to be <C>val</C> via
<Ref Func="SetUserPreference" BookName="ref"/>, by calling
<C>SetUserPreference( "utils", "DownloadMaxTime", val )</C>,
and access the current value via
<Ref Func="UserPreference" BookName="ref"/>, by calling
<C>UserPreference( "utils", "DownloadMaxTime" )</C>.
</Subsection>
</Section>
</Chapter>
¤ Dauer der Verarbeitung: 0.27 Sekunden
(vorverarbeitet)
¤
Die Informationen auf dieser Webseite wurden
nach bestem Wissen sorgfältig zusammengestellt. Es wird jedoch weder Vollständigkeit, noch Richtigkeit,
noch Qualität der bereit gestellten Informationen zugesichert.
Bemerkung:
Die farbliche Syntaxdarstellung ist noch experimentell.
