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

本章按字母顺序介绍了所有 Azure RTOS NetX POP3 客户端服务(如下所列)。

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

nx_pop3_client_create

创建 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 客户端实例,并使用输入参数来设置其配置。

输入参数

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

返回值

  • * NX_SUCCESS:(0x00) 已成功创建客户端
  • * status:NetX 和 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_ADDRESS         IP_ADDRESS(192,2,2,92
#define POP3_SERVER_PORT            110

/* Create a NetX POP3 Client instance. */
ULONG server_ip_address = IP_ADDRESS(1,2,3,4);
status = nx_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

从客户端邮箱下拉中删除指定的邮件项

原型

UINT nx_pop3_client_mail_items_delete(
    NX_POP3_CLIENT *client_ptr,
    UINT mail_index)

说明

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

输入参数

  • client_ptr:指向客户端实例的指针
  • mail_index:客户端邮箱下拉的索引

返回值

  • 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 请求,以从客户端邮箱下拉中检索由索引 mail_item 指定的邮件项。 发出 RETR 请求并从服务器收到正响应后,客户端可以使用 nx_pop3_client_mail_item_message_get 服务开始下载邮件。 请注意,此服务还提供从服务器回复中提取的所请求邮件项目的大小。

输入参数

  • client_ptr:指向客户端实例的指针
  • mail_item:客户端邮箱下拉的索引
  • 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

检索邮箱下拉中的邮件项数

原型

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

说明

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

输入参数

  • client_ptr:指向客户端实例的指针
  • number_mail_item:客户端邮箱下拉中的邮件数
  • 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_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:客户端邮箱下拉的索引
  • 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. */