YOUSEFUL / FILEMAKER

YsflCurl — function reference

Function prefix YsflCu_, 28 functions. A libcurl-based transfer plugin: libcurl 8.22.0 is statically linked (Schannel TLS, zlib, nghttp2 for HTTP/2), so the plugin still has no external DLL dependencies. It is the sibling of YsflHttp (WinHTTP); the HTTP function shapes are identical so a script can switch between them, and YsflCurl adds HTTP/2, client certificates, SOCKS proxies, DNS overrides, cookie jars, ranges, transfer statistics, a verbose log, and every libcurl protocol (ftp, ftps, smtp, smtps, imap, imaps, pop3, pop3s, file, ws, wss).

Transport failures return ? Request: <libcurl message> (code); the CURLcode is in YsflCu_LastError. HTTP status codes are not failures: the body is returned and YsflCu_Status has the code.

Options

Space-separated key=value tokens or one per line. header=, part=, cookie=, useragent=, contenttype=, accept=, referer= and loginoptions= take the rest of their line.

option	meaning
`timeout=<sec>`, `connecttimeout=<sec>`	whole-transfer and connect limits (default 30 each)
`user=`, `password=`, `auth=basic\|digest\|ntlm\|negotiate\|any`	HTTP auth (default basic); `user`/`password` also feed FTP, SMTP, IMAP, POP3 logins
`bearer=<token>`	`Authorization: Bearer`
`header=Name: value`	extra header, repeatable
`contenttype=`, `accept=`, `useragent=`, `referer=`	common headers
`json` / `form`	shorthand content types
`file=<path>` / `tofile=<path>`	body from a file / response saved to a file (returns `0`)
`redirects=0`, `maxredirs=N`	redirect handling (default follow, 20)
`verify=0` or `insecure`	ignore certificate errors
`cacert=<pem>`	trust this CA bundle instead of the Windows store
`cert=<file> key=<file> keypass=`	client certificate (PEM/P12 per libcurl rules)
`proxy=host:port`, `proxyuser=`, `proxypassword=`	HTTP proxy; `socks5=host:port`, `socks4=host:port`
`http1`, `http2`, `http2prior`	protocol version (default: HTTP/1.1; `http2` negotiates over TLS)
`resolve=host:port:addr`	pin a hostname to an address (like `curl --resolve`)
`interface=<ip or name>`	outgoing interface
`cookiejar=<file>`	read cookies from and write them back to a Netscape-format file
`cookie=<string>`	send a literal Cookie header
`range=a-b`, `resume=<offset>`	partial transfers
`lowspeed=<bytes/s> lowspeedtime=<sec>`	abort slow transfers
`decompress=0`	do not request gzip/deflate
`charset=<name>`	force response decoding
`ipv4`, `ipv6`	address family
`expect100=1`	allow `Expect: 100-continue` (suppressed by default)
`verbose`	keep a protocol trace for `YsflCu_Log`
`mailfrom=`, `rcpt=` (repeatable)	SMTP envelope for `smtp://` uploads
`customrequest=<verb>`, `nobody`	raw protocol control (IMAP `SEARCH`, FTP `NLST`, …)
`loginoptions=AUTH=PLAIN`	SASL mechanism selection
`field=`, `filename=`, `part=key=value`	Upload form field, file name, extra fields

Cookies received without cookiejar are kept in memory for the FileMaker session.

Functions

Function	Returns
`YsflCu_Request ( method ; url ; {body} ; {options} )`	body text. For non-HTTP URLs the body is uploaded (SMTP message, FTP `STOR`, IMAP `APPEND`) and the method becomes a custom command
`YsflCu_Get`, `YsflCu_Delete`, `YsflCu_Head ( url ; {options} )`	body text
`YsflCu_Post`, `YsflCu_Put`, `YsflCu_Patch ( url ; body ; {options} )`	body text
`YsflCu_PostJSON ( url ; json ; {options} )`	JSON post
`YsflCu_PostForm ( url ; fields ; {options} )`	`key=value` lines url-encoded
`YsflCu_Upload ( url ; fileOrContainer ; {options} )`	multipart/form-data
`YsflCu_Download ( url ; path ; {options} )`	`0`
`YsflCu_GetContainer ( url ; {options} )`	container
`YsflCu_GraphQL ( url ; query ; {variables} ; {options} )`	JSON response
`YsflCu_Status`, `YsflCu_StatusText`, `YsflCu_Headers`, `YsflCu_Header ( name )`	last response
`YsflCu_Info ( field )`	`effectiveurl`, `redirecturl`, `redirectcount`, `contenttype`, `primaryip`, `primaryport`, `localip`, `scheme`, `httpversion`, `totaltime`, `namelookuptime`, `connecttime`, `tlstime`, `pretransfertime`, `starttransfertime`, `sizedownload`, `sizeupload`, `speeddownload`, `speedupload`, `numconnects`, `sslverifyresult`
`YsflCu_Log`	verbose trace of the last transfer (needs the `verbose` option)
`YsflCu_ParseURL ( url ; part )`	via libcurl's URL parser: `scheme`, `host`, `port` (default filled in), `path`, `query`, `fragment`, `user`, `password`, `url` (normalised)
`YsflCu_Escape ( text )`, `YsflCu_Unescape ( text )`	percent-encoding
`YsflCu_SetDefaults ( {options} )`	options applied before every call's own; `""` resets
`YsflCu_Protocols`	protocols compiled into this libcurl
`YsflCu_Version`	plugin, libcurl, TLS backend and zlib versions
`YsflCu_Register`, `YsflCu_LastError`, `YsflCu_LastErrorText`

Examples

# HTTP/2 with a client certificate
Set Variable [ $r ; YsflCu_Get ( "https://api.example.com/v1/me" ; "http2 cert=C:\certs\client.p12 keypass=secret" ) ]
Set Variable [ $ms ; YsflCu_Info ( "totaltime" ) ]

# send mail through libcurl
Set Variable [ $r ; YsflCu_Request ( "" ; "smtps://smtp.example.com" ; $rawMessage ;
    "user=me@example.com password=" & $pw & " mailfrom=me@example.com rcpt=you@example.com" ) ]

# fetch a message by UID over IMAPS
Set Variable [ $raw ; YsflCu_Get ( "imaps://imap.example.com/INBOX/;UID=1042" ; "user=" & $user & " password=" & $pw ) ]

# FTP listing and upload
Set Variable [ $list ; YsflCu_Get ( "ftp://user:pass@ftp.example.com/outgoing/" ) ]
Set Variable [ $r ; YsflCu_Request ( "" ; "ftp://user:pass@ftp.example.com/outgoing/report.csv" ; $csv ) ]

# debugging a failing call
Set Variable [ $r ; YsflCu_Get ( $url ; "verbose" ) ]
Set Variable [ $trace ; YsflCu_Log ]

Rebuilding libcurl

tools/build-curl.sh [version] downloads the curl source, builds a static library against Schannel, zlib and nghttp2, and vendors the result into shared/third_party/curl (library, headers, COPYING, VERSION.txt). It needs the MSYS2 packages mingw-w64-ucrt-x86_64-zlib and -nghttp2.