TclCurl

NAME

SYNOPSIS

curlHandle configure ?options?

curlHandle perform

curlHandle duhandle

curlHandle getinfo curlinfo_option

curlhandle cleanup

curl::transfer ?options?

curl::version

curl::escape url

curl::unescape url

curl::curlConfig option  

DESCRIPTION

curl::init

RETURN VALUE

curlHandle to use.  

curlHandle configure ?options?

configure is called to set the options for the transfer. Most operations in TclCurl have default actions, and by using the appropriate options you can make them behave differently (as documented). All options are set with the option followed by a parameter.

Notes: the options set with this procedure are valid for the forthcoming data transfers that are performed when you invoke perform

The options are not reset between transfers (except where noted), so if you want subsequent transfer with different options, you must change them between the transfers.

curlHandle is the return code from the curl::init call.

These options are in a bit of random order, but you will figure it out!

-file

File in which the transfered data will be saved.

-infile

File from which the data will be transfered.

-infilesize

When uploading a file to a remote site, this option should be used to tell TclCurl what the expected size of the infile is.

-url

The actual URL to deal with. NOTE: this option is required to be set before perform is called.

-proxy

If you need to use a http proxy to access the outside world, set the proxy string with this option. To specify port number in this string, append :[port] to the end of the host name. The proxy string may be prefixed with [protocol]:// since any such prefix will be ignored.

-proxyport

Use this option to set the proxy port to use unless it is specified in the proxy string by -proxy

-httpproxytunnel

Set the parameter to non-zero to get the library to tunnel all non-HTTP operations through the given HTTP proxy. Do note that there is a big difference to use a proxy and to tunnel through it. If you don't know what this means, you probably don't want this tunnel option.

-verbose

Set the parameter to non-zero to get the library to display a lot of verbose information about its operations.

-header

A non-zero parameter tells the library to include the header in the output. This is only relevant for protocols that actually have a header preceeding the data (like HTTP).

-noprogress

A non-zero parameter tells the library to turn on the built-in progress meter. Nowadays it is turn off by default.

-nobody

A non-zero parameter tells the library not to include the body-part in the output. This is only relevant for protocols that have a separate header and body part.

-failonerror

A non-zero parameter tells the library to fail silently if the HTTP code returned is equal or larger than 400. The default action would be to return the page normally, ignoring that code.

-upload

A non-zero parameter tells the library to prepare for an upload. The infile and infilesize are also interesting for uploads.

-post

A non-zero parameter tells the library to do a regular HTTP post. This is a normal application/x-www-form-urlencoded kind, which is the most commonly used one by HTML forms. See the postfields option for how to specify the data to post and postfieldsize about how to set the data size.

-ftplistonly

A non-zero parameter tells the library to just list the names of a ftp directory, instead of doing a full directory listing that would include file sizes, dates etc.

-ftpappend

A non-zero parameter tells the library to append to the remote file instead of overwriting it. This is only useful when uploading to a ftp site.

-netrc

A non-zero parameter tells the extension to scan your ~/.netrc file to find user name and password for the remote site you are about to access. Do note that TclCurl does not verify that the file has the correct properties set (as the standard unix ftp client does), and that only machine name, user name and password is taken into account (init macros and similar things are not supported).

-followlocation

A non-zero parameter tells the library to follow any Location: header that the server sends as part of a HTTP header. NOTE that this means that the extension will resend the same request on the new location and follow new Location: headers all the way until no more such headers are returned.

-transfertext

A non-zero parameter tells the extension to use ASCII mode for ftp transfers, instead of the default binary transfer. For LDAP transfers it gets the data in plain text instead of HTML and for win32 systems it does not set the stdout to binary mode. This option can be useable when transfering text data between systems with different views on certain characters, such as newlines or similar.

-put

A non-zero parameter tells the extension to use HTTP PUT a file. The file to put must be set with infile and infilesize

-userpwd

Pass a string as parameter, which should be [username]:[password] to use for the connection.

-proxyuserpwd

Pass a string as parameter, which should be [username]:[password] to use for the connection to the HTTP proxy. If the password is left out, you will be prompted for it.

-range

Pass a string as parameter, which should contain the specified range you want. It should be in the format "X-Y", where X or Y may be left out. HTTP transfers also support several intervals, separated with commas as in X-Y,N-M response document in pieces.

-errorbuffer

Pass a variable name where TclCurl may store human readable error messages in. This may be more helpful than just the return code from the extension.

-timeout

Pass the maximum time in seconds that you allow the TclCurl transfer operation to take. Do note that normally, name lookups may take a considerable time and that limiting the operation to less than a few minutes risks aborting perfectly normal operations.

-postfields

Pass a string as parameter, which should be the full data to post in a HTTP post operation. See also the post option.

-postfieldsize

If you want to post data to the server without letting TclCurl do a strlen() to measure the data size, this option must be used. Also, when this option is used, you can post fully binary data which otherwise is likely to fail. If this size is set to zero, the library will use strlen() to get the data size.

-referer

Pass a string as parameter. It will be used to set the referer: header in the http request sent to the remote server. This can be used to fool servers or scripts.

-useragent

Pass a string as parameter. It will be used to set the user-agent: header in the http request sent to the remote server. This can be used to fool servers or scripts.

-ftpport

Pass a string as parameter. It will be used to get the IP address to use for the ftp PORT instruction. The PORT instruction tells the remote server to connect to our specified IP address. The string may be a plain IP address, a host name, an network interface name (under unix) or just a '-' letter to let the library use your systems default IP address.

-lowspeedlimit

Pass the transfer speed in bytes per second that the transfer should be below during lowspeedtime seconds for the extension to consider it too slow and abort.

-lowspeedtime

Pass the time in seconds that the transfer should be below the lowspeedlimit for the extension to consider it too slow and abort.

-resumefrom

Pass the offset in number of bytes that you want the transfer to start from.

-cookie

Pass string as parameter. It will be used to set a cookie in the http request. The format of the string should be [NAME]=[CONTENTS]; Where NAME is the cookie name.

-httpheader

Pass a list with the HTTP headers to pass to the server in your request. If you add a header that is otherwise generated and used by TclCurl internally, your added one will be used instead. If you add a header with no contents as in 'Accept:', the internally used header will just get disabled. Thus, using this option you can add new headers, replace internal headers and remove internal headers.

-httppost

Tells tclcurl you want a multipart/formdata HTTP POST to be made and you give a Tcl list with the data to pass on to the server. This is the only case where the data is reset after a transfer. The list must contain a 'name' tag with the name of the section followed by a string with the name, there are three tags to indicate the value of the section: 'value' followed by a string with the data to post, 'file' followed by the name of the file to post and 'contenttype' with the type of the data (text/plain, image/jpg, ...), you can also indicate a 'false' file name with 'filename', this is useful in case the server checks if the given file name is valid, by testing if it starts with 'c:' as any real file name does, see 'httpPost.tcl' for an example.

-sslcert

Pass a string as parameter. The string should be the file name of your certificate. The default format is "PEM" and can be changed with sslcerttype.

-sslcerttype

Pass a string as parameter. The string should be the format of your certificate. Supported formats are "PEM" and "DER".

-sslcertpasswd

Pass a string as parameter. It will be used as the password required to use the sslcert certificate.

NOTE:This option is replaced by sslkeypasswd and only kept for backward compatibility. You never needed a pass phrase to load a certificate but you need one to load your private key.

-sslkey

Pass a pointer to a zero terminated string as parameter. The string should be the file name of your private key. The default format is "PEM" and can be changed with sslkeytype.

-sslkeytype

Pass a pointer to a zero terminated string as parameter. The string should be the format of your private key. Supported formats are "PEM", "DER" and "ENG".

NOTE:The format "ENG" enables you to load the private key from a crypto engine. in this case sslkey is used as an identifier passed to the engine. You have to set the crypto engine with sslengine.

-sslkeypasswd

Pass a string as parameter. It will be used as the password required to use the sslkey private key.

-sslengine

Pass a string as parameter. It will be used as the identifier for the crypto engine you want to use for your private key.

NOTE:If the crypto device cannot be loaded, an error will be returned.

-sslenginedefault

Sets the actual crypto engine as the default for (asymetric) crypto operations.

NOTE:If the crypto device cannot be set, an error will be returned.

-crlf

Convert unix newlines to CRLF newlines on FTP uploads.

-quote

Pass a list with the FTP commands to pass to the server prior to your ftp request. If you don't want to transfer any files, set nobody to '1' and header to '0'.

-prequote

Pass a list of FTP commands to issue just before the transfer command (RETR or STOR etc). It has turned up a few systems that really need this.

-postquote

Pass a list with the FTP commands to pass to the server after your ftp transfer request. If you don't want to transfer any files, set nobody to '1' and header to '0'.

-writeheader

Pass a the file to be used to write the header part of the received data to. The headers are guaranteed to be written one-by-one to this file handle and only complete lines are written. Parsing headers should be easy enough using this.

-cookiefile

Pass a string as parameter. It should contain the name of your file holding cookie data. The cookie data may be in netscape cookie data format or just regular HTTP-style headers dumped to a file.

-sslversion

Pass what version of SSL to attempt to use, 2 or 3. By default, the SSL library will try to solve this by itself although some servers make this difficult, that is why you at times will have to use this option.

-timecondition

Pass how the timevalue time value is treated. You can set this parameter to ifmodsince or ifunmodsince

-timevalue

Pass the time in seconds since 1 jan 1970, and the time will be used as specified in timecondition or if that is not used, it will be by default.

-customrequest

Pass a string as parameter. It will be used instead of GET or HEAD when doing the HTTP request. This is useful for doing DELETE or other more obscure HTTP requests. Don't do this at will, make sure your server supports the command first.

-stderr

Pass a file as parameter. This is the stream to use instead of stderr internally when reporting errors.

-interface

Pass the interface name to use as outgoing network interface. The name can be an interface name, an IP address or a host name.

-krb4level

Set the krb4 security level, this also enables krb4 awareness. This is a string, 'clear', 'safe', 'confidential' or 'private'. If the string is set but doesn't match one of these, 'private' will be used. Set the string to NULL to disable kerberos4. The kerberos support only works for FTP.

-sslverifypeer

Pass a non-zero value to make TclCurl verify the peer's certificate. The certificate to verify against must be specified with the cainfo option.

-cainfo

Pass a file naming holding the certificate to verify the peer with. This only makes sense when used in combination with the sslverifypeer option.

-filetime

If you pass a non-zero value, TclCurl will attempt to get the modification date of the remote document in this operation. This requires that the remote server sends the time or replies to a time querying command. The getinfo procedure with the filetime argument can be used after a transfer to extract the received time (if any).

-maxredirs

Sets the redirection limit. If that many redirections have been followed, the next redirect will cause an error. This option only makes sense if the followlocation is used at the same time.

-maxconnects

Sets the persistant connection cache size. The set amount will be the maximum amount of simultaneous connections that TclCurl may cache between file transfers. Default is 5, and there isn't much point in changing this value unless you are perfectly aware of how this work and changes TclCurl's behaviour. Note: if you have already performed transfers with this curl handle, setting a smaller maxconnects than before may cause open connections to unnecessarily get closed.

-closepolicy

This option sets what policy TclCurl should use when the connection cache is filled and one of the open connections has to be closed to make room for a new connection. Use leastrecentlyused to make libcurl close the connection that was least recently used, that connection is also least likely to be capable of re-use. Use oldest to make libcurl close the oldest connection, the one that was created first among the ones in the connection cache.

-randomfile

Pass a file name. The file will be used to read from to seed the random engine for SSL. The more random the specified file is, the more secure will the SSL connection becomes.

-egdsocket

Pass a path name to the Entropy Gathering Daemon socket. It will be used to seed the random engine for SSL.

-connecttimeout

Maximum time in seconds that you allow the connection to the server to take. This only limits the connection phase, once it has connected, this option is of no more use. Set to zero to disable connection timeout (it will then only timeout on the system's internal timeouts).

-headervar

Name of the Tcl array variable where TclCurl will store the headers returned by the server.

-bodyvar

Name of the Tcl variable where TclCurl will store the file requested, the file may contain text or binary data.

-progressproc

Name of the Tcl procedure that will invoked by TclCurl whenever there is new data, the prototype of the procedure must be:

proc ProgressCallback {dltotal dlnow ultotal ulnow}

In order to this option to work you have to set the noprogress option to '0'. Settin this options to '0' will restore the original progress function.

-canceltransvar

Name of a Tcl variable, in case you have defined a procedure to call with -progressproc setting this variable to '1' will cancel the transfer.

-writeproc

Use it to set a Tcl procedure that will be invoked by TclCurl as soon as there is received data that needs to be written down.

-readproc

Sets a Tcl procedure to be called by TclCurl as soon as it needs to read data in order to send it to the peer. The procedure has to take one parameter, which will contain the maximun numbers of bytes to read. It should return the actual number of bytes read, or '0' if you want to stop the transfer.

-httpget

If set to non-zero forces the HTTP request to get back to GET. Only really usable if POST, PUT or a custom request have been used previously with the same curl handle.

-sslverifyhost

Set to non-zero if we should verify the Common name from the peer certificate in the SSL hand­shake, set 1 to check existence, 2 to ensure that it matches the provided hostname.

-cookiejar

Pass a file name in which TclCurl will dump all internally known cookies when curlHandle cleanup is called. If no cookies are known, no file will be created. Specify "-" to have the cookies written to stdout.

-sslcypherlist

Pass a string holding the ciphers to use for the SSL connection. The list must consists of one or more cipher strings separated by colons. Commas or spaces are also acceptable separators but colons are normally used, , - and + can be used as operators. Valid examples of cipher lists include 'RC4-SHA', ´SHA1+DES´, 'TLSv1' and You'll find all details about cipher lists on this URL: http://www.openssl.org/docs/apps/ciphers.html

-httpversion

Set to one of the values decribed below, they force TclCurl to use the specific http versions. It should only be used if you really MUST do that because of a silly remote server.

none

We don't care about what version the library uses. TclCurl will use whatever it thinks fit.

1.0

Enforce HTTP 1.0 requests.

1.1

Enforce HTTP 1.1 requests.

-ftpuseepvs

Set to one to tell TclCurl to use the EPSV command when doing passive FTP downloads (which is always does by default). Using EPSV means that it will first attempt to use EPSV before using PASV, but if you pass a zero to this option, it will not try using EPSV, only plain PASV.

-debugproc

Name of the procedure that will receive the debug data produced by the verbose option, it should match the following prototype: debugProc {infoType, data} where infoType specifies what kind of information it is (0 text, 1 outgoing header, 2 incoming header, 3 outgoing data, 4 incoming data).

-dnscachetimeout

Pass the timeout in seconds. Name resolves will be kept in memory for this number of seconds. Set to zero (0) to completely disable caching, or -1 to make the cached entries remain forever. By default, TclCurl caches info for 60 seconds.

-dnsuseglobalcache

If the value passed is non-zero, it tells TclCurl to use a global DNS cache that will survive between curl handles creations and deletions. This is not thread-safe as it uses a global varible.

NOT SUPPORTED

CURLOPT_PASSWDFUNCTION, CURLOPT_PASSWDDATA, CURLOPT_FRESH_CONNECT, CURLOPT_FORBID_REUSE

curlHandle perform

It must be called with the same curlHandle curl::init call returned. You can do any amount of calls to perform while using the same handle. If you intend to transfer more than one file, you are even encouraged to do so. TclCurl will then attempt to re-use the same connection for the following transfers, thus making the operations faster, less CPU intense and using less network resources. Just note that you will have to use configure between the invokes to set options for the following perform.

You must never call this procedure simultaneously from two places using the same handle. Let it return first before invoking it another time. If you want parallel transfers, you must use several curl handles.

RETURN VALUE

errorBuffer was set with configure there will be a readable error message. The error codes are:

1

Unsupported protocol. This build of TclCurl has no support for this protocol.

2

Very early initialization code failed. This is likely to be and internal error or problem.

3

URL malformat. The syntax was not correct.

4

URL user malformatted. The user-part of the URL syntax was not correct.

5

Couldn't resolve proxy. The given proxy host could not be resolved.

6

Couldn't resolve host. The given remote host was not resolved.

7

Failed to connect to host or proxy.

8

FTP weird server reply. The server sent data TclCurl couldn't parse. The given remote server is probably not an OK FTP server.

9

We were denied access when trying to login to a FTP server or when trying to change working directory to the one given in the URL.

10

FTP user/password incorrect. Either one or both were not accepted by the server.

11

FTP weird PASS reply. TclCurl couldn't parse the reply sent to the PASS request.

12

FTP weird USER reply. TclCurl couldn't parse the reply sent to the USER request.

13

FTP weird PASV reply, TclCurl couldn't parse the reply sent to the PASV request.

14

FTP weird 227 format. TclCurl couldn't parse the 227-line the server sent.

15

FTP can't get host. Couldn't resolve the host IP we got in the 227-line.

16

FTP can't reconnect. A bad return code on either PASV or EPSV was sent by the FTP server, preventing TclCurl from being able to continue.

17

FTP couldn't set binary. Couldn't change transfer method to binary.

18

Partial file. Only a part of the file was transfered, this happens when the server first reports an expected transfer size and then delivers data that doesn't match the given size.

19

FTP couldn't RETR file, we either got a weird reply to a 'RETR' command or a zero byte transfer.

20

FTP write error. After a completed file transferm the FTP server did not respond properly.

21

FTP quote error. A custom 'QUOTE' returned error code 400 or higher from the server.

22

HTTP not found. The requested page was not found. This return code only appears if --fail is used and the HTTP server returns an error code that is 400 or higher.

23

Write error. TclCurl couldn't write data to a local filesystem or an error was returned from a write callback.

24

Malformat user. User name badly specified. Not in use anymore

25

FTP couldn't STOR file. The server denied the STOR operation, the error buffer will usually have the server explanation.

26

Read error. There was a problem reading from a local file or an error was returned from the read callback.

27

Out of memory. A memory allocation request failed. This should never happen unless something weird is going on in your computer.

28

Operation timeout. The specified time-out period was reached according to the conditions.

29

FTP couldn't set ASCII. The server returned an unknown reply.

30

FTP PORT command failed, this usually happens when you haven't specified a good enough address for TclCurl to use.

31

FTP couldn't use REST. This should never happen is the server is sane.

32

FTP couldn't use the SIZE command. The command is an extension to the original FTP spec RFC 959, so not all servers support it.

33

HTTP range error. The server doesn't support or accept range requests.

34

HTTP post error. Internal post-request generation error.

35

SSL connect error. The SSL handshaking failed, the error buffer may have a clue to the reason, could be certificates, passwords, ...

36

FTP bad download resume. Couldn't continue an earlier aborted download, probably because you are trying to resume beyond the file size.

37

A file given with FILE:// couldn't be read. Did you checked the permissions?

38

LDAP cannot bind. LDAP bind operation failed.

39

LDAP search failed.

40

Library not found. The LDAP library was not found.

41

A required LDAP function was not found.

42

Aborted by callback. An application told TclCurl to abort the operation.

43

Internal error. A function was called with a bad parameter.

44

Internal error. A function was called in a bad order.

45

Interface error. A specified outgoing interface could not be used.

46

Bad password entered. An error was signalled when the password was entered.

47

Too many redirects. When following redirects, TclCurl hit the maximum amount, set your limit with --maxredirs

48

Unknown TELNET option specified.

49

A telnet option string was illegally formatted.

50

Currently not used.

51

The remote peer's SSL certificate wasn't ok

52

The server didn't reply anything, which here is considered an error.

53

The specified crypto engine wasn't found.

54

Failed setting the selected SSL crypto engine as default!

55

Failed sending network data.

56

Failure with receiving network data.

curlHandle getinfo option

AVAILABLE INFORMATION

effectiveurl

Returns the last used effective URL.

httpcode

Returns the last received HTTP code.

filetime

Returns the remote time of the retrieved document. If you get -1, TclCurl couldn't read it, which can be because of many reasons (unknown, the server hides it or the server doesn't support the command that tells document time, etc) and the time of the document is unknown.

In order for this to work you have to set the -filetime option before the transfer.

totaltime

Returns the total transaction time in seconds for the previous transfer.

namelookuptime

Returns the time, in seconds, it took from the start until the name resolving was completed.

connecttime

Returns the time, in seconds, it took from the start until the connect to the remote host (or proxy) was completed.

pretransfertime

Returns the time, in seconds, it took from the start until the file transfer is just about to begin. This includes all pre-transfer commands and negotiations that are specific to the particular protocol(s) involved.

starttransfertime

Returns the time, in seconds, it took from the start until the first byte is just about to be transfered. This includes the pretransfertime and also the time the server needs to calculate the result.

sizeupload

Returns the total amount of bytes that were uploaded.

sizedownload

Returns the total amount of bytes that were downloaded.

speeddownload

Returns the average download speed that curl measured for the complete download.

speedupload

Returns the average upload speed that curl measured for the complete upload.

headersize

Returns the total size of all the headers received.

requestsize

Returns the total size of the issued requests. This is so far only for HTTP requests. Note that this may be more than one request if followLocation is true.

sslverifyresult

Returns the result of the certification verification that was requested (using the -sslverifypeer option to configure).

contentlengthdownload

Returns the content-length of the download. This is the value read from the Content-Length: field.

contentlengthupload

Returns the specified size of the upload.

contenttype

Returns the content-type of the downloaded object. This is the value read from the Content-Type: field. If you get an empty string, it means the server didn't send a valid Content-Type header or that the protocol used doesn't support this.

curlHandle duphandle

RETURN VALUE

A new curl handle or an error message if the copy fails.

curlHandle cleanup

curl::transfer

curl::version

RETURN VALUE

The string with the version info.

curl::escape url

RETURN VALUE

The converted string.

curl::unescape url

RETURN VALUE

The string unencoded.

curl::curlConfig option

OPTIONS

-prefix

Returns the directory root where you installed cURL

-feature

Returns a list containing particular main features the installed libcurl was built with. The list may include SSL, KRB4 or IPv6, do not assume any particular order.

-vernum

Outputs version information about the installed libcurl, in numerical mode. This outputs the version number, in hexadecimal,
 with 8 bits for each part; major, minor, patch. So  that  libcurl
 7.7.4 would  appear  as 070704 and libcurl 12.13.14 would appear as 0c0d0e...

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

curl::init

curlHandle configure ?options?

NOT SUPPORTED

curlHandle perform

curlHandle getinfo option

AVAILABLE INFORMATION

curlHandle duphandle

curlHandle cleanup

curl::transfer

curl::version

curl::escape url

curl::unescape url

curl::curlConfig option

SEE ALSO