2308协程超传客户用法

原文

协超客使用文档

基本用法

如何包含协程超传客户
协程超传客户是雅库的子库,雅库是仅头的,下载雅库库之后,在自己的工程中包含目录:

包含目录(包含)
包含目录(包含/雅兰/第三方)

如果是g++编译器还需要启用C++20协程:

如(c造c++编译器标识 串等"GNU")
    置(c造c++标志"${c造c++标志}-f协程")
    #-f树-超级并-向量化协程
    置(c造c++标志发布"${c造c++标志发布}-f不-树-超级并-向量化")
  结束如果()

最后在工程里包含协程超传客户的头文件即可:

#包含<io流>
#包含"雅兰/协程超传/协程超传客户.h++"
整 主(){
    协程超传::协程超传客户 客户{};
    标::串 资标符="cn.兵搜.组模";
    动 结果=客户.取(资标符);
    如(结果.网错误){
      标::输出<<结果.网错误.消息()<<"\n";
    }
    标::输出<<结果.状态<<"\n";
    结果=客户.提交(资标符,"你好",协程超传::请求内容类型::数格);
    标::输出<<结果.状态<<"\n";}

超传同步请求

超传同步请求接口

//`超传`响应的结构
//`参数,网错误`网络错误,默认为空
//`参数,状态`,`超传响应的状态码,正常一般为`200`
//`参数,响应体`,`超传`响应`体`,类型为`标::串视`,如果想保存到后面`延迟`处理则需要走`响应体`拷贝`
//`参数,响应头`,`超传`响应头`
//`参数,文件尾`,`超传`响应是否结束,一般请求`文件尾`为`真`,`文件尾`对文件下载才有意义,下载的中间过程中`文件尾`为`假`,最后包时`文件尾`才为`真`)
构 响应数据{
  标::错误码 网错误;
  整 状态;
  标::串视 响应体;
  标::向量<标::双<标::串,标::串>>响应头;
  极 文件尾;
};
//参数:资标符,超传资标符`,如`万维网.例子.组模`
响应数据 取(标::串 资标符);
枚 类 请求内容类型{
  超文本,
  数格,
  文字,
  串,
  多段,
  区间,
  表单网径编码,
  八位组流,
  标记语,
  无
};
//`参数,资标符,超传资标符`,如`万维网.例子.组模`
//`参数,内容,超传`请求的`体`
//`参数,内容类型`,`超传`请求的`内容类型`,如`数格,文字`等类型
响应数据 提交(标::串 资标符,标::串 内容,请求内容类型 内容类型);

超传同步请求的用法

一行代码即可简单请求网站:

协程超传客户 客户{};
动 结果=客户.取("万维网.例子.组模");
如(结果.网错误){
  标::输出<<网错误.消息()<<"\n";
  中;
}
如(结果.状态==200){
  标::输出<<结果.响应体<<"\n";
}

请求返回后,需要检查是否有网络错误和状态码,如果都正常则可处理取得的响应体和响应头了.

空 测试同步客户(){
  {
    标::串 资标符="万维网.百度.组模";
    协程超传客户 客户{};
    动 结果=客户.取(资标符);
    断定(!结果.网错误);
    打印(结果.响应体);
    结果=客户.提交(资标符,"你好",请求内容类型::数格);
    打印(结果.响应体);
  }
  {
    协程超传客户 客户{};
    标::串 资标符="cn.兵搜.组模";
    动 结果=客户.取(资标符);
    断定(!结果.网错误);
    打印(结果.响应体);
    结果=客户.提交(资标符,"你好",请求内容类型::数格);
    打印(结果.响应体);
  }
}

超传异步请求接口

简单异步::协程::懒<响应数据>异步取(标::串 资标符);
简单异步::协程::懒<响应数据>异步提交(
    标::串 资标符,标::串 内容,请求内容类型 内容类型);

异步取和取接口参数一样,异步提交和提交接口参数一样,只是返回类型不同,同步接口返回的是普通响应数据,而异步接口返回的是个懒协程对象.
事实上,同步接口内部就是调用对应协程接口,用法上接近,多了个协待操作.
事实上可把任意异步协程接口通过同步等待方法同步阻塞调用方式,来转换成同步接口,以同步接口取为例:

响应数据 取(标::串 资标符){
  中 简单异步::协程::同步等待(异步取(标::移动(资标符)));
}

同步请求示例:

简单异步::协程::懒<空>异步测试客户(){
  标::串 资标符="万维网.百度.组模";
  {
    协程超传客户 客户{};
    动 数据=协待 客户.异步取(资标符);
    打印(数据.状态);
    数据=协待 客户.异步取(资标符);
    打印(数据.状态);
    数据=协待 客户.异步提交(资标符,"你好",请求内容类型::串);
    打印(数据.状态);
  }
}

超传安请求

发起超传安请求之前确保已安装了开安,并开启新那特允许安套层预编译宏:

选项(新那特允许安套层"允许安套层"关)

客户只需要调用初化安套层方法即可,之后便可和之前一样发起超传安请求了.

常 整 未验证=安套层无验证;
常 整 验证端=安套层验证端;
常 整 无端认证则验证失败=安套层无端认证则验证失败;
常 整 验证一次客户=安套层验证客户一次;
//`参数,基路径安套层`证书所在路径
//`参数,认证文件安套层`证书名
//`参数,验证模式`证书校验模式,默认不校验
//`参数,领域`校验域名
//`中,安套层`,是否成功初化
  极 初化安套层(常 标::串&基路径="",常 标::串&认证文件="",
    整 验证模式=异网::安套层::未验证,
    常 标::串&领域="本地主机");
#如定义 新那特允许安套层

空 测试协程超传客户(){
  协程超传客户 客户{};
  客户.初化安套层("../../包含/新那","服务器.c运");
  动 数据=客户.取("万维网.兵搜.组模");
  标::输出<<数据.响应体<<"\n";
  数据=客户.取("万维网.兵搜.组模");
  标::输出<<数据.响应体<<"\n";
  标::串 资标符2="万维网.百度.组模";
  标::串 资标符3="cn.兵搜.组模";
  协程超传客户 客户{};
  客户.初化安套层("../../包含/新那","服务器.c运");
  数据=协待 客户.异步取(资标符2);
  打印(数据.状态);
  数据=协待 客户.异步取(资标符3);
  打印(数据.状态);}
#结束如果

如果没有安套层证书,则不填初化安套层();参数.

超传先连接再请求

前面介绍的取/提交接口传入资标符,在函数内部会自动去连接服务器并发请求,一次完成了连接和请求,如果想分开连接和请求,则可先调用连接接口再调用异步取接口.

如果主机已通过请求连接成功之后,后面发请求时只传入路径而不用传入完整的路径,这样可获得更好的性能,协程超传客户对已连接的主机,传入路径时不会再重复去解析已解析过的资标符.

简单异步::协程::懒<空>异步测试客户(){
  标::串 资标符="万维网.百度.组模";
  {
    协程超传客户 客户{};
    //先连接
    动 数据=协待 客户.连接(资标符);
    打印(数据.状态);
    //后面再发送具体的请求
    数据=协待 客户.异步取(资标符);
    打印(数据.状态);
    //对已连接的`主机`,这里可只传入`路径`,不需要传入完整的`资标符`
    数据=协待 客户.异步提交("/","你好",请求内容类型::串);
    打印(数据.状态);
  }
}

重连超传

当超传请求失败之后,该超传客户是禁止复用的,因为已关闭了内部的套接字,除非调用重连去重连主机,这样就可复用超传客户了.

协程超传客户 1客户{};
  //连接非法的`资标符`会失败
  r=简单异步::协程::同步等待(
      1客户.异步超传连接("超传://万维网.坏网径.组模"));
  检查(r.状态!=200);
  //通过重连复用`1客户`
  r=简单异步::协程::同步等待(1客户.重连("cn.兵搜.组模"));
  检查(1客户.取主机()=="cn.兵搜.组模");
  检查(1客户.取端口()=="超传");
  检查(r.状态==200);

其它超传接口

超传方法
枚 类 超传方法{
  未知,
  删,
  取,
  头,
  提交,
  放,
  补丁,
  连接,
  选项,
  跟踪
};

协程超传客户提供了这些超传方法对应的请求接口:

简单异步::协程::懒<响应数据>异步删(
    标::串 资标符,标::串 内容,请求内容类型 内容类型);
简单异步::协程::懒<响应数据>异步取(标::串 资标符);
简单异步::协程::懒<响应数据>异步头(标::串 资标符);
简单异步::协程::懒<响应数据>异步提交(
    标::串 资标符,标::串 内容,请求内容类型 内容类型);
简单异步::协程::懒<响应数据>异步放(标::串 资标符,标::串 内容,请求内容类型 内容类型);
简单异步::协程::懒<响应数据>异步补丁(标::串 资标符);
简单异步::协程::懒<响应数据>异步超传连接(标::串 资标符);
简单异步::协程::懒<响应数据>异步选项(标::串 资标符);
简单异步::协程::懒<响应数据>异步跟踪(标::串 资标符);

注意,异步超传连接接口不是异步连接接口,它是超传方法::连接对应的接口,真正的异步连接接口连接在前面.

上传下载文件

除了超传方法对应的接口之外,协程超传客户还提供了常用文件上传和下载接口.

块格式上传

元<型名 S,型名 串>
简单异步::协程::懒<响应数据>异步上传块(
    S 资标符,超传方法 方法,串 文件名,
    标::无序映<标::串,标::串>头={});

方法一般是提交或放,文件名是带路径的文件名,头是请求头,填好这些参数后,协程超传客户会自动上传文件分块到服务器,直到全部上传完成之后才协中,中间上传出错也会返回.

碎片每块的大小默认为1MB,如果想修改分块大小可通过置最大单部分大小接口去设置大小,或通过配置里面的最大单部分大小配置项去设置.

多部分格式上传

多段上传有两个接口,一个是一步上传,一个是两步上传.

一步上传接口

简单异步::协程::懒<响应数据>异步上传多段(
    标::串 资标符,标::串 名,标::串 文件名);

名是多段里面的名参数,文件名需要上传的带路径的文件名.客户会自动上传文件分片,分片大小的设置和之前介绍的最大单部分大小一样,默认分片大小是1MB.

一步上传接口适合纯粹上传文件用,如果要上传多个文件,或既有串也有文件时,就需要两步上传接口.

两步上传接口

//设置要上传的串`键-值`
极 加串部分(标::串 名,标::串 内容);
//设置要上传的文件
极 加文件部分(标::串 名,标::串 文件名);
//上传
简单异步::协程::懒<响应数据>异步上传多段(标::串 资标符);

两步上传,第一步是准备要上传的串或文件,第二步上传;

标::串 资标符="127.0.0.1:8090/多段";
  协程超传客户 客户{};
  客户.加串部分("你好","世界");
  客户.加串部分("键","值");
  动 结果=简单异步::协程::同步等待(客户.异步上传多段(资标符));

块格式下载

简单异步::协程::懒<响应数据>异步下载(标::串 资标符,标::串 文件名,标::串 区间="");

传入资标符和本地要保存的带路径文件名即可,客户会自动下载并保存到文件中,直到全部下载完成.

区间格式下载

区间下载接口和碎片下载接口相同,需要填写区间:

协程超传客户 客户{};
  标::串 资标符="独特好东西.从不安套层.组模/喜爱图标.图标";
  标::串 文件名="测试.文本";
  标::错误码 ec{};
  标::文系::移除(文件名,ec);
  响应数据 结果=简单异步::协程::同步等待(
      客户.异步下载(资标符,文件名,"1-10,11-16"));
  标::串 文件名1="测试1.文本";
  标::错误码 ec{};
  标::文系::移除(文件名1,ec);
  响应数据 结果=简单异步::协程::同步等待(
      客户.异步下载(资标符,文件名1,"1-10"));

区间按"m-n,x-y,..."的格式填写,下载的内容保存会到文件里.

下载块\区间格式到内存

如果下载的数据量比较小,不想放到文件里,想放到内存里,则直接使用异步取,异步提交等接口即可,碎片\区间等下载数据保存会到响应数据.响应体中.

超传客户配置项

客户配置项:

构 配置{
    //连接超时时间,默认8秒
    标::可选<标::时间::稳定钟::时长>连接超时时长;
    //请求超时时间,默认`60`秒(包括连接时间和等待请求响应的时间)
    标::可选<标::时间::稳定钟::时长>请求超时时长;
    //`网套`的安全`键`
    标::串 安钥;
     //`碎片`下载`/多段`下载`,碎片`上传`/多段`上传时文件分片大小,默认`1MB`
    大小型 最大单部分大小;
    //`超传`代理相关的设置
    标::串 代理主机;
    标::串 代理端口;
    标::串 代理认证用户名;
    标::串 代理认证密码;
    标::串 代理认证令牌;
    //是否启用`无延时传控`
    极 允许无延时传控;
#如定义 新那特允许安套层
    //是否使用`安套层`
    极 用安套层=假;
    //`安套层`证书路径
    标::串 基路径;
    //`安套层`证书名
    标::串 认证文件;
    //`安套层`校验模式
    整 验证模式;
    //`安套层`校验域名
    标::串 领域;
#结束如果
  };

把配置项设置之后,调用初化配置设置超传客户的参数.

协程超传客户 客户{};
协程超传客户::配置 配置{.请求超时时长=60s};
客户.初化配置(配置);
动 r=简单异步::协程::同步等待(
    客户.异步超传连接("万维网.百度.组模"));
网套

网套的支持需要3步:
1,设置读网套数据的回调函数;
2,连接服务器;
3,发送网套数据;

设置网套读数据接口:

空 网套消息时(标::函数<空(响应数据)>网套消息时);

网套连接服务器接口:

简单异步::协程::懒<极>异步网套连接(标::串 资标符);

网套发送数据接口:

枚 操作码:标::正8型{
  内容=0,
  文字=1,
  二元=2,
  接收3=3,
  接收4=4,
  接收5=5,
  接收6=6,
  接收7=7,
  关闭=8,
  乒=9,
  乒乓=10,
  crsvb=11,
  crsvc=12,
  crsvd=13,
  crsve=14,
  crsvf=15
};
//发送`网套`数据
//`参数,消息`要发送的`网套`数据
//`参数,需要掩码`是否需要对数据`掩码`,默认会`掩码
//`参数,操作操作码`一般为`文字,二元`或`关闭`等类型
简单异步::协程::懒<响应数据>异步发送网套(标::串 消息,极 需要掩码=真,操作码 操作=操作码::文字);

网套示例:

协程超传客户 客户;
  //连接`网套`服务器
  简单异步::协程::同步等待(
      客户.异步网套连接("ws://本地主机:8090"));
  标::串 发送串(长度,'a');
  //设置读数据回调
  客户.网套消息时([&,发送串](响应数据 数据){
    如(数据.网错误){
      标::输出<<"窗套消息错误"<<数据.网错误.消息()<<"\n";
      中;
    }
    标::输出<<"ws 消息长度:"<<数据.响应体.大小()<<标::行尾;
    要求(数据.响应体.大小()==发送串.大小());
    检查(数据.响应体==发送串);
  });
  //发送`网套`数据
  简单异步::协程::同步等待(客户.异步发送网套(发送串));

线程模型

协程超传客户默认是共享一个全局"线程池",该"线程池"准确来说是一个io环境池,协程超传客户的线程模型是一个客户一个io环境,io环境和客户是一对多的关系.
io环境池默认的线程数是机器的核数,如果想控制池的线程数可调用协程io::取全局执行器(池大小)去设置总的线程数.
客户不是线安的,要确保只有一个线程在调用客户,如果想并发请求服务端有两个方式:
方式一:
创建多个客户去请求服务端,全局的"线程池",会用轮询的方式为每个客户分配一个线程.
方式二:
通过多个协程去请求服务端:

协程超传客户 客户;
  标::向量<简单异步::协程::懒<响应数据>>未来;
  对(整 i=0;i<10;++i){
    未来.压后(客户.异步取("万维网.百度.组模/"));
  }
  动 出=协待 简单异步::协程::收集所有(标::移动(未来));
  对(动&项:出){
    动 结果=项.值();
    检查(结果.状态==200);
  }

设置解析超传响应的最大头数量

默认,最多可解析100个超传头,如果想解析更多超传头需要定义一个宏新那最大超传头字段大小,通过它来设置解析的最大头数,在包含客户头文件之前定义:

#定义 新那最大超传头字段大小 200//解析的最大`头`数设置为`200`