CURLMBS.AddMimePart as CURLMimePartMBS

Returns mime object, so you can set properties.

CURLMBS.OpenMTInputFile(file as folderitem, Offset as Integer = 0) as boolean

Var c As New CURLMBS
Var file As FolderItem = SpecialFolder.Desktop.Child("test.rtf")

If c.OpenMTInputFile(file) Then
  // okay
Else
  MessageBox "Failed to open file to upload."
  Return
End If

// do a SFTP upload
c.OptionURL = "sftp://monkeybreadsoftware.de/folder/test.rtf"
c.OptionUpload = True
c.OptionUsername = "test"
c.OptionPassword = "test"
c.CollectOutputData = false

Var e As Integer = c.Perform

Var ErrorMessage As String = c.LasterrorMessage
Var ErrorLog As String = c.DebugMessages
Var ResultData As String = c.OutputData

Break

The read event is not called with PerformMT.
Offset is helpful for HTTP PUT requests with range, so you can start with an offset.
With 15.2 version of plugin, this also works with Perform.

Must be called before Perform or PerformMT, so we can stream data from the file.
The file is closed automatically when Perform methods finish their work.

The function returns false in case of an error, e.g. if file is already open by another application, the foleritem/path is invalid, the offset is negative or we can't determinate the file size.
It may be wise to have a fallback in your code to use a binarystream in that case (if that one can read the file) and then read all the data in a string and put into the InputData property.

See also:

• OpenMTInputFile(Path as String, Offset as Integer = 0) as boolean

CURLMBS.OpenMTInputFile(Path as String, Offset as Integer = 0) as boolean

The read event is not called with PerformMT.
Offset is helpful for HTTP PUT requests with range, so you can start with an offset.

Must be called before Perform or PerformMT, so we can stream data from the file.
The file is closed automatically when Perform methods finish their work.

The function returns false in case of an error, e.g. if file is already open by another application, the foleritem/path is invalid, the offset is negative or we can't determinate the file size.
It may be wise to have a fallback in your code to use a binarystream in that case (if that one can read the file) and then read all the data in a string and put into the InputData property.

See also:

• OpenMTInputFile(file as folderitem, Offset as Integer = 0) as boolean

CURLMBS.Perform as Integer

// if you get a curl call like this

'curl -X PATCH "https://api.airtable.com/v0/{baseId}/{tableIdOrName}/{recordId}" \
'-H "Authorization: Bearer YOUR_TOKEN" \
'-H "Content-Type: application/json" \
'--data '{
'"fields": {
'"Address": "1 Ferry Building",
'"Name": "Ferry Building",
'"Visited": True
'}
'}'

// you translate it to this:

Var c As New CURLMBS

Var Payload As String = _
  "{"+_
  """fields"": {"+_
  """Address"": ""1 Ferry Building"","+_
  """Name"": ""Ferry Building"","+_
  """Visited"": True"+_
  "}"+_
  "}"

c.OptionCustomRequest = "PATCH"
c.OptionURL = "https://api.airtable.com/v0/{baseId}/{tableIdOrName}/{recordId}"
c.SetOptionHTTPHeader Array("Content-Type: application/json", "Authorization: Bearer YOUR_TOKEN")
c.OptionPostFields = Payload

Var Error As Integer = c.Perform
Var ResponseCode As Integer = c.GetInfoResponseCode
Var DebugLog As String = c.DebugMessages
Var Output As String = c.OutputData

Break

This function is called after all the options are set, and will perform the transfer as described in the options.

You can do any amount of calls to Perform. If you intend to transfer more than one file, you are even encouraged to do so. libCURL will then attempt to re-use the same connection for the following transfers, thus making the operations faster, less CPU intense and using less network resources. Just note that you will have to use the option properties between the invokes to set options for the following Perform.

Typical error codes are 6 for a wrong domain name in the URL, 67 for wrong name/password combination, 60 for missing SSL settings, 1 for an unsupported protocol.

Possible values for the retun value:

const kError_FunctionMissing	= -1
const kError_OK	= 0
const kError_UNSUPPORTED_PROTOCOL	= 1
const kError_FAILED_INIT	= 2
const kError_URL_MALFORMAT	= 3
const kError_URL_MALFORMAT_USER	= 4	(NOT USED)
const kError_COULDNT_RESOLVE_PROXY	= 5
const kError_COULDNT_RESOLVE_HOST	= 6
const kError_COULDNT_CONNECT	= 7
const kError_FTP_WEIRD_SERVER_REPLY	= 8
const kError_FTP_ACCESS_DENIED	= 9	a service was denied by the FTP server due to lack of access when login fails this is not returned.
const kError_FTP_USER_PASSWORD_INCORRECT	= 10
const kError_FTP_WEIRD_PASS_REPLY	= 11
const kError_FTP_WEIRD_USER_REPLY	= 12
const kError_FTP_WEIRD_PASV_REPLY	= 13
const kError_FTP_WEIRD_227_FORMAT	= 14
const kError_FTP_CANT_GET_HOST	= 15
const kError_FTP_CANT_RECONNECT	= 16
const kError_FTP_COULDNT_SET_BINARY	= 17
const kError_PARTIAL_FILE	= 18
const kError_FTP_COULDNT_RETR_FILE	= 19
const kError_FTP_WRITE_ERROR	= 20
const kError_FTP_QUOTE_ERROR	= 21
const kError_HTTP_RETURNED_ERROR	= 22
const kError_WRITE_ERROR	= 23
const kError_MALFORMAT_USER	= 24	NOT USED
const kError_FTP_COULDNT_STOR_FILE	= 25	failed FTP upload
const kError_READ_ERROR	= 26	could open/read from file
const kError_OUT_OF_MEMORY	= 27
const kError_OPERATION_TIMEOUTED	= 28	the timeout time was reached
const kError_FTP_COULDNT_SET_ASCII	= 29	TYPE A failed
const kError_FTP_PORT_FAILED	= 30	FTP PORT operation failed
const kError_FTP_COULDNT_USE_REST	= 31	the REST command failed
const kError_FTP_COULDNT_GET_SIZE	= 32	the SIZE command failed
const kError_HTTP_RANGE_ERROR	= 33	RANGE "command" didn't work
const kError_SSL_CONNECT_ERROR	= 35	wrong when connecting with SSL
const kError_BAD_DOWNLOAD_RESUME	= 36	couldn't resume download
const kError_FILE_COULDNT_READ_FILE	= 37
const kError_LDAP_CANNOT_BIND	= 38
const kError_LDAP_SEARCH_FAILED	= 39
const kError_LIBRARY_NOT_FOUND	= 40
const kError_ABORTED_BY_CALLBACK	= 42
const kError_BAD_FUNCTION_ARGUMENT	= 43
const kError_BAD_CALLING_ORDER	= 44	NOT USED
const kError_INTERFACE_FAILED	= 45	CURLOPT_INTERFACE failed
const kError_BAD_PASSWORD_ENTERED	= 46	NOT USED
const kError_TOO_MANY_REDIRECTS	= 47	catch endless re-direct loops
const kError_UNKNOWN_TELNET_OPTION	= 48	User specified an unknown option
const kError_TELNET_OPTION_SYNTAX	= 49	Malformed telnet option
const kError_OBSOLETE	= 50	NOT USED
const kError_SSL_PEER_CERTIFICATE	= 51	peer's certificate wasn't ok
const kError_GOT_NOTHING	= 52	when this is a specific error
const kError_SSL_ENGINE_NOTFOUND	= 53	SSL crypto engine not found
const kError_SSL_ENGINE_SETFAILED	= 54	can not set SSL crypto engine as default
const kError_SEND_ERROR	= 55	failed sending network data
const kError_RECV_ERROR	= 56	failure in receiving network data
const kError_SHARE_IN_USE	= 57	share is in use
const kError_SSL_CERTPROBLEM	= 58	problem with the local certificate
const kError_SSL_CIPHER	= 59	couldn't use specified cipher
const kError_SSL_CACERT	= 60	problem with the CA cert (path?)
const kError_BAD_CONTENT_ENCODING	= 61	Unrecognized transfer encoding
const kError_LDAP_INVALID_URL	= 62	Invalid LDAP URL
const kError_FILESIZE_EXCEEDED	= 63	Maximum file size exceeded
const kError_FTP_SSL_FAILED	= 64	Requested FTP SSL level failed
const kError_SEND_FAIL_REWIND	= 65	Sending the data requires a rewind that failed
const kError_SSL_ENGINE_INITFAILED	= 66	failed to initialise ENGINE
const kError_LOGIN_DENIED	= 67	user, password or similar was not accepted and we failed to login

The error value -1 is used from the plugin to report that something is missing like OpenSSL dlls on Windows.

With SFTP, you can get logged error "Upload failed: Operation failed (4/-31)" when upload uses path to folder instead of file in URL.

CURLMBS.PerformMT as Integer

Var c As New CURLMBS
Var file As FolderItem = SpecialFolder.Desktop.Child("test.rtf")

If c.OpenMTInputFile(file) Then
  // okay
Else
  MessageBox "Failed to open file to upload."
  Return
End If

// do a SFTP upload
c.OptionURL = "sftp://monkeybreadsoftware.de/folder/test.rtf"
c.OptionUpload = True
c.OptionUsername = "test"
c.OptionPassword = "test"

Var e As Integer = c.PerformMT

Var ErrorMessage As String = c.LasterrorMessage
Var ErrorLog As String = c.DebugMessages
Var ResultData As String = c.OutputData

Break

Same as Perform, but with additional multithreading.

As the actual transfer runs on a preemptive thread, the events Debug, Write, Header and Progress are called asynchrounously and run a few milliseconds later. You can return true in Progress event to stop transfer, but you will get more events before the transfer is stopped.

You can call CreateMTDebugOutputFile, CreateMTHeaderOutputFile and CreateMTOutputFile before PerformMT to have output data be written into files. Call OpenMTInputFile to let the plugin read input data (form post or upload) from an input file.

Do not call other CURL functions on this CURLMBS instance while PerformMT is running!

Typical error codes are 6 for a wrong domain name in the URL, 67 for wrong name/password combination, 60 for missing SSL settings, 1 for an unsupported protocol.

To avoid trouble with app hanging on quit of application, be sure to set cancel property to true in window close event to cancel any pending transfer.

The work is performed on a preemptive thread, so this function does not block the application and can yield time to other Xojo threads. Must be called in a Xojo thread to enjoy benefits. If called in main thread will block, but keep other background threads running.

CURLMBS.ReceiveData(byref data as Memoryblock, BytesToRead as Int64) as Int64

This function receives raw data from the established connection. You may use it together with SendData to implement custom protocols using libcurl. This functionality can be particularly useful if you use proxies and/or SSL encryption: libcurl will take care of proxy negotiation and connection set-up.

The data memoryblock is a reference to your variable that will get the received data. BytesToRead is the maximum amount of data you can get in that buffer. The function returns the number of received bytes.

To establish the connection, set OptionConnectOnly = true before calling Perform. Note that ReceiveData does not work on connections that were created without this option.

The call will return kError_AGAIN if there is no data to read - the socket is used in non-blocking mode internally. When kError_AGAIN is returned, wait for data to arrive.

Wait on the socket only if ReceiveData returns kError_AGAIN. The reason for this is libcurl or the SSL library may internally cache some data, therefore you should call ReceiveData until all data is read which would include any cached data.

Furthermore if you wait on the socket and it tells you there is data to read, ReceiveData may return CURLE_AGAIN if the only data that was read was for internal SSL processing, and no other data is available.

On success, sets lasterror to kError_OK (0), stores the received data into memory block, and returns the number of bytes it actually read.

On failure, returns zero and lasterror is set to the appropriate error code.

The function may return kError_AGAIN. In this case, use your operating system facilities to wait until data can be read, and retry.

Reading exactly 0 bytes indicates a closed connection.

If there's no socket available to use from the previous transfer, this function returns kError_UNSUPPORTED_PROTOCOL.

CURLMBS.Reset

It does not change the following information kept in the handle: live connections, the Session ID cache, the DNS cache, the cookies and shares.

CURLMBS.UpKeep

Perform any connection upkeep checks.
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.
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.
This function must be explicitly called in order to perform the upkeep work. The connection upkeep interval is set with OptionUpkeepIntervalMS.

CURLMBS.WebSocketMeta as CURLWebSocketFrameMBS

Only useful if called in Write event.

CURLMBS.WebSocketReceive(BufferSize as Integer = 65536) as CURLWebSocketFrameMBS

Var curl as CURLMBS // your curl handle

Var m as CURLWebSocketFrameMBS = curl.WebSocketReceive

if m <> nil then
  TextAreaLog.AddText "Received: "+m.Text
end if

Retrieves as much as possible of a received WebSocket data fragment into the buffer, but not more than BufferSize bytes. The bytesReceived property in CURLWebSocketFrameMBS is set to the number of bytes actually stored.

If there is more fragment data to deliver than what fits in the provided buffer, CURL returns a full buffer and the application needs to call this function again to continue draining the buffer.

The returned CURLWebSocketFrameMBS contains the data and the metadata about the received data.

Lasterror property is set.

CURLMBS.WebSocketSend(Data as MemoryBlock, FrameSize as Integer = 0, SendFlags as Integer = 0) as Integer

The buffer holds the data to send.
Returns the number of payload bytes actually sent.

To send a (huge) fragment using multiple calls with partial content per invoke, set the kFlagOffset bit and the FrameSize argument as the total expected size for the first part, then set the kFlagOffset with a zero FrameSize for the following parts.

If not sending a partial fragment or if this is raw mode, FrameSize should be set to zero.

If kWebSocketRaw is enabled in WebSocketOptions, the flags argument should be set to 0.

Lasterror property is set.