WagoLibMail_02.lib. Contents

Transcription

1 WagoLibMail_02.lib WagoLibMail_02.lib The library WagoLibMail_02.lib provide with MAIL_ESMTP_Client a one for all function block for sending mails by an Ethernet-Controller. The library is applicable for the as well as for the The function block MAIL_ESMTP_Client could work as a simple SMTP- Client as well as the function block supports the authentication methods Pop3BeforeSmtp and SMTP-Authentication who described in RFC2554. Supported authentication types are CRAM-MD5, LOGIN and PLAIN. The function blocks MAIL_SMTP_Client and MAIL_POP3_Client could be helpful by devoloping applications with small footprints. Contents WagoLibMail_02.lib 3 MAIL_ESMTP_Client... 3 MAIL_Error (ENUM)... 6 MAIL_OperationMode (ENUM)... 7 MAIL_SMTP_Client... 8 MAIL_POP3_Client MAIL_Base64Code WAGO-I/O-PRO CAA Version WagoLibMail_02.lib - 1

2 MAIL_ESMTP_Client 2 WagoLibMail_02.lib ml00902e WAGO-I/O-PRO CAA

3 WagoLibMail_02.lib WagoLibMail_02.lib MAIL_ESMTP_Client Category: Communication Name: MAIL_ESMTP_Client Type: Function Function block X Program Library name: WagoLibMail_02.lib Used Libraries SysLibSockets.lib; WagoLibEthernet_01.lib; Applicable to: (Release >= 09) and Input parameter: Data type: Comments: ssmtpserver STRING(255) Address or hostname of the computer on which the SMTP server is running. wsmtpport WORD Portnumber of SMTP-Server (default 25) ttimeout TIME Watchdog time for the different steps of the data exchange(default t#5s) eoperationmode MAIL_Operation Mode MAIL_SMTP (default), MAIL_POP3_BEFORE_SMTP, MAIL_SMTP_AUTH spop3server STRING(255) Address or hostname of the computer on which the POP3 server is running. wpop3port WORD Portnumber of POP3-Server (default 110) susername STRING(80) Username of your SMTP- or POP3- account spassword STRING(80) Password of your SMTP- or POP3- account sfrom STRING(255) Forwader mail address sto STRING(255) Recipient s mail address ssubject STRING(255) The subject text smessage STRING(255) The message text sattachmentfilename STRING(80) File name and file extension of the attachment like test.txt or data.bin ptattachment Pointer to Array [1.. MAX_SEND_ TCP_CLIENT] of Byte This pointer shows to the data source for the attachment, The maximum size is limited to aprox 10kB but can exceed by hiding the constant with a local constant of the same name MAX_SEND_TCP_CLIENT := 65000; iattachmentlength INT Attachments bytecount In/Output parameter: Data type: Comments: xsend BOOL The mail will be transfered on a rising edge. This signal will be automatically reset after execution. WAGO-I/O-PRO CAA Version WagoLibMail_02.lib - 3

4 MAIL_ESMTP_Client Output parameter: Data type: Comments: ierror MAIL_Error For details see enumeration sstatus STRING Textual description of current state or unexpected server response. Graphic display: Function description: The function block MAIL_ESMTP_Client could work as a simple SMTP-Client as well as the function block supports the authentication methods Pop3BeforeSmtp and SMTP-Authentication who described in RFC2554. Supported authentication types are CRAM-MD5, LOGIN and PLAIN This function block uses SMTP protocol for transmitting. The mail may include an attachment. The attachment will be build wihtout involving the filesystem. Attachment data is base_64 coded. Therefore it is possible to mail binary data, when the mail server are able to handle Mime V1.0 format. By default the maximum attachment size is limited to 10kByte, but can be increased when hiding the global constant MAX_SEND_TCP_CLIENT from the library WagoLib Ethernet_01.lib. Going this way the is able to send attachments up to 700 kbytes. On the the absolut maximum attachment size is aprox 40kByte because the internal send buffer has a fix size of bytes. By using on a the functionblock may block if the mail server is not aviable. It is therefore recommended to use the functionblock only in a seperate background task. For the it is not necessary to use a background task. The IPC use a different implementation who would not block if the mailö server not aviable. In case of sending a simple mail without attachment or authentication ignore obsulet inputs like sattachmentfilename, ptattachment and iattachmentlength. 4 WagoLibMail_02.lib ml00902e WAGO-I/O-PRO CAA

5 WagoLibMail_02.lib The input xsend is declared as VAR_IN_OUT, it allows the function block to change the value by them selve. A rising edge of input xsend will start the mail transfer. At the end of transfer the function block reset xsend. A successful transfer is indicated by ierror=0 otherwise ierror give a hind for the occurted problem. If the user reset xsend while a transfer is active, then the current transfer will aborted. The output parameter sstatus point out the server response or a textual description of the current operation. WAGO-I/O-PRO CAA Version WagoLibMail_02.lib - 5

6 MAIL_Error (ENUM) MAIL_Error (ENUM) Category: Name: MAIL_Error Type: Data type Enumeration X Library name: WagoLibMail_02.lib Declaration: TYPE MAIL_Error : ( MAIL_NO_ERROR := 0, MAIL_ABORT := 16#8E00, (* A falling edge on input "xsend" will abort a running mail transfer *) MAIL_TIMEOUT_ERROR := 16#8E01, (* Watchdog time elapsed, see sstatus for additional information *) MAIL_INVALID_MODE := 16#8E02, (* Invalid operation mode, supported: NONE, Pop3BeforeSmtp or SMTP-Auth*) MAIL_DNS_REQ_FAILED := 16#8E03, (* DNS-Request failed, could not retrieve IP for the given hostname *) MAIL_IP_CONVERT_FAILED := 16#8E04, (* Could not convert IP address into dottet format *) MAIL_POP_OK_EXPECTED := 16#8A01, (* Do not receive POP3 servers "+OK" telegram *) MAIL_POP_UNKNOWN_USER := 16#8A02, (* Do not receive POP3 servers "+OK" telegram for "USER" *) MAIL_POP_WRONG_PASSWORD := 16#8A03, (* Do not receive POP3 servers "+OK" telegram for "PASS" *) MAIL_SMTP_WRONG_RESPONSE := 16#8B01, (* Do not receive the expected reponse, see sstatus for additional info *) MAIL_SMTP_UNKNOWN_USER := 16#8B02, (* Do not receive SMTP servers "334" telegram for "user" *) MAIL_SMTP_INVALID_PASSWORD := 16#8B03, (* Do not receive SMTP servers "334" telegram for "password" *) MAIL_UNSUPPORTED_AUTH_TYPE := 16#8B04, (* No supported authentication type found (CRAM-MD5, LOGIN or PLAIN) *) MAIL_SMTP_ATTACHMENT_LENGTH := 16#8B05 (* Attachment length exceed maximum, shorten attachment *) ); END_TYPE 6 WagoLibMail_02.lib ml00902e WAGO-I/O-PRO CAA

7 WagoLibMail_02.lib MAIL_OperationMode (ENUM) Category: Name: MAIL_OperationMode Type: Data type Enumeration X Library name: WagoLibMail_02.lib Declaration: TYPE MAIL_OperationMode :( MAIL_SMTP :=0, (* Use Simple Mail Transfer Protocol(SMTP) *) MAIL_POP3_BEFORE_SMTP :=1, (* use Pop3BeforeSmtp *) MAIL_SMTP_AUTH :=2); (* use SMTP-Authentication RFC2554: CRAM-MD5, LOGIN, PLAIN *) END_TYPE WAGO-I/O-PRO CAA Version WagoLibMail_02.lib - 7

8 MAIL_SMTP_Client MAIL_SMTP_Client Category: Communication Name: MAIL_SMTP_Client Type: Function Function block X Program Library name: WagoLibMail_02.lib Used Libraries SysLibSocket.lib,WagoLibEthernet_01.lib Applicable to: (Release07), (Release01) Input parameter: Data type: Comments: ssmtpserver STRING Address of the computer on which the mail server is running. wport WORD Port ttimeout TIME Watchdog time for the different steps of the data exchange. sfrom STRING Address from the users Mail provider sto STRING address of the person who should receive the message ssubject STRING This text will be placed in the head of the mail form smessage STRING(255) Message text sattachmentfilename STRING(255) File name of the attachment ptattachment Pointer to Array[1..] of Byte This pointer shows to the data source for the attachment iattachmentlength INT Number of Bytes in the attachment (max approximately 10k) In/Output parameter: Data type: Comments: xsend BOOL The message will be send with the rising edge of the start input. This signal will be automatically reset after execution of the function block. Output parameter: Data type: Comments: xconnected BOOL Connection established with mail server distatus DINT Status of data transfer according to SMTP protocol in numerical values. sstatus STRING Data send by the mail server according to SMTP protocol 8 WagoLibMail_02.lib ml00902e WAGO-I/O-PRO CAA

9 WagoLibMail_02.lib Graphic display: Function description: This function block uses SMTP protocol. The mail may include an attachment. Attachment data is base_64 coded. Therefore it is possible to mail binary data. The mail server must be able to handle Mime V1.0 format. This function block may block. It is therefore recommended to use the function block only in a seperate background task. Since the operating system on the IPC does not block by executing the connect command it is not necessary to use a background task. In case of sending a simple mail without attachment, do not use the inputs sattachmentfilename, ptattachment and iattachmentlength. The mail function will be started with the rising edge of the input xsend. The output parameters will indicate the result of the function. The variable xsend will be reset by the function block. WAGO-I/O-PRO CAA Version WagoLibMail_02.lib - 9

10 MAIL_POP3_Client MAIL_POP3_Client Category: Communication Name: MAIL_POP3_Client Type: Function Function block X Program Library name: WagoLibMail_02.lib Used Libraries SysLibSocket.lib,WagoLibEthernet_01.lib Applicable to: (Release07), (Release01) Input parameter: Data type: Comments: spop3server STRING Address of the computer on which the Pop3 server is running wport WORD Port ttimeout TIME Watchdog time. suser STRING User name for your mail box spass STRING Password for your mail box In/Output parameter: Data type: Comments: xexecute BOOL With the rising edge of xexecute the connection to the Pop3 server will be established Output parameter: Data type: Comments: xconnected BOOL Connection with pop3 server established xauthorization_ok BOOL User authorized distatus DINT Status send by the pop3 server according to pop3 protocol in numerical values sstatus STRING Data send by the pop3 server according to pop3 protocol 10 WagoLibMail_02.lib ml00902e WAGO-I/O-PRO CAA

11 WagoLibMail_02.lib Graphic display: Function description: This function block uses POP3 protocol. It will establish a connection to the Pop3 server. After this connection is set up successfully, the user may send s using the MAIL_SMTP_Client function block. The function will be started with the rising edge of the input xexecute. The output parameters will indicate the result of the function. This function block may block. It is therefore recommended to use the function block only in a seperate background task. Since the operating system on the IPC does not block by executing the connect command it is not necessary to use a background task. WAGO-I/O-PRO CAA Version WagoLibMail_02.lib - 11

12 MAIL_Base64Code MAIL_Base64Code Category: Communication Name: MAIL_Base64Code Type: Function X Function block Program Library name: WagoLibMail_02.lib Used Libraries Applicable to: Input parameter: Data type: Comments: psourceaddress POINTER TO Address of source data ARRAY[1..] OF BYTE pdestinationaddress POINTER TO Address of coded data ARRAY[1..] OF BYTE BytesToCode INT Quantity of bytes to code In/Output parameter: Data type: Comments: Output parameter: Data type: Comments: MAIL_Base64Code INT Graphic display: Function description: This function block is used by SMTP-Client function block. Function:This function codes data according to base64 rules. Description:The function will return the number of byte in the destination array. This function codes BytesToCode Bytes from the source array of Byte and stores the coded data in the destination array of Bytes. Base64 will calculate for 4 Bytes in the destination array for each 3 Bytes in the source array. 12 WagoLibMail_02.lib ml00902e WAGO-I/O-PRO CAA