inetmail.h

Go to the documentation of this file.

/*
 * 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.21  2007/04/10 05:08:46  rjongbloed
 * Fixed issue with use of static C string variables in DLL environment,
 *   must use functional interface for correct initialisation.
 *
 * 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 (wolfgang.platzer@infonova.at).
 *
 * 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

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.
};


class PSMTPClient : public PSMTP
{
  PCLASSINFO(PSMTPClient, PSMTP)

  public:
    PSMTPClient();

    ~PSMTPClient();


  // Overrides from class PChannel.
    virtual BOOL Close();


  // New functions for class.
    BOOL LogIn(
      const PString & username,   
      const PString & password    
    );

    BOOL BeginMessage(
      const PString & from,        
      const PString & to,          
      BOOL eightBitMIME = FALSE    
    );
    BOOL BeginMessage(
      const PString & from,        
      const PStringList & toList,  
      BOOL eightBitMIME = FALSE    
    );

    BOOL EndMessage();


  protected:
    BOOL OnOpen();

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

  private:
    BOOL _BeginMessage();
};


class PSMTPServer : public PSMTP
{
  PCLASSINFO(PSMTPServer, PSMTP)

  public:
    PSMTPServer();


  // New functions for class.
    BOOL ProcessCommand();

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

    enum ForwardResult {
      LocalDomain,    
      WillForward,    
      CannotForward   
    };
    // Result of forward check

    virtual ForwardResult ForwardDomain(
      PCaselessString & userDomain,       
      PCaselessString & forwardDomainList 
    );

    enum LookUpResult {
      ValidUser,      
      AmbiguousUser,  
      UnknownUser,    
      LookUpError     
    };
    // Result of user name look up

    virtual LookUpResult LookUpName(
      const PCaselessString & name,    
      PString & expandedName           
    );

    virtual BOOL HandleMessage(
      PCharArray & buffer,  
      BOOL starting,        
      BOOL completed        

    );


  protected:
    BOOL OnOpen();

    virtual void OnHELO(
      const PCaselessString & remoteHost  
    );
    // Start connection.

    virtual void OnEHLO(
      const PCaselessString & remoteHost  
    );
    // Start extended SMTP connection.

    virtual void OnQUIT();
    // close connection and die.

    virtual void OnHELP();
    // get help.

    virtual void OnNOOP();
    // do nothing
    
    virtual void OnTURN();
    // switch places
    
    virtual void OnRSET();
    // Reset state.

    virtual void OnVRFY(
      const PCaselessString & name    
    );
    // Verify address.

    virtual void OnEXPN(
      const PCaselessString & name    
    );
    // Expand alias.

    virtual void OnRCPT(
      const PCaselessString & recipient   
    );
    // Designate recipient

    virtual void OnMAIL(
      const PCaselessString & sender  
    );
    // Designate sender
    
    virtual void OnSEND(
      const PCaselessString & sender  
    );
    // send message to screen

    virtual void OnSAML(
      const PCaselessString & sender  
    );
    // send AND mail
    
    virtual void OnSOML(
      const PCaselessString & sender  
    );
    // send OR mail

    virtual void OnDATA();
    // Message text.

    virtual BOOL OnUnknown(
      const PCaselessString & command  
    );

    virtual void OnSendMail(
      const PCaselessString & sender  
    );
    // Common code for OnMAIL(), OnSEND(), OnSOML() and OnSAML() funtions.

    virtual BOOL OnTextData(PCharArray & buffer, BOOL & completed);

    virtual BOOL OnMIMEData(PCharArray & buffer, BOOL & completed);


  // Member variables
    BOOL        extendedHello;
    BOOL        eightBitMIME;
    PString     fromAddress;
    PString     fromPath;
    PStringList toNames;
    PStringList toDomains;
    PINDEX      messageBufferSize;
    enum { WasMAIL, WasSEND, WasSAML, WasSOML } sendCommand;
    StuffState  endMIMEDetectState;
};


// PPOP3

class PPOP3 : public PInternetProtocol
{
  PCLASSINFO(PPOP3, PInternetProtocol)

  public:
    enum Commands {
      USER, PASS, QUIT, RSET, NOOP, STATcmd,
      LIST, RETR, DELE, APOP, TOP,  UIDL,
      AUTH, NumCommands
    };


  protected:
    PPOP3();

    virtual PINDEX ParseResponse(
      const PString & line 
    );

  // Member variables
    static PString okResponse;
    static PString errResponse;
};


class PPOP3Client : public PPOP3
{
  PCLASSINFO(PPOP3Client, PPOP3)

  public:
    PPOP3Client();

    ~PPOP3Client();


  // Overrides from class PChannel.
    virtual BOOL Close();


  // New functions for class.
    enum LoginOptions
    {
      AllowUserPass = 1,      

      UseSASL = 2,            

      AllowClearTextSASL = 4  
    };

    BOOL LogIn(
      const PString & username,       
      const PString & password,       
      int options = AllowUserPass     
    );

    int GetMessageCount();

    PUnsignedArray GetMessageSizes();

    PStringArray GetMessageHeaders();


    /* Begin the retrieval of an entire message. The application may then use
       the <A>PApplicationSocket::ReadLine()</A> function with the
       <CODE>unstuffLine</CODE> parameter set to TRUE. Repeated calls until
       its return valus is FALSE will read the message headers and body.

       @return
       Array of strings continaing message headers.
     */
    BOOL BeginMessage(
      PINDEX messageNumber
    );

    BOOL DeleteMessage(
      PINDEX messageNumber
        /* Number of message to retrieve. This is an integer from 1 to the
           maximum number of messages available.
         */
    );


  protected:
    BOOL OnOpen();

  // Member variables
    BOOL loggedIn;
    PString apopBanner;
};


class PPOP3Server : public PPOP3
{
  PCLASSINFO(PPOP3Server, PPOP3)

  public:
    PPOP3Server();


  // New functions for class.
    BOOL ProcessCommand();

    virtual BOOL HandleOpenMailbox(
      const PString & username,  
      const PString & password   
    );

    virtual void HandleSendMessage(
      PINDEX messageNumber, 
      const PString & id,   
      PINDEX lines          
    );
    
    virtual void HandleDeleteMessage(
      PINDEX messageNumber, 
      const PString & id    
    );
    

  protected:
    BOOL OnOpen();

    virtual void OnUSER(
      const PString & name  
    );
    // Specify user name (mailbox).

    virtual void OnPASS(
      const PString & passwd  
    );
    // Specify password and log user in.

    virtual void OnQUIT();
    // End connection, saving all changes (delete messages).

    virtual void OnRSET();
    // Reset connection (undelete messages).

    virtual void OnNOOP();
    // Do nothing.

    virtual void OnSTAT();
    // Get number of messages in mailbox.

    virtual void OnLIST(
      PINDEX msg  
    );

    virtual void OnRETR(
      PINDEX msg  
    );
    // Retrieve a message from mailbox.

    virtual void OnDELE(
      PINDEX msg  
    );
    // Delete a message from mailbox.

    virtual void OnTOP(
      PINDEX msg,  
      PINDEX count 
    );
    // Get the message header and top <CODE>count</CODE> lines of message.

    virtual void OnUIDL(
      PINDEX msg  
    );

    virtual BOOL OnUnknown(
      const PCaselessString & command  
    );


  // Member variables
    PString        username;
    PUnsignedArray messageSizes;
    PStringArray   messageIDs;
    PBYTEArray     messageDeletions;
};


class PRFC822Channel : public PIndirectChannel
{
    PCLASSINFO(PRFC822Channel, PIndirectChannel);
  public:
    enum Direction {
      Sending,
      Receiving
    };
    PRFC822Channel(
      Direction direction 
    );

    ~PRFC822Channel();


  // Overrides from class PChannel.
    BOOL Close();

    virtual BOOL Write(
      const void * buf, 
      PINDEX len        
    );


    void NewMessage(
      Direction direction  
    );

    PString MultipartMessage();

    BOOL MultipartMessage(
      const PString & boundary
    );

    void NextPart(
      const PString & boundary
    );


    void SetFromAddress(
      const PString & fromAddress  
    );

    void SetToAddress(
      const PString & toAddress 
    );

    void SetCC(
      const PString & ccAddress 
    );

    void SetBCC(
      const PString & bccAddress 
    );

    void SetSubject(
      const PString & subject  
    );

    void SetContentType(
      const PString & contentType   
    );

    void SetContentAttachment(
      const PFilePath & filename   
    );

    void SetTransferEncoding(
      const PString & encoding,   
      BOOL autoTranslate = TRUE   
    );


    void SetHeaderField(
      const PString & name,   
      const PString & value   
    );

    // Common MIME header tags
    static const PString & MimeVersionTag();
    static const PString & FromTag();
    static const PString & ToTag();
    static const PString & CCTag();
    static const PString & BCCTag();
    static const PString & SubjectTag();
    static const PString & DateTag();
    static const PString & ReturnPathTag();
    static const PString & ReceivedTag();
    static const PString & MessageIDTag();
    static const PString & MailerTag();
    static const PString & ContentTypeTag();
    static const PString & ContentDispositionTag();
    static const PString & ContentTransferEncodingTag();

    BOOL SendWithSMTP(
      const PString & hostname
    );

    BOOL SendWithSMTP(
      PSMTPClient * smtp
    );


  protected:
    BOOL OnOpen();

    BOOL        writeHeaders;
    PMIMEInfo   headers;
    BOOL        writePartHeaders;
    PMIMEInfo   partHeaders;
    PStringList boundaries;
    PBase64   * base64;
};


#endif  // _PMAILPROTOCOL


// End Of File ///////////////////////////////////////////////////////////////

---