This chapter contains a description of various issues related to installation, setup, and usage of the NetX Duo SMTP Client component.
The NetX Duo SMTP Client is available at https://github.com/eclipse-threadx/netxduo. The package includes the following files:
To use the NetX Duo SMTP Client API, the entire distribution mentioned previously may be copied to the same directory where NetX Duo is installed. For example, if NetX Duo is installed in the directory “c:\myproject” then the nxd_smtp_client.h, and nxd_smtp_client.c files should be copied into this directory.
To create the NetX Duo SMTP Client application, it must first build the ThreadX and NetX Duo libraries and include them in the build project. The application must then include tx_api.h and nx_api.h in its application source code. This will enable ThreadX and NetX Duo services. It must also include nxd_smtp_client.c and nxd_smtp_client.h after tx_api.h and nx_api.h to use SMTP Client services.
These files must be compiled in the same manner as other application files and the object code must be linked along with the files of the application. This is all that is required to create a NetX Duo SMTP Client application.
An example of using the NetX Duo SMTP Client is described in Figure 1 that appears below. The packet pool for the IP instance is created using the nx_packet_pool_create service, on line 68 and has a very small packet payload. This is because the IP instance only sends control packets which don’t require much payload. The SMTP Client packet pool created on line 84 and is used for transmitting SMTP Client messages to the server and message data. Its packet payload is much larger. The IP instance is created in line 118 using the same packet pool. TCP, required for the SMTP protocol, is enabled on the IP instance in line 130.
In the application thread, the SMTP Client is created using the nxd_smtp_client_create service, in line 170. The nxd_smtp_client_create service supports both IPv4 and IPv6 SMTP server connections although this example is limited to IPv4. Then the mail message is submitted to the SMTP Client for transmission on line 184 using the nx_smtp_mail_send service. Note that the subject line with the mail content header is created separately from the message body. Also note that the send mail request accepts only one recipient mail address which is assumed to be syntactically correct.
Then the application terminates the SMTP Client on line 200. The nx_smtp_client_delete service checks that the socket connection is closed and the port is unbound. Note that it is up to the SMTP Client application to delete the packet pool if it no longer has use for it.
/*
demo_netxduo_smtp_client.c
This is a small demo of the NetX Duo SMTP Client on the high-performance NetX
Duo TCP/IP stack. This demo relies on Thread, NetX Duo and SMTP Client API to
perform simple SMTP mail transfers in an SMTP client application to an SMTP mail
server. */
#include "nx_api.h"
#include "nx_ip.h"
#include "nxd_smtp_client.h"
/* Define the host user name and mail box parameters */
#define USERNAME "myusername"
#define PASSWORD "mypassword"
#define FROM_ADDRESS "my@mycompany.com"
#define RECIPIENT_ADDRESS "your@yourcompany.com"
#define LOCAL_DOMAIN "mycompany.com"
#define SUBJECT_LINE "NetX Duo SMTP Client Demo"
#define MAIL_BODY "NetX Duo SMTP client is an SMTP client \r\n" \
"implementation for embedded devices to send \r\n" \
"email to SMTP servers. This feature is \r\n" \
"intended to allow a device to send simple \r\n " \
"status reports using the most universal \r\n " \
"Internet application, email.\r\n"
/* See the NetX Duo SMTP Client User Guide for how to set the authentication type.
The most common authentication type is PLAIN. */
#define CLIENT_AUTHENTICATION_TYPE 3
#define CLIENT_IP_ADDRESS IP_ADDRESS(1,2,3,5)
#define SERVER_IP_ADDRESS IP_ADDRESS(1,2,3,4)
#define SERVER_PORT 25
/* Define the NetX Duo and ThreadX structures for the SMTP client application. */
NX_PACKET_POOL ip_packet_pool;
NX_PACKET_POOL client_packet_pool;
NX_IP client_ip;
TX_THREAD demo_client_thread;
static NX_SMTP_CLIENT demo_client;
void _nx_ram_network_driver(struct NX_IP_DRIVER_STRUCT *driver_req);
void demo_client_thread_entry(ULONG info);
/* Define main entry point. */
int main()
{
/* Enter the ThreadX kernel. */
tx_kernel_enter();
}
/* Define what the initial system looks like. */
void tx_application_define(void *first_unused_memory)
{
UINT status;
CHAR *free_memory_pointer;
/* Setup the pointer to unallocated memory. */
free_memory_pointer = (CHAR *) first_unused_memory;
/* Create IP default packet pool. */
status = nx_packet_pool_create(&ip_packet_pool, "Default IP Packet Pool",
128, free_memory_pointer, 2048);
/* Update pointer to unallocated (free) memory. */
free_memory_pointer = free_memory_pointer + 2048;
/* Create SMTP Client packet pool. This is only for transmitting packets to the
server. It need not be a separate packet pool than the IP default packet pool
but for more efficient resource use, we use two different packet pools
because the CLient SMTP messages generally require more payload than IP
control packets.
Packet payload depends on the SMTP Client application requirements. Size of
packet payload must include IP and TCP headers. For IPv6 connections, IP and
TCP header data is 60 bytes. For IPv4 IP and TCP header data is 40 bytes (not
including TCP options). */
status |= nx_packet_pool_create(&client_packet_pool, "SMTP Client Packet Pool",
800, free_memory_pointer, (10*800));
if (status != NX_SUCCESS)
{
return;
}
/* Update pointer to unallocated (free) memory. */
free_memory_pointer = free_memory_pointer + (10*800);
/* Initialize the NetX system. */
nx_system_initialize();
/* Create the client thread */
status = tx_thread_create(&demo_client_thread, "client_thread",
demo_client_thread_entry, 0, free_memory_pointer,
2048, 16, 16,
TX_NO_TIME_SLICE, TX_DONT_START);
if (status != NX_SUCCESS)
{
printf("Error creating Client thread. Status 0x%x\r\n", status);
return;
}
/* Update pointer to unallocated (free) memory. */
free_memory_pointer = free_memory_pointer + 4096;
/* Create Client IP instance. Remember to replace the generic driver
with a real ethernet driver to actually run this demo! */
status = nx_ip_create(&client_ip, "SMTP Client IP Instance", CLIENT_IP_ADDRESS,
0xFFFFFF00UL, &ip_packet_pool, _nx_ram_network_driver,
free_memory_pointer, 2048, 1);
free_memory_pointer = free_memory_pointer + 2048;
/* Enable ARP and supply ARP cache memory. */
status = nx_arp_enable(&client_ip, (void **) free_memory_pointer, 1040);
/* Update pointer to unallocated (free) memory. */
free_memory_pointer = free_memory_pointer + 1040;
/* Enable TCP for client. */
status = nx_tcp_enable(&client_ip);
if (status != NX_SUCCESS)
{
return;
}
/* Enable ICMP for client. */
status = nx_icmp_enable(&client_ip);
if (status != NX_SUCCESS)
{
return;
}
/* Start the client thread. */
tx_thread_resume(&demo_client_thread);
return;
}
/* Define the smtp application thread task. */
void demo_client_thread_entry(ULONG info)
{
UINT status;
UINT error_counter = 0;
NXD_ADDRESS server_ip_address;
tx_thread_sleep(100);
/* Set up the server IP address. */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V4;
server_ip_address.nxd_ip_address.v4 = SERVER_IP_ADDRESS;
/* The demo client username and password is the authentication
data used when the server attempts to authentication the client. */
status = nxd_smtp_client_create(&demo_client, &client_ip, &client_packet_pool,
USERNAME,
PASSWORD,
FROM_ADDRESS,
LOCAL_DOMAIN, CLIENT_AUTHENTICATION_TYPE,
&server_ip_address, SERVER_PORT);
if (status != NX_SUCCESS)
{
printf("Error creating the client. Status: 0x%x.\n\r", status);
return;
}
/* Create a mail instance with the above text message and recipient info. */
status = nx_smtp_mail_send(&demo_client, RECIPIENT_ADDRESS,
TP_MAIL_PRIORITY_NORMAL,
SUBJECT_LINE, MAIL_BODY, sizeof(MAIL_BODY) - 1);
/* Check for errors. */
if (status != NX_SUCCESS)
{
/* Mail item was not sent. Note that we need not delete the client. The
error status may be a failed authentication check or a broken connection.
We can simply call nx_smtp_mail_send again. */
error_counter++;
}
/* Release resources used by client. Note that the transmit packet
pool must be deleted by the application if it no longer has use for it.*/
status = nx_smtp_client_delete(&demo_client);
/* Check for errors. */
if (status != NX_SUCCESS)
{
error_counter++;
}
return;
}
There are several configuration options with the NetX Duo SMTP Client API. Following is a list of all options described in detail: