Added logic in imap_perform() to perform an APPEND rather than SELECT
and FETCH if an upload has been specified.

The APPEND operation needs to be performed in several steps:
  1) We send "<tag> APPEND <mailbox> <flags> {<size>}\r\n"
  2) Server responds with continuation respose "+ ...\r\n"
  3) We start the transfer and send <size> bytes of data
  4) Only now we end the request command line by sending "\r\n"
  5) Server responds with "<tag> OK ...\r\n"

This commit performs steps 4 and 5, in the DONE phase, as more
processing is required after the transfer.

Added imap_append() function to initiate upload and imap_append_resp()
to handle the continuation response and start the transfer.

Add number of bytes retrieved from the PP cache to req.bytecount and set
req.maxdownload only when starting a proper download.

Added safer parsing of the untagged FETCH response line and the size of
continuation data.

Accidentally lost the result code in imap_state_capability() and
imap_state_login() with commit b06a7862.

Some state changes would be performed after a failure test that
performed a hard return, whilst others would be performed within a test
for success. Updated the code, for consistency, so all instances are
performed within a success test.

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

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

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

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

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

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

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.

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.

Removed whitespace from imap_perform()

error: declaration of 'imap' shadows a previous local

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

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

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

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

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

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

Corrected char* references made in commit: 709b3506.

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.

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

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

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.

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

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

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