CPop3Connection
v1.11
Welcome to CPop3Connection, a freeware MFC class to support the POP3 protocol. POP3 for those not familiar with all the internet protocols is the protocol used to retrieve internet email.
For detailed information about the Post Office Protocol Version 3 you should read RFC 1725, You can download this from ftp://ds.internic.net/rfc/rfc1725.txt. If this server is unavailable, try ftp://venera.isi.edu/in_notes/
Features |
Usage |
History |
API Reference |
Planned Enhancements |
Contacting the Author |
V1.0 (18th May 1998)
V1.1 (28th June 1998)
V1.11 (4th January 1999)
The API consists of the public member functions of the class CPop3Connection & CPop3Message
CPop3Connection::Connect
CPop3Connection::Disconnect
CPop3Connection::Statistics
CPop3Connection::Delete
CPop3Connection::GetMessageSize
CPop3Connection::GetMessageID
CPop3Connection::Retrieve
CPop3Connection::Reset
CPop3Connection::UIDL
CPop3Connection::GetMessageHeader
CPop3Connection::Noop
CPop3Connection::GetLastCommandResponse
CPop3Connection::GetTimeout
CPop3Connection::SetTimeout
CPop3Message::GetMessageText
BOOL CPop3Connection::Connect(LPCSTR pszHostName, LPCSTR pszUser, LPCSTR pszPassword, int nPort = 110);
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
pszHostName The network address of the socket to connect to: a machine name such as mail.yourisp.com, or a dotted number such as 128.56.22.8.
pszUser This is the POP3 user name of the mailbox.
pszPassword This is the password for the POP3 mailbox.
nPort This is the port number on which to connect. The default value is 110 which is the default POP3 port number.
Remarks
Call this member function to establish a connection to a POP3 mailbox.
See Also
BOOL CPop3Connection::Disconnect();
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
None.
Remarks
The corollary function of Connect.
See Also
BOOL CPop3Connection::Statistics(int& nNumberOfMails, int& nTotalMailSize);
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
nNumberOfMails Upon a successful return this will contain the number of mails waiting in the mailbox.
nTotalMailSize Upon a successful return this will contain the size in bytes (aka Octets) of all mails waiting in the mailbox.
Remarks
Retrieves the statistics for the Mailbox by issuing the "STAT" command.
See Also
CPop3Connection::GetMessageSize
BOOL CPop3Connection::Delete(int nMsg);
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
nMsg The message number of the message to delete. This value starts at 1.
Remarks
Marks a message as "to be deleted" by issuing the "DELE" command.
See Also
CPop3Connection::GetMessageSize
BOOL CPop3Connection::GetMessageSize(int nMsg, DWORD& dwSize);
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
nMsg The message number of the message to retrieve the size of.
dwSize Upon a successful return this will contain the size in bytes of the specified message.
Remarks
Retrieves the size of a specified message. Internally this will issue the "LIST" command if required.
See Also
BOOL CPop3Connection::GetMessageID(int nMsg, CString& sID);
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
nMsg The message number of the message to retrieve the ID of.
sID Upon a successful return this will contain the ID of the specified message as a string.
Remarks
Retrieves the ID of a specified message. Internally this will issue the "UIDL" command if required. As "UIDL" is an optional POP3 command, your client app should handle the return value if it is to correctly work on all POP3 servers.
See Also
BOOL CPop3Connection::Retrieve(int nMsg, CPop3Message& message);
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
nMsg The message number of the message to retrieve the size of.
message Upon a successful return this will contain the POP3 messages.
Remarks
Retrieves the specified message by issuing the "RETR" command.
See Also
CPop3Connection::GetMessageSize
CPop3Connection::GetMessageHeader
BOOL CPop3Connection::GetMessageHeader(int nMsg, CPop3Message& message);
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
nMsg The message number of the message to retrieve the header of.
sID Upon a successful return this will contain the POP3 messages.
Remarks
Retrieves the header of a specified message. Internally this will issue the "TOP" command if required. As "TOP" is an optional POP3 command, your client app should handle the return value if it is to correctly work on all POP3 servers.
See Also
BOOL CPop3Connection::Reset();
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
None.
Remarks
Resets all messages which were previously marked as deleted. i.e. it undoes the work of all the DELE commands in this session. For further information about how messages are deleted in POP3, please refer to the RFC.
See Also
BOOL CPop3Connection::UIDL();
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
None.
Remarks
Sends the "UIDL" command which retrieves the ID for a specified message. As "UIDL" is an optional POP3 command, your client app should handle the return value if it is to correctly work on all POP3 servers.
See Also
BOOL CPop3Connection::Noop();
Return Value
If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. To get extended error information, call ::GetLastError.
Parameters
None.
Remarks
Issues a "NOOP" command to the server.
CPop3Connection::GetLastCommandResponse
CString CPop3Connection::GetLastCommandResponse() const;
Return Value
The last command response from the server as a CString.
Parameters
None.
Remarks
The CPop3Connection class can return additional text information along with most errors. This extended error information can be retrieved by using the GetLastCommandResponse function after an unsuccessful function call. An example of this is if the Connect function failed because of a validation problem, GetLastCommandResponse could return something like "-ERR Access is denied". GetLastCommandResponse can be called multiple times until another CPop3Connection function is called which sends a POP3 command.
DWORD CPop3Connection::GetTimeout() const;
Return Value
The timeout in milliseconds which the code will wait for responses from the POP3 server.
Parameters
None.
Remarks
Since CPop3Connection provides a synchronous API, a timeout mechanism is provided. By default the value is 2 seconds in release mode and 20 seconds in debug mode. The value is larger in debug mode so that the code does not time out when you are debugging it.
See Also
void CPop3Connection::SetTimeout(DWORD dwTimeout) const;
Return Value
None.
Parameters
dwTimeout The new timeout value in milliseconds.
Remarks
Sets the timeout to use for connections to the POP3 server.
See Also
const char* CPop3Connection::GetMessageText() const;
Return Value
A character pointer to the actual message text this class instance represents.
Parameters
None.
Remarks
Upon a successful call to CPop3Connection::Retrieve, the message class will contain a message. This function allows the text to of the message to be accessed. In the future the CPop3Message will be expanded to include a more complete set of functions.
See Also
PJ Naughter
Email: pjn@indigo.ie
Web: http://indigo.ie/~pjn
4th January 1999