 |
Synergy Software Package User's Manual
|
|
Synergy Software Package User's Manual
|
The Post Office Protocol Version 3 (POP3) is a protocol designed to provide a mail transport system for small workstations to access Client maildrops on POP3 Servers. The POP3 utilizes Transmission Control Protocol (TCP) services to perform mail transfers.
Client mail is stored on a POP3 Server in a mailbox or "maildrop." A maildrop is represented as a 1-based array of mail items where each mail is retrieved and deleted using its index in the maildrop. Once a mail message is downloaded, the Client typically marks the mail item for deletion in the Server's maildrop (the Server will probably do this automatically anyway). When finished retrieving mail items, the application should delete the POP3 Client instance and close the TCP connection. To retrieve the mail again, another POP3 Client must be created.
The NetX POP3 Client defines APIs for creating and deleting the POP3 instance and getting its messages. A complete list of the available APIs, an example API call and a short description of each can be found in the following table.
NetX/NetX Duo POP3 Client Module API Summary
| Function Name | Example API Call and Description |
|---|---|
| nx_pop3_client_create | nx_pop3_client_create(&demo_client,NX_FALSE ⁄* disable APOP authentication *⁄,&client_ip, &client_packet_pool,POP3_SERVER_ADDRESS, POP3_SERVER_PORT,LOCALHOST, LOCALHOST_PASSWORD);Create a POP3 Client Instance for IPv4 only. |
| **nxd_pop3_client_create | nxd_pop3_client_create(&demo_client, NX_FALSE ⁄* disable APOP authentication *⁄,&client_ip, &client_packet_pool,*server_ip_address,ULONG server_port,CHAR *client_name, CHAR *client_password);Create a POP3 Client Instance for either IPv4 or IPv6 |
| nx_pop3_client_delete | nx_pop3_client_delete (&demo_client);Delete a POP3 Client Instance |
| nx_pop3_client_mail_item_delete | nx_pop3_client_mail_item_delete(&demo_client, item_index);Delete a Client mail item for a Server maildrop. |
| nx_pop3_client_mail_item_get | nx_pop3_client_mail_item_get (&demo_client, 1, &item_size);Retrieve a specific mail message size. |
| nx_pop3_client_mail_items_get | nx_pop3_client_mail_item_get (&demo_client, 1, &number_mail_items,&maildrop_total_size);Obtain the number of mail items in a maildrop. |
| nx_pop3_client_mail_item_message_get | nx_pop3_client_mail_item_message_get (&demo_client, &recv_packet_ptr,&bytes_retrieved, &final_packet);Download a specific mail message. |
| nx_pop3_client_mail_item_size_get | nx_pop3_client_mail_item_size_get (&demo_client, mail_item, &size);Obtain the size of a specific mail item. |
| nx_pop3_client_quit | nx_pop3_client_quit(&demo_client);Sends a QUIT command to the POP3 server. |
**This API is only available in NetX Duo POP3 Client. For definitions of of NetX Duo specific data types, see the NetX Duo User Guide for the Renesas Synergy™ Platform.
Status Return Values
| Name | Description |
|---|---|
| NX_SUCCESS | API Call Successful |
| NX_PTR_ERROR* | Invalid input pointer parameter |
| NX_POP3_CLIENT_INVALID_INDEX* | Null mail index input |
| NX_POP3_PARAM_ERROR | Invalid non-pointer input |
| NX_POP3_APOP_FAILED_MD5_DIGEST | POP3 Client failed APOP authentication |
| NX_POP3_INVALID_MAIL_ITEM | Invalid mail item index (exceeds number of items in the maildrop box) |
| NX_POP3_INSUFFICIENT_PACKET_PAYLOAD | Client packet payload too small for POP3 request |
| NX_POP3_SERVER_ERROR_STATUS | Server replies with error status |
| NX_POP3_CLIENT_INVALID_STATE | Client not initialized to receive mail messages |
*These are error codes which are only returned if error checking is enabled. Please refer to the NetX User Guide for the Renesas Synergy™ Platform for more details on error checking services in NetX.
The POP3 protocol requires that Clients maintain the state of the POP3 session. The POP3 Client has three distinct states defined by RFC 1939. The initial state is the authorization state in which it must identify itself to the Server. Then the Client enters the Transaction state where the Client downloads mail. When the POP3 Client chooses to end the session, it enters the Update state to disconnect from the Server.
The NetX POP3 Client requires a previously created NetX IP instance and a packet pool to send POP3 messages to the Server. The NetX POP3 Client needs the packet pool for sending out POP3 messages. It can use the same packet pool used by the IP instance or NetX can create a separate packet pool. POP3 Client messages to the Server are limited to simple POP3 commands and login authentication data. This means that if the NetX POP3 Client is using its own packet pool, it need not set the payload size much greater than 150-200 bytes, depending on the length of POP3 Client username and password. Note that the packet pool used by the IP instance, however, must have a payload large enough for receiving POP3 mail data up to the device MTU (typically 1518 bytes).
Because the NetX POP3 Client utilizes TCP services, the TCP must be enabled on the IP instance.
The NetX Client POP3 is compliant with RFC 1939.
The auto generated Synergy code takes care of these tasks at startup/initialization. IP instance and packet pool creation, as well as enabling TCP services, is done automatically.
The POP3 Client property Auto initialization defaults to Disable. You must not enable this property, because the auto generated code will try to connect to the server during initialization before the network link is enabled, and fail. This in turn will abort the application initialization.
So with Auto initialization disabled, the application handles connecting to the Server and retrieving its mail.
The following properties are necessary for connecting to the Server:
However, because of the structure of the POP3 Client, setting these properties are not accessible to the application. Your application must connect to the server using the nx_pop3_client_create API and input these properties directly.
For most applications a typical call might look like:
For NetX Duo, the ULONG server_ip_address is replaced by a pointer to an NXD_ADDRESS type:
This function creates the POP3 Client instance, creates a TCP socket and binds to a local TCP port. Then it attempts to connect to the POP3 Server TCP socket. If this is successful, then it authenticates itself with the user password to the server. More details on POP3 authentication are described later in this section. If all goes well, the POP3 Client is now ready to get its mail.
The application can query the server for how many mail items are in its inbox with the nx_pop3_client*_*mail_items_get API. This will also return the total number of bytes of mail messages, although this should be taken as an estimate. The application can further query the size of each mail item, using the nx_pop3_client_mail_item_size_get API, and again this should be taken as an estimate as the actual size might vary somewhat. Note that the first mail item in the maildrop is at index 1, not zero.
To actually download the mail item, the application indicates to the server which mail item it wants to receive using the nx_pop3_client_get_mail_item service, specifying the index of the mail item. This will also return the mail item size but now the POP3 client can get the message text by calling nx_pop3_client_mail_item_get_message_data. This API will receive one packet at a time. So the application must call it one or more times until the last packet containing the message is received. The Server will indicate the last packet to the Client in the final_packet pointer as shown below:
After receiving each packet, the application should copy the packet data to a buffer and release the packet back to the packet pool (not shown above). This prevents depleting the packet pool used to receive packets. After downloading a message, it is common practice to mark the mail item for deletion. To do so, the application calls nx_pop3_client_mail_item_delete with the index of the mail item to delete.
When done downloading mail items, the Client quits the session by calling nx_pop3_client_quit. This terminates the TCP session. If no longer using POP3, the application can delete the TCP socket by calling nx_pop3_client_delete. If no other tasks are using the POP3 Client packet pool, the application can delete the packet pool using the nx_packet_pool_delete service.
POP3 Authentication
After the TCP connection is established, a POP3 client needs to identify itself to the POP3 server through authentication to access its mailbox. Authentication is accomplished by sending the server a username and password. The username is typically a fully qualified domain name (contains a local part and a domain name, separated by an '@' character.
To enable APOP Authentication, set the APOP Authentication input in the nx_pop3_client_create/nxd_pop3_client_create API to NX_TRUE (or nxd_pop3_client_create API in NetX Duo). APOP Authentication creates an MD5 digest of user name/password supplied to the nx_pop3_client_create/nxd_pop3_client_create call and avoids the security risk of transmitting username and password in clear text. If APOP authentication fails, the NetX POP3 Client will attempt to login using the username and password without encryption.
This section describes how to include either or both the NetX and NetX Duo POP3 Client module in an application using the SSP configurator.
To add the NetX/NetX Duo POP3 Client module to an application, simply add it to a thread using the stacks selection sequence given in the following table.
NetX/NetX Duo POP3 Client Module Selection Sequence
| Resource | ISDE Tab | Stacks Selection Sequence |
|---|---|---|
| g_pop3_client0 NetX POP3 Client | Threads | New Stack> X-Ware> NetX> Protocols> NetX POP3 Client |
| g_pop3_client0 NetX POP3 Client | Threads | New Stack> X-Ware> NetX Duo> Protocols> NetX Duo POP3 Client |
When the NetX and/or NetX Duo POP3 Client module is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.
In the stack above, the NetX Network Driver (or NetX Duo Network Driver in a NetX Duo stack) has not been populated yet. There are multiple possible selections for the Network Driver; they are not all provided so as not to needlessly complicate the figure and the following configuration tables. The available options depend on the MCU target, but some typical options include:
The NetX/NetX Duo POP3 Client module must be configured by the user for the desired operation. The SSP configuration window automatically identifies (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules for successful operation. Only properties that can be changed without causing conflicts are available for modification. Other properties are locked and not available for changes and are identified with a lock icon for the locked property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous manual approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP Configurator and are shown in the following tables for easy reference.
Configuration Settings for the NetX/NetX Duo POP3 Client Module
| ISDE Property | Value | Description |
|---|---|---|
| Maximum buffer size to store messages (bytes) | 2000 | Maximum buffer size to store messages selection |
| Packet time out (seconds) | 1 | Packet time out selection |
| Connection time out (seconds) | 30 | Connection time out selection |
| Disconnect time out (seconds) | 2 | Disconnect time out selection |
| TCP socket send wait (seconds) | 2 | TCP socket send wait selection |
| Server reply timeout (seconds) | 10 | Server reply timeout selection |
| TCP window size (bytes) | 1460 | TCP window size selection |
| Maximum user name length (bytes) | 40 | Maximum user name length selection |
| Maximum password length (bytes) | 20 | Maximum password length selection |
| Name | g_pop3_client0 | Module name |
| APOP Authentication | Enable, Disable Default: Disable | Apop authentication selection |
| **Use server address type | IPv4, IPv6 Default: IPv6 | Use server address type selection |
| Server IPv4 Address (use commas for separation) | 192, 168, 0, 2 | Server IPv4 Address selection |
| **Server IPv6 Address (use commas for separation) | 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 | Server IPv6 Address selection |
| Server Port number | 110 | Server Port number selection |
| Client Name | username@domain.com | Client name selection |
| Client Password | password | Client password selection |
| Auto initialization | Enable, Disable Default: Disable | Auto initialization selection |
| Name of generalized initialization function | pop3_client_init0 | Name of generalized initialization function selection |
** Indicates properties that are only available in NetX Duo.
In some cases, settings other than the defaults for lower-level modules can be desirable. For example, it might be useful to select different MAC or IP Addresses. The configurable properties for the lower-level stack modules are provided in the following sections for completeness and as a reference.
Note: Most of the property settings for lower-level modules are intuitive and usually can be determined by inspection of the associated properties window from the SSP configurator.
Only a small number of settings must be modified from the default for the IP layer and lower-level drivers as indicated via the red text in the thread stack block. Notice that some of the configuration properties must be set to a certain value for proper framework operation and are locked to prevent user modification. The following table identifies all the settings within the properties section for the module:
Configuration Settings for the NetX/NetX Duo IP Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_ip0 | Module name |
| IPv4 Address (use commas for separation) | 192,168,0,2 | IPv4 Address selection |
| Subnet Mask (use commas for separation) | 255,255,255,0 | Subnet Mask selection |
| Default Gateway Address (use commas for separation) | 0,0,0,0 | Default gateway address selection |
| **IPv6 Global Address (use commas for separation) | 0x2001, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x1 | IPv6 global address selection |
| **IPv6 Link Local Address (use commas for separation, All zeros means use MAC address) | 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0, 0x0 | IPv6 link local address selection |
| IP Helper Thread Stack Size (bytes) | 2048 | IP Helper Thread Stack Size (bytes) selection |
| IP Helper Thread Priority | 3 | IP Helper Thread Priority selection |
| ARP | Enable | ARP selection |
| ARP Cache Size in Bytes | 512 | ARP Cache Size in Bytes selection |
| Reverse ARP | Enable, Disable Default: Disable | Reverse ARP selection |
| TCP | Enable, Disable Default: Enable | TCP selection |
| UDP | Enable, Disable Default: Enable | UDP selection |
| ICMP | Enable, Disable Default: Enable | ICMP selection |
| IGMP | Enable, Disable Default: Enable | IGMP selection |
| IP fragmentation | Enable, Disable Default: Disable | IP fragmentation selection |
| Name of generated initialization function | ip_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization function |
| Link status change callback | NULL | Link status change callback selection |
** Indicates properties that are only available in NetX Duo.
Configuration Settings for the NetX/NetX Duo Common Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name of generated initialization function | nx_common_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
Configuration Settings for the NetX/NetX Duo Packet Pool Instance
| ISDE Property | Value | Description |
|---|---|---|
| Name | g_packet_pool0 | Module name |
| Packet Size in Bytes | 640 | Packet size selection |
| Number of Packets in Pool | 16 | Number of packets in pool selection |
| Name of generated initialization function | packet_pool_init0 | Name of generated initialization function selection |
| Auto Initialization | Enable, Disable Default: Enable | Auto initialization selection |
Configuration Settings for the NetX MD5 Instance
| ISDE Property | Value | Description |
|---|---|---|
| No configurable properties |
The ETHERC peripheral module uses the PCLKA as its clock source. The PCLKA frequency is set using the SSP configurator Clock tab prior to a build or by using the CGC interface at run-time.
The ETHERC peripheral module uses pins on the MCU device to communicate to external devices. I/O pins must be selected and configured by the external device as required. The following table illustrates the method for selecting the pins within the SSP configuration window and the subsequent table illustrates an example selection for the I2C pins.
Pin Selection for the ETHERC Module
| Resource | ISDE Tab | Pin selection Sequence |
|---|---|---|
| ETHERC | Pins | Select Peripherals > Connectivity:ETHERC > ETHERC1.RMII |
Pin Configuration Settings for the ETHERC1
| Property | Value | Description |
|---|---|---|
| Operation Mode | Disabled, Custom, RMII Default: Disabled | Select RMII as the Operation Mode for ETHERC1 |
| Pin Group Selection | Mixed, _A only Default: _A only | Pin group selection |
| REF50CK | P701 | REF50CK Pin |
| TXD0 | P700 | TXD0 Pin |
| TXD1 | P406 | TXD1 Pin |
| TXD_EN | P405 | TXD_EN Pin |
| RXD0 | P702 | RXD0 Pin |
| RXD1 | P703 | RXD1 Pin |
| RX_ER | P704 | RX_ER Pin |
| CRS_DV | P705 | CRS_DV Pin |
| MDC | P403 | MDC Pin |
| MDIO | P404 | MDIO Pin |
The steps in using the NetX and NetX Duo BSD Support module in a typical application are:
Step 1. Wait for the network link to be enabled with the nx_ip_status_check API.
Step 2. Create the POP3 Client using nx_pop3_client_create API (nxd_pop3_client_create in NetX Duo POP3 Client).
Step 3. Send a request to the POP3 Server for the number of mail items in mailbox with the nx_pop3_client_mail_items_get API.
Step 4. Assuming there are one or more items in the POP3 Client maildrop, send a request to the POP3 Server one or all of them by calling the nx_pop3_client_mail_item_get API.
Step 5. After each call to nx_pop3_client_mail_item_get, download the actual mail message data using the nx_pop3_client_mail_message_get API.
Step 6. Copy the packet data into a separate buffer and release the receive packet(s) using the nx_packet_release API [Strongly recommended to avoid packet pool depletion]
Step 7. Check if this is the last packet of the message: the final_packet pointer input of nx_pop3_client_mail_message_get will be TRUE if it is the last packet.
If FALSE, call nx_pop3_client_mail_message_get again. If TRUE, go on to step 8.
Step 8. Mark the current mail item for deletion using the nx_pop3_client_mail_item_delete API. This will send a DELE message to the server for it to delete the mail item at some later time.
Step 9. Check if there are more mail items to download. If yes, get the next mail item by calling nx_pop3_client_mail_item_get. If no, go on to step 10.
Step 10. Send a QUIT message to the Server with the nx_pop3_client_delete API
Step 11. Delete the POP3 instance by calling nx_pop3_client_delete API.
The following figure illustrates common steps in a typical operational flow diagram:
