inetmail.h

开源代码的pwlib的1.10.0版本,使用openh323的1.18.0版本毕备

/*
 * inetmail.h
 *
 * Internet Mail channel classes
 * Simple Mail Transport Protocol & Post Office Protocol v3
 *
 * Portable Windows Library
 *
 * Copyright (c) 1993-2002 Equivalence Pty. Ltd.
 *
 * The contents of this file are subject to the Mozilla Public License
 * Version 1.0 (the "License"); you may not use this file except in
 * compliance with the License. You may obtain a copy of the License at
 * http://www.mozilla.org/MPL/
 *
 * Software distributed under the License is distributed on an "AS IS"
 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
 * the License for the specific language governing rights and limitations
 * under the License.
 *
 * The Original Code is Portable Windows Library.
 *
 * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
 *
 * Contributor(s): Federico Pinna and Reitek S.p.A.
 *
 * $Log: inetmail.h,v $
 * Revision 1.20  2005/11/30 12:47:37  csoutheren
 * Removed tabs, reformatted some code, and changed tags for Doxygen
 *
 * Revision 1.19  2004/04/21 00:29:55  csoutheren
 * Added SASL authentication to PPOP3Client and PSMTPClient
 * Thanks to Federico Pinna and Reitek S.p.A.
 *
 * Revision 1.18  2002/11/06 22:47:24  robertj
 * Fixed header comment (copyright etc)
 *
 * Revision 1.17  2002/09/16 01:08:59  robertj
 * Added #define so can select if #pragma interface/implementation is used on
 *   platform basis (eg MacOS) rather than compiler, thanks Robert Monaghan.
 *
 * Revision 1.16  2000/11/10 01:08:11  robertj
 * Added content transfer encoding and automatic base64 translation.
 *
 * Revision 1.15  2000/11/09 06:01:58  robertj
 * Added MIME version and content disposition to RFC822 class.
 *
 * Revision 1.14  2000/11/09 05:50:23  robertj
 * Added RFC822 aware channel class for doing internet mail.
 *
 * Revision 1.13  2000/06/21 01:01:21  robertj
 * AIX port, thanks Wolfgang Platzer ([e-mail]).
 *
 * Revision 1.12  2000/06/19 11:33:53  robertj
 * Fixed incorrect comment documentation
 *
 * Revision 1.11  1999/03/09 08:01:46  robertj
 * Changed comments for doc++ support (more to come).
 *
 * Revision 1.10  1999/02/16 08:07:10  robertj
 * MSVC 6.0 compatibility changes.
 *
 * Revision 1.9  1998/11/30 02:50:51  robertj
 * New directory structure
 *
 * Revision 1.8  1998/09/23 06:19:36  robertj
 * Added open source copyright license.
 *
 * Revision 1.7  1996/12/21 01:24:15  robertj
 * Added missing open message to pop server.
 *
 * Revision 1.6  1996/09/16 12:57:45  robertj
 * Removed redundant functions.
 *
 * Revision 1.5  1996/09/14 13:17:59  robertj
 * Renamed file and changed to be a protocol off new indirect channel to separate
 *   the protocol from the low level byte transport channel.
 *
 * Revision 1.4  1996/07/27 04:14:49  robertj
 * Redesign and reimplement of mail sockets.
 *
 * Revision 1.3  1996/06/28 13:16:32  robertj
 * Changed SMTP incoming message handler so can tell when started, processing or ended message.
 *
 * Revision 1.2  1996/03/16 04:38:24  robertj
 * Added ParseReponse() for splitting reponse line into code and info.
 *
 * Revision 1.1  1996/01/23 13:04:20  robertj
 * Initial revision
 *
 * Revision 1.3  1995/06/17 11:12:15  robertj
 * Documentation update.
 *
 * Revision 1.2  1995/06/17 00:39:53  robertj
 * More implementation.
 *
 * Revision 1.1  1995/06/04 13:17:16  robertj
 * Initial revision
 *
 */

#ifndef _PMAILPROTOCOL
#define _PMAILPROTOCOL

#ifdef P_USE_PRAGMA
#pragma interface
#endif

#include <ptclib/inetprot.h>
#include <ptclib/mime.h>

class PSocket;


//////////////////////////////////////////////////////////////////////////////
// PSMTP

/** A TCP/IP socket for the Simple Mail Transfer Protocol.

   When acting as a client, the procedure is to make the connection to a
   remote server, then to send a message using the following procedure:
      <PRE><CODE>
      PSMTPClient mail("mailserver");
      if (mail.IsOpen()) {
        mail.BeginMessage("[e-mail]", "[e-mail]");
        mail.Write(myMessage);
        if (!mail.EndMessage())
          PError << "Mail send failed." << endl;
      }
      else
         PError << "Mail conection failed." << endl;
      </PRE></CODE>

    When acting as a server, a descendant class would be created to override
    at least the <A>LookUpName()</A> and <A>HandleMessage()</A> functions.
    Other functions may be overridden for further enhancement to the sockets
    capabilities, but these two will give a basic SMTP server functionality.

    The server socket thread would continuously call the
    <A>ProcessMessage()</A> function until it returns FALSE. This will then
    call the appropriate virtual function on parsing the SMTP protocol.
*/
class PSMTP : public PInternetProtocol
{
  PCLASSINFO(PSMTP, PInternetProtocol)

  public:
  // New functions for class.
    enum Commands {
      HELO, EHLO, QUIT, HELP, NOOP,
      TURN, RSET, VRFY, EXPN, RCPT,
      MAIL, SEND, SAML, SOML, DATA,
      AUTH, NumCommands
    };

  protected:
    PSMTP();
    // Create a new SMTP protocol channel.
};


/** A TCP/IP socket for the Simple Mail Transfer Protocol.

   When acting as a client, the procedure is to make the connection to a
   remote server, then to send a message using the following procedure:
      <PRE><CODE>
      PSMTPSocket mail("mailserver");
      if (mail.IsOpen()) {
        mail.BeginMessage("[e-mail]", "[e-mail]");
        mail.Write(myMessage);
        if (!mail.EndMessage())
          PError << "Mail send failed." << endl;
      }
      else
         PError << "Mail conection failed." << endl;
      </PRE></CODE>
*/
class PSMTPClient : public PSMTP
{
  PCLASSINFO(PSMTPClient, PSMTP)

  public:
    /** Create a TCP/IP SMPTP protocol socket channel. The parameterless form
       creates an unopened socket, the form with the <CODE>address</CODE>
       parameter makes a connection to a remote system, opening the socket. The
       form with the <CODE>socket</CODE> parameter opens the socket to an
       incoming call from a "listening" socket.
     */
    PSMTPClient();

    /** Destroy the channel object. This will close the channel and as a
       client, QUIT from remote SMTP server.
     */
    ~PSMTPClient();


  // Overrides from class PChannel.
    /** Close the socket, and if connected as a client, QUITs from server.

       @return
       TRUE if the channel was closed and the QUIT accepted by the server.
     */
    virtual BOOL Close();


  // New functions for class.
    /** Log into the SMTP server using the mailbox and access codes specified.
        Login is actually attempted only if the server supports SASL authentication
        and a common method is found

       @return
       TRUE if logged in.
     */
    BOOL LogIn(
      const PString & username,   ///< User name on remote system.
      const PString & password    ///< Password for user name.
    );

    /** Begin transmission of a message using the SMTP socket as a client. This
       negotiates with the remote server and establishes the protocol state
       for data transmission. The usual Write() or stream commands may then
       be used to transmit the data itself.

       @return
       TRUE if message was handled, FALSE if an error occurs.
     */
    BOOL BeginMessage(
      const PString & from,        ///< User name of sender.
      const PString & to,          ///< User name of recipient.
      BOOL eightBitMIME = FALSE    ///< Mesage will be 8 bit MIME.
    );
    BOOL BeginMessage(
      const PString & from,        ///< User name of sender.
      const PStringList & toList,  ///< List of user names of recipients.
      BOOL eightBitMIME = FALSE    ///< Mesage will be 8 bit MIME.
    );

    /** End transmission of a message using the SMTP socket as a client.

       @return
       TRUE if message was accepted by remote server, FALSE if an error occurs.
     */
    BOOL EndMessage();


  protected:
    BOOL OnOpen();

    BOOL    haveHello;
    BOOL    extendedHello;
    BOOL    eightBitMIME;
    PString fromAddress;
    PStringList toNames;
    BOOL    sendingData;

  private:
    BOOL _BeginMessage();
};


/** A TCP/IP socket for the Simple Mail Transfer Protocol.

   When acting as a client, the procedure is to make the connection to a
   remote server, then to send a message using the following procedure:
      <PRE><CODE>
      PSMTPSocket mail("mailserver");
      if (mail.IsOpen()) {
        mail.BeginMessage("[e-mail]", "[e-mail]");
        mail.Write(myMessage);
        if (!mail.EndMessage())
          PError << "Mail send failed." << endl;
      }
      else
         PError << "Mail conection failed." << endl;
      </PRE></CODE>

    When acting as a server, a descendant class would be created to override
    at least the <A>LookUpName()</A> and <A>HandleMessage()</A> functions.
    Other functions may be overridden for further enhancement to the sockets
    capabilities, but these two will give a basic SMTP server functionality.

    The server socket thread would continuously call the
    <A>ProcessMessage()</A> function until it returns FALSE. This will then
    call the appropriate virtual function on parsing the SMTP protocol.
*/
class PSMTPServer : public PSMTP
{
  PCLASSINFO(PSMTPServer, PSMTP)

  public:
    /** Create a TCP/IP SMPTP protocol socket channel. The parameterless form
       creates an unopened socket, the form with the <CODE>address</CODE>
       parameter makes a connection to a remote system, opening the socket. The
       form with the <CODE>socket</CODE> parameter opens the socket to an
       incoming call from a "listening" socket.
     */
    PSMTPServer();


  // New functions for class.
    /** Process commands, dispatching to the appropriate virtual function. This
       is used when the socket is acting as a server.

       @return
       TRUE if more processing may be done, FALSE if the QUIT command was
       received or the <A>OnUnknown()</A> function returns FALSE.
     */
    BOOL ProcessCommand();

    void ServerReset();
    // Reset the state of the SMTP server socket.

    enum ForwardResult {
      LocalDomain,    ///< User may be on local machine, do LookUpName().
      WillForward,    ///< User may be forwarded to another SMTP host.
      CannotForward   ///< User cannot be forwarded.
    };
    // Result of forward check

    /** Determine if a user for this domain may be on the local system, or
       should be forwarded.

       @return
       Result of forward check operation.
     */
    virtual ForwardResult ForwardDomain(
      PCaselessString & userDomain,       ///< Domain for user
      PCaselessString & forwardDomainList ///< Domains forwarding to
    );

    enum LookUpResult {
      ValidUser,      ///< User name was valid and unique.
      AmbiguousUser,  ///< User name was valid but ambiguous.
      UnknownUser,    ///< User name was invalid.
      LookUpError     ///< Some other error occurred in look up.
    };
    // Result of user name look up

    /** Look up a name in the context of the SMTP server.

       The default bahaviour simply returns FALSE.

       @return
       Result of name look up operation.
     */
    virtual LookUpResult LookUpName(
      const PCaselessString & name,    ///< Name to look up.
      PString & expandedName           ///< Expanded form of name (if found).
    );

    /** Handle a received message. The <CODE>buffer</CODE> parameter contains
       the partial or complete message received, depending on the
       <CODE>completed</CODE> parameter.

       The default behaviour is to simply return FALSE;

       @return
       TRUE if message was handled, FALSE if an error occurs.
     */
    virtual BOOL HandleMessage(
      PCharArray & buffer,  ///< Buffer containing message data received.
      BOOL starting,        ///< This is the first call for the message.
      BOOL completed        ///< This is the last call for the message.
      ///< Indication that the entire message has been received.
    );