# Object - Pop3 邮件接收

## `Pop3`

声明：class

用于连接 POP3 服务器并读取或删除邮件的内置对象

<!-- tags: Object Pop3 邮件接收 读取 获取 对象 实例 邮件 SMTP IMAP 创建 生成 构造函数 实例化 new -->

下列范例使用本机 `127.0.0.1:42110` 的临时 POP3 测试服务

测试账号为 `tsl_user` 和 `tsl_pass`，服务器需支持 APOP 认证

### `create()`

声明：function

无参数构造函数。创建 Pop3 实例，连接和认证参数由实例属性设置

<!-- tags: Object Pop3 邮件接收 创建 生成 对象 实例 邮件 SMTP IMAP -->

可见性：public

### `create(host, user_name, password)`

声明：function

构造函数。按 host、user_name 和 password 初始化 Pop3 实例

<!-- tags: Object Pop3 邮件接收 创建 生成 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数        | 类型   | 说明                                                    |
| ----------- | ------ | ------------------------------------------------------- |
| `host`      | string | Pop3 配置名称。指定后从配置文件读取服务器参数并自动连接 |
| `user_name` | string | 登录用户名                                              |
| `password`  | string | 登录密码                                                |

### `capa()`

声明：function

取服务器的支持命令列表

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：string

#### 示例

```tsl
obj := new Pop3();
obj.host := "127.0.0.1";
obj.port := 42110;
obj.username := "tsl_user";
obj.password := "tsl_pass";
obj.useTLS := false;
obj.authType := 1;
obj.connect();
echo obj.capa();
obj.disconnect();
// 输出：
// USER
// TOP
// UIDL
// IMPLEMENTATION TSL test
```

### `checkMessages()`

声明：function

返回邮件的个数

<!-- tags: Object Pop3 邮件接收 返回 获取 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：integer

#### 示例

```tsl
obj := new Pop3();
obj.host := "127.0.0.1";
obj.port := 42110;
obj.username := "tsl_user";
obj.password := "tsl_pass";
obj.useTLS := false;
obj.authType := 1;
obj.connect();
echo obj.checkMessages();
obj.disconnect();
// 输出：1
```

### `connect()`

声明：function

连接服务器

<!-- tags: Object Pop3 邮件接收 连接 登录 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：any

#### 示例

```tsl
obj := new Pop3();
obj.host := "127.0.0.1";
obj.port := 42110;
obj.username := "tsl_user";
obj.password := "tsl_pass";
obj.useTLS := false;
obj.authType := 1;
echo obj.connect(), "\n";
echo obj.checkMessages(), "\n";
obj.disconnect();
// 输出：
// 0
// 1
```

### `delete(msg_id)`

声明：function

删除指定的邮件，返回删除是否正确

<!-- tags: Object Pop3 邮件接收 删除 移除 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数     | 类型 | 说明   |
| -------- | ---- | ------ |
| `msg_id` | any  | msg_id |

返回：boolean

### `disconnect()`

声明：function

断开连接

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：any

### `disconnectNotifyPeer()`

声明：function

断开并且通知服务器

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：any

### `keepAlive()`

声明：function

发送空指令保持服务的连接

<!-- tags: Object Pop3 邮件接收 发送 提交 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：any

### `login()`

声明：function

连接登录，此前必须制定Username和Password属性

<!-- tags: Object Pop3 邮件接收 连接 登录 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：any

### `reset()`

声明：function

复位，撤销所有本次会话中的删除操作

<!-- tags: Object Pop3 邮件接收 清除 重置 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：boolean

### `retrieve(msg_id, msg)`

声明：function

取邮件的内容

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数     | 类型    | 说明                                                      |
| -------- | ------- | --------------------------------------------------------- |
| `msg_id` | integer | 邮件ID                                                    |
| `msg`    | TSLObj  | 获取成功时返回的邮件内容，具体类型可参考FAQ： MailMsg对象 |

返回：boolean

### `retrieveHeader(msg_id, msg)`

声明：function

取邮件的内容，仅仅取邮件的头部信息，不取附件等内容

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数     | 类型    | 说明                                                          |
| -------- | ------- | ------------------------------------------------------------- |
| `msg_id` | integer | 邮件ID                                                        |
| `msg`    | TSLObj  | 获取成功时返回的邮件头部信息，具体类型可参考FAQ： MailMsg对象 |

返回：boolean

### `retrieveMailBoxSize()`

声明：function

获取邮箱的大小

<!-- tags: Object Pop3 邮件接收 获取 查询 对象 实例 邮件 SMTP IMAP -->

可见性：public

返回：integer

#### 示例

```tsl
obj := new Pop3();
obj.host := "127.0.0.1";
obj.port := 42110;
obj.username := "tsl_user";
obj.password := "tsl_pass";
obj.useTLS := false;
obj.authType := 1;
obj.connect();
echo obj.retrieveMailBoxSize();
obj.disconnect();
// 输出：138
```

### `retrieveMsgSize(msg_id)`

声明：function

取指定邮件的大小

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数     | 类型    | 说明         |
| -------- | ------- | ------------ |
| `msg_id` | integer | 指定邮件序号 |

返回：integer

#### 示例

```tsl
obj := new Pop3();
obj.host := "127.0.0.1";
obj.port := 42110;
obj.username := "tsl_user";
obj.password := "tsl_pass";
obj.useTLS := false;
obj.authType := 1;
obj.connect();
echo obj.retrieveMsgSize(1);
obj.disconnect();
// 输出：138
```

### `retrieveRaw(msg_id, msg_content)`

声明：function

取邮件的原始内容

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数          | 类型    | 说明                         |
| ------------- | ------- | ---------------------------- |
| `msg_id`      | integer | 邮件ID                       |
| `msg_content` | string  | 获取成功时返回的原始邮件内容 |

返回：boolean

### `sendCmd(cmd, cmd_result, ret_code)`

声明：function

发送命令

<!-- tags: Object Pop3 邮件接收 发送 提交 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数         | 类型   | 说明                   |
| ------------ | ------ | ---------------------- |
| `cmd`        | string | 字符串类型，发送的命令 |
| `cmd_result` | string | 可选。返回的结果串     |
| `ret_code`   | string | 可选。返回的代码串     |

返回：integer

#### 示例

```tsl
obj := new Pop3();
obj.host := "127.0.0.1";
obj.port := 42110;
obj.username := "tsl_user";
obj.password := "tsl_pass";
obj.useTLS := false;
obj.authType := 1;
obj.connect();
echo obj.sendCmd("UIDL 1", cmd_result, ret_code);
obj.disconnect();
// 输出：0
```

### `top(msg_id, result, max_lines)`

声明：function

转换取邮件的前N行内容

<!-- tags: Object Pop3 邮件接收 转换 编码 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数        | 类型    | 说明                           |
| ----------- | ------- | ------------------------------ |
| `msg_id`    | integer | 指定邮件序号                   |
| `result`    | string  | 指定邮件内容返回值             |
| `max_lines` | integer | 获取指定邮件前MaxLines行的内容 |

返回：boolean

#### 示例

```tsl
obj := new Pop3();
obj.host := "127.0.0.1";
obj.port := 42110;
obj.username := "tsl_user";
obj.password := "tsl_pass";
obj.useTLS := false;
obj.authType := 1;
obj.connect();
obj.top(1, msg, 3);
echo msg;
obj.disconnect();
// 输出：
// From: sender@example.test
// To: recipient@example.test
// Subject: TSL POP3 test
// Message-ID: <tsl-pop3@example.test>
//
// line one
// line two
```

### `uidl(ids)`

声明：function

取服务器的邮件唯一标示列表

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

| 参数  | 类型   | 说明                         |
| ----- | ------ | ---------------------------- |
| `ids` | string | 字符串，存放获取到的标示列表 |

返回：boolean

#### 示例

```tsl
obj := new Pop3();
obj.host := "127.0.0.1";
obj.port := 42110;
obj.username := "tsl_user";
obj.password := "tsl_pass";
obj.useTLS := false;
obj.authType := 1;
obj.connect();
obj.uidl(ids);
echo ids;
obj.disconnect();
// 输出：1 tsl-message-1
```

### `AuthType`

声明：property

认证类型，0：明文用户密码，1：MD5，2：SASL认证，-1：自定义认证

<!-- tags: Object Pop3 邮件接收 摘要 哈希 散列 digest hash 对象 实例 邮件 SMTP -->

可见性：public

类型：integer

访问：read/write

### `AuthTypeString`

声明：property

自定义认证类型，仅当 AuthType 设置为-1时有效；设置为"AUTH=*"：自动选择服务器支持的认证类型；多个用分号连接

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP AUTH -->

可见性：public

类型：string

访问：read/write

### `AutoLogin`

声明：property

控制是否在连接的时候自动登录

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP -->

可见性：public

类型：boolean

访问：read/write

### `Capabilities`

声明：property

获取取服务器的支持命令列表(不重新发送命令)

<!-- tags: Object Pop3 邮件接收 获取 查询 对象 实例 邮件 SMTP IMAP -->

可见性：public

类型：string

访问：read

### `HasAPOP`

声明：property

指示是否是MD5认证

<!-- tags: Object Pop3 邮件接收 摘要 哈希 散列 digest hash 判断 检查 对象 实例 -->

可见性：public

类型：boolean

访问：read

### `HasCAPA`

声明：property

指示是否执行过CAPA命令

<!-- tags: Object Pop3 邮件接收 判断 检查 对象 实例 邮件 SMTP IMAP CAPA -->

可见性：public

类型：boolean

访问：read

### `Host`

声明：property

获取或设置主机名称或地址

<!-- tags: Object Pop3 邮件接收 获取 查询 对象 实例 邮件 SMTP IMAP -->

可见性：public

类型：string

访问：read/write

### `LastCmdResult`

声明：property

获取最后的命令执行结果

<!-- tags: Object Pop3 邮件接收 获取 查询 对象 实例 邮件 SMTP IMAP -->

可见性：public

类型：string

访问：read

### `LastCmdResultCode`

声明：property

获取最后的命令执行的返回码

<!-- tags: Object Pop3 邮件接收 获取 查询 对象 实例 邮件 SMTP IMAP -->

可见性：public

类型：string

访问：read

### `Password`

声明：property

获取或设置密码

<!-- tags: Object Pop3 邮件接收 获取 查询 对象 实例 邮件 SMTP IMAP -->

可见性：public

类型：string

访问：read/write

### `Port`

声明：property

获取或设置主机端口

<!-- tags: Object Pop3 邮件接收 获取 查询 对象 实例 邮件 SMTP IMAP -->

可见性：public

类型：integer

访问：read/write

### `Username`

声明：property

获取或设置用户名

<!-- tags: Object Pop3 邮件接收 获取 查询 对象 实例 邮件 SMTP IMAP -->

可见性：public

类型：string

访问：read/write

### `UseSTARTTLS`

声明：property

控制是否使用显式 TLS（即 STARTTLS 加密协议）

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP TLS STARTTLS -->

可见性：public

类型：boolean

访问：read/write

### `UseTLS`

声明：property

控制是否采用SSL连接

<!-- tags: Object Pop3 邮件接收 对象 实例 邮件 SMTP IMAP SSL -->

可见性：public

类型：boolean

访问：read/write