pop3 / smtp: Small comment tidy up

Small tidy up to keep some comments consistant across each of the email
protocols.

imap: FETCH response handler cleanup before further changes

Removed superfluous NULL assignment after Curl_safefree() and rewrote
some comments and logging messages.

pop3: Small tidy up of function arguments

imap: Small tidy up of function arguments

smtp: Corrected debug message for POP3_AUTH_FINAL constant

Following commit ad3177da24b8 corrected the debug message in state()
from AUTH to AUTH_FINAL.

pop3: Corrected debug message for POP3_AUTH_FINAL constant

Following commit afad1ce753a1 corrected the debug message in state()
from AUTH to AUTH_FINAL.

imap: Corrected debug message for IMAP_AUTHENTICATE_FINAL constant

Following commit 13006f3de9ec corrected the debug message in state()
from AUTHENTICATE to AUTHENTICATE_FINAL.

imap: Fixed error code returned for invalid FETCH response

If the FETCH command does not result in an untagged response the the
UID is probably invalid. As such do not return CURLE_OK.

imap: Added processing of the final FETCH responses

Not processing the final FETCH responses was not optimal, not only
because the response code would be ignored but it would also leave data
unread on the socket which would prohibit connection reuse.

imap: Introduced FETCH_FINAL state for processing final fetch responses

A typical FETCH response can be broken down into four parts:

  1) "* <uid> FETCH (<what> {<size>}\r\n", using continuation syntax
  2) <size> bytes of the actual message
  3) ")\r\n", finishing the untagged response
  4) "<tag> OK ...", finishing the command

Part 1 is read in imap_fetch_resp(), part 2 is consumed in the PERFORM
phase by the transfer subsystem, parts 3 and 4 are currently ignored.

imap: fix autobuild warning

Removed whitespace from imap_perform()

imap: fix compiler warning

error: declaration of 'imap' shadows a previous local

smtp: Re-factored the final SMTP_AUTH constant

Changed the final SMTP_AUTH constant to SMTP_AUTH_FINAL for consistency
with the response function.

pop3: Re-factored the final POP3_AUTH constant

Changed the final POP3_AUTH constant to POP3_AUTH_FINAL for consistency
with the response function.

imap: Re-factored final IMAP_AUTHENTICATE constant

Changed the final IMAP_AUTHENTICATE constant to IMAP_AUTHENTICATE_FINAL
for consistency with the response function.

imap: Updated the coding style of imap_state_servergreet_resp()

Updated the coding style, in this function, to be consistant with other
response functions rather then performing a hard return on failure.

imap: Reversed the logic of the (un)successful tagged SELECT response

Reversed the logic of the unsuccessful vs successful tagged SELECT
response in imap_state_select_resp() to be more logical to read.

imap: Reversed the logic of the (un)successful tagged CAPABILITY response

Reversed the logic of the unsuccessful vs successful tagged CAPABILITY
response in imap_state_capability_resp() to be more logical to read.

imap: Corrected char* references with char *

Corrected char* references made in commit: 709b3506cd9b.

imap: Added processing of more than one response when sent in same packet

Added a loop to imap_statemach_act() in which Curl_pp_readresp() is
called until the cache is drained. Without this multiple responses
received in a single packet could result in a hang or delay.

imap: Added skipping of SELECT command if already in the same mailbox

Added storage and checking of the last mailbox userd to prevent
unnecessary switching.

imap: Introduced the mailbox variable

Added the mailbox variable to the per-connection structure in
preparation for checking for an already selected mailbox.

email: Slight reordering of connection based variables

Reordered the state and ssl_done variables in order to provide more
consistency between the email protocols as well as for for an upcoming
change.

imap: Tidied up comments for connection based variables

DOCS: Added the IMAP UIDVALIDITY property to the CURLOPT_URL section

imap: Added verification of UIDVALIDITY mailbox attribute

Added support for checking the UIDVALIDITY, and aborting the request, if
it has been specified in the URL and the server response is different.

imap: Added support for parsing the UIDVALIDITY property

Added support for parsing the UIDVALIDITY property from the SELECT
response and storing it in the per-connection structure.

imap: Introduced the mailbox_uidvalidity variable

Added the mailbox_uidvalidity variable to the per-connection structure
in preparation for checking the UIDVALIDITY mailbox attribute.

imap: Corrected comment in imap_endofresp()

imap: Corrected whitespace

imap: Added filtering of CAPABILITY and FETCH untagged responses

Only responses that contain "CAPABILITY" and "FETCH", respectively,
will be sent to their response handler.

imap: Added a helper function for upcoming untagged response filtering

RFC 3501 states that "the client MUST be prepared to accept any response
at all times" yet we assume anything received with "* " at the beginning
is the untagged response we want.

Introduced a helper function that checks whether the input looks like a
response to specified command, so that we may filter the ones we are
interested in according to the current state.

imap: Moved CAPABILITY response handling to imap_state_capability_resp()

Introduced similar handling to the FETCH responses, where even the
untagged data responses are handled by the response handler of the
individual state.

Remove unused variable in smtp_state_data_resp()

email: Small tidy up following recent changes

smtp: Removed bytecountp from the per-request structure

Removed this pointer to a downloaded bytes counter because it was set in
smtp_init() to point to the same variable the transfer functions keep
the count in (k->bytecount), effectively making the code in transfer.c
"*k->bytecountp = k->bytecount" a no-op.

pop3: Removed bytecountp from the per-request structure

Removed this pointer to a downloaded bytes counter because it was set in
pop3_init() to point to the same variable the transfer functions keep
the count in (k->bytecount), effectively making the code in transfer.c
"*k->bytecountp = k->bytecount" a no-op.

imap: Removed bytecountp from the per-request structure

Removed this pointer to a downloaded bytes counter because it was set in
imap_init() to point to the same variable the transfer functions keep
the count in (k->bytecount), effectively making the code in transfer.c
"*k->bytecountp = k->bytecount" a no-op.

imap: Adjusted SELECT and FETCH function order

Moved imap_select() and imap_fetch() to be grouped with the other
perform functions.

imap: Adjusted SELECT and FETCH state order in imap_statemach_act()

Exchanged the position of these states in the switch statements to
match the state enum, execution and function order.

imap: Minor tidy up of comments in imap_parse_url_path()

Tidy up of comments before next round of imap changes.

imap: Fixed incorrect comparison for STARTTLS in imap_endofresp()

Corrected the comparison type in addition to commit 1dac29fa83a9.

DOCS: Corrected IMAP URL examples according to RFC5092

URL examples that included the UID weren't technically correct although
would pass the curl parser.

darwinssl: fix undefined $ssllib warning in runtests.pl

I also added --with-darwinssl to the list of SSL options in configure.

imap: Added check for new internal imap response code

imap: Changed the order of the response types in imap_endofresp()

From a maintenance point of view the code reads better to view tagged
responses, then untagged followed by continuation responses.

Additionally, this matches the order of responses in POP3.

imap: Added stricter parsing of continuation responses

Enhanced the parsing to only allow continuation responses in some
states.

imap: Simplified memcmp() in tagged response parsing

imap: Reworked the logic of untagged command responses

imap: Corrected spacing of trailing brace

imap: Added stricter parsing of tagged command responses

Enhanced the parsing of tagged responses which must start with "OK",
"NO" or "BAD"

imap: Simplified command response test in imap_endofresp()

imap: Corrected comment in imap_endofresp()

DOCS: Corrected layout of POP3 and IMAP URL examples

Corrected layout issues with the POP3 and IMAP URL examples introduced
in commit cb3ae6894fb2.

DOCS: Updated CURLOPT_URL section following recent POP3 and IMAP changes

Updated the POP3 sub-section to refer to message ID rather than mailbox.

Added an IMAP sub-section with example URLs depicting the specification
of mailbox, uid and section.

pop3: Refactored the mailbox variable as it didn't reflect it's purpose

Updated the mailbox variable to correctly reflect it's purpose. The
name mailbox was a leftover from when IMAP and POP3 support was
initially added to curl.

FEATURES: Updated following recent IMAP changes

imap: Added the ability to FETCH a specific UID and SECTION

Updated the FETCH command to send the UID and SECTION parsed from the
URL. By default the BODY specifier doesn't include a section, BODY[] is
now sent whereas BODY[TEXT] was previously sent. In my opinion
retrieving just the message text is rarely useful when dealing with
emails, as the headers are required for example, so that functionality
is not retained. In can however be simulated by adding SECTION=TEXT to
the URL.

Also updated test801 and test1321 due to the BODY change.

email: Additional tidy up of comments following recent changes

smtp: Removed some FTP heritage leftovers

Removed user and passwd from the SMTP struct as these cannot be set on
a per-request basis and are leftover from legacy FTP code.

Changed some comments still using FTP terminology.

smtp: Moved the per-request variables to the per-request data structure

Moved the rcpt variable from the per-connection struct smtp_conn to the
new per-request struct and fixed references accordingly.

pop3: Introduced a custom SMTP structure for per-request data

Created a new SMTP structure and changed the type of the smtp proto
variable in connectdata from FTP* to SMTP*.

imap: Minor correction of comments for max line length

strcasestr: remove check for this unused function

pop3: fix compiler warning

error: declaration of 'pop3' shadows a previous local

imap: Added URL parsing of new variables

Updated the imap_parse_url_path() function to parse uidvalidity, uid and
section parameters based on RFC-5092.

imap: Introduced imap_is_bchar() function

Added imap_is_bchar() for testing if a given character is a valid bchar
or not.

imap: Introduced new per-request veriables

Added uidvalidity, uid and section variables to the per-request IMAP
structure in preparation for upcoming URL parsing.

pingpong: Renamed curl_ftptransfer to curl_pp_transfer

pop3: Removed some FTP heritage leftovers

Removed user and passwd from the POP3 struct as these cannot be set on
a per-request basis and are leftover from legacy FTP code.

Changed some comments still using FTP terminology.

pop3: Moved the per-request variables to the per-request data structure

Moved the mailbox and custom request variables from the per-connection
struct pop3_conn to the new per-request struct and fixed references
accordingly.

pop3: Introduced a custom POP3 structure for per-request data

Created a new POP3 structure and changed the type of the pop3 proto
variable in connectdata from FTP* to POP*.

imap: Fixed escaping of mailbox names

Used imap_atom() to escape mailbox names in imap_select().

pingpong: Moved curl_ftptransfer definition to pingpong.h

Moved the ftp transfer structure into pingpong.h so other protocols that
require it don't have to include ftp.h.

urldata.h: Fixed comment for opt_no_body variable

Corrected comment for opt_no_body variable to CURLOPT_NOBODY.

email: Minor tidy up following IMAP changes

imap: Removed more FTP leftovers

Changed some variables and comments still using FTP terminology.

imap: Removed some FTP heritage leftovers

Removed user and passwd from the IMAP struct as these cannot be set on
a per-request basis and are leftover from legacy FTP code.

imap: Introduced a custom IMAP structure for per-request data

Created a new IMAP structure and changed the type of the imap proto
variable in connectdata from FTP* to the new IMAP*.

Moved the mailbox variable from the per-connection struct imap_conn to
the new per-request struct and fixed references accordingly.

pop3: Updated do phrase clean-up comment

Following commit 65644b833532 for the IMAP module updated the clean-up
comment in POP3.

imap: Fixed memory leak when performing multiple selects

Moved the clean-up of the mailbox variable from imap_disconnect() to
imap_done() as this variable is allocated in the do phase, yet would
have only been freed only once if multiple selects where preformed
on a single connection.

Documentation: Typo in docs/CONTRIBUTE

Fixes a typo get → git in docs/CONTRIBUTE.

repository: ignore patch files generated by git

Ignores the patch files generated by the 'git format-patch' command.

libcurl documentation: clarifications and typos

* Elaborates on default values of some curl_easy_setopt() options.
* Reminds the user to cast variadic arguments to curl_easy_setopt() to
  'void *' where curl internally interprets them as such.
* Clarifies the working of the CURLOPT_SEEKFUNCTION option for
  curl_easy_setopt().
* Fixes typo 'forth' → 'fourth'.
* Elaborates on CURL_SOCKET_TIMEOUT.
* Adds some missing periods.
* Notes that the return value of curl_version() must not be passed to
  free().

lib/url.c: Generic read/write data pointers

Always interprets the pointer passed with the CURLOPT_WRITEDATA or
CURLOPT_READDATA options of curl_easy_setopt() as a void pointer in
order to avoid problems in environments where FILE and void pointers
have non-trivial conversion.

libcurl documentation: updates HTML index

* Adds several links to documentation of library functions which were
  missing.
* Marks documentation of deprecated library functions "(deprecated)".
* Removes spurious .html suffixes.

ossl_seed: avoid recursive seeding!

Fixed checking the socket if there is data waiting in the cache

Use Curl_pp_moredata() in Curl_pp_multi_statemach() to check if there is
more data to be received, rather than the socket state, as a task could
hang waiting for more data from the socket itself.

imap.c: Fixed an incorrect variable reference

Fixed an incorrect variable reference which was introduced in commit
a1701eea289f as a result of a copy and paste from SMTP/POP3.

pingpong: Introduce Curl_pp_moredata()

A simple function to test whether the PP is not sending and there are
still more data in its receiver cache. This will be later utilized to:

1) Change Curl_pp_multi_statemach() and Curl_pp_easy_statemach() to
   not test socket state and just call user's statemach_act() function
   when there are more data to process, because otherwise the task would
   just hang, waiting for more data from the socket.

2) Allow PP users to read multiple responses by looping as long as there
   are more data available and current phase is not finished.
   (Currently needed for correct processing of IMAP SELECT responses.)

FEATURES: why yes, we do support metalink

I just noticed Metalink support wasn't listed as a feature of the tool.

metalink: fix improbable crash parsing metalink filename

The this_url pointer wasn't being initialized, so if strdup() would return
null when copying the filename in a metalink file, then hilarity would
ensue during the cleanup phase. This change was brought to you by clang,
which noticed this and raised a warning.

smtp.c: fix enumerated type mixed with another type

polarssl threadlock cleanup

docs: schannel and darwinssl documentation improvements

Schannel and darwinssl use the certificates built into the
OS to do vert verification instead of bundles. darwinssl
is thread-safe. Corrected typos in the NSS docs.

resolver_error: remove wrong error message output

The attempt to use gai_strerror() or alternative function didn't work as
the 'sock_error' field didn't contain the proper error code. But since
this hasn't been reported and thus isn't really a big deal I decided to
just scrap the whole attempt to output the detailed resolver error and
instead remain with just stating that the resolving of the name failed.

Curl_resolver_is_resolved: show proper host name on failed resolve

Curl_resolver_is_resolved: fix compiler warning

conversion to 'int' from 'long int' may alter its value

compiler warning fix

follow-up to commit ed7174c6f66, rename 'wait' to 'block'

compiler warning fix: declaration of 'wait' shadows a global declaration

It seems older gcc installations (at least) will cause warnings if we
name a variable 'wait'. Now changed to 'block' instead.

Reported by: Jiří Hruška
Bug: http://curl.haxx.se/mail/lib-2013-02/0247.html