第 3 章 - POP3 客户端服务说明

本章将按字母顺序介绍下列所有 NetX Duo POP3 客户端服务。

注意

在以下 API 说明的“返回值”部分中,以粗体显示的值不受定义用于禁用 API 错误检查的 NX_DISABLE_ERROR_CHECKING 影响,而不以粗体显示的值会被完全禁用。

nx_pop3_client_create

创建用于 IPv4 的 POP3 客户端实例

原型

UINT nx_pop3_client_create(
    NX_POP3_CLIENT *client_ptr,
    UINT APOP_authentication,
    NX_IP *ip_ptr,
    NX_PACKET_POOL *packet_pool_ptr,
    ULONG server_ip_address,
    ULONG server_port,
    CHAR *client_name,
    CHAR *client_password);

说明

此服务用于创建 POP3 客户端实例, 仅支持 IPv4 POP3 服务器地址。

请注意,设备应用程序必须先创建一个 IP 实例和一个数据包池,然后 POP3 客户端才能传输数据包。 创建的此数据包池由 POP3 客户端任务独占使用,或者也可以在创建 IP 实例时使用同一数据包池。 数据包池也可以与以太网驱动程序数据包池共享,但这样具有以下缺点:POP3 客户端使用较大的数据包池只能向服务器发送相对较小的 POP3 消息数据包,因为这些数据包池的有效负载用于接收可能较大的数据包有效负载。

输入参数

  • client_ptr:指向要创建的客户端的指针
  • APOP_authentication:启用 APOP 身份验证
  • ip_ptr:指向 IP 实例的指针
  • packet_pool_ptr:指向客户端数据包池的指针
  • server_ip_address:POP3 服务器 IPv4 地址
  • server_port:POP3 服务器端口
  • client_name:指向客户端名称的指针
  • client_password:指向客户端密码的指针

返回值

  • NX_SUCCESS (0x00):已成功创建客户端
  • status:NetX Duo 服务调用和 ThreadX 服务调用的完成状态
  • NX_PTR_ERROR (0x07):输入指针参数无效
  • NX_POP3_PARAM_ERROR (0xB1):非指针输入无效

获准方式

应用程序代码

示例

/* Create the POP3 Client. Note that the Client uses its password for its APOP shared
    secret. */

/* Set up user defined callback services. */
/* Create username and password for our POP3 Client mail drop. */
#define LOCALHOST "recipient@expresslogic.com"
#define LOCALHOST_PASSWORD "pass"
#define POP3_SERVER_ADDRESS IP_ADDRESS(192,2,2,92)
#define POP3_SERVER_PORT 110

/* Create a NetX POP3 Client instance. */
status = 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);

/* If the Client was successfully created, status = NX_SUCCESS. */

nxd_pop3_client_create

创建用于 IPv4 或 IPv6 的 POP3 客户端实例

原型

UINT nxd_pop3_client_create(
    NX_POP3_CLIENT *client_ptr,
    UINT APOP_authentication,
    NX_IP *ip_ptr,
    NX_PACKET_POOL *packet_pool_ptr,
    NXD_ADDRESS *server_ip_address,
    ULONG server_port,
    CHAR *client_name,
    CHAR *client_password);

说明

此服务用于创建 POP3 客户端实例, 此服务同时支持 IPv4 和 IPv6 POP3 服务器地址。 有关 POP3 客户端创建过程的更多详细信息,请参阅前面介绍的 nx_pop3_client_create 服务。

输入参数

  • client_ptr:指向要创建的客户端的指针
  • APOP_authentication:启用 APOP 身份验证
  • ip_ptr:指向 IP 实例的指针
  • packet_pool_ptr:指向客户端数据包池的指针
  • server_ip_address:POP3 服务器 IPv6 或 IPv4 地址
  • server_port:POP3 服务器端口
  • client_name:指向客户端名称的指针
  • client_password:指向客户端密码的指针

返回值

  • NX_SUCCESS (0x00):已成功创建客户端
  • status:NetX Duo 服务调用和 ThreadX 服务调用的完成状态
  • NX_PTR_ERROR (0x07):输入指针参数无效
  • NX_POP3_PARAM_ERROR (0xB1):非指针输入无效

获准方式

应用程序代码

示例

/* Create the POP3 Client. */

/* Create username and password for our POP3 Client mail drop. */
#define LOCALHOST "recipient@expresslogic.com"
#define LOCALHOST_PASSWORD "pass"
#define POP3_SERVER_PORT 110

/* Create a NetX POP3 Client instance. Also note the details of IPv6 address validation
    and enabling IPv6 and ICMPv6 services on the IP task are not shown here. See the
    NetX Duo User Guide for more details on this process.
*/
NXD_ADDRESS server_ip_address;

/* Set client IP interface address. */
server_ip_address.nxd_ip_version = NX_IP_VERSION_V6;
server_ip_address.nxd_ip_address.v6[0] = 0x20010db8;
server_ip_address.nxd_ip_address.v6[1] = 0xf101;
server_ip_address.nxd_ip_address.v6[2] = 0;
server_ip_address.nxd_ip_address.v6[3] = 0x101;
status = nxd_pop3_client_create(&demo_client,
    NX_FALSE /* disable APOP authentication */,
    &client_ip, &client_packet_pool,
    &server_ip_address, POP3_SERVER_PORT,
    LOCALHOST, LOCALHOST_PASSWORD);

/* If the Client was successfully created, status = NX_SUCCESS. */

nx_pop3_client_delete

删除 POP3 客户端实例

原型

UINT nx_pop3_client_delete(NX_POP3_CLIENT *client_ptr);

说明

此服务用于删除以前创建的 POP3 客户端。 请注意,此服务不会删除 POP3 客户端数据包池。 如果不再使用数据包池,则设备应用程序必须单独删除此资源。

输入参数

  • client_ptr:指向要删除的客户端的指针

返回值

  • NX_SUCCESS (0x00):已成功删除客户端
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

应用程序代码

示例

/* Delete the POP3 Client. */
status = nx_pop3_client_delete (&demo_client);

/* If the Client was successfully deleted, status = NX_SUCCESS. */

nx_pop3_client_mail_item_delete

从客户端 maildrop 中删除指定的邮件项

原型

UINT nx_pop3_client_mail_items_delete(
    NX_POP3_CLIENT *client_ptr,
    UINT mail_index);

说明

此服务用于从客户端 maildrop 中删除指定的邮件项。 可以在下载邮件项后使用此服务,但有些 POP3 服务器可能会在客户端请求后自动删除邮件项。

输入参数

  • client_ptr:指向客户端实例的指针
  • mail_index:客户端 maildrop 的索引

返回值

  • NX_SUCCESS (0x00):删除请求已成功完成
  • NX_POP3_INVALID_MAIL_ITEM(0xB2):邮件项索引无效
  • NX_POP3_INSUFFICIENT_PACKET_PAYLOAD(0xB6):客户端数据包有效负载对于 POP3 请求来说太小。
  • NX_POP3_SERVER_ERROR_STATUS(0xB4):服务器回复了错误状态
  • NX_POP3_CLIENT_INVALID_INDEX(0xB8):邮件索引输入无效
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

应用程序代码

示例

ULONG item_index;

/* Delete the POP3 Client mail item. */
status = nx_pop3_client_mail_item_delete(&demo_client, item_index);

/* If the server accepts the DELE request (and deletes the mail item), status =
    NX_SUCCESS. */

nx_pop3_client_mail_item_get

检索指定的邮件项

原型

UINT nx_pop3_client_mail_item_get(
    NX_POP3_CLIENT *client_ptr,
    UINT mail_item,
    ULONG *item_size);

说明

此服务用于发出 RETR 请求,以从客户端 maildrop 中检索索引 mail_item 指定的邮件项。 发出 RETR 请求并从服务器收到正响应后,客户端可以使用 nx_pop3_client_mail_item_message_get 服务开始下载邮件。 请注意,此服务还提供从服务器回复中提取的所请求邮件项目的大小。

输入参数

  • client_ptr:指向客户端实例的指针
  • mail_item:客户端 maildrop 的索引
  • item_size:指向邮件大小的指针

返回值

  • NX_SUCCESS (0x00):已成功检索邮件项
  • NX_POP3_INVALID_MAIL_ITEM (0xB2):邮件项索引无效
  • NX_POP3_INSUFFICIENT_PACKET_PAYLOAD (0xB6):客户端数据包有效负载对于 POP3 请求来说太小。
  • NX_POP3_SERVER_ERROR_STATUS (0xB4):服务器回复了错误状态
  • NX_POP3_CLIENT_INVALID_INDEX (0xB8):邮件索引输入无效
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

应用程序代码

示例

ULONG item_size;

/* Retrieve the POP3 Client mail item. */
status = nx_pop3_client_mail_item_get (&demo_client, 1, &item_size);

/* If the mail item was successfully obtained, status = NX_SUCCESS. */

nx_pop3_client_mail_items_get

检索 maildrop 中的邮件项数

原型

UINT nx_pop3_client_mail_items_get(
    NX_POP3_CLIENT *client_ptr,
    UINT *number_mail_items,
    ULONG *maildrop_total_size);

说明

此服务用于发出 STAT 请求,以检索客户端 maildrop 中的邮件项数和邮件数据总大小。

输入参数

  • client_ptr:指向客户端实例的指针
  • number_mail_item:客户端 maildrop 中的邮件数
  • maildrop_total_size:指向邮件总大小的指针

返回值

  • NX_SUCCESS (0x00):已成功检索邮件项
  • NX_POP3_INVALID_MAIL_ITEM (0xB2):邮件项索引无效
  • NX_POP3_INSUFFICIENT_PACKET_PAYLOAD (0xB6):客户端数据包有效负载对于 POP3 请求来说太小。
  • NX_POP3_SERVER_ERROR_STATUS (0xB4):服务器回复了错误状态
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

应用程序代码

示例

UINT number_mail_items;

ULONG maildrop_total_size;

/* Retrieve the size and number of items in POP3 Client maildrop. */

status = nx_pop3_client_mail_item_get (&demo_client, 1, &number_mail_items,
    &maildrop_total_size);

/* If the maildrop data was successfully obtained, status = NX_SUCCESS. */

nx_pop3_client_mail_item_message_get

检索指定的邮件项消息

原型

UINT nx_pop3_client_mail_item_message_get(
    NX_POP3_CLIENT *client_ptr,
    NX_PACKET **recv_packet_ptr,
    ULONG *bytes_retrieved,
    UINT *final_packet);

说明

此服务用于检索邮件项目消息和邮件大小,以及确定是否为邮件中的最后一个数据包。 如果 final_packet 为 NX_TRUE,则 recv_packet_ptr 指向的数据包为邮件项消息中的最后一个数据包。

输入参数

  • client_ptr:指向客户端实例的指针
  • recv_packet_ptr:接收到的邮件数据包
  • number_mail_item:客户端 maildrop 中的邮件数
  • maildrop_total_size:指向邮件总大小的指针

返回值

  • NX_SUCCESS (0x00):已成功检索邮件项
  • NX_POP3_CLIENT_INVALID_STATE (0xB7):客户端数据包有效负载对于 POP3 请求来说太小。
  • NX_PTR_ERROR (0x07):输入指针参数无效

获准方式

应用程序代码

示例

NX_PACKET *recv_packet_ptr;

ULONG bytes_retrieved;

UINT final_packet;

/* Retrieve the size and number of items in POP3 Client maildrop. */

status = nx_pop3_client_mail_item_message_get (&demo_client, &recv_packet_ptr,
    bytes_retrieved, final_packet);

/* If the maildrop message packet was successfully obtained, status = NX_SUCCESS. */

nx_pop3_client_mail_item_size_get

检索指定邮件项的大小

原型

UINT nx_pop3_client_mail_item_size_get(
    NX_POP3_CLIENT *client_ptr,
    UINT mail_item, ULONG *size);

说明

此服务用于发出 LIST 请求,以获取指定邮件项的大小。

输入参数

  • client_ptr:指向客户端实例的指针
  • mail_item:客户端 maildrop 的索引
  • size:指向邮件大小的指针

返回值

  • NX_SUCCESS (0x00):已成功检索邮件项
  • NX_POP3_INVALID_MAIL_ITEM (0xB2):邮件项索引无效
  • NX_POP3_INSUFFICIENT_PACKET_PAYLOAD (0xB6):客户端数据包有效负载对于 POP3 请求来说太小。
  • NX_POP3_SERVER_ERROR_STATUS (0xB4):服务器回复了错误状态
  • NX_POP3_CLIENT_INVALID_INDEX (0xB8):邮件索引输入无效
  • NX_PTR_ERROR (0x07):输入指针参数无效

获准方式

应用程序代码

示例

ULONG size;

UINT mail_item;

/* Retrieve the size of the specified mail item in POP3 Client maildrop. */

status = nx_pop3_client_mail_item_size_get (&demo_client, mail_item, &size);

/* If the maildrop message packet was successfully obtained, status = NX_SUCCESS. */