Skip to content

Latest commit

 

History

History
1084 lines (862 loc) · 53.3 KB

api.md

File metadata and controls

1084 lines (862 loc) · 53.3 KB

node-libcurl

node-libcurl.Curl ⇐ EventEmitter

Kind: static class of node-libcurl
Extends: EventEmitter

new Curl()

Wrapper class around one easy handle. It provides a more nodejs-friendly interface.

curl.onData : onDataCallback

If you want a callback more like the CURLOPT_WRITEFUNCTION option, use this property to set the callback.

Kind: instance property of Curl

curl.onHeader : onHeaderCallback

If you want a callback more like the CURLOPT_HEADERFUNCTION option, use this property to set the callback.

Kind: instance property of Curl

curl.enable(bitmask) ⇒ Curl

Enables a feature, should not be used while a request is running. Check feature.

Kind: instance method of Curl
Returns: Curl - this

Param Type Description
bitmask Number Bitmask with the features to enable

curl.disable(bitmask) ⇒ Curl

Disables a feature, should not be used while a request is running. Check feature.

Kind: instance method of Curl
Returns: Curl - this

Param Type Description
bitmask Number Bitmask with the features to disable

curl.setOpt(optionIdOrName, optionValue) ⇒ Curl

Use option for predefined constants.

Kind: instance method of Curl
Returns: Curl - this

Param Type Description
optionIdOrName String | Number Option id or name.
optionValue * Value is relative to what option you are using.

curl.getInfo(infoNameOrId) ⇒ String | Number | Array

Use info for predefined constants.

Kind: instance method of Curl
Returns: String | Number | Array - Return type is based on the info requested.

Param Type Description
infoNameOrId String | Number Info id or name.

curl.setProgressCallback(cb) ⇒ Curl

The option XFERINFOFUNCTION was introduced in curl version 7.32.0, versions older than that should use PROGRESSFUNCTION. If you don't want to mess with version numbers you can use this method, instead of directly calling setOpt.

NOPROGRESS should be set to false to make this function actually get called.

Kind: instance method of Curl
Returns: Curl - this

Param Type
cb progressCallback

curl.perform() ⇒ Curl

Add this instance to the processing queue.

Kind: instance method of Curl
Returns: Curl - this
Throws:

  • This method should be called only one time per request, otherwise it will throw an exception.

curl.pause(bitmask) ⇒ Curl

Using this function, you can explicitly mark a running connection to get paused, and you can unpause a connection that was previously paused.

The bitmask argument is a set of bits that sets the new state of the connection.

Kind: instance method of Curl
Returns: Curl - this

Param Type
bitmask pause

curl.reset() ⇒ Curl

Reset this handle options to their defaults.

Kind: instance method of Curl
Returns: Curl - this

curl.dupHandle([shouldCopyCallbacks], [shouldCopyEventListeners]) ⇒ Curl

Duplicate this handle with all their options. Keep in mind that, by default, this also means anonymous functions that were set as callbacks and all event listeners.

Using the arguments to change that behaviour.

Kind: instance method of Curl
Returns: Curl - New handle with all the options set in this handle.

Param Type Default Description
[shouldCopyCallbacks] Boolean true Should copy onData and onHeader callbacks
[shouldCopyEventListeners] Boolean true Should copy current event listeners

curl.close()

Close this handle. NOTE: After closing the handle, it should not be used anymore! Doing so will throw an exception.

Kind: instance method of Curl

"data" (chunk)

Data event

Kind: event emitted by Curl

Param Type Description
chunk Buffer The data that was received.

"header" (chunk)

Header event

Kind: event emitted by Curl

Param Type Description
chunk Buffer The header that was received.

"error" (err, errCode)

Error event

Kind: event emitted by Curl

Param Type Description
err Error Error object
errCode Number libcurl error code.

"end" (status, argBody, argBody)

End event

Kind: event emitted by Curl

Param Type Description
status Number Last received response code
argBody String | Buffer If Curl.feature.NO_DATA_PARSING is set, a Buffer is passed instead of a string.
argBody Array | Buffer If Curl.feature.NO_HEADER_PARSING is set, a Buffer is passed instead of an array with the headers.

Curl.option : enum

Options to be used with easy.setOpt or curl.setOpt See the official documentation of curl_easy_setopt() for reference.

CURLOPT_URL becomes Curl.option.URL

Kind: static enum property of Curl
Read only: true

Curl.multi : enum

Options to be used with multi.setOpt()

CURLMOPT_MAXCONNECTS becomes Curl.multi.MAXCONNECTS

Kind: static enum property of Curl
Read only: true

Curl.share : enum

Options to be used with share.setOpt()

Kind: static enum property of Curl
Read only: true
See: module:node-libcurl.Curl.lock
Properties

Name Type Default
SHARE Number 1
UNSHARE Number 2

Curl.lock : enum

Options to be used with the Curl.share.SHARE and Curl.share.UNSHARE options.

CURL_LOCK_DATA_COOKIE becomes Curl.lock.DATA_COOKIE

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
DATA_COOKIE Number 2
DATA_DNS Number 3
DATA_SSL_SESSION Number 4

Curl.info : enum

Infos to be used with easy.getInfo() or curl.getInfo() See the official documentation of curl_easy_getinfo() for reference.

CURLINFO_EFFECTIVE_URL becomes Curl.info.EFFECTIVE_URL

Kind: static enum property of Curl
Read only: true

Curl.auth : enum

Object with bitmasks that should be used with the HTTPAUTH option.

CURLAUTH_BASIC becomes Curl.auth.BASIC

Kind: static enum property of Curl
Read only: true

Curl.http : enum

Object with constants to be used with the HTTP_VERSION option.

CURL_HTTP_VERSION_NONE becomes Curl.http.VERSION_NONE

Kind: static enum property of Curl
Read only: true

Curl.pause : enum

Object with constants to be used with the pause method.

CURLPAUSE_RECV becomes Curl.pause.RECV

Kind: static enum property of Curl
Read only: true

Curl.protocol : enum

Object with the protocols supported by libcurl, as bitmasks. Should be used when setting PROTOCOLS and REDIR_PROTOCOLS options.

CURLPROTO_HTTP becomes Curl.proto.HTTP

Kind: static enum property of Curl
Read only: true

Curl.header : enum

Object with the avaialable bitmasks to be used with HEADEROPT.

Available since libcurl version >= 7.37.0

CURLHEADER_UNIFIED becomes Curl.header.UNIFIED

Kind: static enum property of Curl
Read only: true

Curl.code : enum

Object with the CURLM_ and CURLE_ constants.

CURLE_OK becomes Curl.code.CURLE_OK

Kind: static enum property of Curl
Read only: true

Curl.netrc : enum

Object with constants to be used with NETRC option.

CURL_NETRC_OPTIONAL becomes Curl.netrc.OPTIONAL

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default Description
IGNORED Number 0 The .netrc will never be read. Default.
OPTIONAL Number 1 A user:password in the URL will be preferred to one in the .netrc.
REQUIRED Number 2 A user:password in the URL will be ignored. Unless one is set programmatically, the .netrc will be queried.

Curl.ftpauth : enum

Object with constants for option FTPSSLAUTH

CURLFTPAUTH_DEFAULT becomes Curl.ftpauth.DEFAULT

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
DEFAULT Number 0
SSL Number 1
TLS Number 2

Curl.ftpssl : enum

Object with constants for option FTP_SSL_CCC

CURLFTPSSL_CCC_NONE becomes Curl.ftpssl.CCC_NONE

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
CCC_NONE Number 0
CCC_PASSIVE Number 1
CCC_ACTIVE Number 2

Curl.ftpmethod : enum

Object with constants for option FTP_FILEMETHOD

CURLFTPMETHOD_MULTICWD becomes Curl.ftpmethod.MULTICWD

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
DEFAULT Number 0
MULTICWD Number 1
NOCWD Number 2
SINGLECWD Number 3

Curl.rtspreq : enum

Object with constants for option RTSP_REQUEST Only available on libcurl >= 7.20

CURL_RTSPREQ_OPTIONS becomes Curl.rtspreq.OPTIONS

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
OPTIONS Number 0
DESCRIBE Number 1
ANNOUNCE Number 2
SETUP Number 3
PLAY Number 4
PAUSE Number 5
TEARDOWN Number 6
GET_PARAMETER Number 7
SET_PARAMETER Number 8
RECORD Number 9
RECEIVE Number 10

Curl.ipresolve : enum

Object with constants for option IPRESOLVE

CURL_IPRESOLVE_V4 becomes Curl.ipresolve.V4

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
WHATEVER Number 0
V4 Number 1
V6 Number 2

Curl.usessl : enum

Object with constants for option USE_SSL

CURLUSESSL_NONE becomes Curl.usessl.NONE

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
NONE Number 0
TRY Number 1
CONTROL Number 2
ALL Number 3

Curl.sslversion : enum

Object with constants for option SSLVERSION

CURL_SSLVERSION_DEFAULT becomes Curl.sslversion.DEFAULT

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
DEFAULT Number 0
TLSv1 Number 1
SSLv2 Number 2
SSLv3 Number 3

Curl.ssh_auth : enum

Object with constants for option SSH_AUTH_TYPES

CURLSSH_AUTH_PASSWORD becomes Curl.ssh_auth.PASSWORD

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
ANY Number ~0
NONE Number 0
PUBLICKEY Number
PASSWORD Number
HOST Number
KEYBOARD Number

Curl.timecond : enum

Object with constants for option TIMECONDITION

CURL_TIMECOND_IFMODSINCE becomes Curl.timecond.IFMODSINCE

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default
IFMODSINCE Number 0
IFUNMODSINCE Number 1

Curl.feature : enum

Object with the features currently supported as bitmasks.

Kind: static enum property of Curl
Read only: true
Properties

Name Type Default Description
NO_DATA_PARSING Number Data received is passed as a Buffer to the end event.
NO_HEADER_PARSING Number Header received is not parsed, it's passed as a Buffer to the end event.
RAW Number Same than NO_DATA_PARSING
NO_DATA_STORAGE Number Data received is not stored inside this handle, implies NO_DATA_PARSING.
NO_HEADER_STORAGE Number Header received is not stored inside this handle, implies NO_HEADER_PARSING.
NO_STORAGE Number Same than NO_DATA_STORAGE

Curl.getCount ⇒ Number

Returns the number of handles currently open in the internal multi handle being used.

Kind: static property of Curl

Curl.getVersion ⇒ String

Returns libcurl version string. The string shows which features are enabled, and the version of the libraries that libcurl was built with.

Kind: static property of Curl

Curl.VERSION_NUM

Current libcurl version

Kind: static constant of Curl

Curl~progressCallback ⇒ Number

Progress callback called by libcurl.

Kind: inner typedef of Curl
Returns: Number - Returning a non-zero value from this callback will cause libcurl to abort the transfer and return CURLE_ABORTED_BY_CALLBACK.
this: {module:node-libcurl.Easy}

Param Type Description
dltotal Number Total number of bytes libcurl expects to download in this transfer.
dlnow Number Number of bytes downloaded so far.
ultotal Number Total number of bytes libcurl expects to upload in this transfer.
ulnow Number Number of bytes uploaded so far.

node-libcurl.Easy

Kind: static class of node-libcurl

new Easy([orig])

Easy handle constructor

Param Type Default Description
[orig] Easy Creates this handle based on another one, this is going to be the same than calling orig.dupHandle();

easy.onData : onDataCallback

Kind: instance property of Easy

easy.onHeader : onHeaderCallback

Kind: instance property of Easy

easy.setOpt(optionIdOrName, optionValue) ⇒ code

Use option for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Kind: instance method of Easy
Returns: code - code Should be Curl.code.CURLE_OK.

Param Type Description
optionIdOrName String | Number Option id or name.
optionValue * Value is relative to what option you are using.

easy.getInfo(infoNameOrId) ⇒ ReturnData

Use info for predefined constants.

Official libcurl documentation: curl_easy_getinfo()

Kind: instance method of Easy
Returns: ReturnData - .data will be the requested info

Param Type Description
infoNameOrId String | Number Info id or name.

easy.send(buf) ⇒ ReturnData

Sends arbitrary data over the established connection.

Official libcurl documentation: curl_easy_send()

Kind: instance method of Easy
Returns: ReturnData - .data will be the numbers of bytes sent.

Param Type Description
buf Buffer The data to be sent

easy.recv(buf) ⇒ module:node-libcurl.Easy.ReturnData

Receives arbitrary data over the established connection.

Official libcurl documentation: curl_easy_recv()

Kind: instance method of Easy
Returns: module:node-libcurl.Easy.ReturnData - .data will be the numbers of bytes received.

Param Type Description
buf Buffer The data will be stored inside this Buffer instance. You need to make sure that the buffer has enought space to store it all.

easy.perform() ⇒ code

Performs the entire request in a blocking manner and returns when done.

Official libcurl documentation: http://curl.haxx.se/libcurl/c/curl_easy_perform.html

Kind: instance method of Easy
Returns: code - code Should be Curl.code.CURLE_OK.

easy.pause(bitmask) ⇒ code

Using this function, you can explicitly mark a running connection to get paused, and you can unpause a connection that was previously paused.

Official libcurl documentation: curl_easy_pause()

Kind: instance method of Easy
Returns: code - code Should be Curl.code.CURLE_OK.

Param Type Description
bitmask pause bitmask set of bits that sets the new state of the connection.

easy.reset() ⇒ code

Reset this handle to their original state.

Official libcurl documentation: curl_easy_reset()

Kind: instance method of Easy
Returns: code - code Should be Curl.code.CURLE_OK.

easy.dupHandle() ⇒ Easy

Duplicate this handle with all their options

Official libcurl documentation: curl_easy_duphandle()

Kind: instance method of Easy
Returns: Easy - handle Returns the new handle.

easy.onSocketEvent(cb) ⇒ Easy

The only time this method should be used is when one enables the internal polling of the connection socket used by this handle (by calling Easy#monitorSocketEvents), the callback is going to be called everytime there is some change to the socket.

One use case for that is when using the Easy#send and Easy#recv methods.

Kind: instance method of Easy
Returns: Easy - this

Param Type
cb onSocketEventCallback

easy.monitorSocketEvents() ⇒ Easy

Start monitoring for events in the connection socket used by this handle.

Kind: instance method of Easy
Returns: Easy - this
See: module:node-libcurl.Easy#unmonitorSocketEvents

easy.unmonitorSocketEvents() ⇒ Easy

Stop monitoring for events in the connection socket used by this handle.

Kind: instance method of Easy
Returns: Easy - this
See: module:node-libcurl.Easy#monitorSocketEvents

easy.close()

Close this handle and dispose any resources bound to it. After closed, the handle MUST not be used again.

This is basically the same than curl_easy_cleanup()

Kind: instance method of Easy

Easy.socket : enum

Kind: static enum property of Easy
Read only: true
Properties

Name Type Default
READABLE Number 1
WRITABLE Number 2

Easy.strError(code) ⇒ String

Returns a description for the given error code.

Official libcurl documentation: curl_easy_strerror()

Kind: static method of Easy

Param Type
code code

Easy~ReturnData : Object

This literal object is returned for calls that cannot return single values. Like getInfo and send

Kind: inner typedef of Easy
Properties

Name Type Description
code code The return code for the given method call. It should be equals Curl.code.CURLE_OK to be valid.
data * Data returned from the method call.

Easy~onDataCallback ⇒ Number

onData callback for taking care of the data we just received. This is basically the CURLOPT_WRITEFUNCTION option.

Kind: inner typedef of Easy
Returns: Number - The callback must return exactly nmemb * size, otherwise it will signal libcurl to abort the transfer, and return with error code CURLE_WRITE_ERROR.

You can return Curl.pause.WRITEFUNC too, this will cause this transfer to become paused.
this: {module:node-libcurl.Easy}
See: module:node-libcurl.Easy#onData

Param Type
buf Buffer
size Number
nitems Number

Easy~onHeaderCallback ⇒ Number

onHeader callback for taking care of the headers we just received. This is basically the CURLOPT_HEADERFUNCTION option.

Kind: inner typedef of Easy
Returns: Number - The callback must return exactly nmemb * size, otherwise it will signal libcurl to abort the transfer, and return with error code CURLE_WRITE_ERROR.
this: {module:node-libcurl.Easy}
See: module:node-libcurl.Easy#onHeader

Param Type
buf Buffer
size Number
nitems Number

Easy~onSocketEventCallback : function

OnSocketEvent callback called when there are changes to the connection socket.

Kind: inner typedef of Easy
this: {module:node-libcurl.Easy}

Param Type Description
err Error Should be null if there are no errors.
events socket The events that were detected in the socket

node-libcurl.Multi

Kind: static class of node-libcurl

new Multi()

Multi handle constructor

multi.setOpt(optionIdOrName, optionValue) ⇒ code

Use multi for predefined constants.

Official libcurl documentation: curl_multi_setopt()

Kind: instance method of Multi
Returns: code - code Should be Curl.code.CURLM_OK.

Param Type Description
optionIdOrName String | Number Option id or name.
optionValue * Value is relative to what option you are using.

multi.addHandle(handle) ⇒ code

Adds an easy handle to be managed by this multi instance.

Official libcurl documentation: curl_multi_add_handle()

Kind: instance method of Multi
Returns: code - code Should be Curl.code.CURLM_OK.

Param Type
handle Easy

multi.onMessage(cb) ⇒ Multi

This is basically an abstraction over curl_multi_info_read().

Kind: instance method of Multi
Returns: Multi - this

Param Type
cb onMessageCallback

multi.removeHandle(handle) ⇒ code

Removes an easy handle that was inside this multi instance.

Official libcurl documentation: curl_multi_remove_handle()

Kind: instance method of Multi
Returns: code - code Should be Curl.code.CURLM_OK.

Param Type
handle Easy

multi.getCount() ⇒ Number

Utility method that returns the number of easy handles that are inside this instance.

Kind: instance method of Multi
Returns: Number - count

multi.close()

Closes this multi handle. Keep in mind that this doesn't closes the easy handles that were still inside this multi instance, you must do it manually.

This is basically the same than curl_multi_cleanup()

Kind: instance method of Multi

Multi.strError(code) ⇒ String

Returns a description for the given error code.

Official libcurl documentation: curl_multi_strerror()

Kind: static method of Multi

Param Type
code code

Multi~onMessageCallback : function

OnMessage callback called when there are new informations about handles inside this multi instance.

Kind: inner typedef of Multi
this: {module:node-libcurl.Multi}
See: module:node-libcurl.Multi#onMessage

Param Type Description
err Error Should be null if there are no errors.
easy Easy The easy handle that triggered the message.
errCode code

node-libcurl.Share

Kind: static class of node-libcurl

new Share()

Share handle constructor

share.setOpt(optionIdOrName, optionValue) ⇒ code

Use share for predefined constants.

Official libcurl documentation: curl_share_setopt()

Kind: instance method of Share
Returns: code - code Should be Curl.code.CURLSHE_OK.

Param Type Description
optionIdOrName String | Number Option id or name.
optionValue * Value is relative to what option you are using.

share.close()

Closes this share handle.

This is basically the same than curl_share_cleanup()

Kind: instance method of Share

Share.strError(code) ⇒ String

Returns a description for the given error code.

Official libcurl documentation: curl_share_strerror()

Kind: static method of Share

Param Type
code code