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.