home *** CD-ROM | disk | FTP | other *** search
/ Personal Computer World 2009 February / PCWFEB09.iso / Software / Linux / SLAX 6.0.8 / slax-6.0.8.iso / slax / base / 006-devel.lzm / usr / include / mimelib / pop.h < prev    next >
Encoding:
C/C++ Source or Header  |  2007-05-14  |  13.8 KB  |  301 lines
  1. //=============================================================================
  2. // File:       pop.h
  3. // Contents:   Declarations for DwPopClient
  4. // Maintainer: Doug Sauder <dwsauder@fwb.gulf.net>
  5. // WWW:        http://www.fwb.gulf.net/~dwsauder/mimepp.html
  6. //
  7. // Copyright (c) 1996, 1997 Douglas W. Sauder
  8. // All rights reserved.
  9. // 
  10. // IN NO EVENT SHALL DOUGLAS W. SAUDER BE LIABLE TO ANY PARTY FOR DIRECT,
  11. // INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT OF
  12. // THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF DOUGLAS W. SAUDER
  13. // HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  14. //
  15. // DOUGLAS W. SAUDER SPECIFICALLY DISCLAIMS ANY WARRANTIES, INCLUDING, BUT
  16. // NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  17. // PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS ON AN "AS IS"
  18. // BASIS, AND DOUGLAS W. SAUDER HAS NO OBLIGATION TO PROVIDE MAINTENANCE,
  19. // SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS.
  20. //
  21. //=============================================================================
  22.  
  23. #ifndef DW_POP_H
  24. #define DW_POP_H
  25.  
  26. #include <stdio.h>
  27.  
  28. #ifndef DW_CONFIG_H
  29. #include <mimelib/config.h>
  30. #endif
  31.  
  32. #ifndef DW_PROTOCOL_H
  33. #include <mimelib/protocol.h>
  34. #endif
  35.  
  36. #ifndef DW_STRING_H
  37. #include <mimelib/string.h>
  38. #endif
  39.  
  40.  
  41. //=============================================================================
  42. //+ Name DwPopClient -- Class for handling the client side of a POP session
  43. //+ Description
  44. //. {\tt DwPopClient} is a class that handles the client side of a POP
  45. //. session.  Specifically, {\tt DwPopClient} provides facilities for
  46. //. opening a connection to a POP server, sending commands to the server,
  47. //. receiving responses from the server, and closing the connection. The
  48. //. protocol implemented is the Post Office Protocol version 3, as specified
  49. //. in RFC-1939.
  50. //.
  51. //. {\tt DwPopClient} is derived from {\tt DwProtocolClient}. For information
  52. //. about inherited member functions, especially member functions for detecting
  53. //. failures or errors, see the man page for {\tt DwProtocolClient}.
  54. //.
  55. //. In a POP session, the client sends commands to the server and receives
  56. //. responses from the server.  A client command consists of a command word
  57. //. and zero or more argument words.  A server response consists of a single
  58. //. line status response, which may be followed immediately by a multi-line
  59. //. response. The first word of the status response is either +OK or -ERR,
  60. //. indicating the success or failure of the command. The status line may
  61. //. also contain other information requested by the client.
  62. //.
  63. //. {\tt DwPopClient} has only a default constructor. On Win32 platforms,
  64. //. it is possible for the constructor to fail. (It calls WSAStartup().)
  65. //. You should verify that the constructor succeeded by calling the inherited
  66. //. member function {\tt DwProtocolClient::LastError()} and checking for a zero
  67. //. return value.
  68. //.
  69. //. To open a connection to the server, call the member function {\tt Open()}
  70. //. with the name of the server as an argument. {\tt Open()} accepts an
  71. //. optional argument that specifies the TCP port that the server listens to.
  72. //. The default port is the standard POP port (110). {\tt Open()} may fail,
  73. //. so you should check the return value to verify that it succeeded. To
  74. //. close the connection, call the inherited member function
  75. //. {\tt DwProtocolClient::Close()}. To check if a connection is open, call
  76. //. the inherited member function {\tt DwProtocolClient::IsOpen()}.
  77. //. {\tt IsOpen()} returns a boolean value that indicates whether or not
  78. //. a call to {\tt Open()} was successful; it will not detect failure in
  79. //. the network or a close operation by the remote host.
  80. //.
  81. //. For each POP command, {\tt DwPopClient} has a member function that sends
  82. //. that command and receives the server's response. If the command takes any
  83. //. arguments, then those arguments are passed as function arguments to the
  84. //. command function. The command functions return the first character
  85. //. of the server's response, which will be '+' if the command succeeded
  86. //. or '-' if the command failed.
  87. //. In some cases, because of a communications error or some other error,
  88. //. it is not possible for the command function to send the command or
  89. //. receive the response.  When this happens, the command function will
  90. //. return 0.  You can determine the precise error or failure by calling
  91. //. the inherited member functions {\tt DwProtocolClient::LastError()} or
  92. //. {\tt DwProtocolClient::LastFailure()}.
  93. //.
  94. //. After each command is sent, {\tt DwPopClient} receives the server's
  95. //. response and remembers it. The member function {\tt StatusCode()}
  96. //. returns the first character of the server's status response; it will be
  97. //. '+' or '-', indicating success or failure, or zero if no response was
  98. //. received from the server. {\tt SingleLineResponse()} returns the entire
  99. //. single line status response from the server, including the initial
  100. //. "+OK" or "-ERR" status word.
  101. //.
  102. //. The server sends a single-line response, including a status code, for all
  103. //. POP commands. For some commands, such as when the client requests a
  104. //. mail message, the server sends a multi-line text response immediately
  105. //. following the single-line status response. Multi-line text responses
  106. //. can be received in either of two ways. The simplest way is to call
  107. //. the member function {\tt MultiLineResponse()} after a command completes
  108. //. successfully. This simple method works fine for non-interactive
  109. //. applications. It can be a problem in interactive applications, however,
  110. //. because there is no data to display to a user until the entire multi-line
  111. //. response is retrieved. An alternative method allows your program to
  112. //. retrieve the multi-line response one line at a time as it is received.
  113. //. To use this method, you must define a subclass of {\tt DwObserver}
  114. //. and assign an object of that class to the {\tt DwPopClient} object
  115. //. using the member function {\tt SetObserver()}. {\tt DwObserver} is an
  116. //. abstract class, declared in protocol.h, that has just one pure virtual
  117. //. member function {\tt Notify()}. After each line of the multi-line response
  118. //. is received, {\tt DwPopClient} will call the {\tt Notify()} member
  119. //. function of its assigned {\tt DwObserver} object. Each invocation of
  120. //. {\tt Notify()} should call the {\tt DwPopClient} member function
  121. //. {\tt MultiLineResponse()} to retrieve the next line of the text response.
  122. //. Note that you cannot use both of these methods at the same time: if
  123. //. an observer is assigned, {\tt MultiLineResponse()} returns only the last
  124. //. line received, not the entire multi-line response.
  125. //=============================================================================
  126.  
  127. //+ Noentry ~DwPopClient
  128.  
  129.  
  130. class DW_EXPORT DwPopClient : public DwProtocolClient {
  131.  
  132. public:
  133.  
  134.     enum {
  135.         kCmdNoCommand=0,
  136.         kCmdUser,
  137.         kCmdPass,
  138.         kCmdQuit,
  139.         kCmdStat,
  140.         kCmdList,
  141.         kCmdRetr,
  142.         kCmdDele,
  143.         kCmdNoop,
  144.         kCmdRset,
  145.         kCmdApop,
  146.         kCmdTop,
  147.         kCmdUidl
  148.     };
  149.  
  150.     DwPopClient();
  151.     //. Initializes the {\tt DwPopClient} object.
  152.     //. It is possible for the constructor to fail.  To verify that the
  153.     //. constructor succeeded, call the member function {\tt LastError()}
  154.     //. and check that it returns zero.  (In the Win32 implementation, the
  155.     //. constructor calls the Winsock function {\tt WSAStartup()}, which
  156.     //. may fail.)
  157.  
  158.     virtual ~DwPopClient();
  159.  
  160.     virtual int Open(const char* aServer, DwUint16 aPort=110);
  161.     //. Opens a TCP connection to the server {\tt aServer} at port {\tt aPort}.
  162.     //. {\tt aServer} may be either a host name, such as "news.acme.com" or
  163.     //. an IP number in dotted decimal format, such as "147.81.64.60".  The
  164.     //. default value for {\tt aPort} is 110, the well-known port for POP3
  165.     //. assigned by the Internet Assigned Numbers Authority (IANA).
  166.     //.
  167.     //. If the connection attempt succeeds, the server sends a response.
  168.     //. {\tt Open()} returns the server's status code ('+' or '-'). The full
  169.     //. response from the server can be retrieved by calling
  170.     //. {\tt SingleLineResponse()}.
  171.     //.
  172.     //. If the connection attempt fails, {\tt Open()} returns 0.  To determine
  173.     //. what error occurred when a connection attempt fails, call the inherited
  174.     //. member function {\tt DwProtocolClient::LastError()}.  To determine if
  175.     //. a failure also occurred, call the inherited member function
  176.     //. {\tt DwProtocolClient::LastFailure()}.
  177.  
  178.     DwObserver* SetObserver(DwObserver* aObserver);
  179.     //. Sets the observer object that interacts with the {\tt DwPopClient}
  180.     //. object to retrieve a multi-line response. If an observer is set,
  181.     //. {\tt DwPopClient} will call the observer's {\tt Notify()} method
  182.     //. after each line of the multi-line response is received.  To remove
  183.     //. an observer, call {\tt SetObserver()} with a NULL argument.
  184.     //. {\tt SetObserver()} returns the previously set observer, or NULL if
  185.     //. no observer was previously set.
  186.  
  187.     int StatusCode() const;
  188.     //. Returns the status code received from the server in response to the
  189.     //. last client command. The status codes in POP3 are '+', indicating
  190.     //. success, and '-', indicating failure. If no response was received,
  191.     //. {\tt StatusCode()} returns zero.
  192.  
  193.     const DwString& SingleLineResponse() const;
  194.     //. Returns the single line status response last received from the server.
  195.     //. If no response was received, perhaps because of a communications
  196.     //. failure, {\tt SingleLineResponse()} returns an empty string.
  197.  
  198.     const DwString& MultiLineResponse() const;
  199.     //. If no observer is set for this object, {\tt MultiLineResponse()}
  200.     //. returns a string that comprises the entire sequence of lines
  201.     //. received from the server.  Otherwise, if an observer {\it is} set
  202.     //. for this object, {\tt MultiLineResponse()} returns only the most
  203.     //. recent line received.
  204.  
  205.     int User(const char* aName);
  206.     //. Sends the USER command and returns the status code received from
  207.     //. the server.  If no response is received, the function returns zero.
  208.     //. {\tt aName} is the name of the user, which is sent in the command.
  209.  
  210.     int Pass(const char* aPasswd);
  211.     //. Sends the PASS command and returns the status code received from
  212.     //. the server.  If no response is received, the function returns zero.
  213.     //. {\tt aPasswd} is the password, which is sent in the command.
  214.  
  215.     int Quit();
  216.     //. Sends the QUIT command and returns the status code received from
  217.     //. the server.  If no response is received, the function returns zero.
  218.  
  219.     int Stat();
  220.     //. Sends the STAT command and returns the status code received from
  221.     //. the server.  If no response is received, the function returns zero.
  222.  
  223.     int List();
  224.     int List(int aMsg);
  225.     //. Sends the LIST command, with or without a message number, and
  226.     //. returns the status code received from the server.  If no response
  227.     //. is received, the function returns zero.
  228.  
  229.     int Retr(int aMsg);
  230.     //. Sends the RETR command and returns the status code received from
  231.     //. the server.  If no response is received, the function returns zero.
  232.     //. {\tt aMsg} is the message number, which is sent in the command.
  233.  
  234.     int Dele(int aMsg);
  235.     //. Sends the DELE command and returns the status code received from
  236.     //. the server.  If no response is received, the function returns zero.
  237.     //. {\tt aMsg} is the message number, which is sent in the command.
  238.  
  239.     int Noop();
  240.     //. Sends the NOOP command and returns the status code received from
  241.     //. the server.  If no response is received, the function returns zero.
  242.  
  243.     int Rset();
  244.     //. Sends the RSET command and returns the status code received from
  245.     //. the server.  If no response is received, the function returns zero.
  246.  
  247.     int Apop(const char* aName, const char* aDigest);
  248.     //. Sends the APOP command and returns the status code received from
  249.     //. the server.  If no response is received, the function returns zero.
  250.     //. {\tt aName} is the name of the user, which is sent in the command.
  251.     //. {\tt aDigest} is the digest argument for the command.
  252.  
  253.     int Top(int aMsg, int aNumLines);
  254.     //. Sends the TOP command and returns the status code received from
  255.     //. the server.  If no response is received, the function returns zero.
  256.     //. {\tt aMsg} is the message number.  {\tt aNumLines} is the number
  257.     //. of lines to send.
  258.  
  259.     int Uidl();
  260.     int Uidl(int aMsg);
  261.     //. Sends the TOP command, with or without a message number, and
  262.     //. returns the status code received from the server.  If no response
  263.     //. is received, the function returns zero.
  264.  
  265.     int Last();
  266.     //. Sends the LAST command and returns the status code received from
  267.     //. the server.  If no response is received, the function returns zero.
  268.  
  269. private:
  270.  
  271.     char*       mSendBuffer;
  272.     char*       mRecvBuffer;
  273.     int         mNumRecvBufferChars;
  274.     int         mRecvBufferPos;
  275.     int         mStatusCode;
  276.     DwString    mSingleLineResponse;
  277.     DwString    mMultiLineResponse;
  278.     DwObserver* mObserver;
  279.  
  280.     int PGetLine(char** aPtr, int* aLen);
  281.     // Tries to get one complete line of input from the socket.  On success,
  282.     // the function sets {\tt *aPtr} to point to the beginning of the line in
  283.     // the object's internal buffer, sets {\tt *aLen} to the length of the
  284.     // line, including the CR LF, and returns 0.  On failure, the function
  285.     // returns -1.
  286.  
  287.     void PGetSingleLineResponse();
  288.     // Gets a single line of input, assigns that line {\tt mSingleLineResponse}, and
  289.     // sets {\tt mStatusCode}.  On failure, clears {\tt mSingleLineResonse}
  290.     // and sets {\tt mStatusCode} to -1.
  291.  
  292.     void PGetMultiLineResponse();
  293.     // Gets a complete multiline response and assigns it to {\tt mMultiLineResponse},
  294.     // or interacts with the {\tt DwObserver} object to deliver a multiline response
  295.     // one line at a time.
  296.     // If an error occurs, its sets {\tt mStatusCode} to -1.
  297.  
  298. };
  299.  
  300. #endif
  301.