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 | |
| cleanup | Close a connection and destroys all associated data. |
| exec | Transfers data from the remote. |
| getData | Gets data temporarily stored in a string during a transfer. |
| getInfo | Returns informations about the status of this handle. |
| postData | Sets data to be sent in one unique POST request. |
| setInCallback | Asks for subsequent uploads to be handled to a given callback. |
| setInStream | Asks for subsequent upload(s) to read data from the given stream. |
| setOption | Sets a cURL option for this specific handle. |
| setOptions | Sets a list of cURL option for this specific handle. |
| setOutCallback | Asks for subsequent transfer(s) to be handled to a given callback. |
| setOutConsole | Asks for subsequent transfer(s) to be sent to process console (raw stdout). |
| setOutStream | Asks for subsequent transfer(s) to be stored in a given stream. |
| setOutString | Asks for subsequent transfer(s) to be stored in a temporary string. |
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.
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.
Transfers data from the remote.
Handle.exec()
| Return | self (to put this call in a chain) | ||
| Raise |
|
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
Gets data temporarily stored in a string during a transfer.
Handle.getData()
| Return | A 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.
Returns informations about the status of this handle.
Handle.getInfo( option )
| option | The specific information to be read. |
| Return | The 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.
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.
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 |
| Return | self (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.
Asks for subsequent upload(s) to read data from the given stream.
Handle.setInStream( stream )
| stream | The stream to be used. |
| Return | self (to put this call in a chain) |
When called, Handle.exec will read data to be uploaded from this stream.
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. |
| Return | self (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).
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. |
| Return | self (to put this call in a chain) |
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. |
| Return | self (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.
Asks for subsequent transfer(s) to be sent to process console (raw stdout).
Handle.setOutConsole()
| Return | self (to put this call in a chain) |
This is the default at object creation.
Asks for subsequent transfer(s) to be stored in a given stream.
Handle.setOutStream( stream )
| stream | The stream to be used. |
| Return | self (to put this call in a chain) |
When called, Handle.exec will store incoming data in this stream object via binary Stream.write operations.
Asks for subsequent transfer(s) to be stored in a temporary string.
Handle.setOutString()
| Return | self (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.