View source for TPop3Cli

[[Main_Page | Main page]] -> [[ICS_Components_Reference | ICS components reference]] -> [[TPop3Cli]]
== Overview ==

*'''unit''' Pop3Cli.pas
*'''inheritance''' TPop3Cli - TComponent

The TPop3Client is a WinSock based component, that allows the user to connect to a POP3 server, retrieve or delete messages by just defining some Properties, using some Events and calling some Methods. It is as easy as it seems.

== Properties ==

{|
| valign="top" width="150" | [[TPop3Cli.ErrorMessage | ErrorMessage]] |||| Use this property to view the error generated by the last command issued by the TPop3Client component. This property does not include wrong password or wrong username.
|-
| valign="top" | [[TPop3Cli.Host | Host]] |||| Set the Host property to your pop3 host, so that the TPop3Client component knows which server you want to connect to. If no host is defined, the Connect method will generate an error.
|-
| valign="top" | [[TPop3Cli.LastResponse | LastResponse]] |||| Use this property to check what was the last response of the server, based on your last command. It can be used to show the error, if any, that occurred during the last method issued. It is more effective than the ErrorMessage property because it include the responses from the server that can be errors on all Methods issued.
|-
| valign="top" | [[TPop3Cli.MsgCount | MsgCount]] |||| Use this property to check the number of messages on the server. Note that messages marked as deleted are not counted in either total. Use the Stat method to update the number of messages in the mail server.
|-
| valign="top" | [[TPop3Cli.MsgLines | MsgLines]] |||| Use this property with MsgNum and Top to define the lines of the message to be displayed. It is also updated by the Last method. Set to zero if you want the default value.
|-
| valign="top" | [[TPop3Cli.MsgNum | MsgNum]] |||| Use this property to define the ID of the message and, defining the MsgLines property and using the Top  method, the client can display information of the message.
|-
| valign="top" | [[TPop3Cli.MsgSize | MsgSize]] |||| MsgSize is the total bytes occupied by the messages on the server. Use this after the Stat method.
|-
| valign="top" | [[TPop3Cli.MsgUidl | MsgUidl]] |||| This is a unique string given by the server to the message. This string does not change as the ID of the message, and the messages can be indentified by it.  Define the ID of the message with the MsgNum property and then call the Uidl method to retreive the information.
|-
| valign="top" | [[TPop3Cli.PassWord | PassWord]] |||| Set this property with the password of the UserName used to connect to the Host.
|-
| valign="top" | [[TPop3Cli.Port | Port]] |||| Set this property with the Port (usually 110 or pop3, on this component) used to connect to the Host. If you are not sure about the port, contact your ISP (Intenet Service Provider).
|-
| valign="top" | [[TPop3Cli.ProtocolState | ProtocolState]] |||| This property can be either pop3Disconnected, pop3WaitingUser, pop3WaitingPass, pop3Transaction or pop3Update.
|-
| valign="top" | [[TPop3Cli.Tag | Tag]] |||| The Tag property is not used at all. It can be used for user-defined integer variable.
|-
| valign="top" | [[TPop3Cli.TimeOut | TimeOut]] |||| Set this property to set the TimeOut of the connection, in seconds. The pop3client component will try to connect until the TimeOut seconds is reached.
|-
| valign="top" | [[TPop3Cli.UserName | UserName]] |||| Set this property with the Username used to connect to the Host.
|-
| valign="top" | [[TPop3Cli.Wait | Wait]] |||| The Pop3Client component uses the TWait component so it can show the TimeOut of the connection with the Host. It cannot be nil.
|}

== Methods ==

{|
| valign="top" width="150" | [[TPop3Cli.Apop | Apop]] |||| Uses APOP authentication that doesn't send plain text username and password but not all servers support this.
|-
| valign="top" | [[TPop3Cli.Connect | Connect]] |||| Use this method to connect to the server. Use this before trying to log on the server. Define the host, with the Host property, the Username with the UserName and the password with the PassWord properties. If it's required, the port in witch the Pop3Client connects can be changed with the Port property.
|-
| valign="top" | [[TPop3Cli.Dele | Dele]] |||| Use this method to make the POP3 server to mark the message as deleted. Define the message ID to be deleted with the MsgNum property. Any future reference to the message-id associated with the message in a POP3 command generates an error. The POP3 server does not actually delete the message until the POP3 session is terminated. The deleted messages can be recovered BEFORE the session ends, with the Rset method.
|-
| valign="top" | [[TPop3Cli.Last | Last]] |||| Use this method to make the POP3 server to issue a response with a line containing the highest message number which accessed. Zero is returned in case no message in the mail-drop has been accessed during previous transactions. A client may thereafter infer that messages, if any, numbered greater than the response to the LAST command are messages not yet accessed by the client.
|-
| valign="top" | [[TPop3Cli.List | List]] |||| Use this method to make the Pop3 server to display informations of the message. Define the ID of the message by the MsgNum property. The first octets present is the message-id of the message. Following the message-id is the size of the message in octets. If no ID is specified, the response is the information of all messages on the mail account, on the server. This method triggers the OnListBegin event. When Pop3Client receives a line, it triggers , the OnListLine. When the command is over, it triggers the OnListEnd.
|-
| valign="top" | [[TPop3Cli.Noop | Noop]] |||| The POP3 server does nothing, it merely replies with a positive response. Useful to prevent being disconnected after some idle time in some servers.
|-
| valign="top" | [[TPop3Cli.Pass | Pass]] |||| Use this method after the User method to make the TPop3Client log on the server.
|-
| valign="top" | [[TPop3Cli.Quit | Quit]] |||| Use this method to make the TPop3Client log off the server.
|-
| valign="top" | [[TPop3Cli.Retr | Retr]] |||| Use this method to retrieve a message from the server. Define the ID of the message with the MsgNum. If no ID is assigned, an error is generated. The server assigns the message ID to the "highest number accessed". If the ID is smaller than the highest number accessed, this remains unchanged.
|-
| valign="top" | [[TPop3Cli.Rpop | Rpop]] |||| Use this method on some servers instead of the Pass method and along with the User method to authenticate access. In order for this command to be successful, the POP3 client must use a reserved TCP port (port < 1024) to connect to the server. The POP3 server uses the argument pair from the USER and RPOP commands to determine if the client should be given access to the appropriate mail-drop. Unlike the Pass method however, the POP3 server considers if the remote user specified by the RPOP command who resides on the POP3 client host is allowed to access the mail-drop for the user specified by the User method. With the exception of this differing in authentication, this command is identical to the Pass method.
|-
| valign="top" | [[TPop3Cli.Rset | Rset]] |||| Use this method so that If any messages have been marked as deleted (Dele method) by the POP3 server, they are unmarked. In addition, the "highest number accessed" is also reset to the value determined at the beginning of the POP3 session.
|-
| valign="top" | [[TPop3Cli.Stat | Stat]] |||| Use this method to make the server respond with information on  the messages on the mail account. The first octets present are the number of messages on the server. Following this, is the size of the messages in octets.
|-
| valign="top" | [[TPop3Cli.Top | Top]] |||| Use this method to make the server send information of a message defined in the MsgNum property. The server will send the Header plus a blank line plus the lines defined in the MsgLines property.
|-
| valign="top" | [[TPop3Cli.Uidl | Uidl]] |||| Use this method to display the Uidl of the message ID defined in the MsgNum. A Uidl is a unique string given by the server to the message. This string does not change as the ID of the message, and the messages can always be identified by it.
|-
| valign="top" | [[TPop3Cli.User | User]] |||| Use this method to send the Username, defined on the UserName property, to the server.
|}

== Events ==

{|
| valign="top" width="150" | [[TPop3Cli.OnDisplay | OnDisplay]] |||| Use this event to display the commands (Methods) of the client and responses of the server.
|-
| valign="top" | [[TPop3Cli.OnHeaderEnd | OnHeaderEnd]] |||| This event is triggered when message header has been transferred. Header ends after two CRLFCRLF are encountered from the top of the message.
|-
| valign="top" | [[TPop3Cli.OnListBegin | OnListBegin]] |||| This event is triggered by the List method. It is used to identify when this method begins.
|-
| valign="top" | [[TPop3Cli.OnListEnd | OnListEnd]] |||| This event is triggered when the List has ended.
|-
| valign="top" | [[TPop3Cli.OnListLine | OnListLine]] |||| This event is triggered when the List receives information on a message.
|-
| valign="top" | [[TPop3Cli.OnMessageBegin | OnMessageBegin]] |||| This event is triggered by the Retr method. It indicates when a message is about to be retrieved by the server.
|-
| valign="top" | [[TPop3Cli.OnMessageEnd | OnMessageEnd]] |||| This event is triggered when the Retr method has ended.
|-
| valign="top" | [[TPop3Cli.OnMessageLine | OnMessageLine]] |||| This event indicates when the Retr method has received a line of a message. It can be used to store the message on a file (keep adding the received lines on the file).
|-
| valign="top" | [[TPop3Cli.OnRequestDone | OnRequestDone]] |||| This event is triggered when server finishes sending a reply after a particular command you sent to it.
|-
| valign="top" | [[TPop3Cli.OnResponse | OnResponse]] |||| This event is triggered before server starts sending a reply after a particular command you sent to it.
|-
| valign="top" | [[TPop3Cli.OnSessionClosed | OnSessionClosed]] |||| This event is triggered right after you are disconnected from the server (usually after QUIT).
|-
| valign="top" | [[TPop3Cli.OnSessionConnected | OnSessionConnected]] |||| This event is triggered right after you are connected to the server after using [[TPop3Cli.Connect | Connect]] method.
|-
| valign="top" | [[TPop3Cli.OnStateChange | OnStateChange]] |||| This event is triggered when the state of the connection changes.
|-
| valign="top" | [[TPop3Cli.OnUidlBegin | OnUidlBegin]] |||| This event is triggered by the Uidl method. It indicates when a UIDL is requested.
|-
| valign="top" | [[TPop3Cli.OnUidlEnd | OnUidlEnd]] |||| This event indicates when the Uidl method has ended.
|-
| valign="top" | [[TPop3Cli.OnUidlLine | OnUidlLine]] |||| This event indicates when the Uidl method receives a line of the Uidl from the message.
|}

== How to ==

{{Components_Footer}}