The purpose of these data types is to unify the functions of interaction with the sending and receiving of messages for the different generate languages.
A very important advantage of this implementation, compared to the previous ones, is that it allows using more than one instance of connection to the email server.
Objects: Transactions, Web Panels, Procedures
Generators: C/SQL (only SMTPSession and POP3Session), Java, .NET, .NET Framework (only SMTPSession, and POP3Session)
To use this new functionality the following data types have been created:
Data type
|
Description
|
Requirements
|
SMTPSession
|
Allows you to use an email session to send messages through a server using the SMTP (Simple Mail Transfer Protocol).
|
TCP/IP protocol. Doesn’t require Office.
|
POP3Session
|
Allows you to use an email session to receive messages from a server using POP3 (Post Office Protocol Version 3).
|
TCP/IP protocol. Doesn’t require Office.
|
The SMTPSession, and POP3Session Data types indicate the mode in which the sending and receiving of emails will be carried out.
Furthermore, internally you can work with the following Data types:
The available properties and methods for this data type are the following:
Attachment directory.
Syntax: &SMTPSession.AttachDir
Specifies which directory will be used for searching attachments to messages (Attachments property).
The default value is an empty chain (“”).
Indicates whether or not to try authentication with the server.
Syntax: &SMTPSession. Authentication
Some SMTP servers require authentication. In these cases you can set the Authentication property to 1 and specigy in the UserName and Password properties thw username and password to be used. These values will be taken into account in the next call to the Login method.
The only authentication mechanism is Clear Text. If you specify the paramaters UserName and Password and the server does not support Clear Text authentication, then the method will return the error 23
The default value is 0.
Error code of the last operation.
Syntax: &SMTPSession.ErrCode
See the section “Error Codes and Messages” of this document.
Error message of the last operation. The message list details can be found in the ErrCode property.
Syntax: &SMTPSession.ErrDescription
See the section “Error Codes and Messages” of this document.
Indicates whether or not error messages will be displayed.
Syntax: &SMTPSession.ErrDisplay
Specifies whether or not, when an error occurs, an error message will be displayed, warning the user with the error text. If ErrDisplay=1 then the message will be displayed, while if it’s 0 then it won’t.
The default value is 0.
Note:
- This property is not available in the C/SQL generator.
Address of the SMTP server.
Syntax: &SMTPSession.Host
You can specify the server name and its address.
Password used for authentication in the server
Syntax: &SMTPSession.Password
This property will be ignored if the Authentication property is set to 0.
Port of the SMTP server in the Host.
Syntax: &SMTPSession.Port
The default value is 25, the port normally used by STMP servers.
Data from the sender, to be included in the sent messages.
Syntax: &SMTPSession.Sender
When you create a variable of the SMTPSession type, the Sender property contains a MailRecipient object with the Name and Address properties empty. For this reason, the sender’s data can be directly assigned to the Name and Address properties of the already-created object, or another object of the MailRecipient type can be assigned, from which these properties will be copied.
For the Login method to work, it’s necessary to have valid values in the Sender property.
Maximum time, in seconds, to wait for an answer from the server after each request.
Syntax: &SMTPSession.Timeout
This value must adapt to the speed of the communications network and the server’s load. For local networks you must use small values, and bigger values if you’re using Internet, especially if you are connecting to very remote servers.
The default value is 30.
Username used for authentication in the server.
Syntax: &SMTPSession.UserName
This property will be ignored if the Authentication property is set to 0.
Begins a session with an SMTP server.
Syntax: &SMTPSession.Login
The SMTP session will begin with the server specified in the Host property in the port specified in the Port property. The values in the UserName and Password properties will be used for authentication with the server.
Ends the session with an SMTP server.
Syntax: &SMTPSession.Logout
Sends a message.
Syntax: &SMTPSession.Send(Message)
Notes:
- The Message parameter is of the MailMessage type.
The available properties and methods for this data type are the following:
Attachment directory.
Syntax: &POP3Session.AttachDir
Specifies the directory in which to save attachments when the Receive method is executed. If this property contains an empty chain (“”), attachments won’t be saved.
The default value is an empty chain (“”).
Cantidad de mensajes a recibir.
Syntax: &POP3Session.Count
Returns the quantity of messages which comply with the conditions of the folder opening. That is to say, if the folder or session was opened specifying that only the unread messages should be received (through the use of the NewMessages property), it will return the number of unread messages; while if the folder was opened specifying that all messages should be received, then it will return the total number of messages.
Error code of the last operation.
Syntax: &POP3Session.ErrCode
See the section “Error Codes and Messages” of this document.
Error message of the last operation. The message list details can be found in the ErrCode property.
Syntax: &Error = &POP3Session.ErrDescription
See the section “Error Codes and Messages” of this document.
Indicates whether or not error messages will be displayed.
Syntax: &POP3Session.ErrDisplay
Specifies whether or not, when an error occurs, an error message will be displayed, warning the user with the error text. If ErrDisplay=1 then the message will be displayed, while if it’s 0 then it won’t.
The default value is 0.
Note:
- This property is not available in the C/SQL generator.
Address of the POP3 server.
Syntax: &POP3Session.Host
You can specify both the server’s name and its IP address.
Indicates whether all messages or only new messages will be received.
Syntax: &POP3Session.NewMessages
If NewMessages= 1 the calls to the Receive method will return only the unread messages of the current folder. If it’s 0, it will return all the messages of the folder.
The default value is 0.
This property will be effective as of the next call to the Login method.
The most recent implementations of POP3 servers do not have the necessary mechanism for the correct functioning of this property when it has value 1. In the case that the Login method is called specifying in the Host property a server that does not have said mechanism and this property has value 1, it will return error 29.
Password used for authentication in the server
Syntax: &POP3Session.Password
Port of the POP3 server in the Host.
Syntax: &POP3Session.Port
The default value is 110, the port normally used by POP3 servers.
Maximum time, in seconds, to wait for an answer from the server after each request.
Syntax: &POP3Session.Timeout
This value must adapt to the speed of the communications network and the server’s load. For local networks you must use small values, and bigger values if you’re using Internet, especially if you are connecting to very remote servers.
The default value is 30.
Username used for authentication in the server.
Syntax: &SMTPSession.UserName
Deletes the last message that was received with the Receive method from the server.
Syntax: &POP3Session.Delete()
The message is permantently deleted, and this is performed when the Logout method is executed.
If the Receive method has not been called, or if the last call didn’t return a message (for example, because of an error), calling the Delete method will return error 26.
Begins a session with POP3 serve.
Syntax: &POP3Session.Login
The POP3 session will begin with the server specified in the Host property in the port specified in the Port property. The values in the UserName and Password properties will be used for authentication with the server.
Ends the session with a POP3 server.
Syntax: &POP3Session.Logout
Receives a message.
Syntax: &POP3Session.Receive(Message)
Returns the data of the next email in the current session or folder.
If the email has attachments, and a directory was specified in the AttachDir property, they will be saved to disk
Note:
- The Message parameter is of the MailMessage data type.
The possible values are: (I=SMTPSession/POP3Session):
Code
|
Message
|
Modes
|
0
|
Ok
|
I
|
1
|
Already logged in
|
I
|
2
|
Not logged in
|
I
|
3
|
Could not complete login
|
I
|
6
|
Invalid sender name
|
I
|
7
|
Invalid sender address
|
I
|
8
|
Invalid user name
|
I
|
9
|
Invalid password
|
I
|
10
|
Could not send message
|
I
|
11
|
No messages to receive
|
I
|
12
|
Could not delete message
|
I
|
13
|
No main recipient specified
|
I
|
14
|
Invalid recipient
|
I
|
15
|
Invalid attachment
|
I
|
16
|
Could not save attachment
|
I
|
17
|
Invalid Authentication value
|
I
|
18
|
Not enough memory
|
I
|
19
|
Connection lost
|
I
|
20
|
Timeout exceeded
|
I
|
21
|
Memory allocation error
|
I
|
23
|
The server does not recognize any of the supported authentication methods
|
I
|
24
|
Authentication error
|
I
|
25
|
User or password refused
|
I
|
26
|
No current message
|
I
|
27
|
Invalid NewMessages value
|
I
|
29
|
POP3 server does not support NewMessages = 1
|
I
|
- The methods previously described were implemented so that they return error codes (as if they were functions), so it is possible to call them as functions.
Shown below are examples of events in GeneXus which allow the sending and receiving of emails with the different data types (SMTPSession/POP3Session):
The &Send and &Receive variable must be defined as MailMessage type, &MessageSMTP must be a SMTPSession type, &MessagePOP3 of the POP3Session type, and the &AddressTo and &AddressCC variables musy ne of the MailRecipient type.
Event 'Send'
&AddressTo.Address = ‘isidoro@cañones.com
&AddressTo.Name = ‘Isidoro Cañones’
&Send.To.Clear()
&Send.To.Add(&AddressTo)
&AddressCC.Address = ‘cachorra@bazuka.com
&AddressCC.Name = ‘Cachorra Bazuka’
&Send.Cc.Clear()
&Send.Cc.Add(&AddressCC)
&Send.Subject = ‘You’re invited to my party’
&Send.HTMLText = ‘Next Saturday I celebrate my birthday, do not miss it!’
// The SMTP server used in this case does not need authentication.
&MessageSMTP.Host = ‘SMTP Server’
&MessageSMTP.Sender.Name = ‘Patoruzu’
&MessageSMTP.Sender.Address = ‘patoruzu@hotmail.com’
&MessageSMTP.Authentication = 1
&MessageSMTP.UserName = ‘My user’
&MessageSMTP.Password = ‘My password’
&MessageSMTP.Login()
&MessageSMTP.Send(&Send)
if &MessageSMTP.ErrCode <> 0
msg(&MessageSMTP.ErrDescription)
endif
&MessageSMTP.Logout()
EndEvent
Event 'Receive’
&MessagePOP3.Host = ‘POP3 Server’
&MessagePOP3.UserName = ‘My user’
&MessagePOP3.Password = &pass
&MessagePOP3.NewMessages = 1
&MessagePOP3.Login()
&MessagePOP3.Receive(&Receive)
&From = &Receive.From.Address()
&Datesen = &Receive.DateSent()
&Daterec = &Receive.DateReceived()
&Sub = &Receive.Subject()
&Texthtml = &Receive.HTMLText()
EndEvent