ldoc

• Index

Contents

• Functions
• Class httpform
• Class easy
• Class multi
• Class error
• Class share

Modules

• cURL
• lcurl

Module lcurl

Functions

form ()	Create HTTP multipart/formdata object.
easy ([options])	Create Easy object
multi ([options])	Create Multi object
share ([options])	Create Share object
version ()	Returns libcurl version as human readable string
version_info ([param])	Returns libcurl version as table

Class httpform

httpform:add_content (name, content[, type[, headers]])	Add new part to form.
httpform:add_buffer (name, filename, content[, type[, headers]])	Add new part to form.
httpform:add_file (name, path[, type[, filename[, headers]]])	Add new part to form.
httpform:add_stream (name[, filename][, type][, headers], size, reader[, context])	Add new part to form.
httpform:get ()	Serialize multipart/formdata HTTP POST chain.
httpform:get (writer[, context])	Serialize multipart/formdata HTTP POST chain.
httpform:get (writer)	Serialize multipart/formdata HTTP POST chain.
httpform:free ()	Free multipart/formdata.

Class easy

easy:perfom ()	Perform a file transfer
easy:escape (url)	URL encodes the given string
easy:unescape (url)	URL decodes the given string
easy:reset ()	Re-initializes all options previously set.
easy:pause (mask)	Pause and unpause a connection.
easy:close ()	End easy session
easy:setopt (opt, ...)	Set options.
easy:unsetopt (opt)	Reset option to default value.
easy:getinfo (info)	Get information.
easy:setopt_writefunction (writer[, context])	Set writer function.
easy:setopt_writefunction (writer)	Set writer function.
easy:setopt_headerfunction (writer[, context])	Set header function.
easy:setopt_headerfunction (writer)	Set header function.
easy:setopt_readfunction (reader[, context])	Set reader function.
easy:setopt_readfunction (reader)	Set reader function.
easy:setopt_progressfunction (progress[, context])	Set progress function.
easy:setopt_progressfunction (progress)	Set progress function.
easy:setopt_httppost (data)	Set HTTP multipart/formdata.
easy:setopt_postfields (data[, length=#data])	Set HTTP multipart/formdata.
easy:setopt_share (data)	Set curl share object.

Class multi

multi:add_handle (handle)	Add Easy object.
multi:remove_handle (handle)	Remove Easy object.
multi:perfom ()	reads/writes available data from each easy handle.
multi:info_read ([remove])	Read multi stack informationals.
multi:setopt (opt, ...)	Set options.
multi:socket_action ([socket=curl.SOCKET_TIMEOUT[, mask=0]])	Perform socket action.
multi:setopt_timerfunction (timer[, context])	Set timer callback.
multi:setopt_timerfunction (timer)	Set timer callback.
multi:wait ([timeout])	Polls on all easy objects in a multi object.
multi:timeout ()	How long to wait for action before proceeding.
multi:close ()	End multi session.

Class error

error:category ()	Get the error category.
error:no ()	Get the number value of error.
error:name ()	Get the error name.
error:msg ()	Get the error description.
error:__tostring ()	Get the full error description.

Class share

share:setopt (opt, ...)	Set options.
share:close ()	End share session.

Functions

form ()

Create HTTP multipart/formdata object.

Returns:

httpform new curl HTTP Post object context

easy ([options])

Create Easy object

Parameters:

• options table

Returns:

easy new curl easy object

Usage:

 c = curl.easy{
   url = 'http://example.com',
   [curl.OPT_VERBOSE] = true,
 }

multi ([options])

Create Multi object

Parameters:

• options table

Returns:

multi new curl multi object

Usage:

 m = curl.multi{
   socketfunction = handle_socket;
   timerfunction  = start_timeout;
 }

share ([options])

Create Share object

Parameters:

• options table

Returns:

share new curl share object

version ()

Returns libcurl version as human readable string

version_info ([param])

Returns libcurl version as table

Parameters:

• param string specific version info

Returns:

table full version into if `param` was not specify

Or

specific info parameter

Usage:

 proto = curl.version_info('protocols')
 if proto.HTTP then ... -- libcurl support http protocol

Class httpform

httpform:add_content (name, content[, type[, headers]])

Add new part to form.

Parameters:

• name string provide the name of this part
• content string actual data to send
• type string provides the content-type for this part
• headers table specifies extra headers for the form POST section

Returns:

self

httpform:add_buffer (name, filename, content[, type[, headers]])

Add new part to form.

Parameters:

• name string provide the name of this part
• filename string provides the filename field in the content header
• content string actual data to send
• type string provides the content-type for this part
• headers table specifies extra headers for the form POST section

Returns:

self

httpform:add_file (name, path[, type[, filename[, headers]]])

Add new part to form.

Parameters:

• name string provide the name of this part
• path string path to file that contain actual data to send
• type string provides the content-type for this part
• filename string provides the filename field in the content header. By default it is basename of path.
• headers table specifies extra headers for the form POST section

Returns:

self

httpform:add_stream (name[, filename][, type][, headers], size, reader[, context])

Add new part to form.

Parameters:

• name string provide the name of this part
• filename string provides the filename field in the content header.
• type string provides the content-type for this part
• headers table specifies extra headers for the form POST section
• size number stream size in bytes
• reader function/object
• context reader context

Returns:

self

See also:

easy:setopt_readfunction

httpform:get ()

Serialize multipart/formdata HTTP POST chain.

Returns:

string serialized data

Usage:

print(post:get())

httpform:get (writer[, context])

Serialize multipart/formdata HTTP POST chain.

Writer function can return true or number of written bytes. Also if function does not return anything is considered as success.

Parameters:

• writer function
• context writer context

Returns:

self

Usage:

 t = {}
 post:get(table.insert, t)
 print(table.concat(t))

httpform:get (writer)

Serialize multipart/formdata HTTP POST chain.

This call same as httpform:get(writer.write, writer)

Parameters:

• writer object

Returns:

self

Usage:

 f = io.open(...)
 post:get(f)

httpform:free ()

Free multipart/formdata.

Class easy

easy:perfom ()

Perform a file transfer

Returns:

self

easy:escape (url)

URL encodes the given string

Parameters:

• url string

Returns:

encoded url

easy:unescape (url)

URL decodes the given string

Parameters:

• url string

Returns:

decoded url

easy:reset ()

Re-initializes all options previously set.

Returns:

easy self

easy:pause (mask)

Pause and unpause a connection.

Parameters:

• mask number set of bits that sets the new state of the connection (one of PAUSE_XXX constant)

Returns:

easy self

easy:close ()

End easy session

easy:setopt (opt, ...)

Set options.

Parameters:

• opt number or table one of `curl.OPT_XXX` constant or options table
• ... value

Returns:

easy self

Usage:

 c:setopt(curl.OPT_URL, "http://example.com")
 c:setopt(curl.OPT_READFUNCTION,
    function(t, n) return table.remove(t) end,
    {"1111", "2222"}
 )
c:setopt{
   url = 'http://example.com',
   [curl.OPT_VERBOSE] = true,
 }

easy:unsetopt (opt)

Reset option to default value.

Parameters:

• opt number one of `curl.OPT_XXX` constant or options table

Returns:

easy self

Usage:

 c:unsetopt(curl.OPT_URL)
 c:unsetopt(curl.OPT_READFUNCTION)

easy:getinfo (info)

Get information.

Parameters:

• info number one of `curl.INFO_XXX` constant

Returns:

value

Usage:

 print(c:getinfo(curl.INFO_EFFECTIVE_URL))
 print(c:getinfo(curl.INFO_TOTAL_TIME))
 print(c:getinfo(curl.INFO_RESPONSE_CODE))

easy:setopt_writefunction (writer[, context])

Set writer function.

A callback accepting one or two parameters. The first is the writer context if any, and the second is a string with the data to be written. Function must return `true` (any non number true value) or full data length or nothing to continue operation. Otherwise the transfer will be aborted with an error.

Parameters:

• writer function
• context writer context

Returns:

self

easy:setopt_writefunction (writer)

Set writer function.

This call same as easy:setopt_writefunction(writer.write, writer)

Parameters:

• writer object

Returns:

self

easy:setopt_headerfunction (writer[, context])

Set header function.

A callback accepting one or two parameters. The first is the writer context if any, and the second is a string with the data to be written. Function must return `true` (any non number true value) or full data length or nothing to continue operation. Otherwise the transfer will be aborted with an error.

Parameters:

• writer function
• context writer context

Returns:

self

easy:setopt_headerfunction (writer)

Set header function.

This call same as easy:setopt_headerfunction(writer.header, writer)

Parameters:

• writer object

Returns:

self

easy:setopt_readfunction (reader[, context])

Set reader function.

A callback accepting one or two parameters. The first is the reader context if any, and the second is the maximum amount of data to be read. You can ignore second argument and pass as mach data as you need. lcurl can split data. Function must return data to continue operation. To stop operation it must return empty string or nil or nothing. Otherwise the transfer will be aborted with an error.

Parameters:

• reader function
• context reader context

Returns:

self

Usage:

 local counter = 10
 c:setopt_readfunction(function()
   if counter > 0 then
     counter = counter - 1
     return 'a'
   end
 end)

easy:setopt_readfunction (reader)

Set reader function.

This call same as easy:setopt_readfunction(reader.read, reader)

Parameters:

• reader object

Returns:

self

easy:setopt_progressfunction (progress[, context])

Set progress function.

A callback accepting four or five parameters. The first is the reader context if any, the second is the total number of bytes expected to be downloaded in this transfer, the third is the number of bytes downloaded so far, the fourth is the total number of bytes expected to be uploaded in this transfer, and the fifth is the number of bytes uploaded so far. Function must return `true` or `1` or nothing to continue operation. Otherwise the transfer will be aborted with an error `ABORTED_BY_CALLBACK`.

!!! NOTE !!! This is differents form libcurl API. In libcurl returning a non-zero value from this callback will cause libcurl to abort the transfer and return. This done to be consisted with writefunction that should return `true` to continue.

Parameters:

• progress function
• context progress context

Returns:

self

easy:setopt_progressfunction (progress)

Set progress function.

This call same as easy:setopt_progressfunction(progress.progress, progress)

Parameters:

• progress object

Returns:

self

easy:setopt_httppost (data)

Set HTTP multipart/formdata.

Caller does not have to save data.

Parameters:

• data httpform

Returns:

self

easy:setopt_postfields (data[, length=#data])

Set HTTP multipart/formdata.

Parameters:

• data string
• length number (default #data)

Returns:

self

easy:setopt_share (data)

Set curl share object.

Caller does not have to save data.

Parameters:

• data share

Returns:

self

Class multi

multi:add_handle (handle)

Add Easy object.

Caller must ensure that easy object is alive until end of operation.

Parameters:

• handle easy

Returns:

multi self

multi:remove_handle (handle)

Remove Easy object.

Parameters:

• handle easy

Returns:

multi self

multi:perfom ()

reads/writes available data from each easy handle.

Returns:

number handles number of active easy handles

multi:info_read ([remove])

Read multi stack informationals.

Note. If curl_multi_remove_handle fail then there no error occure but handle jast stay in multi handle.

Parameters:

• remove remove easy handle if it done.

Returns:

number 0 there no informationals

Or

1. easy handle
2. boolean true

Or

1. easy handle
2. nil
3. error error code

multi:setopt (opt, ...)

Set options.

Parameters:

• opt number or table one of `curl.OPT_MULTI_XXX` constant
• ... value

Returns:

multi self

Usage:

 c:setopt(curl.OPT_MULTI_MAXCONNECTS, 10)
 c:setopt{maxconnects = 10}

multi:socket_action ([socket=curl.SOCKET_TIMEOUT[, mask=0]])

Perform socket action.

Parameters:

• socket number (default curl.SOCKET_TIMEOUT)
• mask number (default 0)

Returns:

multi self

Usage:

 c:socket_action()
 c:socket_action(sock_fd, curl.CSELECT_IN)
 c:socket_action(sock_fd, curl.CSELECT_OUT)

multi:setopt_timerfunction (timer[, context])

Set timer callback.

Parameters:

• timer function timer callback
• context timer context

Returns:

multi self

multi:setopt_timerfunction (timer)

Set timer callback.

This call same as easy:setopt_writefunction(timer.timer, timer)

Parameters:

• timer userdata or table timer object

Returns:

multi self

multi:wait ([timeout])

Polls on all easy objects in a multi object.

Parameters:

• timeout number milliseconds timeout. By default it is `multi:timeout()`.

Returns:

number number of affected objects

multi:timeout ()

How long to wait for action before proceeding.

Returns:

number timeout milliseconds timeout

multi:close ()

End multi session.

Class error

error:category ()

Get the error category.

Returns:

number number of error category (curl.ERROR_XXX constants)

Usage:

 if err:category() == curl.ERROR_EASY then
 -- proceed easy error
 end

error:no ()

Get the number value of error.

Returns:

number number of error (curl.E_XXX constants)

error:name ()

Get the error name.

Returns:

string error name (e.g. "UNSUPPORTED_PROTOCOL", "BAD_OPTION")

error:msg ()

Get the error description.

Returns:

string error description (e.g. "Login denied")

error:__tostring ()

Get the full error description.

Returns:

string string that contain name, message and number of error

Class share

share:setopt (opt, ...)

Set options.

Parameters:

• opt number or table one of `curl.OPT_SHARE_XXX` constant
• ... value

Returns:

share self

Usage:

 c:setopt(curl.OPT_SHARE_SHARE, curl.LOCK_DATA_COOKIE)
 c:setopt{share =  curl.LOCK_DATA_COOKIE}

share:close ()

End share session.