diff options
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/EXPERIMENTAL.md | 1 | ||||
| -rw-r--r-- | docs/FEATURES | 3 | ||||
| -rw-r--r-- | docs/MQTT.md | 61 | ||||
| -rw-r--r-- | docs/Makefile.am | 1 | ||||
| -rw-r--r-- | docs/cmdline-opts/data.d | 2 | ||||
| -rw-r--r-- | docs/cmdline-opts/page-header | 4 | ||||
| -rw-r--r-- | docs/libcurl/opts/CURLINFO_PROTOCOL.3 | 2 | ||||
| -rw-r--r-- | docs/libcurl/symbols-in-versions | 1 |
8 files changed, 71 insertions, 4 deletions
diff --git a/docs/EXPERIMENTAL.md b/docs/EXPERIMENTAL.md index 6c33bcf53..34974fba8 100644 --- a/docs/EXPERIMENTAL.md +++ b/docs/EXPERIMENTAL.md @@ -20,3 +20,4 @@ Experimental support in curl means: - HTTP/3 support and options - alt-svc support and options + - MQTT diff --git a/docs/FEATURES b/docs/FEATURES index 68d38fc27..1d23fccbf 100644 --- a/docs/FEATURES +++ b/docs/FEATURES @@ -180,6 +180,9 @@ IMAPS (*1) - explicit "STARTTLS" usage to "upgrade" plain imap:// connections to use SSL - via http-proxy +MQTT + - Subscribe to and publish topics using url scheme mqtt://broker/topic + FOOTNOTES ========= diff --git a/docs/MQTT.md b/docs/MQTT.md new file mode 100644 index 000000000..1c7b678aa --- /dev/null +++ b/docs/MQTT.md @@ -0,0 +1,61 @@ +# MQTT in curl + +## Experimental! + +MQTT support in curl is considered **EXPERIMENTAL** until further notice. It +needs to be enabled at build-time. See below. + +After the initial merge, further development and tweaking of the MQTT support +in curl will happen in the master branch using pull-requests, just like +ordinary changes. + +Experimental support for MQTT means that we **do not guarantee** that the +current protocol functionality will remain or remain this way going forward. +There are no API or ABI promises for experimental features as for regular curl +features. + +Do not ship anything with this enabled. + +## Build + + ./configure --enable-mqtt + +## Usage + +A plain "GET" subscribes to the topic and prints all published messages. +Doing a "POST" publishes the post data to the topic and exits. + +Example subscribe: + + curl mqtt://host/home/bedroom/temp + +Example publish: + + curl -d 80 mqtt://host/home/bedroom/dimmer + +## What does curl deliver as a response to a subscribe + +It outputs two bytes topic length (MSB | LSB), the topic followed by the +payload. + +## Caveats + +Remaining limitations: + - No username support + - Only QoS level 0 is implemented for publish + - No way to set retain flag for publish + - No username/password support + - No TLS (mqtts) support + - Naive EAGAIN handling won't handle split messages + +## Work + +1. Write a mqtt server for the test suite +2. Create a few tests verifying the existing mqtt functionality +3. Work on fixing some of the worst limitations - with accompanying tests +4. Consider replacing the client-side MQTT code with wolfMQTT + +## Credits + +The initial MQTT patch was authored by Björn Stenberg. This work is built upon +that patch and has been expanded since. diff --git a/docs/Makefile.am b/docs/Makefile.am index 7acce0b04..6ead27b79 100644 --- a/docs/Makefile.am +++ b/docs/Makefile.am @@ -71,6 +71,7 @@ EXTRA_DIST = \ KNOWN_BUGS \ LICENSE-MIXING.md \ MAIL-ETIQUETTE \ + MQTT.md \ PARALLEL-TRANSFERS.md \ README.md \ RELEASE-PROCEDURE.md \ diff --git a/docs/cmdline-opts/data.d b/docs/cmdline-opts/data.d index 8b5200d34..280d38bc0 100644 --- a/docs/cmdline-opts/data.d +++ b/docs/cmdline-opts/data.d @@ -2,7 +2,7 @@ Long: data Short: d Arg: <data> Help: HTTP POST data -Protocols: HTTP +Protocols: HTTP MQTT See-also: data-binary data-urlencode data-raw Mutexed: form head upload-file --- diff --git a/docs/cmdline-opts/page-header b/docs/cmdline-opts/page-header index 3f0b1c33e..60c3b07fe 100644 --- a/docs/cmdline-opts/page-header +++ b/docs/cmdline-opts/page-header @@ -31,8 +31,8 @@ curl \- transfer a URL .B curl is a tool to transfer data from or to a server, using one of the supported protocols (DICT, FILE, FTP, FTPS, GOPHER, HTTP, HTTPS, IMAP, IMAPS, LDAP, -LDAPS, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET -and TFTP). The command is designed to work without user interaction. +LDAPS, MQTT, POP3, POP3S, RTMP, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, +TELNET and TFTP). The command is designed to work without user interaction. curl offers a busload of useful tricks like proxy support, user authentication, FTP upload, HTTP post, SSL connections, cookies, file transfer diff --git a/docs/libcurl/opts/CURLINFO_PROTOCOL.3 b/docs/libcurl/opts/CURLINFO_PROTOCOL.3 index 2f5a3edfc..5825669c4 100644 --- a/docs/libcurl/opts/CURLINFO_PROTOCOL.3 +++ b/docs/libcurl/opts/CURLINFO_PROTOCOL.3 @@ -38,7 +38,7 @@ CURLPROTO_IMAPS, CURLPROTO_LDAP, CURLPROTO_LDAPS, CURLPROTO_POP3, CURLPROTO_POP3S, CURLPROTO_RTMP, CURLPROTO_RTMPE, CURLPROTO_RTMPS, CURLPROTO_RTMPT, CURLPROTO_RTMPTE, CURLPROTO_RTMPTS, CURLPROTO_RTSP, CURLPROTO_SCP, CURLPROTO_SFTP, CURLPROTO_SMB, CURLPROTO_SMBS, CURLPROTO_SMTP, -CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP +CURLPROTO_SMTPS, CURLPROTO_TELNET, CURLPROTO_TFTP, CURLPROTO_MQTT .SH PROTOCOLS All .SH EXAMPLE diff --git a/docs/libcurl/symbols-in-versions b/docs/libcurl/symbols-in-versions index c2ed53880..3b340ed8e 100644 --- a/docs/libcurl/symbols-in-versions +++ b/docs/libcurl/symbols-in-versions @@ -676,6 +676,7 @@ CURLPROTO_IMAP 7.20.0 CURLPROTO_IMAPS 7.20.0 CURLPROTO_LDAP 7.19.4 CURLPROTO_LDAPS 7.19.4 +CURLPROTO_MQTT 7.71.0 CURLPROTO_POP3 7.20.0 CURLPROTO_POP3S 7.20.0 CURLPROTO_RTMP 7.21.0 |