Platforms to show: All Mac Windows Linux Cross-Platform

Back to CURLNMBS class.

Previous items

CURLNMBS.OptionUpkeepIntervalMS as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 18.5 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Connection upkeep interval.

Some protocols have "connection upkeep" mechanisms. These mechanisms usually send some traffic on existing connections in order to keep them alive; this can prevent connections from being closed due to overzealous firewalls, for example.

The user needs to explicitly call Upkeep in order to perform the upkeep work.

Currently the only protocol with a connection upkeep mechanism is HTTP/2: when the connection upkeep interval is exceeded and Upkeep is called, an HTTP/2 PING frame is sent on the connection.
(Read and Write property)

See also UPKEEP_INTERVAL_MS option in CURL manual.

CURLNMBS.OptionUpload as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 9.8 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
True tells the library to prepare for an upload.

The OptionInFileSize or OptionInFileSizeLarge options are also interesting for uploads. If the protocol is HTTP, uploading means using the PUT request unless you tell libCURL otherwise.

Using PUT with HTTP 1.1 implies the use of a "Expect: 100-continue" header. You can disable this header with OptionHTTPHeader as usual.

If you use PUT to a HTTP 1.1 server, you can upload data without knowing the size before starting the transfer if you use chunked encoding. You enable this by adding a header like "Transfer-Encoding: chunked" with OptionHTTPHeader. With HTTP 1.0 or without chunked transfer, you must specify the size.

The Lasterror property is set. 0 for success.
You can set this value and later you can read it, but you cannot read the default value.
(Read and Write property)

See also UPLOAD option in CURL manual.

CURLNMBS.OptionUploadBufferSize as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 18.5 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Set preferred upload buffer size.

Pass a long specifying your preferred size (in bytes) for the upload buffer in libcurl. It makes libcurl uses a larger buffer that gets passed to the next layer in the stack to get sent off. In some setups and for some protocols, there's a huge performance benefit of having a larger upload buffer.

This is just treated as a request, not an order. You cannot be guaranteed to actually get the given size.

The upload buffer size is by default 64 kilobytes. The maximum buffer size allowed to be set is 2 megabytes. The minimum buffer size allowed to be set is 16 kilobytes.

Since curl 7.61.1 the upload buffer is allocated on-demand - so if the handle isn't used for upload, this buffer will not be allocated at all.

For slow upload/downloads, it may be better to set buffer size to 1 MB with OptionUploadBufferSize or OptionBufferSize properties to make transfers faster.
(Read and Write property)

See also UPLOAD_BUFFERSIZE option in CURL manual.

CURLNMBS.OptionURL as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 9.8 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
The actual URL to deal with.
Example

Dim c As New CURLNMBS

// this example sends a xml request to a server
c.OptionURL = "http://www.someserver.com/service"

// some XML for a SOAP request
Dim request As String = "<?xml version=""1.0""?><methodCall><methodName>application.getValue</methodName><params><param><value>info</value></param></params></methodCall>"

c.OptionPostFields = request

Dim header(-1) As String
header.Append "Content-Type: text/xml"
c.SetOptionHTTPHeader header

// this should be c.kError_OK if okay.
Dim result As Integer = c.Perform

Dim output As String = c.OutputData
Dim debugLog As String = c.DebugMessages
Dim HTTPStatus As Integer = c.GetInfoResponseCode

Break

If you need to pass username or password, please consider using the OptionUsername and OptionPassword properties. If you username or password contains characters like @ or :, you must use those properties.

The Lasterror property is set. 0 for success.
You can set this value and later you can read it, but you cannot read the default value.

The parameter should be a char * to a zero terminated string. The string must remain present until CURL no longer needs it, as it doesn't copy the string.

If the given URL lacks the protocol part ("http://" or "ftp://" etc), it will attempt to guess which protocol to use based on the given host name. If the given protocol of the set URL is not supported, libCURL will return on error (kError_UNSUPPORTED_PROTOCOL) when you call Perform. Use VersionInfo for detailed info on which protocols that are supported.

The string given to CURLOPT_URL must be url-encoded and following the RFC 2396:
http://CURL.haxx.se/rfc/rfc2396.txt

CURLOPT_URL is the only option that must be set before Perform is called.
For file uploads or downloads, please include the file name in the URL.

Please do never include username and passwords in URLs, as those get often written to log files and would reveal your credentials!
Instead use OptionUsername and OptionPassword.

If you miss the protocol in the URL, you may get an error about HTTP/0.9 being used and not allowed.
(Read and Write property)

See also URL option in CURL manual.

CURLNMBS.OptionUserAgent as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 9.8 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
The user agent string to pass to the server.
Example

Dim c As New CURLNMBS

// setup request and any options you need
c.OptionURL = URL
c.OptionUserAgent = "MyDownloader 1.0"

It will be used to set the User-Agent: header in the http request sent to the remote server. This can be used to fool servers or scripts. You can also set any custom header with OptionHTTPHeader.

The Lasterror property is set. 0 for success.
You can set this value and later you can read it, but you cannot read the default value.
(Read and Write property)

See also USERAGENT option in CURL manual.

CURLNMBS.OptionUsername as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 10.0 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
The user name to be used in protocol authentication

In order to specify the password to be used in conjunction with the user name use the OptionPassword option
(Read and Write property)

See also USERNAME option in CURL manual.

CURLNMBS.OptionUseSSL as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 15.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Request using SSL / TLS for the transfer.
Example
dim c as CURLNMBS
c.OptionUseSSL = c.kFTPSSL_ALL
c.OptionSSLVersion = c.kSSLVersionTLSv12

Set to an integer using one of the values from below, to make libCURL use your desired level of SSL for the transfer.
These are all protocols that start out plain text and get "upgraded" to SSL using the STARTTLS command.
This is for enabling SSL/TLS when you use FTP, SMTP, POP3, IMAP etc.

CURLUSESSL_NONE0Don't attempt to use SSL.
CURLUSESSL_TRY1Try using SSL, proceed as normal otherwise.
CURLUSESSL_CONTROL2Require SSL for the control connection or fail with CURLE_USE_SSL_FAILED.
CURLUSESSL_ALL3Require SSL for all communication or fail with CURLE_USE_SSL_FAILED.
(Read and Write property)

See also USE_SSL option in CURL manual.

CURLNMBS.OptionVerbose as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 9.8 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Whether debug messages are sent to the DebugMessage event.

Default is false.
You need to subclass the CURLNMBS class to add code in the DebugMessage event.
Or you set CollectDebugMessages = true and later query DebugMessages property.
Or you use CreateMTDebugOutputFile to stream them to a file.
(Read and Write property)

See also VERBOSE option in CURL manual.

CURLNMBS.OptionWildCardMatch as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 15.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Enable wildcard matching.

Set onoff to true if you want to transfer multiple files according to a file name pattern. The pattern can be specified as part of the OptionURL option, using an fnmatch-like pattern (Shell Pattern Matching) in the last part of URL (file name).

By default, libCURL uses its internal wildcard matching implementation. You can provide your own matching function by the CURLNMBS.FileNameMatch event.

A brief introduction of its syntax follows:

  • - ASTERISK

ftp://example.com/some/path/*.txt (for all txt's from the root directory)

? - QUESTION MARK

Question mark matches any (exactly one) character.

ftp://example.com/some/path/photo?.jpeg

[ - BRACKET EXPRESSION

The left bracket opens a bracket expression. The question mark and asterisk have no special meaning in a bracket expression. Each bracket expression ends by the right bracket and matches exactly one character. Some examples follow:

[a-zA-Z0-9] or [f-gF-G] - character interval
[abc] - character enumeration
[^abc] or [!abc] - negation
[[:name:]] class expression. Supported classes are alnum,lower, space, alpha, digit, print, upper, blank, graph, xdigit.
[][-!^] - special case - matches only '-', ']', '[', '!' or '^'. These characters have no special purpose.
[\[\]\\] - escape syntax. Matches '[', ']' or '´.

Using the rules above, a file name pattern can be constructed:

ftp://example.com/some/path/[a-z[:upper:]\\].jpeg

This feature is only supported for FTP download. Not for SFTP or HTTP.
(Read and Write property)

See also WILDCARDMATCH option in CURL manual.

CURLNMBS.OptionXOAuth2Bearer as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 18.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
The XOAUTH2 bearer token.

(Read and Write property)

See also XOAUTH2_BEARER option in CURL manual.

CURLNMBS.OutputData as String

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 12.3 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
The output data from CURL.
Example

Dim d As New CURLNMBS

// download here
d.OptionURL = URL

// if you use SSL, maybe put in a certificate or disable verification?
d.OptionSSLVerifyHost = 0
d.OptionSSLVerifyPeer = 0

// run download
dim e as integer = d.Perform

// check result
Dim data As String = d.OutputData
Dim DebugMessage As String = d.DebugMessages // check in debugger on error

ResultText.text="Result: "+str(e) // 0 = Okay, others are error codes, so check debug messsages

If CollectOutputData property is true, the plugin puts the data received in write event also into this property, so you can grab it after the transfer. Use ClearData method to clear when reusing CURL object.

Limited to 2 GB. Please stream to file for bigger data with CreateMTOutputFile function.
(Read only property)

CURLNMBS.Paused as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 18.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Whether transfer is paused.

You can set it to true while transfer runs to pause it.
(Read and Write property)

CURLNMBS.ProgressDownloadCurrent as Int64

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 15.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Bytes downloaded so far.

(Read only property)

CURLNMBS.ProgressDownloadTotal as Int64

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 15.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Bytes to download in total.

(Read only property)

CURLNMBS.ProgressPercent as Double

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 15.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Current download/upload progress in percent.

Range from 0 to 100.
(Read only property)

CURLNMBS.ProgressUploadCurrent as Int64

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 15.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Bytes uploaded so far.

(Read only property)

CURLNMBS.ProgressUploadTotal as Int64

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 15.2 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Bytes to upload in total.

(Read only property)

CURLNMBS.Tag as Variant

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 23.3 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
The tag value.

You can store whatever reference value you need.
(Read and Write property)

CURLNMBS.WebSocketOptions as Integer

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 23.0 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
WebSocket behavior options.

Pass a bitmask to tell libcurl about specific WebSocket behaviors.

To detach a WebSocket connection and use the WebSocketSend and WebSocketReceive functions after the HTTP upgrade procedure, set the OptionConnectOnly option to 2.

Available bits in the bitmask:

kWebSocketRaw:
Deliver "raw" WebSocket traffic to the Write event.

In raw mode, libcurl does not handle pings or any other frame for the application.
(Read and Write property)

CURLNMBS.YieldTime as Boolean

Type Topic Plugin Version macOS Windows Linux iOS Targets
property CURL MBS CURL Plugin 9.8 ✅ Yes ✅ Yes ✅ Yes ❌ No Desktop, Console & Web
Whether plugin should yield time.
Example
dim curl as new CURLNMBS

curl.YieldTime = true

If set the plugin will yield time to Xojo back so threads and timers work while you download.

Seems like in RB 2009 this property only has effect if you run CURL in a thread.
(Read and Write property)

Previous items

The items on this page are in the following plugins: MBS CURL Plugin.


💬 Ask a question or report a problem
The biggest plugin in space...