7.2Class Handle

Stores an handle for a CURL (easy) connection.

Class Handle( [uri] )
uri A string or an URI to be used to initialize the connection.

The following is a simple complete program that retrieves the main page of the Falcon programming language site:


   import from curl

   try
      h = curl.Handle( "http://www.falconpl.org" )
      h.setOutString()
      h.exec()
      > "Complete data transfer:", h.getData()
   catch curl.CurlError in e
      > "ERROR: ", e
   end
Properties
data User available data.
Methods
cleanupClose a connection and destroys all associated data.
execTransfers data from the remote.
getDataGets data temporarily stored in a string during a transfer.
getInfoReturns informations about the status of this handle.
postDataSets data to be sent in one unique POST request.
setInCallbackAsks for subsequent uploads to be handled to a given callback.
setInStreamAsks for subsequent upload(s) to read data from the given stream.
setOptionSets a cURL option for this specific handle.
setOptionsSets a list of cURL option for this specific handle.
setOutCallbackAsks for subsequent transfer(s) to be handled to a given callback.
setOutConsoleAsks for subsequent transfer(s) to be sent to process console (raw stdout).
setOutStreamAsks for subsequent transfer(s) to be stored in a given stream.
setOutStringAsks for subsequent transfer(s) to be stored in a temporary string.

Properties

data

User available data.

User available data. Store any data that the client application wants to be related to this handle in this property. It is also possible to derive a child from this class and store more complete behavior there.

Methods

cleanup

Close a connection and destroys all associated data.

Handle.cleanup()

After this call, the handle is not usable anymore. This is executed also automatically at garbage collection, but the user may be interested in clearing the data as soon as possible.

exec

Transfers data from the remote.

Handle.exec()
Returnself (to put this call in a chain)
Raise
CurlError on error

This function performs the whole transfer towards the target that has been selected via Handle.setOutString, Handle.setOutStream, Handle.setOutConsole or Handle.setOutCallback routines.

The call is blocking and normally it cannot be interrupted; however, a timeout can be set through

Note: Internally, this method performs a curl_easy_perform call on the inner

getData

Gets data temporarily stored in a string during a transfer.

Handle.getData()
ReturnA string containing data that has been transfered.

This function returns the data received in the meanwhile. This data is captured when the Handle.setOutString option has been set.

getInfo

Returns informations about the status of this handle.

Handle.getInfo( option )
option The specific information to be read.
ReturnThe value associated with the required information, or nil if the option is not available.

This method returns one of the informations that can be retrieved from this handle. The option value are stored in the INFO enumeration, and they correspond to the values in the CURLINFO_* set of defines of the libcurl SDK, associated with the curl_easy_getinfo function.

The type of the returned value depends of the type of information required; in general it may be a number or a string.

Possible values for option are

- INFO.EFFECTIVE_URL - the last used effective URL.

- INFO.HTTPAUTH_AVAIL - bitmask indicating the authentication method(s) available. The meaning of the bits is explained in the OPT.HTTPAUTH option for Handle.setOption.

- INFO.PROXYAUTH_AVAIL - bitmask indicating the authentication method(s) available for your proxy authentication.

postData

Sets data to be sent in one unique POST request.

Handle.postData( data )
data A string to be sent as post data.

This function substitutes the CURLOPT_POSTFIELDS family of options of the C level libcurl. It allows to set a string that will be sent in HTTP post request.

All the other setOut* methods can be used for the same purpose to take data from streams, callback or even strings, but all the other methods will transfer data in chunks, and require to set the HTTP header transfer-encoding as "chunked" via the CURL.HTTP_HEADERS option, and to use HTTP/1.1 protocol.

Using this method, the postData will be sent as an unique chunk, so it doesn't require extra header setting and works with any HTTP protocol.

Note: The data will be sent not encoded in any particular format (it will be binary-transmitted as it is in the string memory). If the remote server expects a particular encoding (usually, UTF-8), appropriate transocoding functions must be used in advance.

setInCallback

Asks for subsequent uploads to be handled to a given callback.

Handle.setInCallback( cb )
cb A callback item that will write data in an incoming MemBuf
Returnself (to put this call in a chain)

This method instructs this handle to call a given callback when new data can be uploaded to the remote side.

The function receives a MemBuf that must be filled with data.

It should return the amount of data really written to the membuf.

It can also return CURL.WRITE_PAUSE to ask for Handle.exec to return with a pause status.

The callback must return 0 when it has no more data to transfer.

setInStream

Asks for subsequent upload(s) to read data from the given stream.

Handle.setInStream( stream )
stream The stream to be used.
Returnself (to put this call in a chain)

When called, Handle.exec will read data to be uploaded from this stream.

setOption

Sets a cURL option for this specific handle.

Handle.setOption( option, data )
option The option to be set (an enumeration).
data The value to be set.
Returnself (to put this call in a chain)

Depending on the option, data must be a boolean, a number or a string.

Some options, as CURLOPT.HTTPHEADER, require the data to be an array of strings.

Note: CURLOPT.POSTFIELDS family options are not supported directly by this function; use Handle.postData function instead.

Note: Callback related options are not supported by this function. Specific functions are provided to setup automated or manual callback facilities (see the various set* methods in this class).

setOptions

Sets a list of cURL option for this specific handle.

Handle.setOptions( opts )
opts A dictionary of options, where each key is an option number, and its value is the option value.
Returnself (to put this call in a chain)

setOutCallback

Asks for subsequent transfer(s) to be handled to a given callback.

Handle.setOutCallback( cb )
cb A callback item that will receive incoming data as a binary string.
Returnself (to put this call in a chain)

This method instructs this handle to call a given callback when data is received.

When called, Handle.exec will repeatedly call the cb item providing a single string as a parameter.

The string is not encoded in any format, and could be considered filled with binary data.

setOutConsole

Asks for subsequent transfer(s) to be sent to process console (raw stdout).

Handle.setOutConsole()
Returnself (to put this call in a chain)

This is the default at object creation.

setOutStream

Asks for subsequent transfer(s) to be stored in a given stream.

Handle.setOutStream( stream )
stream The stream to be used.
Returnself (to put this call in a chain)

When called, Handle.exec will store incoming data in this stream object via binary Stream.write operations.

setOutString

Asks for subsequent transfer(s) to be stored in a temporary string.

Handle.setOutString()
Returnself (to put this call in a chain)

After Handle.exec has been called, the data will be available in a string that can be retrieved via the Handle.getData method.

Made with http://www.falconpl.org