diff --git a/functions/imap.xml b/functions/imap.xml index b72517d15d..f359f4b400 100644 --- a/functions/imap.xml +++ b/functions/imap.xml @@ -1,5 +1,5 @@ - IMAP functions + IMAP, POP3 and NNTP functions IMAP @@ -9,8 +9,9 @@ c-client library to be installed. Grab the latest version from &url.imap; and compile it. Then copy c-client/c-client.a to - /usr/local/lib or some other directory on - your link path and copy c-client/rfc822.h, + /usr/local/lib/libc-client.a or some other + directory on your link path and copy + c-client/rfc822.h, mail.h and linkage.h to /usr/local/include or some other directory in your include path. @@ -19,9 +20,66 @@ Note that these functions are not limited to the IMAP protocol, despite their name. The underlying c-client library also supports NNTP, - POP3 and local mailbox access methods. See the - imap_open for more information. + POP3 and local mailbox access methods. + + This document can't go into detail on all the topics touched by the + provided functions. Further information is provided by the + documentation of the c-client library source + (docs/internal.txt) + and the following RFC documents: + + + + RFC821 : + Simple Mail Transfer Protocol (SMTP) + + + + + RFC822 : + Standard for ARPA internet text messages + + + + + RFC2060 : + Internet Message Access Protocol (IMAP) Version 4rev1 + + + + + RFC1939 : + Post Office Protocol Version 3 (POP3) + + + + + RFC977 : + Network News Transfer Protocol (NNTP) + + + + + RFC2076 : + Common Internet Message Headers + + + + + RFC2045 , + RFC2046 , + RFC2047 , + RFC2048 & + RFC2049 : + Multipurpose Internet Mail Extensions (MIME) + + + + A detailed overview is also available in the book + Programming Internet Email + by David Wood. + @@ -38,7 +96,7 @@ int imap_stream string mbox string message - stringflags + stringflags Returns true on sucess, false on error. @@ -69,7 +127,11 @@ imap_base64 function decodes BASE-64 encoded - text. The decoded message is returned as a string. + text (see RFC2045, + Section 6.8). The decoded message is returned as a string. + + + See also imap_binary. @@ -86,7 +148,7 @@ string imap_body int imap_stream int msg_number - int flags + int flags imap_body returns the body of the message, @@ -96,7 +158,7 @@ - FT_UID - The msgno is a UID + FT_UID - The msgno is a UID @@ -133,18 +195,36 @@ The imap_check function checks the current mailbox status on the server and returns the information in an - object with following properties. + object with following properties: - - - Date : date of the message - Driver : driver - Mailbox : name of the mailbox - Nmsgs : number of messages - Recent : number of recent messages - - + + + + Date - last change of mailbox contents + + + + + Driver - protocol used to access this mailbox: POP3, IMAP, NNTP + + + + + Mailbox - the mailbox name + + + + + Nmsgs - number of messages in the mailbox + + + + + Recent - number of recent messages in the mailbox + + + @@ -159,7 +239,7 @@ int imap_close int imap_stream - int flags + int flags Close the imap stream. Takes an optional @@ -184,15 +264,15 @@ imap_createmailbox creates a new mailbox specified by mbox - (see imap_open for the format - of mbox names). Returns true on success and false on error. - See also imap_renamemailbox and - imap_deletemailbox. + See also imap_renamemailbox, + imap_deletemailbox and + imap_open for the format + of mbox names. @@ -210,15 +290,21 @@ int imap_delete int imap_stream int msg_number + int flags Returns true. imap_delete function marks message pointed - by msg_number for deletion. Actual - deletion of the messages is done by - imap_expunge. + by msg_number for deletion. + The optional flags parameter only + has a single option, FT_UID, which tells + the function to treat the msg_number + argument as a UID. + Messages marked for deletion will stay in the mailbox until either + imap_expunge is called or imap_close + is called with the optional parameter CL_EXPUNGE. @@ -244,8 +330,10 @@ Returns true on success and false on error. - See also imap_createmailbox and - imap_reanmemailbox. + See also imap_createmailbox, + imap_reanmemailbox and + imap_open for the format of + mbox. @@ -263,7 +351,10 @@ imap_expunge deletes all the messages marked - for deletion by imap_delete. + for deletion by imap_delete, + imap_move_mail or + imap_setflag_full. + Returns true. @@ -283,7 +374,7 @@ int imap_stream int msg_number string part_number - flags flags + flags flags This function causes a fetch of a particular section of the body @@ -298,7 +389,7 @@ - FT_UID - The msgono is a UID + FT_UID - The msg_number is a UID @@ -629,10 +720,12 @@ fetchsubject (subject line formatted to fit subjectlength array imap_listmailbox int imap_stream string ref - string pat + string pattern Returns an array containing the names of the mailboxes. + See imap_getmailboxes for a description + of ref and pattern @@ -651,7 +744,7 @@ fetchsubject (subject line formatted to fit subjectlength array imap_getmailboxes int imap_stream string ref - string pat + string pattern Returns an array of objects containing mailbox information. Each @@ -723,10 +816,9 @@ fetchsubject (subject line formatted to fit subjectlength Returns an array of all the mailboxes that you have - subscribed. The ref and - pattern arguments specify the base - location to search from and the pattern the mailbox name must - match. + subscribed. This is almost identical to + imap_listmailbox, but will only return + mailboxes the user you logged in as has subscribed. @@ -764,7 +856,7 @@ fetchsubject (subject line formatted to fit subjectlength int imap_stream string msglist string mbox - int flags + int flags Returns true on success and false on error. @@ -772,7 +864,8 @@ fetchsubject (subject line formatted to fit subjectlength Copies mail messages specified by msglist to specified mailbox. msglist is a range - not just message numbers. + not just message numbers (as described in + RFC2060). Flags is a bitmask of one or more of @@ -805,11 +898,23 @@ fetchsubject (subject line formatted to fit subjectlength int imap_stream string msglist string mbox + int flags Moves mail messages specified by msglist to specified mailbox. msglist is a range - not just message numbers. + not just message numbers (as described in + RFC2060). + + + Flags is a bitmask and may contain the single option + + + + CP_UID - the sequence numbers contain UIDS + + + Returns true on success and false on error. @@ -866,7 +971,7 @@ fetchsubject (subject line formatted to fit subjectlength string mailbox string username string password - int flags + int flags Returns an IMAP stream on success and false on error. This @@ -908,7 +1013,7 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); - OP_ANONYMOUS - Dont use or update a .newsrc for news + OP_ANONYMOUS - Dont use or update a .newsrc for news (NNTP only) @@ -924,6 +1029,34 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); + + + + <function>imap_open</function> example + +$mbox = imap_open("{your.imap.host:143}","username","password"); + +echo "<p><h1>Mailboxes</h1>\n"; +$folders = imap_listmailbox($mbox, "{your.imap.host:143}", "*"); +if($folders == false) + echo "Call failed<br>\n"; +else + while(list($key,$val) = each($folders)) + echo $val."<br>\n"; + +echo "<p><h1>Headers in INBOX</h1>\n"; +$headers = imap_headers($mbox); +if($headers == false) + echo "Call failed<br>\n"; +else + while(list($key,$val) = each($headers)) + echo $val."<br>\n"; + +imap_close($mbox); + + + + @@ -945,7 +1078,9 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); imap_ping function pings the stream to see it is still active. It may discover new mail; this is the preferred method for a periodic "new mail check" as well as a - "keep alive" for servers which have inactivity timeout. + "keep alive" for servers which have inactivity timeout + ( As PHP scripts do not tend to run that long, i can hardly + immagine that this function will be usefull to anyone ). @@ -972,8 +1107,10 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); Returns true on success and false on error. - See also imap_createmailbox and - imap_deletemailbox. + See also imap_createmailbox, + imap_deletemailbox and + imap_open for the format of + mbox. @@ -992,10 +1129,10 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); string flags - - Returns true on success and false on error. - This function reopens the specified stream to new mailbox. + This function reopens the specified stream to a new mailbox on + an IMAP or NNTP server. + The options are a bit mask with one or more of the following: @@ -1006,7 +1143,7 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); - OP_ANONYMOUS - Dont use or update a .newsrc for news + OP_ANONYMOUS - Dont use or update a .newsrc for news (NNTP only) @@ -1018,10 +1155,15 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); CL_EXPUNGE - Expunge mailbox automatically upon mailbox close + ( see also imap_delete and + imap_expunge ) + + Returns true on success and false on error. + @@ -1062,7 +1204,8 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); This function removes the deletion flag for a specified message, - which is set by imap_delete. + which is set by imap_delete or + imap_mail_move. Returns true on success and false on error. @@ -1104,9 +1247,15 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); string string - Convert a quoted-printable string to an 8 bit string + Convert a quoted-printable string to an 8 bit string + ( according to RFC2045, section 6.7 ). + - Returns an 8 bit (binary) string + Returns an 8 bit (binary) string. + + + See also imap_8bit. + @@ -1124,9 +1273,17 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); string string - Convert an 8bit string to a quoted-printable string. + Convert an 8bit string to a quoted-printable string. + ( according to + RFC2045, + section 6.7 ). + - Returns a quoted-printable string + Returns a quoted-printable string + + + See also imap_qprint. + @@ -1144,11 +1301,17 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); string string - Convert an 8bit string to a base64 string. + Convert an 8bit string to a base64 string + (according to + RFC2045, + Section 6.8). Returns a base64 string. + + See also imap_base64. + @@ -1165,11 +1328,14 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); array imap_scanmailbox int imap_stream - string string + string content Returns an array containing the names of the mailboxes that have string in the text of the mailbox. + This function is simmilar to imap_listmailbox, + but it will additionally check for the presence of the string + content inside the mailbox data. @@ -1191,21 +1357,27 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); The imap_mailboxmsginfo function checks the - current mailbox status on the server and returns the information + current mailbox status on the server. It is similar to + imap_status, but will additionally sum up the + size of all messages in the mailbox, which will take some additional + time to execute. It returns the information in an object with following properties. - - - Date : date of the message - Driver : driver - Mailbox : name of the mailbox - Nmsgs : number of messages - Recent : number of recent messages - Unread : number of unread messages - Size : mailbox size - - + + Mailbox properties + + + Date date of last change + Driver driver + Mailboxname of the mailbox + Nmsgs number of messages + Recent number of recent messages + Unread number of unread messages + Size mailbox size + + +
@@ -1229,8 +1401,9 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); string personal - Returns a properly formatted email address given the mailbox, - host, and personal info. + Returns a properly formatted email address as defined in + RFC822 + given the mailbox, host, and personal info. @@ -1250,8 +1423,10 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); string default_host - This function parses the address string and for each address, - returns an array of objects. The 4 objects are: + This function parses the address string as defined in + RFC822 and + for each address, returns an array of objects. + The 4 objects are: @@ -1320,6 +1495,9 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); This function causes a store to delete the specified flag to the flags set for the messages in the specified sequence. + The flags which you can unset are "\\Seen", "\\Answered", + "\\Flagged", "\\Deleted", "\\Draft", and "\\Recent" ( as defined + by RFC2060) The options are a bit mask with one or more of the following: @@ -1394,7 +1572,8 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); int flags - This function causes a fetch of the complete, unfiltered RFC 822 + This function causes a fetch of the complete, unfiltered + RFC822 format header of the specified message as a text string and returns that text string. @@ -1434,7 +1613,10 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); This function returns the UID for the given message sequence - number. It is the inverse of imap_msgno. + number. An UID is an unique identifier that will not change over + time while a message sequence number may change whenever the + content of the mailbox changes. + This function is the inverse of imap_msgno. @@ -1614,7 +1796,7 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); use: "UNANSWERED FROM mom". Searches appear to be case insensitive. This list of criteria is from a reading of the UW c-client source code and may be uncomplete or - inaccurate. Searcher beware. + inaccurate (see also RFC2060, section 6.4.4). Valid values for flags are SE_UID, which causes the returned @@ -1644,8 +1826,6 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); subsequently, with no intervening errors, will return the same error. - CAUTION: this function is not yet available in PHP4. - @@ -1671,9 +1851,6 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); imap_errors is called, the error stack is subsequently cleared. - - CAUTION: this function is not yet available in PHP4 - @@ -1785,7 +1962,10 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); Returns the decoded 8bit data, or false if the input string was - not valid modified UTF-7. + not valid modified UTF-7. The modified UTF-7 encoding is defined in + RFC 2060, section 5.1.3 + (original UTF-7 was defned in + RFC1642). @@ -1806,7 +1986,9 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); Converts 8bit data to modified UTF-7 text. The modified UTF-7 encoding is defined in - RFC 2060. + RFC 2060, section 5.1.3 + (original UTF-7 was defned in + RFC1642). Returns the modified UTF-7 text. @@ -1814,6 +1996,164 @@ $nntp = imap_open("{localhost/nntp:119}comp.test","",""); + + + imap_utf8 + + Converts text to UTF8 + + + + Description + + string imap_utf8 + string text + + + Converts the given text to + UTF8 (as defined in + RFC2044). + + + + + + + imap_fetch_overview + + Read an overview of the information in the headers of the given message + + + + Description + + array imap_fetch_overview + int imap_stream + string sequence + + + This function fetches a mail header and returns an overview of its contents. + It will return an array of objects describing one message header each: + + + + subject - the messages subject + + + + + from - who sent it + + + + + date - when was it sent + + + + + message_id - Message-ID + + + + + references - is a reference to this message id + + + + + size - size in bytes + + + + + uid - UID the message has in the mailbox + + + + + msgno - message sequence number in the maibox + + + + + recent - this message is flagged as recent + + + + + flagged - this message is flagged + + + + + answered - this message is flagged as answered + + + + + deleted - this message is flagged for deletion + + + + + seen - this message is flagged as already read + + + + + draft - this message is flagged as being a draft + + + + + + + + + + imap_mail_compose + + Create a MIME message based on given envelope and body sections + + + + Description + + string imap_mail_compose + array envelope + array body + + + + + + + + + imap_mail + + Send an email message + + + + Description + + string imap_mail + string to + string subject + string message + string additional_headers + string cc + string bcc + string rpath + + + This function is currently only available in PHP3. + + + +