{@link "Easy".Easy | Easy} handle that should be used instead of creating a new one.
Stores current response payload.
This will not store anything in case NoDataStorage flag is enabled
Current response length.
Will always be zero in case NoDataStorage flag is enabled
Internal Easy handle being used
Stores current headers payload.
This will not store anything in case NoDataStorage flag is enabled
Current headers length.
Will always be zero in case NoDataStorage flag is enabled
Whether this instance is running or not (perform() was called).
Make sure to not change their value, otherwise unexpected behavior would happen.
This is marked as protected only with the TSDoc to not cause a breaking change.
Integer representing the current libcurl version.
It was built the following way:
<8 bits major number> | <8 bits minor number> | <8 bits patch number>.Version 7.69.1 is therefore returned as 0x074501 / 476417
This is the default user agent that is going to be used on all Curl instances.
You can overwrite this in a per instance basis, calling curlHandle.setOpt('USERAGENT', 'my-user-agent/1.0'), or
by directly changing this property so it affects all newly created Curl instances.
To disable this behavior set this property to null.
This symbol shall be used to install a listener for only monitoring 'error'
events. Listeners installed using this symbol are called before the regular
'error' listeners are called.
Installing a listener using this symbol does not change the behavior once an
'error' event is emitted, therefore the process will still crash if no
regular 'error' listener is installed.
Returns the number of handles currently open in the internal {@link "Multi".Multi | Multi} handle being used.
Returns libcurl version string.
The string shows which libraries libcurl was built with and their versions, example:
libcurl/7.69.1-DEV OpenSSL/1.1.1d zlib/1.2.11 WinIDN libssh2/1.9.0_DEV nghttp2/1.40.0Calls curl_global_cleanup()
This is automatically called when the process is exiting.
Calls curl_global_init().
For flags see the the enum CurlGlobalInit.
This is automatically called when the addon is loaded, to disable this, set the environment variable
NODE_LIBCURL_DISABLE_GLOBAL_INIT_CALL=false
This is a object with members resembling the CURLINFO_* libcurl constants.
It can be used with {@link "Easy".Easy.getInfo | Easy#getInfo} or Curl#getInfo.
See the official documentation of curl_easy_getinfo()
for reference.
CURLINFO_EFFECTIVE_URL becomes Curl.info.EFFECTIVE_URL
This is a object with members resembling the CURLOPT_* libcurl constants.
It can be used with {@link "Easy".Easy.setOpt | Easy#setOpt} or Curl#setOpt.
See the official documentation of curl_easy_setopt()
for reference.
CURLOPT_URL becomes Curl.option.URL
Whether this instance is closed or not (close() was called).
Make sure to not change their value, otherwise unexpected behavior would happen.
When uploading a stream (by calling setUploadStream)
some event listeners are attached to the stream instance.
This will remove them so our callbacks are not called anymore.
Close this handle.
NOTE: After closing the handle, it must not be used anymore. Doing so will throw an error.
Official libcurl documentation: curl_easy_cleanup()
This is the default callback passed to setOpt('HEADERFUNCTION', cb).
This is the default callback passed to setOpt('WRITEFUNCTION', cb).
This is used by the default callback passed to setOpt('WRITEFUNCTION', cb)
when the feature to stream response is enabled.
Disables a feature, must not be used while a request is running.
Use CurlFeature for predefined constants.
Duplicate this handle with all their options. Keep in mind that, by default, this also means all event listeners.
Official libcurl documentation: curl_easy_duphandle()
If you don't want to copy the event listeners, set this to false.
Enables a feature, must not be used while a request is running.
Use CurlFeature for predefined constants.
Returns headers from the current stored chunks - if any
Retrieves some information about the last request made by a handle.
This overloaded method has never as type for the argument
because one of the other overloaded signatures must be used.
Official libcurl documentation: curl_easy_getinfo()
Info name or integer value. Use Curl.info for predefined constants.
Returns information about the finished connection.
Official libcurl documentation: curl_easy_getinfo()
Info to retrieve. Use {@link "Curl".Curl.info | Curl.info} for predefined constants.
Returns information about the finished connection.
Official libcurl documentation: curl_easy_getinfo()
Info to retrieve. Use {@link "Curl".Curl.info | Curl.info} for predefined constants.
This is emitted if the StreamResponse feature was enabled.
The data paramater passed to the listener callback will be one of the following:
Buffer if the feature NoDataStorage flag was enabledBuffer if the feature NoDataParsing flag was enabledThe headers parameter passed to the listener callback will be one of the following:
Buffer if the feature NoHeaderStorage flag was enabledBuffer if the feature NoHeaderParsing flag was enabledCallback called when this handle has finished the request.
This is called from the internal callback we use with the {@link "Multi".Multi.onMessage | onMessage}
method of the global {@link "Multi".Multi | Multi} handle used by all Curl instances.
This should not be called in any other way.
Callback called when an error is thrown on this handle.
This is called from the internal callback we use with the {@link "Multi".Multi.onMessage | onMessage}
method of the global {@link "Multi".Multi | Multi} handle used by all Curl instances.
Use this function to pause / unpause a connection.
The bitmask argument is a set of bits that sets the new state of the connection.
Use CurlPause for predefined constants.
Official libcurl documentation: curl_easy_pause()
Add this instance to the processing queue. This method should be called only one time per request, otherwise it will throw an error.
Reset this handle options to their defaults.
This will put the handle in a clean state, as if it was just created.
Official libcurl documentation: curl_easy_reset()
This is used to reset a few properties to their pre-request state.
Sets an option the handle.
This overloaded method has never as type for the arguments
because one of the other overloaded signatures must be used.
Official libcurl documentation: curl_easy_setopt()
Option name or integer value. Use Curl.option for predefined constants.
The value of the option, value type depends on the option being set.
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
You can either return a single CurlHstsReadCallbackResult object or an array of CurlHstsReadCallbackResult objects.
If returning an array, the callback will only be called once per request.
If returning a single object, the callback will be called multiple times until null is returned.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.
Official libcurl documentation: curl_easy_setopt()
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 Curl#setOpt.
NOPROGRESS should be set to false to make this function actually get called.
This sets the callback to be used as the progress function when using any of the stream features.
This is needed because when this Curl instance is enabled to use streams for upload/download, it needs
to set the libcurl progress function option to an internal function.
If you are using any of the streams features, do not overwrite the progress callback to something else,
be it using setOpt or setProgressCallback, as this would
cause undefined behavior.
If are using this callback, there is no need to set the NOPROGRESS option to false (as you normally would).
Set the param to null to use the Node.js default value.
This will passed directly to the Readable stream created to be returned as the response'
This will set an internal READFUNCTION callback that will read all the data from this stream.
One usage for that is to upload data directly from streams. Example:
const curl = new Curl()
curl.setOpt('URL', 'https://some-domain/upload')
curl.setOpt('UPLOAD', true)
// so we do not need to set the content length
curl.setOpt('HTTPHEADER', ['Transfer-Encoding: chunked'])
const filePath = './test.zip'
const stream = fs.createReadStream(filePath)
curl.setUploadStream(stream)
curl.setStreamProgressCallback(() => {
// this will use the default progress callback from libcurl
return CurlProgressFunc.Continue
})
curl.on('end', (statusCode, data) => {
console.log('\n'.repeat(5))
// data length should be 0, as it was sent using the response stream
console.log(
`curl - end - status: ${statusCode} - data length: ${data.length}`,
)
curl.close()
})
curl.on('error', (error, errorCode) => {
console.log('\n'.repeat(5))
console.error('curl - error: ', error, errorCode)
curl.close()
})
curl.perform()Multiple calls with the same stream that was previously set has no effect.
Setting this to null will remove the READFUNCTION callback and disable this behavior.
The internal function passed to PROGRESSFUNCTION (XFERINFOFUNCTION on most recent libcurl versions)
when using any of the stream features.
Perform any connection upkeep checks.
Official libcurl documentation: curl_easy_upkeep()
Returns an object with a representation of the current libcurl version and their features/protocols.
This is basically curl_version_info()
Returns a string that looks like the one returned by
curl -VExample:
Version: libcurl/7.69.1-DEV OpenSSL/1.1.1d zlib/1.2.11 WinIDN libssh2/1.9.0_DEV nghttp2/1.40.0
Protocols: dict, file, ftp, ftps, gopher, http, https, imap, imaps, ldap, ldaps, pop3, pop3s, rtsp, scp, sftp, smb, smbs, smtp, smtps, telnet, tftp
Features: AsynchDNS, IDN, IPv6, Largefile, SSPI, Kerberos, SPNEGO, NTLM, SSL, libz, HTTP2, HTTPS-proxyUseful if you want to check if the current libcurl version is greater or equal than another one.
major
minor
patch
Generated using TypeDoc
Wrapper around {@link "Easy".Easy |
Easy} class with a more nodejs-friendly interface.This uses an internal {@link "Multi".Multi |
Multi} instance allowing for asynchronous requests.