File : src/aws-pop.ads


------------------------------------------------------------------------------
--                              Ada Web Server                              --
--                       P O P - Post Office Protocol                       --
--                                                                          --
--                         Copyright (C) 2003-2004                          --
--                                ACT-Europe                                --
--                                                                          --
--  Authors: Dmitriy Anisimkov - Pascal Obry                                --
--                                                                          --
--  This library is free software; you can redistribute it and/or modify    --
--  it under the terms of the GNU General Public License as published by    --
--  the Free Software Foundation; either version 2 of the License, or (at   --
--  your option) any later version.                                         --
--                                                                          --
--  This library is distributed in the hope that it will be useful, but     --
--  WITHOUT ANY WARRANTY; without even the implied warranty of              --
--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU       --
--  General Public License for more details.                                --
--                                                                          --
--  You should have received a copy of the GNU General Public License       --
--  along with this library; if not, write to the Free Software Foundation, --
--  Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA.          --
--                                                                          --
--  As a special exception, if other files instantiate generics from this   --
--  unit, or you link this unit with other files to produce an executable,  --
--  this  unit  does not  by itself cause  the resulting executable to be   --
--  covered by the GNU General Public License. This exception does not      --
--  however invalidate any other reasons why the executable file  might be  --
--  covered by the  GNU Public License.                                     --
------------------------------------------------------------------------------

--  $Id: aws-pop.ads,v 1.8 2004/02/08 20:57:51 obry Exp $

with Ada.Finalization;
with Ada.Strings.Unbounded;

with AWS.Headers;
with AWS.Net.Std;
with AWS.Resources.Streams;

package AWS.POP is

   use Ada.Strings.Unbounded;

   POP_Error : exception;
   --  Raised by all routines when an error has been detected

   -------------
   -- Mailbox --
   -------------

   Default_POP_Port : constant := 110;

   type Mailbox is private;

   type Authenticate_Mode is (Clear_Text, APOP);

   function Initialize
     (Server_Name  : in String;
      User         : in String;
      Password     : in String;
      Authenticate : in Authenticate_Mode := Clear_Text;
      Port         : in Positive          := Default_POP_Port)
      return Mailbox;
   --  Connect on the given Port to Server_Name and open User's Mailbox. This
   --  mailbox object will be used to retrieve messages.

   procedure Close (Mailbox : in POP.Mailbox);
   --  Close mailbox

   function User_Name (Mailbox : in POP.Mailbox) return String;
   --  Returns User's name for this mailbox

   function Message_Count (Mailbox : in POP.Mailbox) return Natural;
   --  Returns the number of messages in the user's mailbox

   function Size (Mailbox : in POP.Mailbox) return Natural;
   --  Returns the total size in bytes of the user's mailbox

   -------------
   -- Message --
   -------------

   type Message is tagged private;

   function Get
     (Mailbox : in POP.Mailbox;
      N       : in Positive;
      Remove  : in Boolean     := False)
      return Message;
   --  Retrieve Nth message from the mailbox, let the message on the mailbox
   --  if Remove is False.

   procedure Delete
     (Mailbox : in POP.Mailbox;
      N       : in Positive);
   --  Detele message number N from the mailbox

   function Get_Header
     (Mailbox : in POP.Mailbox;
      N       : in Positive)
      return Message;
   --  Retrieve headers for the Nth message from the mailbox, let the message
   --  on the mailbox. This is useful to build a quick summary of the mailbox.

   generic
      with procedure Action
        (Message : in     POP.Message;
         Index   : in     Positive;
         Quit    : in out Boolean);
   procedure For_Every_Message
     (Mailbox : in POP.Mailbox;
      Remove  : in Boolean := False);
   --  Calls Action for each message read on the mailbox, delete the message
   --  from the mailbox if Remove is True. Set Quit to True to stop the
   --  iterator. Index is the mailbox's message index.

   generic
      with procedure Action
        (Message : in     POP.Message;
         Index   : in     Positive;
         Quit    : in out Boolean);
   procedure For_Every_Message_Header (Mailbox : in POP.Mailbox);
   --  Calls Action for each message read on the mailbox. Only the headers are
   --  read from the mailbox. Set Quit to True to stop the iterator. Index is
   --  the mailbox's message index.

   function Size (Message : in POP.Message) return Natural;
   --  Returns the message size in bytes

   function Content (Message : in POP.Message) return Unbounded_String;
   --  Returns message's content as an Unbounded_String. Each line are
   --  separated by CR+LF characters.

   function From (Message : in POP.Message) return String;
   --  Returns From header value

   function CC (Message : in POP.Message; N : Natural := 0) return String;
   --  Retruns the CC header value. If N = 0 returns all recipients separated
   --  by a coma otherwise it returns the Nth CC recipient.

   function CC_Count (Message : in POP.Message) return Natural;
   --  Returns the number of CC recipient for Message. Returns 0 if there is
   --  no CC for this message.

   function Subject (Message : in POP.Message) return String;
   --  Returns Subject header value

   function Date (Message : in POP.Message) return String;
   --  Returns Date header value

   function Header
     (Message : in POP.Message;
      Header  : in String)
      return String;
   --  Returns header value for header named Header, returns the empty string
   --  if such header does not exist.

   ----------------
   -- Attachment --
   ----------------

   type Attachment is private;

   function Attachment_Count (Message : in POP.Message) return Natural;
   --  Returns the number of Attachments into Message

   function Get
     (Message    : in POP.Message'Class;
      Attachment : in Positive)
      return Attachment;
   --  Returns the Nth Attachment for Message, Raises Constraint_Error if
   --  there is not such attachment.

   generic
      with procedure Action
        (Attachment : in     POP.Attachment;
         Index      : in     Positive;
         Quit       : in out Boolean);
   procedure For_Every_Attachment (Message : in POP.Message);
   --  Calls action for every Attachment in Message. Stop iterator if Quit is
   --  set to True, Quit is set to False by default.

   function Content
     (Attachment : in POP.Attachment)
      return AWS.Resources.Streams.Stream_Access;
   --  Returns Attachment's content as a memory stream. Note that the stream
   --  has already been decoded. Most attachments are MIME Base64 encoded.

   function Content (Attachment : in POP.Attachment) return Unbounded_String;
   --  Returns Attachment's content as an Unbounded_String. This routine must
   --  only be used for non file attachments. Raises Constraint_Error if
   --  called for a file attachment.

   function Filename (Attachment : in POP.Attachment) return String;
   --  Returns the Attachment filename or the empty string if it is not a file
   --  but an embedded message.

   function Is_File (Attachment : in POP.Attachment) return Boolean;
   --  Returns True if Attachment is a file

   procedure Write (Attachment : in POP.Attachment; Directory : in String);
   --  Writes Attachment's file content into Directory. This must only be used
   --  for a file attachment.

private

   use Ada;

   -------------
   -- Mailbox --
   -------------

   type Mailbox is record
      Sock          : Net.Std.Socket_Type;
      Name          : Unbounded_String;
      User_Name     : Unbounded_String;
      Message_Count : Natural;
      Size          : Natural;
   end record;

   type Count_Access is access Natural;

   type Attachment_Access is access Attachment;

   -------------
   -- Message --
   -------------

   type Message is new Finalization.Controlled with record
      Ref_Count   : Count_Access;
      Size        : Natural;
      Headers     : AWS.Headers.List;
      Content     : Unbounded_String;
      Attachments : Attachment_Access;
      Last        : Attachment_Access;
   end record;

   procedure Initialize (Message : in out POP.Message);
   procedure Adjust     (Message : in out POP.Message);
   procedure Finalize   (Message : in out POP.Message);

   ----------------
   -- Attachment --
   ----------------

   type Attachment is new Finalization.Controlled with record
      Ref_Count : Count_Access;
      Headers   : AWS.Headers.List;
      Content   : AWS.Resources.Streams.Stream_Access;
      Filename  : Unbounded_String;
      Next      : Attachment_Access;
   end record;

   procedure Initialize (Attachment : in out POP.Attachment);
   procedure Adjust     (Attachment : in out POP.Attachment);
   procedure Finalize   (Attachment : in out POP.Attachment);

end AWS.POP;