forked from extern/egroupware
140 lines
5.9 KiB
Plaintext
140 lines
5.9 KiB
Plaintext
phpgw_msg_pop3.inc.php
|
|
Itzchak Rehberg <izzy@qumran.org>
|
|
v1.0, 07 August 2000
|
|
|
|
documentation of the pop3 "msg" class
|
|
______________________________________________________________________
|
|
|
|
Table of Contents
|
|
|
|
|
|
1. Why this pop class?
|
|
2. Function reference
|
|
2.1. function pop_close($stream,$flags="")
|
|
2.2. function pop_delete($stream,$msg_num,$flags="")
|
|
2.3. function pop_fetchbody($stream,$msgnr,$partnr="",$flags="")
|
|
2.4. function pop_fetchstructure($stream,$msg_num,$flags="")
|
|
2.5. function pop_header($stream,$msg_nr,$fromlength="",$tolength="",
|
|
$defaulthost="")
|
|
2.6. function pop_mailboxmsginfo($stream)
|
|
2.7. function pop_sort($stream,$criteria,$reverse="",$options="",
|
|
$msg_info="")
|
|
3. Additional functionality
|
|
|
|
|
|
______________________________________________________________________
|
|
|
|
|
|
1. Why this pop class?
|
|
|
|
You may ask, why we use another pop class - php's imap_*() functions
|
|
would work on pop3, too. Well, that may be true - but there are lots
|
|
of folks out there having their php *not* compiled --with-imap, and
|
|
some of them feel unable doing such. So it's the easiest thing to have
|
|
an own pop3 class built on straight socket calls - and since I already
|
|
did the same writing the smtp "send" class... And by the way this pop3
|
|
class will have some advantages over php's imap_*() functions...
|
|
|
|
We named this class "msg" instead of "pop3", since we use another
|
|
class with the same structure for imap. Additionally to imap_open()
|
|
(or pop_open() in this case) we have the "wrapper method" open(),
|
|
which allows us just to decide on user configuration wether using
|
|
imap or pop and then just to include the appropriate file, using the
|
|
same function/method calls for both.
|
|
|
|
______________________________________________________________________
|
|
|
|
|
|
2. Function reference
|
|
|
|
When I built up this pop class, I felt it an important issue to have
|
|
it most compatible in syntax to the imap_*() functions, so we could
|
|
adapt it easily into phpGroupWare. So if I made some improvements, as
|
|
e.g. to the pop_sort() method, I did it in a manner, that one still
|
|
can call it the same way as he would call imap_sort() (in this case).
|
|
|
|
Due to this fact I have *not* to explain the syntax of each single
|
|
method here (for this, please refer to your php manual). I will just
|
|
list up differences one has to keep in mind when using them.
|
|
|
|
The first difference is, that this is a class. So before you can use
|
|
the functions, you have to create an instance of this class, e.g.
|
|
|
|
$mypop3 = new msg;
|
|
$mypop3->open($mailbox,$username,$password,$flags); // or:
|
|
$mypop3->pop_open($mailbox,$username,$password,$flags);
|
|
|
|
both methods do the same - see "wrapper" above in section 1. So if you
|
|
want to use this pop3 class outside the phpGroupWare environment, you
|
|
may just want to strip these wrapper methods off the file and just use
|
|
the pop_*() methods themselves.
|
|
|
|
Not all imap_*() funcs have their (working) pendant here, since pop3
|
|
does not support all the features imap has (e.g. multiple folders).
|
|
Those methods (e.g. pop_expunge()) just return a default value (here
|
|
false) and do nothing. They are just kept here in case one of our
|
|
wrapper methods tries to call them :) These methods are not listed in
|
|
this document, neither are those who are fully described by their imap
|
|
pendant.
|
|
|
|
|
|
2.1. function pop_close($stream,$flags="")
|
|
|
|
$flags is not used here and won't ever be (makes no sense), but just
|
|
kept for compatibility.
|
|
|
|
2.2. function pop_delete($stream,$msg_num,$flags="")
|
|
|
|
Does a real delete - not just marks as deleted (as in imap_delete),
|
|
since this function is not available to pop3 (in fact the mail is
|
|
deleted by calling pop_close() afterwards - but there's no undelete)
|
|
|
|
2.3. function pop_fetchbody($stream,$msgnr,$partnr="",$flags="")
|
|
|
|
$partnr and $flags are ignored and just put here for compatibility
|
|
purposes to imap_fetchbody
|
|
|
|
2.4. function pop_fetchstructure($stream,$msg_num,$flags="")
|
|
|
|
$flags is not used here (yet).
|
|
|
|
2.5. function pop_header($stream,$msg_nr,$fromlength="",$tolength="",
|
|
$defaulthost="")
|
|
|
|
Not all information you find returned by imap_header is included here,
|
|
some fields of the array just contain empty values, since these are
|
|
not available in pop. Note further, that just the first two params of
|
|
the method are evaluated here. $info[date] contains the date as it
|
|
appears in the msg header. The method returns false if message does
|
|
not exist.
|
|
|
|
2.6. function pop_mailboxmsginfo($stream)
|
|
|
|
Only Nmsgs and Size contain real values. All other fields are empty
|
|
and just in here for compatibility (those informations you'ld expect
|
|
in there is not retainable from pop3 servers - e.g. Recent or Unread)
|
|
|
|
2.7. function pop_sort($stream,$criteria,$reverse="",$options="")
|
|
|
|
$options is not used here. For speed optimizing this method will make
|
|
use of an array stored within the class (and temporary "out-sourced"
|
|
to a file, since else it would be lost after the page is once built),
|
|
holding all the header infos needed to fulfill the sort task. So it
|
|
only retrieves new header info when either the page is called for the
|
|
very first time that session, the count of messages reported by the
|
|
array differs from the count reported by the pop3 server (which in
|
|
this case would be the same ;), or the class variable $force_check is
|
|
set to true (which is done automatically by pop_delete, e.g.) - thus
|
|
not only saving bandwith but gaining additional speed (you will really
|
|
feel this with several hundreds of mails in your mailbox :)
|
|
|
|
______________________________________________________________________
|
|
|
|
|
|
3. Additional functionality
|
|
|
|
The msg->err Array is available as described for the smtp "send"
|
|
method.
|
|
|
|
The $msg->logout() method does remove the temp file.
|