Copyright: Copyright 1995 StarTech Computer Services


yesGetMail Component HelpTRUEGETMAILyesyes29/06/95


Table of Contents

Using the GetMail Component

The Mail_Server Property

The Mail_Port Property

The Mail_Protocol property

The WinsockStarted property

The Mail_Action property

The Mail_Status Property

The Mail_Text Property

The Msg_Subject Property

The Msg_To Property

The Msg_From Property

The Msg_Date Property

The Opt_Preview Property

The Opt_Skip Property

The Opt_Attachment Property

The Attachment Property

The OnAttachmentNameSuggest event

The OnHeadersLoaded event

The Opt_Delete Property

The OnMessageLoaded event

The OnMailInfo event

The Close Method

The Message_Count property

The Message_List property

The Msg_Number property

The Msg_Size property

The User_Id property

The User_Password property

The DoGetMail Method

IsHeader Method

Application Notes


Help file produced by  HELLLP! v2.4b , a product of Guy Software, on 6/29/95 for Unregistered User.

The above table of contents will be automatically completed and will also provide an excellent cross-reference for context strings and topic titles.  You may leave it as your main table of contents for your help file, or you may create your own and cause it to be displayed instead by using the I button on the toolbar.  This page will not be displayed as a topic.  It is given a context string of _._ and a HelpContextID property of 32517, but these are not presented for jump selection.

HINT:  If you do not wish some of your topics to appear in the table of contents as displayed to your users (you may want them ONLY as PopUps), move the lines with their titles and contexts to below this point.  If you do this remember to move the whole line, not part.  As an alternative, you may wish to set up your own table of contents, see Help under The Structure of a Help File.

  Do not delete any codes in the area above the Table of Contents title, they are used internally by HELLLP!

events

methods

properties


Using the GetMail Component

Properties	Methods	Events	Application Notes

 The StarTech GetMail component is used to retrieve Internet mail from mail servers supporting a variety of protocols. Before you use the GetMail component, you should determine if Winsock is available on the system, using the WinsockStarted property. You will next need to provide the server address, using the Mail_Server property, the server port, using the Mail_Port property and the protocol to use, using the Mail_Protocol property. The User_Id and User_Password should also be set.

To check mail, you will set the Mail_Action property or use the DoGetMail method and check for initial success using the Mail_Status property. When you get the OnMessageLoaded event, a message will be contained in Mail_Text, along with the subject in Msg_Subject, the sender in Msg_From,recipient in Msg_To and date in Msg_Date. Additionally, the message number will be stored in Msg_Number, the size will be stored in Msg_Size , the total number of messages will be stored in Message_Count and a list of messages will be stored in Message_List. After transferring the message information, you should set Opt_Delete to determine if the message will be deleted from the server.

If you want to preview a message's headers before downloading it, you can do so with some protocols (POP3 for example) by setting Opt_Preview. When you receive a OnHeadersLoaded event, the headers for a message will be loaded in the Mail_Text property. After examining the headers, you should set Opt_Skip to determine wether the message will be downloaded or skipped.

The OnAttachmentNameSuggest event is generated whenever the GetMail component is processing a message attachment. You should provide a valid filename in  Opt_Attachment so that the attachment can be saved, or provide an empty string so that up to 64K of the attachment can be stored in Attachment.The OnMailInfo event is generated in response to progress indication events, errors and completion status. The Close method is used to cancel a transaction when the connection has timed out.


The Mail_Server Property

Applies to:

GetMail

Declaration:

property Mail_Server: string;

Description:

The Mail_Server property is used to set the mail server. This can either be the name of the server (pop.acme.com) or the address of the server (198.87.65.12).

See Also:

Mail_Port property

Mail_Protocol property


The Mail_Port Property

Applies to:

GetMail

Declaration:

property Mail_Port: integer;

Description:

The Mail_Port property is used to set the mail port of the mail server. This is usually a standard port number dependent on the protocol used, as shown below:

POP2	109

POP3	110

Setting the Mail_Protocol property will set the default port in Mail_Port. It will only need to be changed if the installation being used is not standard.

See Also:

Mail_Server property

Mail_Protocol property


The Mail_Protocol property

Applies to:

GetMail

Declaration:

property Mail_Protocol: TMailProtocol;

type TMailProtocol=(None,POP2,POP3,IMAP2,IMAP3,SMTP);

Description:

The Mail_Protocol property is used to set the protocol of the server. Currently, only POP2 and POP3 are supported, although it is expected that  IMAP and SMTP will be supported shortly. If the Server_Port property has not been set, it will be set to the default port for the given protocol.

See also:

Mail_Port property

Mail_Server property


The WinsockStarted property

Applies to:

GetMail

Declaration:

property WinsockStarted: Boolean;

Description:

Usually, if Winsock is not started when Mail_Action is set, Winsock will be started automatically. However, it is often desirable to check for the presence of Winsock at the beginning of a program. To do this, set the WinsockStarted property to True. If Winsock is not started, it will start. If Winsock did not start successfully, the WinsockStarted property will be False, otherwise it will remain true.

See Also:

Mail_Action property


The Mail_Action property

Applies to:

GetMail

Declaration:

property Mail_Action: GMAction;

type GMAction=(None,Read_Mail);

Description:

Setting Mail_Action to Read_Mail will initiate a transaction to check mail. After setting Mail_Action, you should check for any errors that might  have kept the transaction from continuing, using the Mail_Status property.

See Also:

Mail_Status property

DoGetMail method


The Mail_Status Property

Applies to:

GetMail

Declaration:

property Mail_Status: GetMailInfo

type GetMailInfo=(gmAvailable,gmServerConnected,

gmServerDisconnected,gmNumberMessage,gmMessageSize,

gmGettingMessage,gmTraceIn,gmTraceOut,gmAttachmentName,

gmBusy,gmAlreadyBusy,gmNoWinsock,gmNoMailServer,gmInvalidServer,

gmSocketError,gmReadError,gmWriteError,gmProtocolError,

gmPrematureDisconnect,gmAccessDenied,gmAccessGranted);

Description:

The Mail_Status will contain the intermediate and final status of the transaction. Mail_Status can have the following values:

gmAvailable: indicates end of a transaction, readiness for another transaction.

gmBusy,gmAlreadyBusy: the GetMail component is busy with the previous transaction.

gmNoWinsock: Winsock is not started or available on this system.

gmNoMailServer: A mail server was not specified.

gmInvalidServer: The address or name of the server could not be resolved.

gmSocketError, gmReadError,gmWriteError: A low level socket error occurred (very rare)

gmProtocolError: An unexpected response was received from the server. The wrong protocol or port is being used.

gmPrematureDisconnect: The connection was closed before the transaction completed.

gmAccessDenied: The user id and/or password are not valid on this server.


The Msg_Text Property
The Mail_Text Property

Applies to:

GetMail

Declaration:

property Mail_Text: TStrings

Description:

Mail_Text will contain the headers of a message following an OnHeadersLoaded event, or the headers and body of a message following an OnMessageLoaded event.

See Also:

Msg_Subject property

Msg_To property

Msg_From property

Msg_Date property

Msg_Number property

Msg_Size property


The Msg_Subject Property

Applies to:

GetMail

Declaration:

property Msg_Subject: string;

Description:

The Msg_Subject property will contain the content of the Subject header of a message following an OnMessageLoaded event. or an OnHeadersLoaded event.

See Also:

Mail_Text property

Msg_To property

Msg_From property

Msg_Date property

Msg_Number property

Msg_Size property


The Msg_To Property

Applies to:

GetMail

Declaration:

property Msg_To: string;

Description:

The Msg_To property contains the content of the 'To:' header of a message following an OnMessageLoaded event. or an OnHeadersLoaded event.

See Also:

Mail_Text property

Msg_Subject property

Msg_From property

Msg_Date property

Msg_Number property

Msg_Size property


The Msg_From Property

Applies to:

GetMail

Declaration:

property Msg_From: string;

Description:

The Msg_From property contains the content of the 'From:' header of a message following an OnMessageLoaded event. or an OnHeadersLoaded event.

See Also:

Mail_Text property

Msg_Subject property

Msg_To property

Msg_Date property

Msg_Number property

Msg_Size property


The Message_Date Property
The Msg_Date Property

Applies to:

GetMail

Declaration:

property Msg_Date: string;

Description:

The Msg_Date property contains the content of the 'Date:' header of a message following an OnMessageLoaded event. or an OnHeadersLoaded event.

See Also:

Mail_Text property

Msg_Subject property

Msg_To property

Msg_From property

Msg_Number property

Msg_Size property


The Opt_Preview Property

Applies to:

GetMail

Declaration:

property Opt_Preview: Boolean;

Description:

When the Opt_Preview property is set to True, the message headers will be loaded in Mail_Text and the OnHeadersLoaded event is triggered. This allows you to inspect the message headers and decide if you want to download the  message. Whether the message is downloaded next is controlled by the Opt_Skip property. Some protocols, such as POP2, do not support the Headers Preview option. In such cases, Opt_Preview will remain False, even after setting it to True.

See Also:

Opt_Skip property

OnHeadersLoaded event


The Opt_Skip Property

Applies to:

GetMail

Declaration:

property Opt_Skip: Boolean;

Description:

Setting the Opt_Skip property to True inside the OnHeadersLoaded event handler will cause the current message to be skipped. Setting the Opt_Skip property to False will cause the current message to be loaded.

See Also:

Opt_Preview

OnHeadersLoaded event


The Opt_Attachment Property

Applies to:

GetMail

Declaration:

property Opt_Attachment: string;

Description:

The Opt_Attachment property is set during the OnAttachmentNameSuggest event handler with the full path and filename desired for the attachment currently being processed. Setting the Opt_Attachment property to an  invalid path will cause the attachment to be skipped. Setting  Opt_Attachment to '' will cause as much as the attachment as possible (slightly under 64K) to be stored in the Attachment property.

See Also:

OnAttachmentNameSuggest event

Attachment property


The Attachment Property

Applies to:

GetMail

Declaration:

property Attachment: TStrings;

Description:

The Attachment property will contain as much of the attachment as possible (under 64K) if the Opt_Attachment property is set to '' during the  OnAttachmentNameSuggest event handler.

See Also:

OnAttachmentNameSuggest event

Opt_Attachment property


The OnAttachmentNameSuggest event

Applies to:

GetMail

Declaration:

property OnAttachmentNameSuggest: TAttachmentNameEvent;

TAttachmentNameEvent= procedure (Sender:TObject;name:string)of object;

Description:

The OnAttachmentNameSuggest event is triggered whenever a MIME attachment is encountered in a message. If a filename is found in the attachment header, it will be provided in the name parameter. Note that the filename supplied in the name parameter might not be a suitable DOS name. For example, an attachment might be called long_Unix_name.tar.gz. When handling this event, the desired path and file name should be specified in the Opt_Attachment property. If the Opt_Attachment property specifies an invalid path, or a filename that cannot be created, the attachment will be skipped. If the Opt_Attachment property contains an empty string (''), as much of the attachment as possible (up to 64K) will be stored in the Attachment property.

See Also:

Opt_Attachment property

Attachment property


The OnHeadersLoaded event

Applies to:

GetMail

Declaration:

property OnHeadersLoaded:TGetHeadersEvent;

TGetHeadersEvent= procedure (Sender:TObject)of object;

Description:

The OnHeadersLoaded will be generated if the Opt_Preview property is set to True. When the OnHeadersLoaded event is triggered, the Mail_Text property will contain the headers for a message, the Msg_Subject property will contain the subject of the message, the Msg_From will contain the sender of the message, the Msg_To property will contain the recipient of the message and Msg_Date will contain the date of the message. The Msg_Number property will contain the current message number. Before exiting the OnHeadersLoaded event handler, the  Opt_Skip property should be set to indicate whether the message should be loaded or skipped.

See Also:

Mail_Text property

Msg_Subject property

Msg_To property

Msg_From property

Msg_Date property

Msg_Number property

Opt_Skip property

Opt_Preview


The Opt_Delete Property

Applies to:

GetMail

Declaration:

property Opt_Delete: Boolean;

Description:

The Opt_Delete property determines whether retrieved mail is kept on the server or deleted. Opt_Delete is usually set inside the OnMessageLoaded event handler. Setting Opt_Delete to True will cause the current message to be deleted from the server. If Opt_Delete is set to False, the message will be kept on the server after it is downloaded.

See Also:

OnMessageLoaded event


The OnMailLoaded event
The OnMessageLoaded event

Applies to:

GetMail

Declaration:

property OnMessageLoaded: TGetMessageEvent;

TGetMessageEvent= procedure (Sender:TObject) of object;

Description:

The OnMessageLoaded event is generated after each message is loaded. The message headers and body will be stored in Mail_Text, the sender in Msg_From, the recipient in Msg_To, the subject in Msg_Subject ,the date in Msg_Date. , the message number in Msg_Number and the message size in Msg_Size During the handling of this event, the needed properties should be copied to static storage and the Opt_Delete flag should set, to indicate wether the message should be deleted or left on the server,

See Also:

Mail_Text property

Msg_Subject property

Msg_To property

Msg_From property

Msg_Date property

Msg_Number property

Msg_Size property

Opt_Delete property


The OnGetMailInfo event
The OnMailInfo event

Applies to:

GetMail

Declaration:

property OnMailInfo: TGetMailInfoEvent;

TGetMailInfoEvent = procedure (Sender : TObject; info: GetMailInfo; addinfo: string) of object;

type GetMailInfo=(gmAvailable,gmServerConnected,

gmServerDisconnected,gmNumberMessage,gmMessageSize,

gmGettingMessage,gmTraceIn,gmTraceOut,gmAttachmentName,

gmBusy,gmAlreadyBusy,gmNoWinsock,gmNoMailServer,gmInvalidServer,

gmSocketError,gmReadError,gmWriteError,gmProtocolError,

gmPrematureDisconnect,gmAccessDenied,gmAccessGranted);

Description:

The OnMailInfo event provides progress information, error reports and completion notification. The info parameter will have one of the following values:

gmAvailable: indicates end of a transaction, readiness for another transaction.

gmNoWinsock: Winsock is not started or available on this system.

gmSocketError, gmReadError,gmWriteError: A low level socket error occurred (very rare)

gmProtocolError: An unexpected response was received from the server. The wrong protocol or port is being used.

gmPrematureDisconnect: The connection was closed before the transaction completed.

gmAccessDenied: The user id and/or password are not valid on this server.

gmAccessGranted: Indicates successful logon to server.

gmNumberMessage: Indicates number of messages in mailbox, addinfo contains number of messages. Sent before any messages are retrieved.

gmMessageSize: Sent before a message is retrieved to indicate size of message. addinfo will contain the size of the forthcoming message, in bytes

gmGettingMessage: Sent while a message is being retrieved to indicate how many bytes have been retrieved so far. addinfo will contain the number of bytes downloaded so far.

gmTraceIn,gmTraceOut: usually used for debugging, indicate everything received or sent by the socket in addinfo.

gmAttachmentName: Specifies in addinfo the name of the attachment currently being processed.

gmServerConnected: Indicates connection to a server. addinfo will contain the address of the server.

gmServerDisconnected: Indicates closing of the connection

The following figure illustrates the order of events for a simple transaction with one message containing one attachment: (omitting TraceIn and TraceOut for simplicity)

OnMailInfo	gmServerConnected	128.23.54.3

OnMailInfo	gmAccessGranted

OnMailInfo	gmNumberMessage	1

OnMailInfo	gmMessageSize	10602

OnMailInfo	gmGettingMessage	200

..................................................................................................

OnMailInfo	gmGettingMessage	6504

OnAttachmentNameSuggest

OnMailInfo	gmGettingMessage	6798

..................................................................................................

OnMailInfo	gmGettingMessage	10602

OnMessageLoaded

OnMailInfo	gmServerDisconnected

OnMailInfo	gmAvailable


The Close Method

Applies to:

GetMail

Declaration:

procedure Close;

Description:

The Close method is provided to enable the canceling of a transaction due to a time-out. For instance, connecting the GetMail component to a finger port will cause the component to wait for input from the server, which will never arrive. A cancel button or timer which calls the Close method will enable the connection to be closed, without waiting for the server to close the connection, which could take several minutes.


The Message_Count property

Applies to:

GetMail

Declaration:

property Message_Count: integer;

Description:

The Message_Count property contains the number of messages in the users mailbox on the server.

See Also:

Message_List property


The Message_List property

Applies to:

GetMail

Declaration:

property Message_List: TStrings;

Description:

The Message_List property contains the list of messages in the users mailbox on the server and the size of the messages.

See Also:

Message_Count property


The Msg_Number property

Applies to:

GetMail

Declaration:

property Msg_Number: integer;

Description:

The Msg_Number property contains the current message number following an OnMessageLoaded event. or an OnHeadersLoaded event.

See Also:

Mail_Text property

Msg_Subject property

Msg_To property

Msg_From property

Msg_Date property

Msg_Size property


The Msg_Size property

Applies to:

GetMail

Declaration:

property Msg_Size: Longint;

Description:

The Msg_Size property contains the size of the current message number following an OnMessageLoaded event. or an OnHeadersLoaded event.

See Also:

Mail_Text property

Msg_Subject property

Msg_To property

Msg_From property

Msg_Date property

Msg_Number property


The User_Id property

Applies to:

GetMail

Declaration:

property User_Id: string;

Description:

The User_Id property should contain the id of user logging in onto the mail server.

See Also:

User_Password property


The User_Password property

Applies to:

GetMail

Declaration:

property User_Password: string;

Description:

The User_Password property should contain the password of user logging in onto the mail server.

See Also:

User_Id property


The DoGetMail Method

Applies to:

GetMail

Declaration:

procedure DoGetMail;

Description:

Calling the DoGetMail method will initiate a transaction to check mail. After calling DoGetMail, you should check for any errors that might  have kept the transaction from continuing, using the Mail_Status property.

See Also:

Mail_Status property

Mail_Action property


Application Notes

The following code fragments show the steps involving in checking for mail:

1. Setup server and user information:

Mail_Server:=pop.acme.com;

Mail_Protocol:=POP3;

Mail_Port:=110

User_Id:=jdoe;

User_Password:=secret;

Opt-Preview:=True;{optional}

2. Connect and check for errors:

Mail_Action:=Read_Mail; {or DoReadMail;}

If Mail_Status<>Busy then

we have an error, transaction is over

else

everything proceeding normally

3. In this example, we are looking for messages with the subject Maillist:

procedure OnHeadersLoaded(Sender: Tobject);

begin

if Lowercase(Msg_Subject)=maillist then Opt_Skip:=False

else Opt_Skip:=True;

end;

4. We handle attachments here:

procedure OnAttachmentNameSuggest(Sender: Tobject, name: string);

var

s:	TSaveDialog

begin

try

s:=TSaveDialog.Create;

s.Filename:=name;

if s.Execute then Opt_Attachment:=s.Filename;

except

{}

end;

end;

5. We handle the body of the message here:

procedure OnMessageLoaded(Sender: Tobject);

begin

transfer Mail_Text to a local mailbox;

end;

6. We wait for completion here:

procedure OnMailInfo(Sender:TObject,info: GetMailInfo, addinfo:string);

begin

if info:=gmAvailable then

if Mail_Status:=gmAvailable then

everything went ok

else

error is stored in Mail_Status

end;

end;


IsHeader Method

Applies to:

GetMail

Declaration:

function IsHeader(name: string; var value: string): Boolean;

Description:

The IsHeader Method is provided to facilitate the parsing of headers during an OnHeadersLoaded event. The name parameter should contain the name of the header to search for, including the terminating colon. If the header is found, its value will be stored in the value parameter and the function will return True. Otherwise, the function will return False and the value of the value parameter will be undefined.

See Also:

OnHeadersLoaded event


properties

Attachment	Message_List

Opt_Attachment	Msg_Date

Opt_Delete	Msg_From

Opt_Preview	Msg_Number

Opt_Skip	Msg_Subject

Mail_Action	Mail_Text

Mail_Port	Msg_To

Mail_Protocol	Msg_Size

Mail_Server	User_ID

Mail_Status	User_Password

Message_Count


events

OnMailInfo

OnMessageLoaded

OnHeadersLoaded

OnAttachmentNameSuggest


methods

Close

DoGetMail

IsHeader