|
|
PHDEmail Component POP3 Object Interface |
Last modified: 20 July 2001. |
|
IntroductionThe PHDPOP3 object in the PHDEmail COM component lets you read emails using POP3. It runs in any COM programming language or container.Most people will use the PHDPOP3 object in an application that has to interrogate a server to read emails. However you can also happily call it from an ASP script, or a Dynamic-CD GASP script.
Limitations
Technical informationThe PHDPOP3 object interface Program ID is"PHDEmail.PHDPOP3".
PHDEMail is an ANSI component, ie it works with 8-bit characters. If you are running an application that sends non-ANSI characters to PHDEmail, then these will be received as question marks (?). Characters read by your application will be converted to your code page as best as possible. See below for details of how message text is encoded.
The Post Office Protocol 3 (POP3) defines one way to read emails over the net.
POP3 was originally defined in RFC 1460;
the latest definition is in RFC 1939.
The email message format was originally defined in RFC 822;
the latest definition is in RFC 2822.
Other RFCs define other aspects of message formatting. UsageDo not forget to register the PHDEmail component first.In your chosen programming environment, create an instance of the "PHDEmail.PHDPOP3" object. Then set the RemoteHostName, UserName and Password properties. Call the ConnectToRemoteHost(), USER() and PASS() methods to connect to your POP3 server, identify the mailbox and authenticate yourself, not forgetting to check the return results from each method call. You will normally then call STAT() and inspect the single line in Response to determine the number of messages in the mailbox. The number of messages will not change in this session if you mark a message for deletion using DELE(). If you want, you can then set MessageNumber to zero and call LISTn() to get a multi-line response, with one line per available message containing its number and raw size in bytes. Initially the message numbers will increment from 1 upwards. However if you mark a message for deletion using DELE(), then that message number will not appear in future. For example if you delete the third message of four available, a subsequent LISTn(0) will return lines with message numbers 1, 2 and 4.
To read a message, set MessageNumber to the appropriate message
number and call RETR().
The whole message is stored in Message and its constituent
parts are extracted and put in MessageHeader,
MessageBody,
MessageDate,
MessageSubject and
MessageSender. If you do not want to get all a message, then call TOPn() for the desired MessageNumber. Give TOPn() a parameter indicating the number of lines of the message body that you want to receive, ie a number from zero upwards. The header is always read. All the same variables are set as for RETR(), with the MessageBody empty if the requested number of lines is zero. Note that there is a chance that some older POP3 servers may not support TOPn(). To delete a message, set the MessageNumber and call DELE(). The message will be marked for deletion and will not appear in a LISTn(0) listing. However the message will only actually be deleted when a call to QUIT() completes successfully. When you have finished, call QUIT(). Your POP3 server will now delete any messages that you have marked for deletion using DELE(). ErrorsAll the PHDPOP3 methods return zero if successful. This usually indicates that the POP3 server started its Response with the POP3 success indication "+OK". For POP3 error indications starting "+ERR" and other PHDPOP3 detected errors, a negative value is returned. Numbers greater than 10000 are communication errors, such as a timeout. The fileEmailErr.h in the development kit
is a C++ header with definitions of the PHDEmail negative error values.
The ErrorMsg read-only property contains a full description of the error. The Response read-only property contains the last response line or lines obtained from your POP3 server. Response may be an empty string. If you get timeout errors, then you might like to try increasing the values of the RecvTimeout and SendTimeout parameters. PHDEmailTest C++ ExampleThe PHDEmailTest program shows how to access the PHDEmail PHDPOP3 object from C++. See the main page for basic information about PHDEmailTest.The picture below shows the POP3 tab of PHDEmailTest in action. The user has connected and got a list of messages. Message 8 has been selected and retrieved.
The PHDPOP3 interface has been imported into a class called IPHDPOP3, defined in
In the SMTP example, an IPHDSMTP instance was only used
when the Send button was pressed. In the POP3 code, the IPHDPOP3 instance
(pointer The code for the Connect button makes many PHDEmail PHDPOP3 calls. It sets the RemoteHostName, UserName and Password properties, and then calls ConnectToRemoteHost(), USER() and PASS() to connect to the POP3 server. Routine GetMessageList() calls STAT() to determine the total number of messages. It then calls LISTn() to get a list of available message numbers. For each available message, TOPn() is called to retrieve the message header. This information is used to fill the message list box. Clicking on Disconnect results in a call to QUIT(); any messages marked for deletion are deleted if this call works. Alternatively calling Abandon simply calls CleanupConnection() so that messages marked for deletion are NOT deleted. Clicking on Exit is the same as calling Disconnect. Get Message retrieves the selected message using RETR(). Delete Message marks the selected message for deletion using DELE(); the message list is refilled using GetMessageList(). Finally, Top Lines retrieves the top lines of the selected message using TOPn(). Use of RSET() method is not illustrated. If you call this, then any messages marked as deleted are undeleted. PropertiesHere is a complete list of the PHDEMail component PHDPOP3 object properties. Those listed in a yellow background are advanced parameters that are not normally used.
MethodsHere is a complete list of the PHDEMail component PHDPOP3 object methods, ie functions. Those listed in a yellow background are advanced methods that are not normally used.All methods set ErrorMsg and Response unless otherwise noted.
Message EncodingOriginally emails could only be 7-bit with very limited line lengths, ie 76-80 characters. Various Internet RFC standards have been defined over the years to overcome these restrictions to let us send and receive whatever text and files we want in emails. These standards specify how text and files should be encoded so that no information is lost.PHDPOP3 does not currently support the full gamut of email encodings. However PHDPOP3 automatically recognises the Quoted-Printable encoding and decodes the MessageBody returned by the RETR() and TOPn() methods. Note that the Message property is not decoded. PHDPOP3 does nothing for all other encodings. |
