luo980/curl
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

URL-SYNTAX: add IMAP UID SEARCH example

Browse Source 
- Explain the difference between IMAP search via URL (which returns
  message sequence numbers) and IMAP search via custom request (which
  can return UID numbers if prefixed with UID, eg "UID SEARCH ...").

Bug: https://github.com/curl/curl/issues/7626
Reported-by: orycho@users.noreply.github.com

Ref: https://github.com/curl/curl/issues/2789

Closes https://github.com/curl/curl/pull/7881
This commit is contained in:
Jay Satiro 2021-10-19 15:37:19 -04:00
parent 2c8a81407f
commit 4a3c324add
1 changed files with 24 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

29
docs/URL-SYNTAX.md
View File

@ -5,7 +5,8 @@
The official "URL syntax" is primarily defined in these two different
specifications:
- [RFC 3986](https://tools.ietf.org/html/rfc3986) (although URL is called "URI" in there)
- [RFC 3986](https://tools.ietf.org/html/rfc3986) (although URL is called
"URI" in there)
- [The WHATWG URL Specification](https://url.spec.whatwg.org/)
RFC 3986 is the earlier one, and curl has always tried to adhere to that one
@ -41,8 +42,8 @@ security concerns:
1. If you have an application that runs as or in a server application, getting
an unfiltered URL can trick your application to access a local resource
instead of a remote resource. Protecting yourself against localhost accesses is very
hard when accepting user provided URLs.
instead of a remote resource. Protecting yourself against localhost accesses
is very hard when accepting user provided URLs.
2. Such custom URLs can access other ports than you planned as port numbers
are part of the regular URL format. The combination of a local host and a
@ -285,8 +286,26 @@ subject line:
imap://user:password@mail.example.com/INBOX?SUBJECT%20shadows
For more information about the individual components of an IMAP URL please see
RFC 5092.
Searching via the query part of the URL `?` is a search request for the results
to be returned as message sequence numbers (MAILINDEX). It is possible to make
a search request for results to be returned as unique ID numbers (UID) by using
a custom curl request via `-X`. UID numbers are unique per session (and
multiple sessions when UIDVALIDITY is the same). For example, if you are
searching for `"foo bar"` in header+body (TEXT) and you want the matching
MAILINDEX numbers returned then you could search via URL:
imap://user:password@mail.example.com/INBOX?TEXT%20%22foo%20bar%22
.. but if you wanted matching UID numbers you'd have to use a custom request:
imap://user:password@mail.example.com/INBOX -X "UID SEARCH TEXT \"foo bar\""
For more information about IMAP commands please see RFC 9051. For more
information about the individual components of an IMAP URL please see RFC 5092.
* Note old curl versions would FETCH by message sequence number when UID was
specified in the URL. That was a bug fixed in 7.62.0, which added MAILINDEX to
FETCH by mail sequence number.
## LDAP