Options
All
  • Public
  • Public/Protected
  • All
Menu

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

Index

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
  • 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

getInfo

  • 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[]>

  • Returns information about the finished connection.

    Official libcurl documentation: curl_easy_getinfo()

    Parameters

    Returns GetInfoReturn

monitorSocketEvents

  • monitorSocketEvents(): this
  • 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
  • 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

  • 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

    Returns CurlCode

perform

  • 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 }
  • 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 }

reset

  • 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 }
  • Sends arbitrary data over the established connection.

    See also onSocketEvent.

    Official libcurl documentation: curl_easy_send()

    Parameters

    • data: Buffer

    Returns { bytesSent: number; code: CurlCode }

setOpt

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • 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

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • 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

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • 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

  • 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

  • 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

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    • option: "SHARE"
    • value: Share | null

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • 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

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • 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

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    • option: "PROXYTYPE"
    • value: CurlProxy | null

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

  • 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

  • Use {@link "Curl".Curl.option|Curl.option} for predefined constants.

    Official libcurl documentation: curl_easy_setopt()

    Parameters

    Returns CurlCode

unmonitorSocketEvents

  • unmonitorSocketEvents(): this
  • 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

  • Perform any connection upkeep checks.

    Official libcurl documentation: curl_easy_upkeep()

    Returns CurlCode

Static strError

  • Returns a description for the given error code.

    Official libcurl documentation: curl_easy_strerror()

    Parameters

    Returns string

Generated using TypeDoc