PTLib  Version 2.10.11
inetmail.h
Go to the documentation of this file.
1 /*
2  * inetmail.h
3  *
4  * Internet Mail channel classes
5  * Simple Mail Transport Protocol & Post Office Protocol v3
6  *
7  * Portable Windows Library
8  *
9  * Copyright (c) 1993-2002 Equivalence Pty. Ltd.
10  *
11  * The contents of this file are subject to the Mozilla Public License
12  * Version 1.0 (the "License"); you may not use this file except in
13  * compliance with the License. You may obtain a copy of the License at
14  * http://www.mozilla.org/MPL/
15  *
16  * Software distributed under the License is distributed on an "AS IS"
17  * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
18  * the License for the specific language governing rights and limitations
19  * under the License.
20  *
21  * The Original Code is Portable Windows Library.
22  *
23  * The Initial Developer of the Original Code is Equivalence Pty. Ltd.
24  *
25  * Contributor(s): Federico Pinna and Reitek S.p.A.
26  *
27  * $Revision: 25387 $
28  * $Author: rjongbloed $
29  * $Date: 2011-03-22 22:51:09 -0500 (Tue, 22 Mar 2011) $
30  */
31 
32 #ifndef PTLIB_INETMAIL_H
33 #define PTLIB_INETMAIL_H
34 
35 #ifdef P_USE_PRAGMA
36 #pragma interface
37 #endif
38 
39 #include <ptclib/inetprot.h>
40 #include <ptclib/mime.h>
41 
42 class PSocket;
43 
44 
46 // PSMTP
47 
73 class PSMTP : public PInternetProtocol
74 {
76 
77  public:
78  // New functions for class.
79  enum Commands {
84  };
85 
86  protected:
87  PSMTP();
88  // Create a new SMTP protocol channel.
89 };
90 
91 
108 class PSMTPClient : public PSMTP
109 {
111 
112  public:
119  PSMTPClient();
120 
124  ~PSMTPClient();
125 
126 
127  // Overrides from class PChannel.
133  virtual PBoolean Close();
134 
135 
136  // New functions for class.
144  PBoolean LogIn(
145  const PString & username,
146  const PString & password
147  );
148 
158  const PString & from,
159  const PString & to,
160  PBoolean eightBitMIME = false
161  );
163  const PString & from,
164  const PStringList & toList,
165  PBoolean eightBitMIME = false
166  );
167 
174 
175 
176  protected:
177  PBoolean OnOpen();
178 
185 
186  private:
187  bool InternalBeginMessage();
188 };
189 
190 
216 class PSMTPServer : public PSMTP
217 {
219 
220  public:
227  PSMTPServer();
228 
229 
230  // New functions for class.
239 
240  void ServerReset();
241  // Reset the state of the SMTP server socket.
242 
247  };
248  // Result of forward check
249 
257  PCaselessString & userDomain,
258  PCaselessString & forwardDomainList
259  );
260 
266  };
267  // Result of user name look up
268 
276  virtual LookUpResult LookUpName(
277  const PCaselessString & name,
278  PString & expandedName
279  );
280 
290  virtual PBoolean HandleMessage(
291  PCharArray & buffer,
292  PBoolean starting,
293  PBoolean completed
294  );
296 
297 
298  protected:
299  PBoolean OnOpen();
300 
301  virtual void OnHELO(
302  const PCaselessString & remoteHost
303  );
304  // Start connection.
305 
306  virtual void OnEHLO(
307  const PCaselessString & remoteHost
308  );
309  // Start extended SMTP connection.
310 
311  virtual void OnQUIT();
312  // close connection and die.
313 
314  virtual void OnHELP();
315  // get help.
316 
317  virtual void OnNOOP();
318  // do nothing
319 
320  virtual void OnTURN();
321  // switch places
322 
323  virtual void OnRSET();
324  // Reset state.
325 
326  virtual void OnVRFY(
327  const PCaselessString & name
328  );
329  // Verify address.
330 
331  virtual void OnEXPN(
332  const PCaselessString & name
333  );
334  // Expand alias.
335 
336  virtual void OnRCPT(
337  const PCaselessString & recipient
338  );
339  // Designate recipient
340 
341  virtual void OnMAIL(
342  const PCaselessString & sender
343  );
344  // Designate sender
345 
346  virtual void OnSEND(
347  const PCaselessString & sender
348  );
349  // send message to screen
350 
351  virtual void OnSAML(
352  const PCaselessString & sender
353  );
354  // send AND mail
355 
356  virtual void OnSOML(
357  const PCaselessString & sender
358  );
359  // send OR mail
360 
361  virtual void OnDATA();
362  // Message text.
363 
370  virtual PBoolean OnUnknown(
371  const PCaselessString & command
372  );
373 
374  virtual void OnSendMail(
375  const PCaselessString & sender
376  );
377  // Common code for OnMAIL(), OnSEND(), OnSOML() and OnSAML() funtions.
378 
390  virtual PBoolean OnTextData(PCharArray & buffer, PBoolean & completed);
391 
403  virtual PBoolean OnMIMEData(PCharArray & buffer, PBoolean & completed);
404 
405 
406  // Member variables
416 };
417 
418 
420 // PPOP3
421 
459 class PPOP3 : public PInternetProtocol
460 {
462 
463  public:
464  enum Commands {
468  };
469 
470 
471  protected:
472  PPOP3();
473 
485  virtual PINDEX ParseResponse(
486  const PString & line
487  );
488 
489  // Member variables
490  static const PString & okResponse();
491  static const PString & errResponse();
492 };
493 
494 
522 class PPOP3Client : public PPOP3
523 {
525 
526  public:
533  PPOP3Client();
534 
538  ~PPOP3Client();
539 
540 
541  // Overrides from class PChannel.
547  virtual PBoolean Close();
548 
549 
550  // New functions for class.
552  {
554  UseSASL = 2,
556  AllowClearTextSASL = 4
558  };
559 
565  PBoolean LogIn(
566  const PString & username,
567  const PString & password,
568  int options = AllowUserPass
569  );
570 
576  int GetMessageCount();
577 
585 
596 
597 
598  /* Begin the retrieval of an entire message. The application may then use
599  the <A>PApplicationSocket::ReadLine()</A> function with the
600  <CODE>unstuffLine</CODE> parameter set to true. Repeated calls until
601  its return valus is false will read the message headers and body.
602 
603  @return
604  Array of strings continaing message headers.
605  */
607  PINDEX messageNumber
611  );
612 
619  PINDEX messageNumber
620  /* Number of message to retrieve. This is an integer from 1 to the
621  maximum number of messages available.
622  */
623  );
624 
625 
626  protected:
627  PBoolean OnOpen();
628 
629  // Member variables
632 };
633 
634 
647 class PPOP3Server : public PPOP3
648 {
650 
651  public:
658  PPOP3Server();
659 
660 
661  // New functions for class.
670 
680  virtual PBoolean HandleOpenMailbox(
681  const PString & username,
682  const PString & password
683  );
684 
692  virtual void HandleSendMessage(
693  PINDEX messageNumber,
694  const PString & id,
695  PINDEX lines
696  );
697 
705  virtual void HandleDeleteMessage(
706  PINDEX messageNumber,
707  const PString & id
708  );
709 
710 
711  protected:
712  PBoolean OnOpen();
713 
714  virtual void OnUSER(
715  const PString & name
716  );
717  // Specify user name (mailbox).
718 
719  virtual void OnPASS(
720  const PString & passwd
721  );
722  // Specify password and log user in.
723 
724  virtual void OnQUIT();
725  // End connection, saving all changes (delete messages).
726 
727  virtual void OnRSET();
728  // Reset connection (undelete messages).
729 
730  virtual void OnNOOP();
731  // Do nothing.
732 
733  virtual void OnSTAT();
734  // Get number of messages in mailbox.
735 
739  virtual void OnLIST(
740  PINDEX msg
741  );
742 
743  virtual void OnRETR(
744  PINDEX msg
745  );
746  // Retrieve a message from mailbox.
747 
748  virtual void OnDELE(
749  PINDEX msg
750  );
751  // Delete a message from mailbox.
752 
753  virtual void OnTOP(
754  PINDEX msg,
755  PINDEX count
756  );
757  // Get the message header and top <CODE>count</CODE> lines of message.
758 
762  virtual void OnUIDL(
763  PINDEX msg
764  );
765 
772  virtual PBoolean OnUnknown(
773  const PCaselessString & command
774  );
775 
776 
777  // Member variables
782 };
783 
784 
811 {
812  PCLASSINFO(PRFC822Channel, PIndirectChannel);
813  public:
814  enum Direction {
817  };
821  Direction direction
822  );
823 
826  ~PRFC822Channel();
827 
828 
829  // Overrides from class PChannel.
834  PBoolean Close();
835 
844  virtual PBoolean Write(
845  const void * buf,
846  PINDEX len
847  );
848 
849 
854  void NewMessage(
855  Direction direction
856  );
857 
868 
879  const PString & boundary
880  );
881 
892  void NextPart(
893  const PString & boundary
894  );
895 
896 
900  void SetFromAddress(
901  const PString & fromAddress
902  );
903 
907  void SetToAddress(
908  const PString & toAddress
909  );
910 
914  void SetCC(
915  const PString & ccAddress
916  );
917 
921  void SetBCC(
922  const PString & bccAddress
923  );
924 
928  void SetSubject(
929  const PString & subject
930  );
931 
939  void SetContentType(
940  const PString & contentType
941  );
942 
951  const PFilePath & filename
952  );
953 
963  void SetTransferEncoding(
964  const PString & encoding,
965  PBoolean autoTranslate = true
966  );
967 
968 
972  void SetHeaderField(
973  const PString & name,
974  const PString & value
975  );
976 
977  // Common MIME header tags
978  static const PCaselessString & MimeVersionTag();
979  static const PCaselessString & FromTag();
980  static const PCaselessString & ToTag();
981  static const PCaselessString & CCTag();
982  static const PCaselessString & BCCTag();
983  static const PCaselessString & SubjectTag();
984  static const PCaselessString & DateTag();
985  static const PCaselessString & ReturnPathTag();
986  static const PCaselessString & ReceivedTag();
987  static const PCaselessString & MessageIDTag();
988  static const PCaselessString & MailerTag();
992 
998  const PString & hostname
999  );
1000 
1006  PSMTPClient * smtp
1007  );
1008 
1009 
1010  protected:
1011  PBoolean OnOpen();
1012 
1019 };
1020 
1021 
1022 #endif // PTLIB_INETMAIL_H
1023 
1024 
1025 // End Of File ///////////////////////////////////////////////////////////////
void NewMessage(Direction direction)
Begin a new message.
PBoolean eightBitMIME
Definition: inetmail.h:181
static const PCaselessString & SubjectTag()
PBoolean eightBitMIME
Definition: inetmail.h:408
Definition: inetmail.h:815
virtual PBoolean HandleMessage(PCharArray &buffer, PBoolean starting, PBoolean completed)
Handle a received message.
static const PCaselessString & ContentTypeTag()
Definition: inetmail.h:465
This class contains the Multipurpose Internet Mail Extensions parameters and variables.
Definition: mime.h:52
static const PCaselessString & ContentTransferEncodingTag()
Definition: inetmail.h:991
Definition: inetmail.h:414
Definition: inetmail.h:816
virtual void OnHELO(const PCaselessString &remoteHost)
virtual void OnSTAT()
Allow the use of the plain old USER/PASS if APOP or SASL are not available.
Definition: inetmail.h:553
A TCP/IP socket for the Post Office Protocol version 3.
Definition: inetmail.h:647
virtual void OnEHLO(const PCaselessString &remoteHost)
PUnsignedArray messageSizes
Definition: inetmail.h:779
virtual void OnPASS(const PString &passwd)
Array of characters.
Definition: array.h:551
Definition: inetmail.h:414
void SetFromAddress(const PString &fromAddress)
Set the sender address.
#define PCLASSINFO(cls, par)
Declare all the standard PTLib class information.
Definition: object.h:1049
static const PString & okResponse()
PSMTPServer()
Create a TCP/IP SMPTP protocol socket channel.
virtual PBoolean OnTextData(PCharArray &buffer, PBoolean &completed)
Read a standard text message that is being received by the socket.
virtual void OnQUIT()
virtual PBoolean Write(const void *buf, PINDEX len)
Low level write to the channel.
PBoolean writePartHeaders
Definition: inetmail.h:1015
User name was valid but ambiguous.
Definition: inetmail.h:263
Direction
Definition: inetmail.h:814
This class is used to encode/decode data using the MIME standard base64 encoding mechanism as defined...
Definition: cypher.h:70
virtual void OnMAIL(const PCaselessString &sender)
static const PCaselessString & MessageIDTag()
PString MultipartMessage()
Enter multipart MIME message mode.
Definition: inetmail.h:83
Definition: inetmail.h:466
void SetContentType(const PString &contentType)
Set the content type.
void SetHeaderField(const PString &name, const PString &value)
Set the and arbitrary header field.
A channel for sending/receiving RFC822 compliant mail messages.
Definition: inetmail.h:810
virtual void OnDATA()
Definition: inetmail.h:465
virtual void HandleSendMessage(PINDEX messageNumber, const PString &id, PINDEX lines)
Handle the sending of the specified message to the remote client.
PBoolean OnOpen()
This callback is executed when the Open() function is called with open channels.
User name was invalid.
Definition: inetmail.h:264
void SetCC(const PString &ccAddress)
Set the Carbon Copy address(es).
ForwardResult
Definition: inetmail.h:243
Definition: inetmail.h:466
PINDEX messageBufferSize
Definition: inetmail.h:413
void SetToAddress(const PString &toAddress)
Set the recipient address(es).
Definition: inetmail.h:466
virtual PBoolean OnUnknown(const PCaselessString &command)
Handle an unknown command.
Definition: inetmail.h:81
void SetSubject(const PString &subject)
Set the message subject.
This class describes a full description for a file on the particular platform.
Definition: filepath.h:65
PStringArray messageIDs
Definition: inetmail.h:780
LoginOptions
Definition: inetmail.h:551
Definition: inetmail.h:81
Definition: inetmail.h:467
PBoolean sendingData
Definition: inetmail.h:184
static const PCaselessString & ReceivedTag()
This is a channel that operates indirectly through another channel(s).
Definition: indchan.h:49
PStringList toNames
Definition: inetmail.h:183
This class is a variation of a string that ignores case.
Definition: pstring.h:1708
User may be on local machine, do LookUpName().
Definition: inetmail.h:244
PBoolean ProcessCommand()
Process commands, dispatching to the appropriate virtual function.
virtual void OnHELP()
static const PCaselessString & ContentTypeTag()
Definition: inetmail.h:989
A TCP/IP socket for the Simple Mail Transfer Protocol.
Definition: inetmail.h:73
virtual void OnLIST(PINDEX msg)
Get the size of a message in mailbox.
PBoolean loggedIn
Definition: inetmail.h:630
static const PCaselessString & ToTag()
static const PCaselessString & CCTag()
Definition: inetmail.h:465
PUnsignedArray GetMessageSizes()
Get an array of a integers representing the sizes of each of the messages in the mail box...
This is an array collection class of PString objects.
Definition: pstring.h:2024
PBYTEArray messageDeletions
Definition: inetmail.h:781
PBoolean OnOpen()
This callback is executed when the Open() function is called with open channels.
Definition: inetmail.h:80
virtual void OnRCPT(const PCaselessString &recipient)
Definition: inetmail.h:80
PMIMEInfo headers
Definition: inetmail.h:1014
Definition: inetmail.h:83
Definition: inetmail.h:81
A TCP/IP socket for the Simple Mail Transfer Protocol.
Definition: inetmail.h:108
~PPOP3Client()
Destroy the channel object.
A TCP/IP socket for process/application layer high level protocols.
Definition: inetprot.h:62
LookUpResult
Definition: inetmail.h:261
PBoolean BeginMessage(PINDEX messageNumber)
Definition: inetmail.h:466
static const PCaselessString & DateTag()
BOOL PBoolean
Definition: object.h:102
~PSMTPClient()
Destroy the channel object.
PPOP3Client()
Create a TCP/IP POP3 protocol socket channel.
virtual void OnSOML(const PCaselessString &sender)
Definition: inetmail.h:465
virtual void OnTURN()
Array of unsigned characters.
Definition: array.h:670
static const PCaselessString & MimeVersionTag()
PBoolean LogIn(const PString &username, const PString &password, int options=AllowUserPass)
Log into the POP server using the mailbox and access codes specified.
Definition: inetmail.h:465
Commands
Definition: inetmail.h:79
A TCP/IP socket for the Post Office Protocol version 3.
Definition: inetmail.h:522
enum PSMTPServer::@23 sendCommand
Definition: inetmail.h:80
virtual ForwardResult ForwardDomain(PCaselessString &userDomain, PCaselessString &forwardDomainList)
Determine if a user for this domain may be on the local system, or should be forwarded.
virtual PBoolean OnMIMEData(PCharArray &buffer, PBoolean &completed)
Read an eight bit MIME message that is being received by the socket.
virtual PBoolean OnUnknown(const PCaselessString &command)
Handle an unknown command.
static const PCaselessString & ContentDispositionTag()
Definition: inetmail.h:465
virtual void HandleDeleteMessage(PINDEX messageNumber, const PString &id)
Handle the deleting of the specified message from the mail box.
User may be forwarded to another SMTP host.
Definition: inetmail.h:245
PSMTPClient()
Create a TCP/IP SMPTP protocol socket channel.
Definition: inetmail.h:81
~PRFC822Channel()
Close the channel before destruction.
virtual PBoolean Close()
Close the socket, and if connected as a client, QUITs from server.
static const PCaselessString & ContentTransferEncodingTag()
virtual void OnEXPN(const PCaselessString &name)
PString fromAddress
Definition: inetmail.h:182
PBoolean BeginMessage(const PString &from, const PString &to, PBoolean eightBitMIME=false)
Begin transmission of a message using the SMTP socket as a client.
void SetContentAttachment(const PFilePath &filename)
Set the content disposition for attachments.
PStringArray GetMessageHeaders()
Get an array of a strings representing the standard internet message headers of each of the messages ...
virtual PINDEX ParseResponse(const PString &line)
Parse a response line string into a response code and any extra info on the line. ...
PBoolean haveHello
Definition: inetmail.h:179
static const PCaselessString & FromTag()
Definition: inetmail.h:414
Definition: inetmail.h:80
A TCP/IP socket for the Post Office Protocol version 3.
Definition: inetmail.h:459
virtual void OnDELE(PINDEX msg)
PPOP3Server()
Create a TCP/IP POP3 protocol socket channel.
PRFC822Channel(Direction direction)
Construct a RFC822 aware channel.
PBoolean Close()
Close the channel.
void NextPart(const PString &boundary)
Indicate that a new multipart message part is to begin.
The character string class.
Definition: pstring.h:108
Definition: inetmail.h:414
Definition: inetmail.h:466
PBoolean writeHeaders
Definition: inetmail.h:1013
Array of unsigned integers.
Definition: array.h:737
Definition: inetmail.h:82
static const PString & errResponse()
PString fromPath
Definition: inetmail.h:410
Use SASL if the AUTH command is supported by the server.
Definition: inetmail.h:555
virtual void OnSEND(const PCaselessString &sender)
PBoolean LogIn(const PString &username, const PString &password)
Log into the SMTP server using the mailbox and access codes specified.
PBoolean extendedHello
Definition: inetmail.h:180
PBoolean OnOpen()
This callback is executed when the Open() function is called with open channels.
Allow LOGIN and PLAIN mechanisms to be used.
Definition: inetmail.h:557
virtual PBoolean HandleOpenMailbox(const PString &username, const PString &password)
Log the specified user into the mail system and return sizes of each message in mail box...
This is a list collection class of PString objects.
Definition: pstring.h:2184
PString username
Definition: inetmail.h:778
User cannot be forwarded.
Definition: inetmail.h:246
static const PCaselessString & ReturnPathTag()
virtual void OnNOOP()
void SetTransferEncoding(const PString &encoding, PBoolean autoTranslate=true)
Set the content transfer encoding.
PBoolean extendedHello
Definition: inetmail.h:407
virtual LookUpResult LookUpName(const PCaselessString &name, PString &expandedName)
Look up a name in the context of the SMTP server.
PBoolean DeleteMessage(PINDEX messageNumber)
Delete the message specified from the mail box.
PStringList toNames
Definition: inetmail.h:411
Definition: inetmail.h:82
A TCP/IP socket for the Simple Mail Transfer Protocol.
Definition: inetmail.h:216
virtual void OnRSET()
Definition: inetmail.h:82
void ServerReset()
Some other error occurred in look up.
Definition: inetmail.h:265
Definition: inetmail.h:82
StuffState endMIMEDetectState
Definition: inetmail.h:415
virtual void OnUIDL(PINDEX msg)
Get unique ID for message in mailbox.
virtual void OnSAML(const PCaselessString &sender)
virtual void OnSendMail(const PCaselessString &sender)
PString fromAddress
Definition: inetmail.h:409
PStringList toDomains
Definition: inetmail.h:412
static const PCaselessString & BCCTag()
Definition: inetmail.h:466
User name was valid and unique.
Definition: inetmail.h:262
StuffState
Definition: inetprot.h:369
void SetBCC(const PString &bccAddress)
Set the Blind Carbon Copy address(es).
virtual void OnQUIT()
static const PCaselessString & MailerTag()
PBoolean OnOpen()
This callback is executed when the Open() function is called with open channels.
virtual void OnNOOP()
PMIMEInfo partHeaders
Definition: inetmail.h:1016
PBase64 * base64
Definition: inetmail.h:1018
A network communications channel.
Definition: socket.h:58
PBoolean ProcessCommand()
Process commands, dispatching to the appropriate virtual function.
PString apopBanner
Definition: inetmail.h:631
Definition: inetmail.h:81
Definition: inetmail.h:82
Definition: inetmail.h:80
PBoolean SendWithSMTP(const PString &hostname)
Send this message using an SMTP socket.
virtual void OnRETR(PINDEX msg)
int GetMessageCount()
Get a count of the number of messages in the mail box.
virtual void OnUSER(const PString &name)
static const PCaselessString & ContentDispositionTag()
Definition: inetmail.h:990
Commands
Definition: inetmail.h:464
virtual void OnTOP(PINDEX msg, PINDEX count)
virtual void OnVRFY(const PCaselessString &name)
Definition: inetmail.h:467
virtual void OnRSET()
PBoolean OnOpen()
This callback is executed when the Open() function is called with open channels.
PStringList boundaries
Definition: inetmail.h:1017
virtual PBoolean Close()
Close the socket, and if connected as a client, QUITs from server.
PBoolean EndMessage()
End transmission of a message using the SMTP socket as a client.