第 3 章 - SMTP 客户端服务的客户端说明

本章按典型 SMTP 客户端应用程序中的使用顺序,介绍如下所列的所有 NetX Duo SMTP 客户端服务。

注意

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

nxd_smtp_client_create

创建 SMTP 客户端实例

原型

UINT nxd_smtp_client_create(NX_SMTP_CLIENT *client_ptr,
    NX_IP *ip_ptr, NX_PACKET_POOL
    *client_packet_pool_ptr,
    CHAR *username, CHAR *password,
    CHAR *from_address,
    CHAR *client_domain,
    UINT authentication_type, NXD_ADDRESS *server_address,
    UINT port);

说明

此服务在指定的 IP 实例上创建 SMTP 客户端实例。

输入参数

  • client_ptr:指向 SMTP 客户端控制块的指针;
  • ip_ptr:指向 IP 实例的指针;
  • packet_pool_ptr:指向客户端数据包池的指针;
  • username:用于身份验证的用户名,以 NULL 结尾
  • password:用于身份验证的密码,以 NULL 结尾
  • from_address:以 NULL 结尾的发件人地址
  • client_domain:以 NULL 结尾的域名
  • authentication_type:客户端身份验证类型。 支持的类型包括:
    • NX_SMTP_CLIENT_AUTH_LOGIN
    • NX_SMTP_CLIENT_AUTH_PLAIN
    • NX_SMTP_CLIENT_AUTH_NONE
  • server_address:指向 SMTP 服务器 IP 地址的指针
  • server_port:SMTP 服务器 TCP 端口

返回值

  • NX_SUCCESS (0x00):已成功创建 SMTP 客户端。 TCP 套接字创建状态
  • NX_SMTP_INVALID_PARAM (0xA5):非指针输入无效
  • NX_IP_ADDRESS_ERROR (0x21):IP 地址类型无效
  • NX_PTR_ERROR (0x07):输入指针参数无效

允许来自

应用程序代码

示例

/* Create the SMTP Client instance. */
NX_PACKET_POOL client_packet_pool;
NX_IP client_ip;
NX_SMTP_CLIENT demo_client;

#define USERNAME “myusername”
#define PASSWORD “mypassword”
#define FROM_ADDRESS “<myname@mycompany.com>”
#define LOCAL_DOMAIN “mycompany.com”
#define SERVER_PORT 25

/* Define client authentication type as LOGIN. 
    If not specified or unknown the SMTP Client will set it to PLAIN. */
#define CLIENT_AUTHENTICATION_TYPE NX_SMTP_CLIENT_AUTH_LOGIN

NXD_ADDRESS server_ip_address;

#ifdef USE_IPV6
    /* Set up the Server IPv6 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] = 0x106;
#else
    server_ip_address.nxd_ip_version = NX_IP_VERSION_V4;
    server_ip_address.nxd_ip_address.v4 = SERVER_IP_ADDRESS;
#endif

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 an SMTP Client instance was successfully created, status = NX_SUCCESS. */

nx_smtp_client_delete

删除 SMTP 客户端实例

原型

UINT nx_smtp_client_delete(NX_SMTP_CLIENT *client_ptr);

说明

此服务用于删除以前创建的 SMTP 客户端实例。

输入参数

  • client_ptr:指向 SMTP 客户端实例的指针。

返回值

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

允许来自

线程数

示例

/* Delete the SMTP Client instance “my_client.” */

NX_SMTP_CLIENT demo_client;

status = nx_smtp_client_delete(&demo_client);

/* If an SMTP Client instance was successfully deleted, status = NX_SUCCESS. */

nx_smtp_mail_send

创建和发送 SMTP 邮件项

原型

UINT nx_smtp_mail_send(NX_SMTP_CLIENT *client_ptr,
    CHAR *recipient_address,
    UINT priority, CHAR *subject,
    CHAR *mail_body,
    UINT mail_body_length);

说明

此服务用于创建和发送 SMTP 邮件项。 SMTP 客户端会与 SMTP 服务器建立 TCP 连接,并发送一系列 SMTP 命令。 如果未遇到任何错误,则会将邮件传输至服务器。 不论是否成功发送该邮件,都会终止该 TCP 连接,并返回状态以指出传输邮件的结果。 应用程序可以针对任意数量的待发送邮件调用此服务,没有任何限制。

输入参数

  • client_ptr:指向 SMTP 客户端的指针
  • recipient_address:以 NULL 结尾的收件人地址。
  • subject:以 NULL 结尾的主题行文本。
  • priority:传递邮件的优先级
  • mail_body:指向邮件的指针
  • mail_body_length:邮件大小

返回值

  • NX_SUCCESS (0x00):已成功发送邮件
  • NX_SMTP_CLIENT_NOT_INITIALIZED (0xB2):SMTP 客户端实例未初始化
  • NX_PTR_ERROR (0x07):指针参数无效
  • NX_SMTP_INVALID_PARAM (0xA5):非指针输入无效
  • NX_CALLER_ERROR (0x11):此服务的调用方无效

获准方式

线程数

示例

/* Create and send a Client mail item. */

#define RECIPIENT_ADDRESS “<your@yourcompany.com>”
#define SUBJECT “NetX Duo SMTP Client Demo”
#define MAIL_BODY "NetX Duo SMTP client is an SMTP client ” \
    “implementation for embedded devices \r\n” \
    "to send email to SMTP servers.\r\n"

status = nx_smtp_mail_send(&demo_client, RECIPIENT_ADDRESS,
    NX_SMTP_MAIL_PRIORITY_NORMAL,
    SUBJECT_LINE, MAIL_BODY,
    sizeof(MAIL_BODY) - 1);

/* Return status being NX_SUCCESS indicates the mail has been
    successfully sent. */