include/ptlib/mail.h

   1 /*
   2  * mail.h
   3  *
   4  * Electronic Mail abstraction class.
   5  *
   6  * Portable Windows Library
   7  *
   8  * Copyright (c) 1993-1998 Equivalence Pty. Ltd.
   9  *
  10  * The contents of this file are subject to the Mozilla Public License
  11  * Version 1.0 (the "License"); you may not use this file except in
  12  * compliance with the License. You may obtain a copy of the License at
  13  * http://www.mozilla.org/MPL/
  14  *
  15  * Software distributed under the License is distributed on an "AS IS"
  16  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
  17  * the License for the specific language governing rights and limitations
  18  * under the License.
  19  *
  20  * The Original Code is Portable Windows Library.
  21  *
  22  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
  23  *
  24  * Portions are Copyright (C) 1993 Free Software Foundation, Inc.
  25  * All Rights Reserved.
  26  *
  27  * Contributor(s): ______________________________________.
  28  *
  29  * $Log$
  30  * Revision 1.13  2003/09/17 05:41:58  csoutheren
  31  * Removed recursive includes
  32  *
  33  * Revision 1.12  2003/09/17 01:18:02  csoutheren
  34  * Removed recursive include file system and removed all references
  35  * to deprecated coooperative threading support
  36  *
  37  * Revision 1.11  2002/09/16 01:08:59  robertj
  38  * Added #define so can select if #pragma interface/implementation is used on
  39  *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
  40  *
  41  * Revision 1.10  2001/05/22 12:49:32  robertj
  42  * Did some seriously wierd rewrite of platform headers to eliminate the
  43  *   stupid GNU compiler warning about braces not matching.
  44  *
  45  * Revision 1.9  1999/03/09 02:59:50  robertj
  46  * Changed comments to doc++ compatible documentation.
  47  *
  48  * Revision 1.8  1999/02/16 08:12:00  robertj
  49  * MSVC 6.0 compatibility changes.
  50  *
  51  * Revision 1.7  1999/02/10 13:20:53  robertj
  52  * Added ability to have attachments in mail messages.
  53  *
  54  * Revision 1.6  1998/09/23 06:20:51  robertj
  55  * Added open source copyright license.
  56  *
  57  * Revision 1.5  1997/05/16 12:14:08  robertj
  58  * Added BCC capability to send mail.
  59  *
  60  * Revision 1.4  1995/07/02 01:19:46  robertj
  61  * Change GetMessageBidy to return BOOL and have body string as
  62  *   parameter, due to slight change in semantics for large bodies.
  63  *
  64  * Revision 1.3  1995/06/17 00:42:22  robertj
  65  * Added mail reading interface.
  66  * Changed name to simply PMail
  67  *
  68  * Revision 1.2  1995/04/01 08:27:57  robertj
  69  * Added GUI support.
  70  *
  71  * Revision 1.1  1995/03/14  12:44:11  robertj
  72  * Initial revision
  73  *
  74  */
  75
  76 #ifndef _PMAIL
  77 #define _PMAIL
  78
  79 #ifdef P_USE_PRAGMA
  80 #pragma interface
  81 #endif
  82
  83 #ifdef _WIN32
  84
  85 #  ifndef P_HAS_MAPI
  86 #  define P_HAS_MAPI 1
  87 #  endif
  88
  89 #  ifndef P_HAS_CMC
  90 #  define P_HAS_CMC 1
  91 #  endif
  92
  93 #  if P_HAS_MAPI
  94 #  include <mapi.h>
  95 #  endif
  96
  97 #  if P_HAS_CMC
  98 #  include <xcmc.h>
  99 #  endif
 100
 101 #endif  // _WIN32
 102
 103
 104 /**This class establishes a mail session with the platforms mail system.
 105 */
 106 class PMail : public PObject
 107 {
 108   PCLASSINFO(PMail, PObject);
 109
 110   public:
 111   /**@name Construction */
 112   //@{
 113     /**Create a mail session. It is initially not logged in.
 114      */
 115     PMail();
 116
 117     /**Create a mail session.
 118        Attempt to log in using the parameters provided.
 119      */
 120     PMail(
 121       const PString & username,  /// User withing mail system to use.
 122       const PString & password   /// Password for user in mail system.
 123     );
 124
 125     /**Create a mail session.
 126        Attempt to log in using the parameters provided.
 127      */
 128     PMail(
 129       const PString & username,  /// User withing mail system to use.
 130       const PString & password,  /// Password for user in mail system.
 131       const PString & service
 132       /**A platform dependent string indicating the location of the underlying
 133          messaging service, eg the path to a message store or node name of the
 134          mail server.
 135        */
 136     );
 137
 138
 139     virtual ~PMail();
 140     /* Destroy the mail session, logging off the mail system if necessary.
 141      */
 142   //@}
 143
 144   /**@name Log in/out functions */
 145   //@{
 146     /**Attempt to log on to the mail system using the parameters provided.
 147
 148        @return
 149        TRUE if successfully logged on.
 150      */
 151     BOOL LogOn(
 152       const PString & username,  /// User withing mail system to use.
 153       const PString & password   /// Password for user in mail system.
 154     );
 155
 156     /**Attempt to log on to the mail system using the parameters provided.
 157
 158        @return
 159        TRUE if successfully logged on.
 160      */
 161     BOOL LogOn(
 162       const PString & username,  /// User withing mail system to use.
 163       const PString & password,  /// Password for user in mail system.
 164       const PString & service
 165       /**A platform dependent string indicating the location of the underlying
 166          messaging service, eg the path to a message store or node name of the
 167          mail server.
 168        */
 169     );
 170
 171     /**Log off from the mail system.
 172
 173        @return
 174        TRUE if successfully logged off.
 175      */
 176     virtual BOOL LogOff();
 177
 178     /**Determine if the mail session is active and logged into the mail system.
 179
 180        @return
 181        TRUE if logged into the mail system.
 182      */
 183     BOOL IsLoggedOn() const;
 184   //@}
 185
 186   /**@name Send message functions */
 187   //@{
 188     /**Send a new simple mail message.
 189
 190        @return
 191        TRUE if the mail message was successfully queued. Note that this does
 192        {\bf not} mean that it has been delivered.
 193      */
 194     BOOL SendNote(
 195       const PString & recipient,  /// Name of recipient of the mail message.
 196       const PString & subject,    /// Subject name for the mail message.
 197       const char * body           /// Text body of the mail message.
 198     );
 199
 200     /**Send a new simple mail message.
 201
 202        @return
 203        TRUE if the mail message was successfully queued. Note that this does
 204        {\bf not} mean that it has been delivered.
 205      */
 206     BOOL SendNote(
 207       const PString & recipient,  /// Name of recipient of the mail message.
 208       const PString & subject,    /// Subject name for the mail message.
 209       const char * body,          /// Text body of the mail message.
 210       const PStringList & attachments
 211                         /// List of files to attach to the mail message.
 212     );
 213
 214     /**Send a new simple mail message.
 215
 216        @return
 217        TRUE if the mail message was successfully queued. Note that this does
 218        {\bf not} mean that it has been delivered.
 219      */
 220     BOOL SendNote(
 221       const PString & recipient,  /// Name of recipient of the mail message.
 222       const PStringList & carbonCopies, /// Name of CC recipients.
 223       const PStringList & blindCarbons, /// Name of BCC recipients.
 224       const PString & subject,        /// Subject name for the mail message.
 225       const char * body,              /// Text body of the mail message.
 226       const PStringList & attachments
 227                         /// List of files to attach to the mail message.
 228     );
 229   //@}
 230
 231   /**@name Read message functions */
 232   //@{
 233     /**Get a list of ID strings for all messages in the mail box.
 234
 235        @return
 236        An array of ID strings.
 237      */
 238     PStringArray GetMessageIDs(
 239       BOOL unreadOnly = TRUE    /// Only get the IDs for unread messages.
 240     );
 241
 242     /// Message header for each mail item.
 243     struct Header {
 244       /// Subject for message.
 245       PString  subject;
 246       /// Full name of message originator.
 247       PString  originatorName;
 248       /// Return address of message originator.
 249       PString  originatorAddress;
 250       /// Time message received.
 251       PTime    received;
 252     };
 253
 254     /**Get the header information for a message.
 255
 256        @return
 257        TRUE if header information was successfully obtained.
 258      */
 259     BOOL GetMessageHeader(
 260       const PString & id,      /// Identifier of message to get header.
 261       Header & hdrInfo         /// Header info for the message.
 262     );
 263
 264     /**Get the body text for a message into the #body# string
 265        parameter.
 266
 267        Note that if the body text for the mail message is very large, the
 268        function will return FALSE. To tell between an error getting the message
 269        body and having a large message body the #GetErrorCode()# function
 270        must be used.
 271
 272        To get a large message body, the #GetMessageAttachments()# should
 273        be used with the #includeBody# parameter set to TRUE so that
 274        the message body is placed into a disk file.
 275
 276        @return
 277        TRUE if the body text was retrieved, FALSE if the body was too large or
 278        some other error occurred.
 279      */
 280     BOOL GetMessageBody(
 281       const PString & id,      /// Identifier of message to get body.
 282       PString & body,          /// Body text of mail message.
 283       BOOL markAsRead = FALSE  /// Mark the message as read.
 284     );
 285
 286     /**Get all of the attachments for a message as disk files.
 287
 288        @return
 289        TRUE if attachments were successfully obtained.
 290      */
 291     BOOL GetMessageAttachments(
 292       const PString & id,       /// Identifier of message to get attachments.
 293       PStringArray & filenames, /// File names for each attachment.
 294       BOOL includeBody = FALSE, /// Include the message body as first attachment
 295       BOOL markAsRead = FALSE   /// Mark the message as read
 296     );
 297
 298     /**Mark the message as read.
 299
 300        @return
 301        TRUE if message was successfully marked as read.
 302      */
 303     BOOL MarkMessageRead(
 304       const PString & id      /// Identifier of message to get header.
 305     );
 306
 307     /**Delete the message from the system.
 308
 309        @return
 310        TRUE if message was successfully deleted.
 311      */
 312     BOOL DeleteMessage(
 313       const PString & id      /// Identifier of message to get header.
 314     );
 315   //@}
 316
 317   /**@name User look up functions */
 318   //@{
 319     /// Result of a lookup operation with the #LookUp()# function.
 320     enum LookUpResult {
 321       /// User name is unknown in mail system.
 322       UnknownUser,
 323       /// User is ambiguous in mail system.
 324       AmbiguousUser,
 325       /// User is a valid, unique name in mail system.
 326       ValidUser,
 327       /// An error occurred during the look up
 328       LookUpError
 329     };
 330
 331     /**Look up the specified name and verify that they are a valid address in
 332        the mail system.
 333
 334        @return
 335        result of the name lookup.
 336      */
 337     LookUpResult LookUp(
 338       const PString & name,  /// Name to look up.
 339       PString * fullName = NULL
 340       /**String to receive full name of user passed in #name#. If
 341          NULL then the full name is {\bf not} returned.
 342        */
 343     );
 344   //@}
 345
 346   /**@name Error functions */
 347   //@{
 348     /**Get the internal error code for the last error by a function in this
 349        mail session.
 350
 351        @return
 352        integer error code for last operation.
 353      */
 354     int GetErrorCode() const;
 355
 356     /**Get the internal error description for the last error by a function in
 357        this mail session.
 358
 359        @return
 360        string error text for last operation.
 361      */
 362     PString GetErrorText() const;
 363   //@}
 364
 365
 366   protected:
 367     void Construct();
 368     // Common construction code.
 369
 370     /// Flag indicating the session is active.
 371     BOOL loggedOn;
 372
 373
 374 // Include platform dependent part of class
 375 #ifdef _WIN32
 376 #include "msos/ptlib/mail.h"
 377 #else
 378 #include "unix/ptlib/mail.h"
 379 #endif
 380 };
 381
 382 #endif
 383
 384 // End Of File ///////////////////////////////////////////////////////////////