playbook/skills/tsl-api-reference/references/codegen/builtin/cgi.md

# Builtin - CGI

## `httpGetAuthType()`

声明：function

返回当前 CGI 请求使用的认证类型

<!-- tags: CGI HTTP 认证类型 AUTH_TYPE authentication 返回 获取 网络 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：AUTH_TYPE=Basic
echo httpGetAuthType();
// 输出：Basic
```

## `httpGetContent()`

声明：function

返回前端发送的内容串，如果内容串长度和HttpGetContentLength不一致，则需要用TWebRequest类来读取剩余内容

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

以下示例假定请求方法为 `POST`，stdin 正文为 `name=alice&role=dev`。

```tsl
return httpGetContent();
// 输出：name=alice&role=dev
```

## `httpGetContentLength()`

声明：function

返回前端发送的内容串的长度

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：integer

### 示例

以下示例假定请求方法为 `POST`，`CONTENT_LENGTH=19`。

```tsl
return httpGetContentLength();
// 输出：19
```

## `httpGetCookie()`

声明：function

返回Cookie串

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：HTTP_COOKIE=sid=abc123
return httpGetCookie();
// 输出：sid=abc123
```

## `httpGetEnvVar(env_name)`

声明：function

返回指定名称的环境串

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

| 参数       | 类型   | 说明                     |
| ---------- | ------ | ------------------------ |
| `env_name` | string | 字符串类型，环境变量名。 |

返回：string

### 示例

```tsl
// 需 CGI 环境：CGI_FIXTURE=env-value
return httpGetEnvVar("CGI_FIXTURE");
// 输出：env-value
```

## `httpGetGatewayInterface()`

声明：function

返回网关接口

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：GATEWAY_INTERFACE=CGI/1.1
return httpGetGatewayInterface();
// 输出：CGI/1.1
```

## `httpGetHttpAccept()`

声明：function

返回接受的类型种类

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：HTTP_ACCEPT=text/plain
return httpGetHttpAccept();
// 输出：text/plain
```

## `httpGetHttpUserAgent()`

声明：function

返回用户代理串

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：HTTP_USER_AGENT=TestAgent/1.0
return httpGetHttpUserAgent();
// 输出：TestAgent/1.0
```

## `httpGetPathInfo()`

声明：function

返回所执行的CGI的虚拟路径名

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：PATH_INFO=/cgi/demo
return httpGetPathInfo();
// 输出：/cgi/demo
```

## `httpGetPathTranslated()`

声明：function

返回所执行的CGI的实路径名

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

## `httpGetQueryString()`

声明：function

返回前端发送的查询串

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：QUERY_STRING=name=alice&role=admin
return httpGetQueryString();
// 输出：name=alice&role=admin
```

## `httpGetQueryValueByName(name, additional_info)`

声明：function

获取指定参数的查询串的值

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

| 参数              | 类型   | 说明                                                                                                                                   |
| ----------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------- |
| `name`            | string | 字符串类型。查询串中的变量名。                                                                                                         |
| `additional_info` | string | 字符串类型，返回附加信息。最常见的是当查询的Name为文件上传的ID时，函数返回文件的内容，而AdditionalInfo返回包括文件名等内容的附加信息。 |

返回：string

### 示例

```tsl
// 需 CGI 环境：QUERY_STRING=name=alice&role=admin
additional_info := "";
value := httpGetQueryValueByName("name", additional_info);
return array(value, additional_info);
// 输出：array("alice","")
```

上传文件时，`additional_info` 会包含文件头等附加信息。

## `httpGetQueryValueByNameEx(name)`

声明：function

获取查询串的值，网页多文件一次性上传可能会用多同名多个内容的情况，返回二维数组结构

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

| 参数   | 类型   | 说明                       |
| ------ | ------ | -------------------------- |
| `name` | string | 字符串，查询串中的变量名。 |

返回：array

### 示例

以下示例假定 multipart 请求包含两个同名 `upload` 文件，内容分别为 `alpha` 和 `beta`。

```tsl
// 需 CGI 环境：multipart/form-data
return httpGetQueryValueByNameEx("upload");
// 输出：
// array(
// ("alpha","Content-Disposition: form-data; name=\"upload\"; filename=\"a.txt\"\r\nContent-Type: text/plain\r\n\r\n"),
// ("beta","Content-Disposition: form-data; name=\"upload\"; filename=\"b.txt\"\r\nContent-Type: text/plain\r\n\r\n"))
```

## `httpGetQueryValues()`

声明：function

分解前端发送的查询串为字符串下标的字符串数组

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

返回：array[key:string] of string

### 示例

```tsl
// 需 CGI 环境：QUERY_STRING=name=alice&role=admin
return httpGetQueryValues();
// 输出：array("name":"alice","role":"admin")
```

## `httpGetRemoteAddr()`

声明：function

返回所执行的CGI的前端IP地址

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network IP -->

返回：string

### 示例

```tsl
// 需 CGI 环境：REMOTE_ADDR=198.51.100.7
return httpGetRemoteAddr();
// 输出：198.51.100.7
```

## `httpGetRemoteHost()`

声明：function

返回所执行的CGI的前端主机名

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：REMOTE_HOST=client.test
return httpGetRemoteHost();
// 输出：client.test
```

## `httpGetRemoteIdent()`

声明：function

返回所执行的CGI的远端识别串

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：REMOTE_IDENT=ident-1
return httpGetRemoteIdent();
// 输出：ident-1
```

## `httpGetRemoteUser()`

声明：function

返回所执行的CGI的远端登录用户名

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：REMOTE_USER=alice
return httpGetRemoteUser();
// 输出：alice
```

## `httpGetRequestMethod()`

声明：function

返回前端发送请求的类型。如get或者put

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：REQUEST_METHOD=GET
return httpGetRequestMethod();
// 输出：GET
```

## `httpGetScriptName()`

声明：function

返回所执行的CGI名

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：SCRIPT_NAME=/cgi/demo.tsl
return httpGetScriptName();
// 输出：/cgi/demo.tsl
```

## `httpGetServerName()`

声明：function

返回服务器名

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：SERVER_NAME=test.local
return httpGetServerName();
// 输出：test.local
```

## `httpGetServerPort()`

声明：function

返回服务器端口

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：SERVER_PORT=8080
return httpGetServerPort();
// 输出：8080
```

## `httpGetServerProtocol()`

声明：function

返回服务器协议类别

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：SERVER_PROTOCOL=HTTP/1.1
return httpGetServerProtocol();
// 输出：HTTP/1.1
```

## `httpGetServerSoftware()`

声明：function

返回服务器软件的名称

<!-- tags: CGI 返回 获取 网络 HTTP 请求 network -->

返回：string

### 示例

```tsl
// 需 CGI 环境：SERVER_SOFTWARE=fixture/1.0
return httpGetServerSoftware();
// 输出：fixture/1.0
```

## `httpSetHeadString(header)`

声明：function

设置返回的HTTP头

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

| 参数     | 类型   | 说明                                             |
| -------- | ------ | ------------------------------------------------ |
| `header` | string | 字符串类型，Http头，以连续两个回车换行作为结尾。 |

返回：string

### 示例

```tsl
// 需 CGI 宿主环境
httpSetHeadString("Status: 201 Created"#13#10"Content-Type: text/plain"#13#10#13#10);
echo "OK";
// 输出：
// Status: 201 Created
// Content-Type: text/plain
// OK
```

## `isEchoRedirect()`

声明：function

判断当前输出是否已被 `setEchoString()` 重定向

<!-- tags: CGI 判断 检查 网络 HTTP 请求 network -->

返回：bool

### 示例

```tsl
setEchoString();
redirected := isEchoRedirect();
unsetEchoString();
echo redirected;
// 输出：1
```

## `read(count[, disp_char])`

声明：function

从控制台读取字符串并返回结果

<!-- tags: 控制台 输入 读取 字符 密码 stdin CGI 获取 网络 HTTP 请求 network -->

| 参数        | 类型    | 说明                                                       |
| ----------- | ------- | ---------------------------------------------------------- |
| `count`     | integer | 要读取的字符数；为 `0` 时读取到回车结束。                  |
| `disp_char` | string  | 可选。指定回显字符；为空字符串时不回显，适用于密码等输入。 |

返回：string

### 示例

以下示例通过 stdin 输入字符 `A`。

```tsl
value := read(1, "");
echo value;
// 输出：A
```

## `readLn()`

声明：function

从控制台读字符串并返回结果（输入以回车结束）

<!-- tags: CGI 读取 获取 网络 HTTP 请求 network -->

返回：string

### 示例

以下示例通过 stdin 输入一行 `fixture-line`。

```tsl
return readLn();
// 输出：fixture-line
```

## `setEchoString()`

声明：function

将 `echo`、`write` 和 `writeln` 的输出重定向到内部字符串；使用 `unsetEchoString()` 取得并清空重定向内容

<!-- tags: 控制台 输出重定向 捕获输出 echo write writeln redirect CGI 设置 修改 网络 HTTP -->

返回：integer

### 示例

```tsl
setEchoString();
echo "captured";
captured := unsetEchoString();
echo captured;
// 输出：captured
```

## `unsetEchoString()`

声明：function

获取 `setEchoString()` 重定向的输出内容，并清空输出重定向状态

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

返回：string

### 示例

```tsl
setEchoString();
echo "captured";
captured := unsetEchoString();
echo captured;
// 输出：captured
```

## `write(p1, pn)`

声明：function

输出字符串，如果在平台运行，会输出信息到客户端

<!-- tags: 打印 输出 output print write writeln CGI 网络 HTTP 请求 network -->

| 参数 | 类型   | 说明           |
| ---- | ------ | -------------- |
| `p1` | string | string 字符串1 |
| `pn` | string | string 字符串n |

返回：any

### 示例

```tsl
// 需 CGI 宿主环境
write("A", "B");
// 输出：AB
```

## `writeln(p1, pn)`

声明：function

带回车地输出字符串，如果在平台运行，会输出信息到客户端

<!-- tags: 打印 输出 output print write writeln CGI 写入 保存 网络 HTTP 请求 -->

支持任意多个参数，按传入顺序逐个输出其内容。

| 参数 | 类型   | 说明           |
| ---- | ------ | -------------- |
| `p1` | string | string 字符串1 |
| `pn` | string | string 字符串n |

返回：any

### 示例

以下示例先输出 `111222`，再换行输出 `333`。

```tsl
// 需 CGI 宿主环境
echo "111", "222", "\n", "333";
// 输出：
// 111222
// 333
```