Options
All
  • Public
  • Public/Protected
  • All
Menu

Class Curl

Wrapper around Easy class with a more nodejs-friendly interface.

This uses an internal Multi instance to asynchronous fire the requests.

Hierarchy

  • EventEmitter
    • Curl

Index

Constructors

constructor

Properties

Protected chunks

chunks: Buffer[]

Stores current response payload.

This will not store anything in case NoDataStorage flag is enabled

Protected chunksLength

chunksLength: number

Current response length.

Will always be zero in case NoDataStorage flag is enabled

Protected features

features: CurlFeature

Currently enabled features.

See enable and disable

Protected handle

Internal Easy handle being used

Protected headerChunks

headerChunks: Buffer[]

Stores current headers payload.

This will not store anything in case NoDataStorage flag is enabled

Protected headerChunksLength

headerChunksLength: number

Current headers length.

Will always be zero in case NoDataStorage flag is enabled

Protected isRunning

isRunning: boolean

Whether this instance is running or not (perform() was called).

Make sure to not change their value, otherwise unexpected behavior would happen.

Static VERSION_NUM

VERSION_NUM: number = _Curl.VERSION_NUM

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

Static defaultMaxListeners

defaultMaxListeners: number

Static defaultUserAgent

defaultUserAgent: string = `node-libcurl/${pkg.version}`

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.

Static getCount

getCount: getCount = multiHandle.getCount

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

Static getVersion

getVersion: getVersion = _Curl.getVersion

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.0

Static globalCleanup

globalCleanup: globalCleanup = _Curl.globalCleanup

This is automatically called when the process is exiting.

Static globalInit

globalInit: globalInit = _Curl.globalInit

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

Static info

info: CurlInfo = _Curl.info

This is a object with members resembling the CURLINFO_* libcurl constants.

It can 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

Static option

option: CurlOption = _Curl.option

This is a object with members resembling the CURLOPT_* libcurl constants.

It can be used with Easy#setOpt or Curl#setOpt.

See the official documentation of curl_easy_setopt() for reference.

CURLOPT_URL becomes Curl.option.URL

Methods

addListener

  • addListener(event: string | symbol, listener: (...args: any[]) => void): this
  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

close

  • close(): void
  • 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()

    Returns void

Protected defaultHeaderFunction

  • defaultHeaderFunction(chunk: Buffer, size: number, nmemb: number): number

Protected defaultWriteFunction

  • defaultWriteFunction(chunk: Buffer, size: number, nmemb: number): number

disable

dupHandle

  • dupHandle(shouldCopyEventListeners?: boolean): Curl
  • 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()

    Parameters

    • Default value shouldCopyEventListeners: boolean = true

      If you don't want to copy the event listeners, set this to false.

    Returns Curl

emit

  • emit(event: string | symbol, ...args: any[]): boolean
  • Parameters

    • event: string | symbol
    • Rest ...args: any[]

    Returns boolean

enable

eventNames

  • eventNames(): Array<string | symbol>
  • Returns Array<string | symbol>

getInfo

  • getInfo(infoNameOrId: CurlInfoName): null | string | number
  • Retrieves some information about the last request made by a handle.

    Official libcurl documentation: curl_easy_getinfo()

    Parameters

    Returns null | string | number

getMaxListeners

  • getMaxListeners(): number
  • Returns number

listenerCount

  • listenerCount(type: string | symbol): number
  • Parameters

    • type: string | symbol

    Returns number

listeners

  • listeners(event: string | symbol): Function[]
  • Parameters

    • event: string | symbol

    Returns Function[]

off

  • off(event: string | symbol, listener: (...args: any[]) => void): this
  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

on

  • on(event: string | symbol, listener: (...args: any[]) => void): this
  • on(event: "data", listener: (this: Curl, chunk: Buffer, curlInstance: Curl) => void): this
  • on(event: "header", listener: (this: Curl, chunk: Buffer, curlInstance: Curl) => void): this
  • on(event: "error", listener: (this: Curl, error: Error, errorCode: CurlCode, curlInstance: Curl) => void): this
  • on(event: "end", listener: (this: Curl, status: number, data: string | Buffer, headers: Buffer | HeaderInfo[], curlInstance: Curl) => void): this
  • on(event: string, listener: Function): this
  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

  • Parameters

    • event: "data"
    • listener: (this: Curl, chunk: Buffer, curlInstance: Curl) => void
        • (this: Curl, chunk: Buffer, curlInstance: Curl): void
        • Parameters

          • this: Curl
          • chunk: Buffer
          • curlInstance: Curl

          Returns void

    Returns this

  • Parameters

    • event: "header"
    • listener: (this: Curl, chunk: Buffer, curlInstance: Curl) => void
        • (this: Curl, chunk: Buffer, curlInstance: Curl): void
        • Parameters

          • this: Curl
          • chunk: Buffer
          • curlInstance: Curl

          Returns void

    Returns this

  • Parameters

    • event: "error"
    • listener: (this: Curl, error: Error, errorCode: CurlCode, curlInstance: Curl) => void
        • Parameters

          Returns void

    Returns this

  • Parameters

    • event: "end"
    • listener: (this: Curl, status: number, data: string | Buffer, headers: Buffer | HeaderInfo[], curlInstance: Curl) => void
        • (this: Curl, status: number, data: string | Buffer, headers: Buffer | HeaderInfo[], curlInstance: Curl): void
        • Parameters

          • this: Curl
          • status: number
          • data: string | Buffer
          • headers: Buffer | HeaderInfo[]
          • curlInstance: Curl

          Returns void

    Returns this

  • Parameters

    • event: string
    • listener: Function

    Returns this

onEnd

  • onEnd(): void
  • Callback called when this handle has finished the request.

    This is called from the internal callback we use with the onMessage method of the global Multi handle used by all Curl instances.

    Returns void

onError

  • onError(error: Error, errorCode: CurlCode): void
  • Callback called when an error is thrown on this handle.

    This is called from the internal callback we use with the onMessage method of the global Multi handle used by all Curl instances.

    Parameters

    Returns void

once

  • once(event: string | symbol, listener: (...args: any[]) => void): this
  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

pause

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

    Parameters

    Returns this

perform

  • perform(): this
  • Add this instance to the processing queue. This method should be called only one time per request, otherwise it will throw an error.

    remarks

    This basically calls the Multi#addHandle method.

    Returns this

prependListener

  • prependListener(event: string | symbol, listener: (...args: any[]) => void): this
  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

prependOnceListener

  • prependOnceListener(event: string | symbol, listener: (...args: any[]) => void): this
  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

rawListeners

  • rawListeners(event: string | symbol): Function[]
  • Parameters

    • event: string | symbol

    Returns Function[]

removeAllListeners

  • removeAllListeners(event?: string | symbol): this
  • Parameters

    • Optional event: string | symbol

    Returns this

removeListener

  • removeListener(event: string | symbol, listener: (...args: any[]) => void): this
  • Parameters

    • event: string | symbol
    • listener: (...args: any[]) => void
        • (...args: any[]): void
        • Parameters

          • Rest ...args: any[]

          Returns void

    Returns this

reset

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

    Returns this

setMaxListeners

  • setMaxListeners(n: number): this
  • Parameters

    • n: number

    Returns this

setOpt

  • setOpt(optionIdOrName: never, optionValue: never): this
  • setOpt(option: DataCallbackOptions, value: ((data: Buffer, size: number, nmemb: number) => number) | null): this
  • setOpt(option: ProgressCallbackOptions, value: ((dltotal: number, dlnow: number, ultotal: number, ulnow: number) => number | CurlProgressFunc) | null): this
  • setOpt(option: StringListOptions, value: string[] | null): this
  • setOpt(option: "CHUNK_BGN_FUNCTION", value: ((fileInfo: FileInfo, remains: number) => number) | null): this
  • setOpt(option: "CHUNK_END_FUNCTION", value: (() => number) | null): this
  • setOpt(option: "DEBUGFUNCTION", value: ((type: number, data: Buffer) => 0) | null): this
  • setOpt(option: "FNMATCH_FUNCTION", value: ((pattern: string, value: string) => number) | null): this
  • setOpt(option: "SEEKFUNCTION", value: ((offset: number, origin: number) => number) | null): this
  • setOpt(option: "TRAILERFUNCTION", value: (() => string[] | false) | null): this
  • setOpt(option: "SHARE", value: Share | null): this
  • setOpt(option: "HTTPPOST", value: HttpPostField[] | null): this
  • setOpt(option: "GSSAPI_DELEGATION", value: CurlGssApi | null): this
  • setOpt(option: "PROXY_SSL_OPTIONS", value: CurlSslOpt | null): this
  • setOpt(option: "SSL_OPTIONS", value: CurlSslOpt | null): this
  • setOpt(option: Exclude<CurlOptionName, SpecificOptions>, value: string | number | boolean | null): this

setProgressCallback

  • setProgressCallback(cb: ((dltotal: number, dlnow: number, ultotal: number, ulnow: number) => number) | null): this
  • 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.

    Parameters

    • cb: ((dltotal: number, dlnow: number, ultotal: number, ulnow: number) => number) | null

    Returns this

upkeep

  • upkeep(): this

Static getVersionInfo

Static getVersionInfoString

  • getVersionInfoString(): string
  • Returns a string that looks like the one returned by

    curl -V

    Example:

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

    Returns string

Static isVersionGreaterOrEqualThan

  • isVersionGreaterOrEqualThan(x: number, y: number, z?: number): boolean
  • Useful if you want to check if the current libcurl version is greater or equal than another one.

    Parameters

    • x: number

      major

    • y: number

      minor

    • Default value z: number = 0

      patch

    Returns boolean

Static listenerCount

  • listenerCount(emitter: EventEmitter, event: string | symbol): number
  • deprecated

    since v4.0.0

    Parameters

    • emitter: EventEmitter
    • event: string | symbol

    Returns number

Generated using TypeDoc