PageRenderTime 38ms CodeModel.GetById 14ms app.highlight 17ms RepoModel.GetById 1ms app.codeStats 0ms

/src/yolk-email-composer.ads

http://github.com/ThomasLocke/yolk
Ada | 152 lines | 76 code | 16 blank | 60 comment | 0 complexity | fd34ab7a9d4059ddbd3e62560473fb89 MD5 | raw file
  1-------------------------------------------------------------------------------
  2--                                                                           --
  3--                   Copyright (C) 2010-, Thomas Løcke                   --
  4--                                                                           --
  5--  This library is free software;  you can redistribute it and/or modify    --
  6--  it under terms of the  GNU General Public License  as published by the   --
  7--  Free Software  Foundation;  either version 3,  or (at your  option) any  --
  8--  later version. This library is distributed in the hope that it will be   --
  9--  useful, but WITHOUT ANY WARRANTY;  without even the implied warranty of  --
 10--  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.                     --
 11--                                                                           --
 12--  As a special exception under Section 7 of GPL version 3, you are         --
 13--  granted additional permissions described in the GCC Runtime Library      --
 14--  Exception, version 3.1, as published by the Free Software Foundation.    --
 15--                                                                           --
 16--  You should have received a copy of the GNU General Public License and    --
 17--  a copy of the GCC Runtime Library Exception along with this program;     --
 18--  see the files COPYING3 and COPYING.RUNTIME respectively.  If not, see    --
 19--  <http://www.gnu.org/licenses/>.                                          --
 20--                                                                           --
 21-------------------------------------------------------------------------------
 22
 23package Yolk.Email.Composer is
 24
 25   procedure Add_Custom_Header
 26     (ES      : in out Structure;
 27      Name    : in     String;
 28      Value   : in     String;
 29      Charset : in     Character_Set := US_ASCII);
 30   --  Add a custom header to the ES email object. Custom headers are usually
 31   --  things like User-Agent, Organization or X- headers.
 32
 33   procedure Add_File_Attachment
 34     (ES           : in out Structure;
 35      Path_To_File : in     String;
 36      Charset      : in     Character_Set := US_ASCII);
 37   --  Add a file attachment to the ES email object. These are _always_ BASE64
 38   --  encoded. At this point we do not check whether the file actually exists,
 39   --  so anything can be added, even an empty String Path_To_File.
 40
 41   procedure Add_From
 42     (ES      : in out Structure;
 43      Address : in     String;
 44      Name    : in     String := "";
 45      Charset : in     Character_Set := US_ASCII);
 46   --  Add a From mailbox to the email. If multiple From mailboxes are added,
 47   --  then a subsequent call to Set_Sender is required, as per RFC 5322.
 48
 49   procedure Add_Recipient
 50     (ES      : in out Structure;
 51      Address : in     String;
 52      Name    : in     String := "";
 53      Kind    : in     Recipient_Kind := To;
 54      Charset : in     Character_Set := US_ASCII);
 55   --  Add a recipient to the email.
 56
 57   procedure Add_Reply_To
 58     (ES      : in out Structure;
 59      Address : in     String;
 60      Name    : in     String := "";
 61      Charset : in     Character_Set := US_ASCII);
 62   --  Reply-To indicates the address(es) to which the author of the message
 63   --  suggests that replies be sent. In the absence of Reply-To, the default
 64   --  is to send replies to the From mailboxes.
 65
 66   procedure Add_SMTP_Server
 67     (ES   : in out Structure;
 68      Host : in     String;
 69      Port : in     Positive := 25);
 70   --  Set the SMTP servers to use when sending an email. The first server
 71   --  added is the first server tried. If the first server fails, then the
 72   --  system moves on to the next server, until it either runs out of SMTP
 73   --  servers to try, or it manages to send the email.
 74
 75   function Is_Send
 76     (ES : in Structure)
 77      return Boolean;
 78   --  Return True if the email has been successfully delivered to one of the
 79   --  set SMTP servers. False otherwise.
 80
 81   procedure Send
 82     (ES : in out Structure);
 83   --  Process the ES object. This entails composing the email source and
 84   --  sending it via one of the set SMTP servers.
 85   --  Exceptions:
 86   --    Attachment_File_Not_Found
 87   --    No_Address_Set
 88   --    No_Sender_Set_With_Multiple_From
 89   --    No_SMTP_Host_Set
 90
 91   procedure Send
 92     (ES           : in out Structure;
 93      From_Address : in     String;
 94      From_Name    : in     String := "";
 95      To_Address   : in     String;
 96      To_Name      : in     String := "";
 97      Subject      : in     String;
 98      Text_Part    : in     String;
 99      SMTP_Server  : in     String := "localhost";
100      SMTP_Port    : in     Positive := 25;
101      Charset      : in     Character_Set := US_ASCII);
102   --  Convenience wrapper for Send (ES : in out Email_Structure) for Text only
103   --  emails.
104   --  Exceptions raised by the "parent" Send procdure are passively propagated
105   --  up through the call stack to the caller of this Send procedure.
106
107   procedure Send
108     (ES           : in out Structure;
109      From_Address : in     String;
110      From_Name    : in     String := "";
111      To_Address   : in     String;
112      To_Name      : in     String := "";
113      Subject      : in     String;
114      Text_Part    : in     String;
115      HTML_Part    : in     String;
116      SMTP_Server  : in     String := "localhost";
117      SMTP_Port    : in     Positive := 25;
118      Charset      : in     Character_Set := US_ASCII);
119   --  Convenience wrapper for Send (ES : in out Email_Structure) for Text and
120   --  HTML multipart emails.
121   --  Exceptions raised by the "parent" Send procdure are passively propagated
122   --  up through the call stack to the caller of this Send procedure.
123
124   procedure Set_HTML_Part
125     (ES      : in out Structure;
126      Part    : in     String;
127      Charset : in     Character_Set := US_ASCII);
128   --  When adding a HTML part to an email, it is automatically converted to
129   --  a multipart message. If no Text part is added, an empty one will be
130   --  created automatically.
131
132   procedure Set_Sender
133     (ES      : in out Structure;
134      Address : in     String;
135      Name    : in     String := "";
136      Charset : in     Character_Set := US_ASCII);
137   --  If an email has multiple From addresses, then it is required, as per
138   --  RFC 5322, to set a single Sender.
139
140   procedure Set_Subject
141     (ES      : in out Structure;
142      Subject : in     String;
143      Charset : in     Character_Set := US_ASCII);
144   --  Add a Subject to the email.
145
146   procedure Set_Text_Part
147     (ES      : in out Structure;
148      Part    : in     String;
149      Charset : in     Character_Set := US_ASCII);
150   --  Add the Text part to an email.
151
152end Yolk.Email.Composer;