# Builtin - 网络

## `appendHttpHeader(session, header)`

声明：function

向指定 HTTP 会话添加请求头

<!-- tags: 网络 添加 追加 HTTP 请求 network -->

| 参数      | 类型    | 说明           |
| --------- | ------- | -------------- |
| `session` | integer | HTTP 会话 ID。 |
| `header`  | string  | HTTP 请求头。  |

返回：void

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
appendHttpHeader(session, "Accept: text/html");
ok := getHttp(session, "https://example.com/", 10000, body, code);
echo ok and code = 200, "\n";
// 输出：1
destroyHttpSession(session);
```

## `clearHttpHeader([session])`

声明：function

清除指定 HTTP 会话中已添加的请求头；session 可省略

<!-- tags: 网络 清除 重置 HTTP 请求 network -->

| 参数      | 类型    | 说明           |
| --------- | ------- | -------------- |
| `session` | integer | HTTP 会话 ID。 |

返回：void

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
appendHttpHeader(session, "Accept: text/html");
clearHttpHeader(session);
echo destroyHttpSession(session), "\n";
// 输出：1
```

## `createHttpSession()`

声明：function

创建一个http Session对象，并返回会话ID，即Session id。仅新一代TSL语言支持该函数

<!-- tags: 网络 创建 生成 HTTP 请求 network ID -->

返回：integer

### 示例

范例01：创建 HTTP 会话

```tsl
echo createHttpSession(), "\n";
```

## `destroyHttpSession([session])`

声明：function

销毁 HTTP 会话；session 可省略

<!-- tags: 网络 HTTP 请求 network -->

| 参数      | 类型    | 说明           |
| --------- | ------- | -------------- |
| `session` | integer | HTTP 会话 ID。 |

返回：boolean

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
echo destroyHttpSession(session), "\n";
// 输出：1
```

## `getHttp([session,] url, time_out, var value, var code)`

声明：function

以 GET 方式访问 URL，并写回响应内容和 HTTP 状态码；session 可省略

<!-- tags: 网络 获取 查询 HTTP 请求 network GET URL -->

| 参数       | 类型    | 说明                   |
| ---------- | ------- | ---------------------- |
| `session`  | integer | HTTP 会话 ID。         |
| `url`      | string  | 请求 URL。             |
| `time_out` | integer | 超时时间，单位为毫秒。 |
| `value`    | string  | 写回响应内容。         |
| `code`     | integer | 写回 HTTP 状态码。     |

返回：boolean

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
ok := getHttp(session, "https://example.com/", 10000, body, code);
echo ok and code = 200 and length(body) > 0, "\n";
// 输出：1
destroyHttpSession(session);
```

## `getHttpContent(session[, from_pos])`

声明：function

获取 HTTP 会话已经接收的响应内容；from_pos 可指定从第几个字符开始读取，缺省时读取全部

<!-- tags: 网络 获取 查询 HTTP 请求 network -->

| 参数       | 类型    | 说明                                      |
| ---------- | ------- | ----------------------------------------- |
| `session`  | integer | HTTP 会话 ID。                            |
| `from_pos` | integer | 可选起始位置，从 1 开始；省略时读取全部。 |

返回：string

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
ok := getHttp(session, "https://example.com/", 10000, body, code);
content := getHttpContent(session);
echo ok and length(content) > 0, "\n";
// 输出：1
destroyHttpSession(session);
```

## `getHttpCookies(session)`

声明：function

获取指定 HTTP 会话保存的服务器 Cookie

<!-- tags: 网络 获取 查询 HTTP 请求 network -->

| 参数      | 类型    | 说明           |
| --------- | ------- | -------------- |
| `session` | integer | HTTP 会话 ID。 |

返回：string

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
getHttp(session, "https://www.baidu.com/", 10000, body, code);
cookies := getHttpCookies(session);
echo length(cookies) > 0, "\n";
// 输出：1
destroyHttpSession(session);
```

## `getHttpResponseHeader([session])`

声明：function

获取 HTTP 响应头；session 可省略

<!-- tags: 网络 获取 查询 HTTP 请求 network -->

| 参数      | 类型    | 说明           |
| --------- | ------- | -------------- |
| `session` | integer | HTTP 会话 ID。 |

返回：string

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
getHttp(session, "https://example.com/", 10000, body, code);
header := getHttpResponseHeader(session);
echo length(header) > 0, "\n";
// 输出：1
destroyHttpSession(session);
```

## `getUrl(src_url, parse_url)`

声明：function

解析在HTML中出现的URL，返回全路径URL串

<!-- tags: 网络 解析 parse HTTP 请求 network HTML URL -->

| 参数        | 类型   | 说明                                       |
| ----------- | ------ | ------------------------------------------ |
| `src_url`   | string | 字符串类型，所需解析的URL所在HTML的源URL。 |
| `parse_url` | string | 字符串类型，所需要解析的URL。              |

返回：string

### 示例

范例01：解析相对 URL

```tsl
echo getUrl("https://example.com/docs/", "index.html"), "\n";
```

## `internetRequest([session,] url, refer, header, post_data, user_name, password, result_type, var result, var response_code, time_out)`

声明：function

发送 HTTP 请求，并写回响应内容和状态码；result_type 为 0 时返回字符串，非 0 时返回二进制。session 可省略

<!-- tags: 网络 发送 提交 HTTP 请求 network -->

| 参数            | 类型           | 说明                            |
| --------------- | -------------- | ------------------------------- |
| `session`       | integer        | HTTP 会话 ID。                  |
| `url`           | string         | 请求 URL。                      |
| `refer`         | string         | Referer 内容。                  |
| `header`        | string         | HTTP 请求头。                   |
| `post_data`     | string         | 请求正文。                      |
| `user_name`     | string         | 用户名。                        |
| `password`      | string         | 密码。                          |
| `result_type`   | integer        | 0 返回字符串，非 0 返回二进制。 |
| `result`        | string\|binary | 写回响应内容。                  |
| `response_code` | integer        | 写回 HTTP 状态码。              |
| `time_out`      | integer        | 超时时间，单位为毫秒。          |

返回：boolean

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
ok := internetRequest(
    session,
    "https://example.com/",
    "",
    "",
    "",
    "",
    "",
    0,
    body,
    code,
    10000
);
echo ok and code = 200 and length(body) > 0, "\n";
// 输出：1
destroyHttpSession(session);
```

## `parseHtml(html, parsed, attr_name_is_index)`

声明：function

将指定的Html字符串解析成为类似于DOM格式的结构

<!-- tags: 网络 解析 parse HTTP 请求 network DOM -->

| 参数                 | 类型       | 说明                                                                                                                  |
| -------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------- |
| `html`               | string     | 字符串类型，所需解析的HTML串。                                                                                        |
| `parsed`             | array      | 存放返回的类DOM结构。                                                                                                 |
| `attr_name_is_index` | bool=false | 节点的属性是否以属性名作为下标。缺省值为假，属性以0,1,2自然下标序列的数字下标排列，为真则属性值以属性名为字符串下标。 |

返回：bool

### 示例

范例01：解析静态 HTML 字符串

```tsl
html := '<a href="/docs">Docs</a>';
ok := parseHtml(html, parsed, true);
echo ok, ":", parsed["c"][0]["n"], "\n";
// 输出：1:a
```

## `postHttp([session,] url, content, time_out, var value, var code)`

声明：function

以 POST 方式访问 URL，并写回响应内容和 HTTP 状态码；session 可省略

<!-- tags: 网络 发送 提交 HTTP 请求 network POST URL -->

| 参数       | 类型           | 说明                   |
| ---------- | -------------- | ---------------------- |
| `session`  | integer        | HTTP 会话 ID。         |
| `url`      | string         | 请求 URL。             |
| `content`  | string\|binary | 请求或管道内容。       |
| `time_out` | integer        | 超时时间，单位为毫秒。 |
| `value`    | string         | 写回响应内容。         |
| `code`     | integer        | 写回 HTTP 状态码。     |

返回：boolean

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
ok := postHttp(session, "https://example.com/", "hello", 10000, body, code);
echo ok and code > 0, "\n";
// 输出：1
destroyHttpSession(session);
```

## `setHttpAuth(session, user_name, password[, auth_type])`

声明：function

设置 HTTP 会话的认证信息。auth_type 可省略：0 为 HTTP，1 为代理，2 为 TLS，3 为代理 TLS

<!-- tags: 网络 设置 修改 HTTP 请求 network TLS -->

| 参数        | 类型    | 说明                     |
| ----------- | ------- | ------------------------ |
| `session`   | integer | HTTP 会话 ID。           |
| `user_name` | string  | 用户名。                 |
| `password`  | string  | 密码。                   |
| `auth_type` | integer | 可选认证类型，缺省为 0。 |

返回：void

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
setHttpAuth(session, "demo", "secret", 0);
echo destroyHttpSession(session), "\n";
// 输出：1
```

## `setHttpCallBack(session, callback[, callback_type])`

声明：function

设置 HTTP 会话回调。callback_type 可省略；缺省为 progress，也可指定 header。回调返回 0 表示继续请求，非 0 表示终止

<!-- tags: 网络 设置 修改 HTTP 请求 network -->

| 参数            | 类型     | 说明                               |
| --------------- | -------- | ---------------------------------- |
| `session`       | integer  | HTTP 会话 ID。                     |
| `callback`      | function | 回调函数对象。                     |
| `callback_type` | string   | 可选回调类型：progress 或 header。 |

返回：void

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
setHttpCallBack(session, findFunction("httpProgress"));
ok := getHttp(session, "https://example.com/", 10000, body, code);
echo ok and code = 200, "\n";
// 输出：1
destroyHttpSession(session);

function httpProgress(session, all_down, downloaded, all_up, uploaded);
begin
    return 0;
end;
```

## `setHttpCookies(session, cookies)`

声明：function

设置 HTTP 会话发送的 Cookie；多个 Cookie 使用分号分隔

<!-- tags: 网络 设置 修改 HTTP 请求 network -->

| 参数      | 类型    | 说明                              |
| --------- | ------- | --------------------------------- |
| `session` | integer | HTTP 会话 ID。                    |
| `cookies` | string  | Cookie 字符串，多个值以分号分隔。 |

返回：void

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
setHttpCookies(session, "client=tsl");
ok := getHttp(session, "https://postman-echo.com/cookies", 10000, body, code);
echo ok and code = 200 and pos("client", body) > 0, "\n";
// 输出：1
destroyHttpSession(session);
```

## `setHttpMode(session, mode)`

声明：function

设置 HTTP 响应模式。0 表示完整接收后返回，1 表示分段返回

<!-- tags: 网络 设置 修改 HTTP 请求 network -->

| 参数      | 类型    | 说明           |
| --------- | ------- | -------------- |
| `session` | integer | HTTP 会话 ID。 |
| `mode`    | integer | 模式数值。     |

返回：void

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
setHttpMode(session, 0);
echo destroyHttpSession(session), "\n";
// 输出：1
```

## `setHttpProxy(session, proxy_addr[, proxy_type])`

声明：function

设置 HTTP 会话的代理地址。proxy_type 可省略：0 为 HTTP，1 为 HTTP/1.0，2 为 HTTPS，4 至 7 为 SOCKS 代理

<!-- tags: 网络 设置 修改 HTTP 请求 network HTTPS SOCKS -->

| 参数         | 类型    | 说明                                     |
| ------------ | ------- | ---------------------------------------- |
| `session`    | integer | HTTP 会话 ID。                           |
| `proxy_addr` | string  | 代理服务器地址；空字符串表示不使用代理。 |
| `proxy_type` | integer | 可选代理类型，缺省为 0。                 |

返回：void

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
setHttpProxy(session, "", 0);
echo destroyHttpSession(session), "\n";
// 输出：1
```

## `setHttpVerifySsl(session, verify)`

声明：function

设置 HTTP 会话是否校验服务器证书

<!-- tags: 网络 设置 修改 HTTP 请求 network -->

| 参数      | 类型    | 说明                 |
| --------- | ------- | -------------------- |
| `session` | integer | HTTP 会话 ID。       |
| `verify`  | boolean | 是否校验服务器证书。 |

返回：void

### 示例

范例01：基本用法

```tsl
session := createHttpSession();
setHttpVerifySsl(session, false);
echo destroyHttpSession(session), "\n";
// 输出：1
```

## `sysSendMail(host, subject, to_address, from_address, text, out_message)`

声明：function

通过 SMTP 服务器发送邮件。发送成功返回真；失败返回假，并可通过输出参数 `out_message` 获取错误信息

<!-- tags: 网络 HTTP 请求 network SMTP -->

| 参数           | 类型   | 说明                                     |
| -------------- | ------ | ---------------------------------------- |
| `host`         | string | SMTP 服务器地址或配置别名。              |
| `subject`      | string | 邮件标题。                               |
| `to_address`   | string | 收件人地址。                             |
| `from_address` | string | 发件人地址。                             |
| `text`         | string | 邮件正文。                               |
| `out_message`  | string | 可选。发送失败时接收具体错误信息的变量。 |

返回：bool

### 示例

范例01：验证本地 SMTP 连接失败信息

```tsl
ok := sysSendMail(
    "127.0.0.1:1",
    "TSL example",
    "to@example.com",
    "from@example.com",
    "body",
    error_message
);
echo ok, ":", error_message, "\n";
// 输出：0，error_message 包含连接失败信息。
```