YStudio Y++

管道类

Y++ / YStudio 开发文档 · 一点滴

类对象支持库（不是扁平命令）。路径：支持库 → 扩展类库 → 管道类。

类型名必须写完整「管道类」。声明时自动创建，一般无需再调 创建*。

硬约束

  1. 类型名必须写「管道类」。命名管道 / 匿名管道。
  2. 可读可写端与阻塞行为以方法说明为准。

快速开始

管道类 p
// 创建/连接/读写：见下方命令介绍

管道类/创建

共 2 条。

创建管道

  • 签名：通用 创建管道()
  • 说明：命名管道或匿名管道会话。一般直接写「管道类 p」，不必先调本命令。

枚举管道

  • 签名：文本数组 枚举管道()
  • 说明：枚举本机命名管道短名（\.\pipe\ 下），返回文本数组。

管道类/方法

共 47 条。

枚举管道

  • 签名：文本数组 枚举管道()
  • 说明：等同自由命令「枚举管道()」。

创建服务端

  • 签名：逻辑 创建服务端(文本 名称, [整数 缓冲大小=65536], [逻辑 消息模式=假], [整数 最大实例=1], [整数 方向=0], [文本 安全描述符=""], [逻辑 拒绝远程=假])
  • 说明：创建命名管道服务端。失败返回假，可用取错误()查看原因。
  • 参数一│文本 名称: 短名、\.\pipe... 或 \服务器\pipe...
  • 参数二│[整数 缓冲大小=65536]: 收发缓冲字节数
  • 参数三│[逻辑 消息模式=假]: 真=消息模式，假=字节流
  • 参数四│[整数 最大实例=1]: 1～254；≤0 表示不限（按系统上限）
  • 参数五│[整数 方向=0]: 0双工、1入站(服务端只读)、2出站(服务端只写)
  • 参数六│[文本 安全描述符=”“]: SDDL；空=系统默认安全描述符
  • 参数七│[逻辑 拒绝远程=假]: 真=仅本机客户端可连接

等待连接

  • 签名：逻辑 等待连接([整数 超时毫秒=-1])
  • 说明：服务端等待客户端接入。成功返回真。
  • 参数一│[整数 超时毫秒=-1]: -1 无限等待；0 立即；>0 毫秒

连接

  • 签名：逻辑 连接(文本 名称, [整数 超时毫秒=5000])
  • 说明：作为客户端连接已存在的命名管道。
  • 参数一│文本 名称: 与服务端相同的短名、\.\pipe... 或 \服务器\pipe...
  • 参数二│[整数 超时毫秒=5000]: 等待管道可用的毫秒数；-1 无限；0 不等待

创建匿名写端

  • 签名：通用 创建匿名写端([逻辑 可继承=假])
  • 说明：创建一对匿名管道：本对象成为读端，返回写端对象。
  • 参数一│[逻辑 可继承=假]: 真=两端句柄可被子进程继承

移交已连接端

  • 签名：通用 移交已连接端()
  • 说明：把当前已连接服务端句柄交给新对象，本对象重新进入监听。

从句柄打开

  • 签名：逻辑 从句柄打开(整数 句柄, [整数 角色=0], [逻辑 接管=真])
  • 说明：用已有 HANDLE 包装为本对象。
  • 参数一│整数 句柄: Win32 HANDLE 整数值
  • 参数二│[整数 角色=0]: 0客户端、1服务端、2匿名读、3匿名写
  • 参数三│[逻辑 接管=真]: 真=关闭时 CloseHandle；假=先 Duplicate

断开

  • 签名：逻辑 断开()
  • 说明：服务端断开当前客户端；之后可再等待连接。

关闭

  • 签名：逻辑 关闭()
  • 说明：关闭管道句柄。已关闭再调也返回真。

是否已打开

  • 签名：逻辑 是否已打开()
  • 说明：当前是否持有有效管道句柄。

是否已连接

  • 签名：逻辑 是否已连接()
  • 说明：是否已与对端建立可读写连接。

是否服务端

  • 签名：逻辑 是否服务端()
  • 说明：当前对象是否为命名管道服务端。

重置

  • 签名：无 重置()
  • 说明：关闭管道并清空状态；超时恢复为 5000ms。

置超时

  • 签名：逻辑 置超时(整数 毫秒)
  • 说明：设置默认接收超时（毫秒）。0=非阻塞读。发送默认不受此限制。
  • 参数一│整数 毫秒: ≥0；接收/事务/接收文件可临时覆盖

取超时

  • 签名：整数 取超时()
  • 说明：取当前默认超时（毫秒）。

取可读字节数

  • 签名：整数 取可读字节数()
  • 说明：窥探管道中当前可读字节数（不消费数据）。

冲刷

  • 签名：逻辑 冲刷()
  • 说明：FlushFileBuffers：尽量把已写数据冲到对端。

清空缓冲

  • 签名：逻辑 清空缓冲([逻辑 清接收=真], [逻辑 冲刷写出=假])
  • 说明：丢弃当前可读数据，可选再冲刷写出缓冲。
  • 参数一│[逻辑 清接收=真]: 真=读空管道中已到达数据
  • 参数二│[逻辑 冲刷写出=假]: 真=再调用冲刷()

置可继承

  • 签名：逻辑 置可继承(逻辑 可继承)
  • 说明：设置句柄是否可被子进程继承。
  • 参数一│逻辑 可继承

取可继承

  • 签名：逻辑 取可继承()
  • 说明：当前句柄是否带 HANDLE_FLAG_INHERIT。

发送

  • 签名：逻辑 发送(文本 内容, [整数 超时毫秒=-1])
  • 说明：按 UTF-8 发送文本。成功返回真。
  • 参数一│文本 内容
  • 参数二│[整数 超时毫秒=-1]: <0 一直等到写完；0=写不进就失败；>0 毫秒

发送字节集

  • 签名：逻辑 发送字节集(字节集 数据, [整数 超时毫秒=-1])
  • 说明：发送原始字节。成功返回真。
  • 参数一│字节集 数据
  • 参数二│[整数 超时毫秒=-1]: 含义同「发送」

接收

  • 签名：文本 接收([整数 最大字节=0], [整数 超时毫秒=-1])
  • 说明：读取数据并按 UTF-8 转为文本。
  • 参数一│[整数 最大字节=0]: ≤0 默认 4096
  • 参数二│[整数 超时毫秒=-1]: <0 用置超时；0=非阻塞

接收字节集

  • 签名：字节集 接收字节集([整数 最大字节=0], [整数 超时毫秒=-1])
  • 说明：读取原始字节。
  • 参数一│[整数 最大字节=0]: ≤0 默认 4096
  • 参数二│[整数 超时毫秒=-1]: <0 用置超时；0=非阻塞

接收整条消息

  • 签名：文本 接收整条消息([整数 最大字节=0], [整数 超时毫秒=-1])
  • 说明：消息模式：把当前这一条消息读完再返回（UTF-8）。
  • 参数一│[整数 最大字节=0]: ≤0 默认上限 16MB，硬顶 64MB
  • 参数二│[整数 超时毫秒=-1]: <0 用置超时；为整条消息的总时限

接收整条消息字节集

  • 签名：字节集 接收整条消息字节集([整数 最大字节=0], [整数 超时毫秒=-1])
  • 说明：消息模式：把当前这一条消息读完，返回原始字节。
  • 参数一│[整数 最大字节=0]: ≤0 默认上限 16MB，硬顶 64MB
  • 参数二│[整数 超时毫秒=-1]: <0 用置超时

窥探

  • 签名：文本 窥探([整数 最大字节=0])
  • 说明：查看管道里已到达的数据并按 UTF-8 转成文本，不取走。
  • 参数一│[整数 最大字节=0]: ≤0 默认 4096

窥探字节集

  • 签名：字节集 窥探字节集([整数 最大字节=0])
  • 说明：查看已到达的原始字节，不取走。
  • 参数一│[整数 最大字节=0]: ≤0 默认 4096

事务

  • 签名：文本 事务(文本 请求, [整数 最大字节=0], [整数 超时毫秒=-1])
  • 说明：一次写出请求并读回应答（TransactNamedPipe）；UTF-8 文本。
  • 参数一│文本 请求
  • 参数二│[整数 最大字节=0]: 应答缓冲；≤0 默认 4096
  • 参数三│[整数 超时毫秒=-1]: <0 用置超时

事务字节集

  • 签名：字节集 事务字节集(字节集 请求, [整数 最大字节=0], [整数 超时毫秒=-1])
  • 说明：一次写出请求并读回应答；原始字节。
  • 参数一│字节集 请求
  • 参数二│[整数 最大字节=0]: 应答缓冲；≤0 默认 4096
  • 参数三│[整数 超时毫秒=-1]: <0 用置超时

模拟客户端

  • 签名：逻辑 模拟客户端()
  • 说明：服务端以已连接客户端的安全令牌模拟（ImpersonateNamedPipeClient）。

还原模拟

  • 签名：逻辑 还原模拟()
  • 说明：结束模拟客户端，恢复本进程令牌（RevertToSelf）。

是否在模拟

  • 签名：逻辑 是否在模拟()
  • 说明：当前是否处于模拟客户端状态。

取管道名

  • 签名：文本 取管道名()
  • 说明：取创建服务端/连接时传入的名称；匿名端为占位文案。

取错误

  • 签名：文本 取错误()
  • 说明：取最近一次失败原因；成功操作后一般为空。

取句柄

  • 签名：整数 取句柄()
  • 说明：取底层 HANDLE 的整数值；无效为 0。高级互操作慎用。

取对端进程ID

  • 签名：整数 取对端进程ID()
  • 说明：命名管道：服务端取客户端 PID，客户端取服务端 PID；失败为 0。

取对端会话ID

  • 签名：整数 取对端会话ID()
  • 说明：命名管道：服务端取客户端会话 ID，客户端取服务端会话 ID；失败为 0。

是否消息模式

  • 签名：逻辑 是否消息模式()
  • 说明：当前命名管道是否为消息模式。匿名管道返回假。

取输出缓冲

  • 签名：整数 取输出缓冲()
  • 说明：命名管道输出缓冲字节数（GetNamedPipeInfo）。失败为 0。

取输入缓冲

  • 签名：整数 取输入缓冲()
  • 说明：命名管道输入缓冲字节数。失败为 0。

取最大实例

  • 签名：整数 取最大实例()
  • 说明：命名管道允许的最大实例数。255 表示不限。失败为 0。

取当前实例

  • 签名：整数 取当前实例()
  • 说明：当前已创建的命名管道实例数。失败为 0。

取本消息剩余

  • 签名：整数 取本消息剩余()
  • 说明：消息模式：本条消息尚未读完的字节数。字节流一般为 0。

取客户端用户名

  • 签名：文本 取客户端用户名()
  • 说明：已连接服务端取客户端用户名（域\用户）。本机客户端也会尽量从令牌取出。

发送文件

  • 签名：逻辑 发送文件(文本 路径, [整数 块大小=65536], [整数 超时毫秒=-1])
  • 说明：按字节流发送文件：先写 8 字节小端长度，再写内容。
  • 参数一│文本 路径: 要发送的本地文件
  • 参数二│[整数 块大小=65536]: 每次写出的字节数，最大 1MB
  • 参数三│[整数 超时毫秒=-1]: <0 不限时；≥0 为整次发送总时限

接收文件

  • 签名：逻辑 接收文件(文本 路径, [整数 超时毫秒=-1])
  • 说明：读取发送文件() 写出的长度前缀和内容，保存到路径（已存在则覆盖）。
  • 参数一│文本 路径: 保存路径
  • 参数二│[整数 超时毫秒=-1]: <0 用置超时；为整次传输总时限

易错对照

错误 正确
类型写成「管道」 必须「管道类」

相关

进程类 · TCP类