EasyNativeBinding | node-libcurl

Easy class that acts as an wrapper around the libcurl connection handle.

C++ source code

It can be used by itself, in a synchronous way:

import { Curl, CurlCode, Easy } from 'node-libcurl'
import { StringDecoder } from 'string_decoder'

const decoder = new StringDecoder('utf8')
const easyHandle = new Easy()

easyHandle.setOpt(Curl.option.URL, 'https://www.google.com')
// This is used to receive the headers
// See https://curl.haxx.se/libcurl/c/CURLOPT_HEADERFUNCTION.html
easyHandle.setOpt(Curl.option.HEADERFUNCTION, function (buf, size, nmemb) {
  console.log('Received some headers:', decoder.write(buf))
  return size * nmemb
})

// This is used to receive the response data
// See https://curl.haxx.se/libcurl/c/CURLOPT_WRITEFUNCTION.html
easyHandle.setOpt(Curl.option.WRITEFUNCTION, function (buf, size, nmemb) {
  console.log('Received some body:', decoder.write(buf))
  return size * nmemb
})

// this will trigger the request
const ret = easyHandle.perform()
// The Easy handle will block the JS main thread:
console.log('I will only show after the request has finished')
// In case there is something wrong, you can use Easy.strError to get a human readable string about the error
console.log(ret, ret === CurlCode.CURLE_OK, Easy.strError(ret))
// Remember to always close the handle after you have finished using it for good
easyHandle.close()

or with the Multi class, allowing asynchronous usage.

Hierarchy

EasyNativeBinding
- Easy

Index

Properties

Methods

Properties

Readonly isInsideMultiHandle

isInsideMultiHandle: boolean

This will be true if the handle was added to a Multi handle.

Readonly isMonitoringSockets

isMonitoringSockets: boolean

This will be true if monitorSocketEvents was called.

Readonly isOpen

isOpen: boolean

This will be true if close was not called.

private

private: any

You can set this to anything - Use it to bind some data to this Easy instance.

This will not be copied to other instaces created when duplicating this one.

Methods

close

close(): void

- Defined in lib/types/EasyNativeBinding.ts:568
Close this handle and dispose any resources bound to it. After closed, the handle MUST not be used again, doing so will throw an Error.

This is basically the same than curl_easy_cleanup()

Returns void

dupHandle

dupHandle(): EasyNativeBinding

- Defined in lib/types/EasyNativeBinding.ts:526
Duplicate this handle with all their options and callbacks.

Official libcurl documentation: curl_easy_duphandle()

Returns EasyNativeBinding

getInfo

getInfo(info: "CERTINFO"): GetInfoReturn<string[]>
getInfo(info: Exclude<CurlInfoName, CurlInfoNameSpecific>): GetInfoReturn

- Defined in lib/types/EasyNativeBinding.ts:459
Official libcurl documentation: curl_easy_getinfo()

Parameters
- info: "CERTINFO"
  
  Info to retrieve. Use {@link "Curl".Curl.info | Curl.info} for predefined constants.
Returns GetInfoReturn<string[]>
- Defined in lib/types/EasyNativeBinding.ts:468
Returns information about the finished connection.

Official libcurl documentation: curl_easy_getinfo()

Parameters
- info: Exclude<CurlInfoName, CurlInfoNameSpecific>
  
  Info to retrieve. Use {@link "Curl".Curl.info | Curl.info} for predefined constants.
Returns GetInfoReturn

monitorSocketEvents

monitorSocketEvents(): this

- Defined in lib/types/EasyNativeBinding.ts:552
Start monitoring for events in the connection socket used by this handle.

This is only useful if using the onSocketEvent callback.

This method will throw an Error if the handle is already monitoring socket events. You can use isMonitoringSockets to check if socket events are already being monitored or not.

Returns this

onSocketEvent

onSocketEvent(cb: ((error: Error | null, events: SocketState) => void) | null): this

- Defined in lib/types/EasyNativeBinding.ts:540
This method is only useful when the internal polling of the connection socket is enabled by calling monitorSocketEvents.

The passed callback is going to be called everytime there are changes to the connection socket.

One use case for this is when using the send and recv methods

A full example is available at examples/15-send-recv-methods.js

Pass null to remove the current callback set.

Parameters
- cb: ((error: Error | null, events: SocketState) => void) | null
Returns this

pause

pause(bitmask: CurlPause): CurlCode

- Defined in lib/types/EasyNativeBinding.ts:510
Using this function, you can explicitly mark a running connection to get paused, and you can unpause a connection that was previously paused.

Use the CurlPause enum for predefined constants.

Official libcurl documentation: curl_easy_pause()

Parameters
- bitmask: CurlPause
Returns CurlCode

perform

perform(): CurlCode

- Defined in lib/types/EasyNativeBinding.ts:493
Performs the entire request in a blocking manner and returns when done.

Official libcurl documentation: curl_easy_perform()

Returns CurlCode

recv

recv(storage: Buffer): { bytesReceived: number; code: CurlCode }

- Defined in lib/types/EasyNativeBinding.ts:486
Receives data over the established connection, data will be written to the passed buffer.

See also onSocketEvent.

Official libcurl documentation: curl_easy_recv()

Parameters
- storage: Buffer
Returns { bytesReceived: number; code: CurlCode }
- bytesReceived: number
- code: CurlCode

reset

reset(): CurlCode

- Defined in lib/types/EasyNativeBinding.ts:519
Reset this handle to their original state.

This method is useful if you plan to reuse this handle later on.

Official libcurl documentation: curl_easy_reset()

Returns CurlCode

send

send(data: Buffer): { bytesSent: number; code: CurlCode }

- Defined in lib/types/EasyNativeBinding.ts:477
Sends arbitrary data over the established connection.

See also onSocketEvent.

Official libcurl documentation: curl_easy_send()

Parameters
- data: Buffer
Returns { bytesSent: number; code: CurlCode }
- bytesSent: number
- code: CurlCode

setOpt

setOpt(option: DataCallbackOptions, value: ((this: EasyNativeBinding, data: Buffer, size: number, nmemb: number) => number) | null): CurlCode
setOpt(option: ProgressCallbackOptions, value: ((this: EasyNativeBinding, dltotal: number, dlnow: number, ultotal: number, ulnow: number) => number | CurlProgressFunc) | null): CurlCode
setOpt(option: StringListOptions, value: string[] | null): CurlCode
setOpt(option: BlobOptions, value: ArrayBuffer | Buffer | string | null): CurlCode
setOpt(option: "CHUNK_BGN_FUNCTION", value: ((this: EasyNativeBinding, fileInfo: FileInfo, remains: number) => CurlChunk) | null): CurlCode
setOpt(option: "CHUNK_END_FUNCTION", value: ((this: EasyNativeBinding) => CurlChunk) | null): CurlCode
setOpt(option: "DEBUGFUNCTION", value: ((this: EasyNativeBinding, type: CurlInfoDebug, data: Buffer) => 0) | null): CurlCode
setOpt(option: "FNMATCH_FUNCTION", value: ((this: EasyNativeBinding, pattern: string, value: string) => CurlFnMatchFunc) | null): CurlCode
setOpt(option: "HSTSREADFUNCTION", value: ((this: EasyNativeBinding) => null | CurlHstsCacheEntry | CurlHstsCacheEntry[]) | null): CurlCode
setOpt(option: "HSTSWRITEFUNCTION", value: ((this: EasyNativeBinding, cacheEntry: CurlHstsCacheEntry, cacheCount: CurlHstsCacheCount) => any) | null): CurlCode
setOpt(option: "PREREQFUNCTION", value: ((this: EasyNativeBinding, connPrimaryIp: string, connLocalIp: string, connPrimaryPort: number, conLocalPort: number) => CurlPreReqFunc) | null): CurlCode
setOpt(option: "SEEKFUNCTION", value: ((this: EasyNativeBinding, offset: number, origin: number) => number) | null): CurlCode
setOpt(option: "TRAILERFUNCTION", value: ((this: EasyNativeBinding) => string[] | false) | null): CurlCode
setOpt(option: "SHARE", value: Share | null): CurlCode
setOpt(option: "HTTPPOST", value: HttpPostField[] | null): CurlCode
setOpt(option: "FTP_SSL_CCC", value: CurlFtpSsl | null): CurlCode
setOpt(option: "FTP_FILEMETHOD", value: CurlFtpMethod | null): CurlCode
setOpt(option: "GSSAPI_DELEGATION", value: CurlGssApi | null): CurlCode
setOpt(option: "HEADEROPT", value: CurlHeader | null): CurlCode
setOpt(option: "HTTP_VERSION", value: CurlHttpVersion | null): CurlCode
setOpt(option: "IPRESOLVE", value: CurlIpResolve | null): CurlCode
setOpt(option: "NETRC", value: CurlNetrc | null): CurlCode
setOpt(option: "PROTOCOLS", value: CurlProtocol | null): CurlCode
setOpt(option: "PROXY_SSL_OPTIONS", value: CurlSslOpt | null): CurlCode
setOpt(option: "PROXYTYPE", value: CurlProxy | null): CurlCode
setOpt(option: "REDIR_PROTOCOLS", value: CurlProtocol | null): CurlCode
setOpt(option: "RTSP_REQUEST", value: CurlRtspRequest | null): CurlCode
setOpt(option: "SSH_AUTH_TYPES", value: CurlSshAuth | null): CurlCode
setOpt(option: "SSL_OPTIONS", value: CurlSslOpt | null): CurlCode
setOpt(option: "SSLVERSION", value: CurlSslVersion | null): CurlCode
setOpt(option: "TIMECONDITION", value: CurlTimeCond | null): CurlCode
setOpt(option: "USE_SSL", value: CurlUseSsl | null): CurlCode
setOpt(option: "HSTS_CTRL", value: CurlHsts | null): CurlCode
setOpt(option: Exclude<CurlOptionName, SpecificOptions>, value: string | number | boolean | null): CurlCode

- Defined in lib/types/EasyNativeBinding.ts:125
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: DataCallbackOptions
- value: ((this: EasyNativeBinding, data: Buffer, size: number, nmemb: number) => number) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:142
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: ProgressCallbackOptions
- value: ((this: EasyNativeBinding, dltotal: number, dlnow: number, ultotal: number, ulnow: number) => number | CurlProgressFunc) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:160
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: StringListOptions
- value: string[] | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:167
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: BlobOptions
- value: ArrayBuffer | Buffer | string | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:177
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "CHUNK_BGN_FUNCTION"
- value: ((this: EasyNativeBinding, fileInfo: FileInfo, remains: number) => CurlChunk) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:193
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "CHUNK_END_FUNCTION"
- value: ((this: EasyNativeBinding) => CurlChunk) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:203
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "DEBUGFUNCTION"
- value: ((this: EasyNativeBinding, type: CurlInfoDebug, data: Buffer) => 0) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:215
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "FNMATCH_FUNCTION"
- value: ((this: EasyNativeBinding, pattern: string, value: string) => CurlFnMatchFunc) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:235
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()

Parameters
- option: "HSTSREADFUNCTION"
- value: ((this: EasyNativeBinding) => null | CurlHstsCacheEntry | CurlHstsCacheEntry[]) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:249
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "HSTSWRITEFUNCTION"
- value: ((this: EasyNativeBinding, cacheEntry: CurlHstsCacheEntry, cacheCount: CurlHstsCacheCount) => any) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:265
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "PREREQFUNCTION"
- value: ((this: EasyNativeBinding, connPrimaryIp: string, connLocalIp: string, connPrimaryPort: number, conLocalPort: number) => CurlPreReqFunc) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:283
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "SEEKFUNCTION"
- value: ((this: EasyNativeBinding, offset: number, origin: number) => number) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:295
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "TRAILERFUNCTION"
- value: ((this: EasyNativeBinding) => string[] | false) | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:305
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "SHARE"
- value: Share | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:312
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "HTTPPOST"
- value: HttpPostField[] | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:319
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "FTP_SSL_CCC"
- value: CurlFtpSsl | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:326
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "FTP_FILEMETHOD"
- value: CurlFtpMethod | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:333
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "GSSAPI_DELEGATION"
- value: CurlGssApi | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:340
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "HEADEROPT"
- value: CurlHeader | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:347
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "HTTP_VERSION"
- value: CurlHttpVersion | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:354
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "IPRESOLVE"
- value: CurlIpResolve | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:361
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "NETRC"
- value: CurlNetrc | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:368
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "PROTOCOLS"
- value: CurlProtocol | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:375
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "PROXY_SSL_OPTIONS"
- value: CurlSslOpt | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:382
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "PROXYTYPE"
- value: CurlProxy | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:389
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "REDIR_PROTOCOLS"
- value: CurlProtocol | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:396
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "RTSP_REQUEST"
- value: CurlRtspRequest | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:403
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "SSH_AUTH_TYPES"
- value: CurlSshAuth | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:410
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "SSL_OPTIONS"
- value: CurlSslOpt | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:417
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "SSLVERSION"
- value: CurlSslVersion | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:424
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "TIMECONDITION"
- value: CurlTimeCond | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:431
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "USE_SSL"
- value: CurlUseSsl | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:438
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: "HSTS_CTRL"
- value: CurlHsts | null
Returns CurlCode
- Defined in lib/types/EasyNativeBinding.ts:445
Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

Official libcurl documentation: curl_easy_setopt()

Parameters
- option: Exclude<CurlOptionName, SpecificOptions>
- value: string | number | boolean | null
Returns CurlCode

unmonitorSocketEvents

unmonitorSocketEvents(): this

- Defined in lib/types/EasyNativeBinding.ts:560
Stop monitoring for events in the connection socket used by this handle.

This method will throw an Error if the handle is not monitoring socket events. You can use isMonitoringSockets to check if socket events are already being monitored or not.

Returns this

upkeep

upkeep(): CurlCode

- Defined in lib/types/EasyNativeBinding.ts:500
Perform any connection upkeep checks.

Official libcurl documentation: curl_easy_upkeep()

Returns CurlCode

Static strError

strError(errorCode: CurlCode): string

- Defined in lib/types/EasyNativeBinding.ts:578
Returns a description for the given error code.

Official libcurl documentation: curl_easy_strerror()

Parameters
- errorCode: CurlCode
Returns string

Hierarchy

Index

Properties

Methods

Properties

Readonly isInsideMultiHandle

Readonly isMonitoringSockets

Readonly isOpen

private

Methods

close

Returns void

dupHandle

Returns EasyNativeBinding

getInfo

Parameters

info: "CERTINFO"

Returns GetInfoReturn<string[]>

Parameters

info: Exclude<CurlInfoName, CurlInfoNameSpecific>

Returns GetInfoReturn

monitorSocketEvents

Returns this

onSocketEvent

Parameters

cb: ((error: Error | null, events: SocketState) => void) | null

Returns this

pause

Parameters

bitmask: CurlPause

Returns CurlCode

perform

Returns CurlCode

recv

Parameters

storage: Buffer

Returns { bytesReceived: number; code: CurlCode }

bytesReceived: number

code: CurlCode

reset

Returns CurlCode

send

Parameters

data: Buffer

Returns { bytesSent: number; code: CurlCode }

bytesSent: number

code: CurlCode

setOpt

Parameters

option: DataCallbackOptions

value: ((this: EasyNativeBinding, data: Buffer, size: number, nmemb: number) => number) | null

Returns CurlCode

Parameters

option: ProgressCallbackOptions

value: ((this: EasyNativeBinding, dltotal: number, dlnow: number, ultotal: number, ulnow: number) => number | CurlProgressFunc) | null

Returns CurlCode

Parameters

option: StringListOptions

value: string[] | null

Returns CurlCode

Parameters

option: BlobOptions

value: ArrayBuffer | Buffer | string | null

Returns CurlCode

Parameters

option: "CHUNK_BGN_FUNCTION"

value: ((this: EasyNativeBinding, fileInfo: FileInfo, remains: number) => CurlChunk) | null

Returns CurlCode

Parameters

option: "CHUNK_END_FUNCTION"

value: ((this: EasyNativeBinding) => CurlChunk) | null

Returns CurlCode

Parameters

option: "DEBUGFUNCTION"

value: ((this: EasyNativeBinding, type: CurlInfoDebug, data: Buffer) => 0) | null

Returns CurlCode

Parameters

option: "FNMATCH_FUNCTION"

value: ((this: EasyNativeBinding, pattern: string, value: string) => CurlFnMatchFunc) | null

Returns CurlCode