Festo AG & Co.

KG

Festo_SMTP.lib
Documentation of the library Festo_SMTP.lib for CoDeSys 2.3

staf
18.02.2010
2 Festo_SMTP.lib

Content
General ..................................................................................................................................................... 3

Architecture ............................................................................................................................................. 3

Conditions ................................................................................................................................................ 5

The functions/function blocks ................................................................................................................. 6

Overview of the inputs and outputs of the function block SMTP_sendMail........................................... 7

Usage of the function block SMTP_sendMail ..................................................................................... 8

Festo AG & Co.KG

3 Festo_SMTP.lib

General
Festo_SMTP.lib is an internal CoDeSys 2.3 library. With this library it’s possible to send E-Mail’s via
simple mail transfer protocol.

Architecture
To send a message, you must save an instance of the function module SMTP_sendMail. The function
block on the other hand calls functions and function blocks until the mail is sent or an error occurred.
On failure, the output variable error contains the error message of the server.

The module uses the function SMTP_connect to establish a connection to the SMTP server, whose IP-
Address was passed at the entrance. If a connection could be established, the SMTP commands to the
server will be sent by the function module SMTP_sendBuf and evaluated each response from the
server via the function module SMTP_recvReply. The SMTP_close function closes the connection to
the server.

The following flowchart represents the calling hierarchy and functionality of SMTP_sendMail :

Festo AG & Co.KG

4 Festo_SMTP.lib

SMTP_connect()
Server connected? no
Establish connection to the specified
SMTP-Server

yes

SMTP_recvReply() SMTP_SendBuf()
Receive reply from Servers Send SMTP-command EHLO

yes SMTP_SendBuf()
Server need
Authentication ?
Send SMTP-command AUTH

no

SMTP_recvReply() SMTP_SendBuf()
Receive reply from Servers Send SMTP-command MAIL

SMTP_recvReply() SMTP_SendBuf()
Receive reply from Servers Send SMTP-command RCPT

SMTP_recvReply() SMTP_SendBuf()
Receive reply from Servers Send SMTP-command DATA

SMTP_recvReply() SMTP_SendBuf()
Receive reply from Servers Send SMTP-command QUIT

SMTP_recvReply()
Receive reply from Servers

SMTP_close() Finish function block

Close connection

Festo AG & Co.KG

5 Festo_SMTP.lib

Conditions
The function block SMTP_sendMail requires access to an SMTP server over TCP/IP (TCP port 25).
The IP address of the SMTP server must be known. The name of the server is not sufficient because
DNS is not supported by each controller.

Determine of the IP address of the server

The IP address of the SMTP server (if not known) can be determined, by pinging the server from the
PC.

Simply open the Windows command prompt and type the command ping with the SMTP server name:

e.g.: ping mx0.gmx.de

Log on to an SMTP server

It is usually necessary to log in to a SMTP-server with username and password to send mail’s through
the server. In local networks is not strictly necessary.

There are different methods to log in to a SMTP-server.

SMTP_sendMail supports the most common methods of PLAIN, LOGIN and CRAM-MD5.

Festo AG & Co.KG

6 Festo_SMTP.lib

The functions/function blocks

The Festo_SMTP.lib includes the following function blocks (FB's) and functions(FUN):

Function block which is called by the user:

Function/Functionblock Description

SMTP_sendMail FB to send a mail

Function blocks respectively functions which are used by SMTP_sendMail:

Function/Functionblock Description

SMTP_connect Function to establish a connection to a SMTP-Server

SMTP_sendBuf FB to send SMTP-commands respectively E-Mail data

SMTP_recvReply FB to receive and evaluate answers from the SMTP-Servers

SMTP_close Function to close connection to t he SMTP-Servers

Key features that are used by SMTP_sendMail to encoding/decoding:

Function/Functionblock Description

Base64_encode Function to encode data by base64 method

Base64_decode Function to decode data by base64 method

Base64_encode_file Function to encode of Email attachments by base64 method

Hmac_MD5 Function to encode data by CRAM-MD5 method

Festo AG & Co.KG

Overview of the inputs and outputs of the function block SMTP_sendMail
Following table shows the inputs and outputs of the function block:

Input Datatype Description Optional

ServerIP STRING IP address of the SMTP server No

OwnIP STRING IP address of the controller No

SenderAddress STRING Email address of the controller No

ReceiverAddress STRING The recipient E-Mail address No

Only one recipient can be specified

Subject STRING Subjectline Yes

Mailcontent DWORD Pointer to a storage area that contains the No

mailtext. Maximum size of the mailtext
ist 32KB.

Size INT Size oft he mailtext in bytes No

Filename STRING filename oft he mailattachment Yes

Only one attachment can be specified

User STRING Username for log in on a SMTP-Server Yes

Password STRING Password for log in on a SMTP-Server Yes

Output Datatype description Optional

State INT State of the functionblock No

0 = finished without errors

-1 = busy
>0 = finished with errors
Error STRING In case of an error this output contains No
the error message oft he SMTP-Servers
respectively of the function block
Usage of the function block SMTP_sendMail

Initialize

An instance of the SMTP_sendMail function block must be created. A buffer for the content of the
mail has to create also. If you want to attach a file to the mail, the file must exist on the controller or
have to be created.

Example:
9 Festo_SMTP.lib

Function block call

Festo AG & Co.KG