@tars/stream

00 - 安装

$ npm install @tars/stream

01 - stream模块基本介绍和使用方法

stream模块用作Tars(tars/TUP)基础协议编解码库,使用该模块可以基于tars协议描述格式对数据流进行编解码,并能够与目前使用tars协议的TARS服务端以及终端进行无障碍通信。

tars编解码模块工作流方式一般有如下三种:

第一种,以tars文件作为调用方和服务方的通信桥梁(双方约定最终协议以tars文件为准)。

该tars文件也就是我们常说的以”.tars”结尾的协议描述文件。

该tars文件一般由后台开发制定,前台开发需向后台开发索求经评审确认的tars文件,然后经工具转换成适用于NodeJS的编解码源代码文件。

  1. module TRom
  2. {
  3. struct User_t
  4. {
  5. 0 optional int id = 0;
  6. 1 optional float score = 0;
  7. 2 optional string name = "";
  8. };
  9. struct Result_t
  10. {
  11. 0 optional int id = 0;
  12. };
  13. interface NodeJsComm
  14. {
  15. int test();
  16. int getall(User_t stUser, out Result_t stResult);
  17. int getUsrName(string sUsrName, out string sValue1, out string sValue2);
  18. int secRequest(vector<byte> binRequest, out vector<byte> binResponse);
  19. };
  20. };

比如,我们将如上内容保存为“Protocol.tars”后,可以使用如下的命令生成不同的文件:

$ tars2node Protocol.tars

上述命令将忽略interface描述段,只转换文件中定义的“常量”、“枚举值”、“结构体”等数据类型,供开发者当不使用Tars框架作为调用工具时的编解码库文件。生成的文件名称为“Protocol.js”。

$ tars2node Protocol.tars —client

上述命令不仅转换文件中定义的“常量”、“枚举值”、“结构体”等数据类型,同时将interface的描述段翻译成RPC调用框架。生成的文件名称为“ProtocolProxy.js”,该文件供调用方使用。开发者引入该文件之后,可以直接调用服务端的服务。具体的使用方法请参考“npm install rpc”模块的说明文档。

$ tars2node Protocol.tars —server

上述命令不仅转换文件中定义的“常量”、“枚举值”、“结构体”等数据类型,同时将interface的描述段翻译成服务端的接口文件。生成的文件名称为“Protocol.js”以及“ProtocolImp.js”,开发者不要改动“Protocol.js”,只需要继续完善“ProtocolImp.js”,实现文件中具体的函数,即可作为Tars服务端提供服务。具体的使用方法请参考“npm install rpc”模块的说明文档。

第二种,没有协议描述文件,需要我们自己手工书写编解码代码时。

比如服务后台提供购买某件商品的功能,它需要“用户号码”、“用户昵称”、“商品编号”、“商品数量”等四个参数。 后台对这四个参数的编号(也就是tars中所指的tag)分别为0、1、2、3。

  1. //第一步,引入tars/TUP编解码库
  2. var Tars = require("@tars/stream");
  3. //第二步,客户端按照服务端要求,对输入参数进行编码
  4. var ost = new Tars.OutputStream();
  5. ost.writeUInt32(0, 155069599); //写入“用户号码”;在服务端“0”代表“用户号码”。
  6. ost.writeString(1, "KevinTian"); //写入“用户昵称”;在服务端“1”代表“用户昵称”。
  7. ost.writeUInt32(2, 1002121); //写入“商品编号”;在服务端“2”代表“商品编号”。
  8. ost.writeUInt32(3, 10); //写入“商品数量”;在服务端“3”代表“商品数量”。
  9. //第三步,客户端将打包后的二进制Buffer发送给服务端
  10. send ( ost.getBinBuffer().toNodeBuffer() ) to server
  11. //第四步,服务端从客户端接收完整的请求二进制Buffer
  12. recv ( var requestBuffer = new Buffer() ) from client
  13. //第五步,将该请求进行解码反序列化
  14. var ist = new Tars.InputStream(new Tars.BinBuffer(requestBuffer));
  15. var uin = ist.readUInt32(0, true); //根据编号“0”读取“用户号码”。
  16. var name = ist.readString(1, true); //根据编号“1”读取“用户昵称”。
  17. var gid = ist.readUInt32(2, true); //根据编号“2”读取“商品编号”。
  18. var num = ist.readUInt32(3, true); //根据编号“3”读取“商品数量”。
  19. //第六步,根据相关传入参数进行相应的逻辑操作
  20. console.log("name:", name);
  21. console.log("num :", num);
  22. ......

第三种,服务端接受TUP协议格式的数据。

  1. //第一步,引入tars/TUP编解码库
  2. var Tars = require("@tars/stream");
  3. //第二步,客户端按照服务端要求,对输入参数进行编码
  4. var tup_encode = new Tars.Tup();
  5. tup_encode.writeUInt32("uin", 155069599); //服务端接口函数“用户号码”的变量名称为“uin”。
  6. tup_encode.writeString("name", "KevinTian"); //服务端接口函数“用户昵称”的变量名称为“name”。
  7. tup_encode.writeUInt32("gid", 1002121); //服务端接口函数“商品编号”的变量名称为“gid”。
  8. tup_encode.writeUInt32("num", 10); //服务端接口函数“商品数量”的变量名称为“uum”。
  9. var BinBuffer = tup_encode.encode(true);
  10. //第三步,客户端将打包后的二进制Buffer发送给服务端
  11. send ( BinBuffer.toNodeBuffer() ) to server
  12. //第四步,服务端从客户端接收完整的请求二进制Buffer
  13. recv ( var requestBuffer = new Buffer() ) from client
  14. //第五步,将该请求进行解码反序列化
  15. var tup_decode = new Tars.Tup();
  16. tup_decode.decode(new Tars.BinBuffer(requestBuffer));
  17. var uin = tup_decode.readUInt32("uin"); //服务端根据变量名“uin”读取“用户号码”。
  18. var name = tup_decode.readString("name"); //服务端根据变量名“name”读取“用户昵称”。
  19. var num = tup_decode.readUInt32("num"); //服务端根据变量名“gid”读取“商品编号”。
  20. var gid = tup_decode.readUInt32("gid"); //服务端根据变量名“num”读取“商品数量”。
  21. //第六步,根据相关传入参数进行相应的逻辑操作
  22. console.log("name:", name);
  23. console.log("num :", num);
  24. ......

02 - stream支持的数据类型以及使用方法

基本数据类型

数据类型 对应C++语言的数据类型
布尔值 bool
整型 char(int8)、short(int16)、int(int32)、long long(int64)
整型 unsigned char(uint8)、unsigned short(uint16)、unsigned int(uint32)
数值 float(32位)、double(64位)
字符串 std::string

复杂数据类型

数据类型 对应C++语言的数据类型
结构体 struct(在Tars框架中需要使用tars2node根据tars文件来生成Javascript中的类)
二进制Buffer vector<char>(在NodeJs中使用[stream].BinBuffer类型来模拟)
数组 vector<DataType>(在NodeJs中使用[stream].List(vproto)类型来模拟)
词典 map<KeyType, DataType>(在NodeJs中使用[stream].Map(kproto, vproto)类型来模拟)

关于NodeJs中数据类型的特别说明

[1]: “复杂数据类型”与“基本数据类型”,或者“复杂数据类型”与“复杂数据类型”组合使用可以组成其他高级数据类型。

[2]: 虽然NodeJS中支持Float和Double数据类型,但我们不推荐使用,因为在序列化和反序列化之后,数值存在精度损失,某些情况下会对业务逻辑造成伤害。

[3]: 我们这里实现的64位整形实际上是伪64位,在NodeJs中它的原形仍然是Number。

我们都知道Js中的Number类型采用IEEE754双精度浮点数标准来表示。IEEE754规定有效数字第一位默认为1,再加上后面的52位来表示数值。

也就是说IEEE754提供的有效数字的精度为53个二进制位,这就意味着NodeJs的Number数值或者说我们实现的Int64数据类型只能精确表示绝对值小于2的53次方的整数。

[4]: 在Javascript中String类型是Unicode编码,在tars编解码时我们将其转换成了UTF8编码格式;

后台服务程序接受到的字符串是UTF8编码,如果需要按照GBK编码的方式处理字符串,需要后台程序先做下转码(UTF8->GBK);

后台服务程序如果使用的是GBK,发送字符串之前,需要将其转成UTF8编码。

03 - 基本类型使用方法

  1. //必须引入stream模块
  2. var Tars = require("@tars/stream");
  3. //使用Tars.OutputStream对数据进行序列化
  4. var os = new Tars.OutputStream();
  5. os.writeBoolean(0, false);
  6. os.writeInt8(1, 10);
  7. os.writeInt16(2, 32767);
  8. os.writeInt32(3, 0x7FFFFFFE);
  9. os.writeInt64(4, 8589934591);
  10. os.writeUInt8(5, 200);
  11. os.writeUInt16(6, 65535);
  12. os.writeUInt32(7, 0xFFFFFFEE);
  13. os.writeString(8, "我的测试程序");
  14. //使用Tars.InputStream对数据进行反序列化
  15. var is = new Tars.InputStream(os.getBinBuffer());
  16. var tp0 = is.readBoolean(0, true, false);
  17. console.log("BOOLEAN:", tp0);
  18. var tp1 = is.readInt8(1, true, 0);
  19. console.log("INT8:", tp1);
  20. var tp2 = is.readInt16(2, true, 0);
  21. console.log("INT16:", tp2);
  22. var tp3 = is.readInt32(3, true, 0);
  23. console.log("INT32:", tp3);
  24. var tp4 = is.readInt64(4, true, 0);
  25. console.log("INT64:", tp4);
  26. var tp5 = is.readUInt8(5, true, 0);
  27. console.log("UINT8:", tp5);
  28. var tp6 = is.readUInt16(6, true, 0);
  29. console.log("UINT16:", tp6);
  30. var tp7 = is.readUInt32(7, true, 0);
  31. console.log("UINT32:", tp7);
  32. var tp8 = is.readString(8, true, "");
  33. console.log("STRING:", tp8);

04 - 复杂类型前传 - 用于表示复杂类型的类型原

首先,我们理解下什么是 类型原型

在C++中,我们可以按如下方法声明一个字符串的容器向量:

  1. #include <string>
  2. #include <vector>
  3. std::vector<std::string> vec;
  4. vec.push_back("qzone");
  5. vec.push_back("wechat");

其中std::vectorstd::string,std::vector表示容器类型,而std::string则表示该容器所容纳的 类型原型

那我们如何在NodeJs中表示该类型?并能使之与tars的编解码库无缝的融合?

为了解决这个问题,我们使用如下的方法对std::vector进行模拟,以达到上述C++代码所能完成的功能:

  1. var Tars = require("@tars/stream");
  2. var abc = new Tars.List(Tars.String);
  3. abc.push("qzone");
  4. abc.push("wechat");

其中Tars.List(Tars.String),Tars.List表示数组类型,而Tars.String则用来表示该容器所容纳的 类型原型

至此,我们明白类型原型主要是用来与复杂数据类型组合,表示更加复杂的数据类型。

目前的版本中,我们支持如下的类型原型定义:

数据类型 描述
布尔值 [stream].Boolean
整型 [stream].Int8, [stream].Int16, [stream].32, [stream].64, [stream].UInt8, [stream].UInt16, [stream].UInt32
数值 [stream].Float, [stream].Double
字符串 [stream].String
枚举值 [stream].Enum
数组 [stream].List
字典 [stream].Map
二进制Buffer [stream].BinBuffer

为了大家更加清晰的理解该概念,我们提前描述一部分复杂类型的在NodeJs中的表示方法。

数据类型的详细使用方法,请参考后续的详细说明。

  1. var Tars = require("@tars/stream");
  2. //c++语法:std::vector<int>
  3. var abc = new Tars.List(Tars.Int32)
  4. abc.push(10000);
  5. abc.push(10001);
  6. //c++语法:std::vector<std::vector<std::string> >
  7. var abc = new Tars.List(Tars.List(Tars.String));
  8. var ta = new Tars.List(Tars.String);
  9. ta.push("ta1");
  10. ta.push("ta2");
  11. var tb = new Tars.List(Tars.String);
  12. tb.push("tb1");
  13. tb.push("tb2");
  14. abc.push(ta);
  15. abc.push(tb);
  16. //c++语法:std::map<std::string, std::string>
  17. var abc = new Tars.Map(Tars.String, Tars.String);
  18. abc.insert("key1", "value1");
  19. abc.insert("key2", "value2");
  20. //c++语法:std::map<std::string, std::vector<string> >
  21. var abc = new Tars.Map(Tars.String, Tars.List(Tars.String));
  22. var ta = new Tars.List(Tars.String);
  23. ta.push("ta1");
  24. ta.push("ta2");
  25. var tb = new Tars.List(Tars.String);
  26. tb.push("tb1");
  27. tb.push("tb2");
  28. abc.insert("key_a", ta);
  29. abc.insert("key_b", tb);
  30. //c++语法:std::vector<char>
  31. var abc = new Tars.BinBuffer();
  32. abc.writeInt32(10000);
  33. abc.writeInt32(10001);

05 - 复杂类型 - struct(结构体)的使用方法说明

  1. module Ext
  2. {
  3. struct ExtInfo {
  4. 0 optional string sUserName;
  5. 1 optional map<string, vector<byte> > data;
  6. 2 optional map<string, map<string, vector<byte> > > cons;
  7. };
  8. };

将上述内容保存为文件“Demo.tars”,然后使用命令“tars2node Demo.tars”生成编解码文件“Demo.js”。

“Demo.js”内容如下所示:

  1. var TarsStream = require("@tars/stream");
  2. var Ext = Ext || {};
  3. module.exports.Ext = Ext;
  4. Ext.ExtInfo = function() {
  5. this.sUserName = "";
  6. this.data = new TarsStream.Map(TarsStream.String, TarsStream.BinBuffer);
  7. this.cons = new TarsStream.Map(TarsStream.String, TarsStream.Map(TarsStream.String, TarsStream.BinBuffer));
  8. };
  9. Ext.ExtInfo._write = function (os, tag, value) { os.writeStruct(tag, value); }
  10. Ext.ExtInfo._read = function (is, tag, def) { return is.readStruct(tag, true, def); }
  11. Ext.ExtInfo._readFrom = function (is) {
  12. var tmp = new Ext.ExtInfo();
  13. tmp.sUserName = is.readString(0, false, "");
  14. tmp.data = is.readMap(1, false, TarsStream.Map(TarsStream.String, TarsStream.BinBuffer));
  15. tmp.cons = is.readMap(2, false, TarsStream.Map(TarsStream.String, TarsStream.Map(TarsStream.String, TarsStream.BinBuffer)));
  16. return tmp;
  17. };
  18. Ext.ExtInfo.prototype._writeTo = function (os) {
  19. os.writeString(0, this.sUserName);
  20. os.writeMap(1, this.data);
  21. os.writeMap(2, this.cons);
  22. };
  23. Ext.ExtInfo.prototype._equal = function (anItem) {
  24. return anItem.sUserName === this.sUserName
  25. && anItem.data === this.data
  26. && anItem.cons === this.cons;
  27. }
  28. Ext.ExtInfo.prototype._genKey = function () {
  29. if (!this._proto_struct_name_) {
  30. this._proto_struct_name_ = 'STRUCT' + Math.random();
  31. }
  32. return this._proto_struct_name_;
  33. }
  34. Ext.ExtInfo.prototype.toBinBuffer = function () {
  35. var os = new TarsStream.OutputStream();
  36. this._writeTo(os);
  37. return os.getBinBuffer();
  38. }
  39. Ext.ExtInfo.create = function (is) {
  40. return Ext.ExtInfo._readFrom(is);
  41. }

对“module Ext”的说明

Ext在C++中就是命名空间,在Javascript中我们将它翻译成一个Object,该命名空间下所有的“常量”、“枚举值”、“结构体”、“函数”都挂接在该Object之下。

tars文件中描述的结构体的表示方法

首先,结构体翻译成一个Object。翻译程序根据数据类型以及tars文件中定义的默认值,生成数据成员。除tars中定义的数据成员之外,根据编解码的需要,翻译程序为结构体添加了若干辅助函数。这些函数如_writeTo,在需要将结构体序列化成数据流的地方,被编解码库调用,该函数逐个将数据成员写入数据流中。

翻译程序默认添加的辅助函数

方法 限制 描述
_write 开发者不可用 静态函数。当结构体用作类型原型时使用。
_read 开发者不可用 静态函数。当结构体用作类型原型时使用。
_readFrom 开发者不可用 静态函数。从数据流中读取结构体的数据成员值,并生成一个权限的结构体示例返回。
_writeTo 开发者不可用 成员函数。将当前结构体的数据成员写入指定的数据流中。
_equal 开发者不可用 成员函数。将当前结构体用作字典类型Key值时的比较函数。
_genKey 开发者不可用 成员函数。将当前结构体用作字典类型Key值时,内部使用该函数获得当前结构体的别名。
toBinBuffer 开发者可用 成员函数。将当前结构体序列化成二进制Buffer,返回值类型为require(“@tars/stream”).BinBuffer。
create 开发者可用 成员函数。从数据流中返回一个全新的结构体。

结构体的使用示例

我们演示结构体在三个典型场景的使用方法:

第一种场景: 当结构体用作RPC函数的参数时。

由于rpc框架会自动对参数进行序列化,所以我们无需关心编解码,只需要按照普通的类一样,先new后赋值,然后传入参数直接调用RPC函数即可。

假如服务端有个RPC如下定义:

  1. module TRom
  2. {
  3. struct Param {
  4. 0 optional string sUserName;
  5. 1 optional int iId;
  6. };
  7. interface process {
  8. int getUserLevel(Param userInfo, out int iLevel);
  9. };
  10. };}

安装上述方法生成tars编解码文件(生成文件名称为:Protocol.js)之后,按如下方法调用对端服务:

  1. var Tars = require("@tars/rpc").client;
  2. var TRom = require("./Protocol.js").TRom;
  3. var prx = Tars.stringToProxy(TRom.NodeJsCommProxy, "TRom.NodeJsTestServer.NodeJsCommObj@tcp -h 10.12.22.13 -p 8080 -t 60000");
  4. var usr = new TRom.Param();
  5. usr.sUserName = "KevinTian";
  6. usr.iId = 10000;
  7. prx.getUserLevel(usr).then(function (result) {
  8. console.log("success:", result);
  9. }, function (result) {
  10. console.log("error:", result);
  11. }).done();

第二种场景: 对端非标准rpc框架,接受序列化的数据流作为参数。

在这种场景下需要我们自己对结构体进行序列化。还是以上面的tars文件作为例子,一般的方法如下:

  1. //客户端安装如下方法进行打包,然后将打包后的二进制数据流发送到服务端
  2. var Tars = require("@tars/stream");
  3. var TRom = require("./Protocol.js").TRom;
  4. var usr = new TRom.Param();
  5. usr.sUserName = "KevinTian";
  6. usr.iId = 10000;
  7. var os = new Tars.OutputStream();
  8. os.writeStruct(1, usr);
  9. //打包并得到发送的二进制数据流
  10. var toSendBuffer = os.getBinBuffer().toNodeBuffer();

客户端将toSendBuffer发送给服务端,并且服务端接受完毕之后按如下方法进行解码:

  1. var Tars = require("@tars/stream");
  2. var TRom = require("./Protocol.js").TRom;
  3. var is = new Tars.InputStream(new Tars.BinBuffer(toSendBuffer));
  4. var usr = is.readStruct(1, true, TRom.Param);
  5. console.log("TRom.Param.sUserName:", usr.sUserName);
  6. console.log("TRom.Param.iId:", usr.iId);

第三种场景: 对方服务要求数据流使用Tup协议,并且已经约定好了各个变量的名字。我们可以按如下的方法进行编解码:

  1. //客户端根据约定的名字,将结构体放入Tup中
  2. var Tars = require("@tars/stream");
  3. var TRom = require("./Protocol.js").TRom;
  4. var usr = new TRom.Param();
  5. usr.sUserName = "KevinTian";
  6. usr.iId = 10000;
  7. var tup_encode = new Tars.Tup();
  8. tup_encode.writeStruct("userInfo", usr);
  9. //打包并得到发送的二进制数据流
  10. var toSendBuffer = tup_encode.encode(true).toNodeBuffer();

客户端将toSendBuffer发送给服务端,并且服务端接受完毕之后按如下方法进行解码:

  1. var Tars = require("@tars/stream");
  2. var TRom = require("./Protocol.js").TRom;
  3. var tup_decode = new Tars.Tup();
  4. tup_decode.decode(new Tars.BinBuffer(toSendBuffer));
  5. var usr = tup_decode.readStruct("userInfo", TRom.Param);
  6. console.log("TRom.Param.sUserName:", usr.sUserName);
  7. console.log("TRom.Param.iId:", usr.iId);

06 - 复杂类型 - vector(数组)的使用方法说明

由于Javascript原生的Array不支持tars中的一些特殊化操作,所以我们对它进行了一次封装。开发者可按下述的代码理解:

  1. [stream].List = function(proto)
  2. {
  3. this.proto = proto;
  4. this.value = new Array();
  5. this.push = function (value) { this.value.push(value); }
  6. ......
  7. }

[stream].List 对象属性

属性 描述
value Js中的Array数据类型。Tars.List实际是基于该Array进行的上层封装。
length 返回数组中元素的数目。

[stream].List 对象方法

方法 描述
at 返回数组中指定位置的元素。
push 向数组的末尾添加一个元素。
forEach 当前数组的遍历方法,具体使用方法请参考后面的示例。
toObject 将List实例转化成基本的数据对象,具体使用方法请参考后面的示例。
readFromObject 将传入的数组处理后push到List实例中,具体使用方法请参考后面的示例。

proto是Vector的类型原型(类型原型决定了在对Vector编解码时采用的方法,所以声明Vector的时候必须传入正确的类型原型)。

[stream].List的声明示例

  1. var Tars = require("@tars/stream");
  2. //例子1:声明vector<int32>
  3. var va = new Tars.List(Tars.Int32);
  4. //例子2:声明vector<string>
  5. var vb = new Tars.List(Tars.String);
  6. //例子3:声明vector<map<uint32, string> >
  7. var vc = new Tars.List(Tars.Map(Tars.UInt32, Tars.String));
  8. //例子4:声明vector<struct>,假设结构体名称为TRom.Param
  9. var vd = new Tars.Vector(TRom.Param);

[stream].List的操作示例

  1. var Tars = require("@tars/stream");
  2. var ve = new Tars.List(Tars.String);
  3. //向数组中添加元素
  4. ve.push("TENCENT-MIG");
  5. ve.push("TENCENT-SNG");
  6. ve.push("TENCENT-IEG");
  7. ve.push("TENCENT-TEG");
  8. //获取数组的长度
  9. console.log("Length:", ve.length);
  10. //获取指定位置的元素
  11. console.log("Array[1]:", ve.at(1));
  12. //遍历方法1:
  13. ve.forEach(function (value, index, oArray) {
  14. console.log("Array[" + index + "]:", value);
  15. });
  16. // 遍历方法2:
  17. for (var index = 0, len = ve.length; index < len; index++) {
  18. console.log("Array[" + index + "]:", ve.at(index));
  19. }
  20. // toObject方法和readFromObject方法的详细例子可以参照sample/list路径下的test-list-c3.js文件
  21. var user1 = new TRom.User_t();
  22. user1.id = 1;
  23. user1.name = 'x1';
  24. user1.score = 1;
  25. var user2 = new TRom.User_t();
  26. user2.id = 2;
  27. user2.name = 'x2';
  28. user2.score = 2;
  29. var user3 = new TRom.User_t();
  30. user3.id = 3;
  31. user3.name = 'x3';
  32. user3.score = 3;
  33. var userList1 = new Tars.List(TRom.User_t);
  34. console.log('user1: ', user1);
  35. console.log('user2: ', user2);
  36. userList1.push(user1);
  37. userList1.push(user2);
  38. //toObject方法
  39. console.log('userList1: ', userList1.toObject());
  40. var userList2 = new Tars.List(TRom.User_t);
  41. //readFromObject方法
  42. userList2.readFromObject([user1, user2, user3]);
  43. console.log('userList2: ', userList2.toObject());

07 - 复杂类型 - map(字典)的使用方法说明

由于Javascript原生的Object不支持tars中的一些特殊化操作,所以我们对它进行了一次封装。开发者可按下述的代码理解:

  1. [stream].Map = function(kproto, vproto) {
  2. var Map = function() {
  3. this._kproto = kproto;
  4. this._vproto = vproto;
  5. this.value = new Object();
  6. this.put = function(key, value) { this.insert(key, value); }
  7. ......
  8. }
  9. return new Map();
  10. }

[stream].Map 对象属性

属性 描述
value Js中的Object数据类型。[stream].Map实际是基于该Object进行的上层封装。

[stream].Map 方法属性

方法 描述
insert 向字典中添加一个元素。
set 同insert。
put 同insert。
remove 根据指定的key,从字典中删除对应的数值。
clear 清空当前字典。
has 根据指定的key,判断字典中是否包含对应的数值。
size 返回当前字典中元素的数目。
forEach 当前数组的遍历方法,具体使用方法请参考后面的示例。
toObject 将Map实例转化成基本的数据对象,具体使用方法请参考后面的示例。
readFromObject 将传入的对象处理后insert到Map实例中,具体使用方法请参考后面的示例。

[stream].Map的声明示例

  1. var Tars = require("@tars/stream");
  2. //例子1:声明map<int32, int32>
  3. var ma = new Tars.Map(Tars.Int32, Tars.Int32);
  4. //例子2:声明map<uint32, string>
  5. var mb = new Tars.Map(Tars.Int32, Tars.String);
  6. //例子3:声明map<string, string>的方法
  7. var mc = new Tars.Map(Tars.String, Tars.String);
  8. //例子4:声明map<string, vector<int32> >
  9. var md = new Tars.Map(Tars.String, Tars.List(Tars.Int32));
  10. //例子5:声明map<string, map<int32, vector<string> > >
  11. var me = new Tars.Map(Tars.String, Tars.Map(Tars.Int32, Tars.List(Tars.String)));
  12. //例子6:声明map<string, struct>的方法,假设结构体名称为TRom.Param
  13. var mf = new Tars.map(Tars.String, TRom.Param);

[stream].Map的操作示例

  1. var Tars = require("@tars/stream");
  2. var mc = new Tars.Map(Tars.String, Tars.String);
  3. //向字典中添加元素
  4. mc.insert("KEY-00", "TENCENT-MIG");
  5. mc.insert("KEY-01", "TENCENT-IEG");
  6. mc.insert("KEY-02", "TENCENT-TEG");
  7. mc.insert("KEY-03", "TENCENT-SNG");
  8. //获取字典元素大小
  9. console.log("SIZE:", mc.size());
  10. //判断字典中是否有指定的值
  11. console.log("Has:", mc.has("KEY-04"));
  12. //字典遍历
  13. mc.forEach(function (key, value) {
  14. console.log("KEY:", key);
  15. console.log("VALUE:", value);
  16. });
  17. // toObject方法和readFromObject方法的详细例子可以参照sample/map路径下的test-map-c5.js文件
  18. var user1 = new TRom.User_t();
  19. user1.id = 1;
  20. user1.name = 'x1';
  21. user1.score = 1;
  22. var user2 = new TRom.User_t();
  23. user2.id = 2;
  24. user2.name = 'x2';
  25. user2.score = 2;
  26. var user3 = new TRom.User_t();
  27. user3.id = 3;
  28. user3.name = 'x3';
  29. user3.score = 3;
  30. var userMap1 = new Tars.Map(Tars.String, TRom.User_t);
  31. userMap1.insert('user1', user1);
  32. userMap1.insert('user2', user2);
  33. //toObject方法
  34. console.log('userMap1: ', userMap1.toObject());
  35. var userMap2 = new Tars.Map(Tars.String, TRom.User_t);
  36. //readFromObject方法
  37. userMap2.readFromObject({
  38. 'user1': user1,
  39. 'user2': user2,
  40. 'user3': user3
  41. });
  42. console.log('userMap2: ', userMap2.toObject());

支持MultiMap类型

支持MultiMap类型,此类型允许以一个结构体作为Map的key。javascript原生对象没有办法表示此数据类型,因此此类型没有实现普通Map支持的toObject和readFromObject方法。

其操作实例如下:

  1. //构造Map类型
  2. var msg = new Tars.Map(Test.StatMicMsgHead, Test.StatMicMsgBody);
  3. msg.put(StatMicMsgHead1, StatMicMsgBody1);
  4. msg.put(StatMicMsgHead2, StatMicMsgBody2);
  5. //tars编码
  6. var os = new Tars.OutputStream();
  7. os.writeMap(1, msg);
  8. //tars解码
  9. var data = os.getBinBuffer().toNodeBuffer();
  10. var is = new Tars.InputStream(new Tars.BinBuffer(data));
  11. var ta = is.readMap(1, true, Tars.Map(Test.StatMicMsgHead, Test.StatMicMsgBody));
  12. //遍历Map结果集
  13. ta.forEach(function (key, value){
  14. console.log("KEY:", key.masterName, "VALUE.totalRspTime", value.totalRspTime);
  15. });
  16. //根据值去获取
  17. var tb = ta.get(StatMicMsgHead2);
  18. if (tb == undefined) {
  19. console.log("not found by name : StatMicMsgHead2");
  20. } else {
  21. console.log(tb.totalRspTime);
  22. }

08 - 复杂类型 - 二进制Buffer的使用方法说明

在浏览器中我们可以使用“DataView”和“ArrayBuffer”来存储和操作二进制数据。NodeJS为了提升性能,自身提供了一个Buffer类。为了方便Tars的编解码,我们对Buffer类进行了一层封装。开发者可按下述的代码理解:

  1. [stream].BinBuffer = function (buffer) {
  2. this._buffer = (buffer != undefined && buffer instanceof Buffer)?buffer:null;
  3. this._length = (buffer != undefined && buffer instanceof Buffer)?buffer.length:0;
  4. this._capacity = this._length;
  5. this._position = 0;
  6. }

[stream].BinBuffer 对象属性

属性 描述
length 获取该二进制Buffer的数据长度
capacity 获取该二进制Buffer在不重新分配内存的情况下,可容纳数据的最大长度
position 获取或者设置当前二进制Buffer的访问指针

length和capacity的区别:

假如我们向BinBuffer中写入一个Int32类型的数据。写成功之后,length和capacity的区别:

由于BinBuffer类在第一次分配时使用默认的512长度来申请内存,此时 capacity 的值为 512

length表示当前Buffer中存在真实数据的大小,此时 length 的值为 4

[stream].BinBuffer 方法属性

toNodeBuffer

函数定义;[stream].BinBuffer.toNodeBuffer()

函数作用:返回当前二进制Buffer的数据,该值为深拷贝的类型为NodeJS.Buffer的数据

输入参数:无

返回数据:NodeJS.Buffer类型

print

函数定义:[stream].BinBuffer.print()

函数作用:以每行16个字节,并16进制的方式打印当前的Buffer

writeNodeBuffer

函数定义:[stream].BinBuffer.writeNodeBuffer(srcBuffer, offset, byteLength)

函数作用:向二进制Buffer中写入NodeJS.Buffer类数据

输入参数:

参数 数据类型 描述
srcBuffer NodeJS.Buffer 原始的Buffer数据
offset UInt32 表示拷贝srcBuffer的起始位置
byteLength UInt32 表示从offset开始,从srcBuffer中拷贝的数据量

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + byteLength

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + byteLength

writeBinBuffer

函数定义:[stream].BinBuffer.writeBinBuffer(value)

函数作用:向二进制Buffer中写入[stream].BinBuffer类数据

输入参数:

参数 数据类型 描述
value [stream].BinBuffer 表示二进制Buffer

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + value.length

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + value.length

writeInt8

函数定义:[stream].BinBuffer.writeInt8(value)

函数作用:向二进制Buffer中写入Int8类数据

输入参数:

参数 数据类型 描述
value Int8 8位的整型数据

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 1

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 1

writeInt16

函数定义:[stream].BinBuffer.writeInt16(value)

函数作用:向二进制Buffer中写入Int16类数据

输入参数:

参数 数据类型 描述
value Int16 16位的整型数据

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 2

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 2

[3]数据存储采用网络字节序

writeInt32

函数定义:[stream].BinBuffer.writeInt32(value)

函数作用:向二进制Buffer中写入Int32类数据

输入参数:

参数 数据类型 描述
value Int32 32位的整型数据

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 4

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 4

[3]数据存储采用网络字节序

writeInt64

函数定义:[stream].BinBuffer.writeInt64(value)

函数作用:向二进制Buffer中写入Int64类数据

输入参数:

参数 数据类型 描述
value Int64 64位的整型数据

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 8

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 8

[3]数据存储采用网络字节序

writeUInt8

函数定义:[stream].BinBuffer.writeUInt8(value)

函数作用:向二进制Buffer中写入UInt8类数据

输入参数:

参数 数据类型 描述
value UInt8 8位的整型数据

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 1

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 1

writeUInt16

函数定义:[stream].BinBuffer.writeUInt16(value)

函数作用:向二进制Buffer中写入UInt16类数据

输入参数:

参数 数据类型 描述
value UInt16 16位的整型数据

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 2

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 2

[3]数据存储采用网络字节序

writeUInt32

函数定义:[stream].BinBuffer.writeUInt32(value)

函数作用:向二进制Buffer中写入UInt32类数据

输入参数:

参数 数据类型 描述
value UInt32 32位的整型数据

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 4

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 4

[3]数据存储采用网络字节序

writeFloat

函数定义:[stream].BinBuffer.writeFloat(value)

函数作用:向二进制Buffer中写入Float(32位,单精度浮点数)类数据

输入参数:

参数 数据类型 描述
value Float 32位的单精度浮点数

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 4

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 4

[3]数据存储采用网络字节序

writeDouble

函数定义:[stream].BinBuffer.writeDouble(value)

函数作用:向二进制Buffer中写入Double(64位,双精度浮点数)类数据

输入参数:

参数 数据类型 描述
value Double 64位的双精度浮点数

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 8

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 8

[3]数据存储采用网络字节序

writeString

函数定义:[stream].BinBuffer.writeString(value)

函数作用:向二进制Buffer中写入String(UTF8编码)类数据

输入参数:

参数 数据类型 描述
value String UTF8编码的字符串

函数说明:

[1]当前BinBuffer的 length = length(原Buffer数据长度) + 字符串的字节长度

[2]当前BinBuffer的 position = position(原Buffer的位置指针) + 字符串的字节长度

readInt8

函数定义:[stream].BinBuffer.readInt8()

函数作用:从二进制Buffer中,根据当前数据指针读取一个Int8类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 1

readInt16

函数定义:[stream].BinBuffer.readInt16()

函数作用:从二进制Buffer中,根据当前数据指针读取一个Int16类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 2

readInt32

函数定义:[stream].BinBuffer.readInt32()

函数作用:从二进制Buffer中,根据当前数据指针读取一个Int32类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 4

readInt64

函数定义:[stream].BinBuffer.readInt64()

函数作用:从二进制Buffer中,根据当前数据指针读取一个Int64类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 8

readUInt8

函数定义:[stream].BinBuffer.readUInt8()

函数作用:从二进制Buffer中,根据当前数据指针读取一个UInt8类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 1

readUInt16

函数定义:[stream].BinBuffer.readUInt16()

函数作用:从二进制Buffer中,根据当前数据指针读取一个UInt16类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 2

readUInt32

函数定义:[stream].BinBuffer.readUInt32()

函数作用:从二进制Buffer中,根据当前数据指针读取一个UInt32类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 4

readFloat

函数定义:[stream].BinBuffer.readFloat()

函数作用:从二进制Buffer中,根据当前数据指针读取一个Float(32位的单精度浮点数)类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 4

readDouble

函数定义:[stream].BinBuffer.readDouble()

函数作用:从二进制Buffer中,根据当前数据指针读取一个Double(64位的双精度浮点数)类型的变量

输入参数:无

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 8

readString

函数定义:[stream].BinBuffer.readString(byteLength)

函数作用:从二进制Buffer中,根据当前数据指针读取一个String(UTF8编码)类型的变量

输入参数:

参数 数据类型 描述
byteLength UInt32 字符串的字节长度

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 字符串的字节长度

[2]后台对字符串的编码需要使用UTF8字符集

readBinBuffer

函数定义:[stream].BinBuffer.readBinBuffer(byteLength)

函数作用:从二进制Buffer中,根据当前数据指针读取一个[stream].BinBuffer类型的变量

输入参数:

参数 数据类型 描述
byteLength UInt32 二进制Buffer的字节长度

函数说明:

[1]当前BinBuffer的 position = position(原Buffer的位置指针) + 二进制Buffer的字节长度

09 - 编码工具 - OutputStream的使用方法说明

构造函数

函数定义:[stream].OutputStram()

函数作用:声明一个输出流对象

输入参数:无

使用示例:var os = new [stream].OutputStream()

getBinBuffer

函数定义:var buffer = [stream].OutputStream.getBinBuffer()

函数作用:调用该函数获得打包后的二进制数据流

输入参数:无

返回数据:返回打包后的二进制数据流,该返回值类型为[stream].BinBuffer

writeBoolean

函数定义:[stream].OutputStream.writeBoolean(tag, value)

函数作用:向数据流中写一个Boolean类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value Boolean 表示该变量的值,取值范围{false, true}

返回数据:void

writeInt8

函数定义:[stream].OutputStream.writeInt8(tag, value)

函数作用:向数据流中写一个int8类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value int8(Number) 表示该变量的值,取值范围[-128, 127]

返回数据:void

writeInt16

函数定义:[stream].OutputStream.writeInt16(tag, value)

函数作用:向数据流中写一个Int16类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value int16(Number) 表示该变量的值,取值范围[-32768, 32767]

返回数据:void

writeInt32

函数定义:[stream].OutputStream.writeInt32(tag, value)

函数作用:向数据流中写一个Int32类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value int32(Number) 表示该变量的值,取值范围[-2147483648, 2147483647]

返回数据:void

writeInt64

函数定义:[stream].OutputStream.writeInt64(tag, value)

函数作用:向数据流中写一个Int64类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value int64(Number) 表示该变量的值,取值范围[-9223372036854775808, 9223372036854775807]

返回数据:void

writeUInt8

函数定义:[stream].OutputStream.writeUInt8(tag, value)

函数作用:向数据流中写一个UInt8类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value UInt8(Number) 表示该变量的值,取值范围[0, 255]

返回数据:void

writeUInt16

函数定义:[stream].OutputStream.writeUInt16(tag, value)

函数作用:向数据流中写一个UInt16类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value UInt16(Number) 表示该变量的值,取值范围[0, 65535]

返回数据:void

writeUInt32

函数定义:[stream].OutputStream.writeUInt32(tag, value)

函数作用:向数据流中写一个UInt32类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value UInt32(Number) 表示该变量的值,取值范围[0, 4294967295]

返回数据:void

writeFloat

函数定义:[stream].OutputStream.writeFloat(tag, value)

函数作用:向数据流中写一个float(32位)类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value Float(Number) 单精度浮点数,因为有精度损失问题,不推荐使用该类型

返回数据:void

writeDouble

函数定义:[stream].OutputStream.writeDouble(tag, value)

函数作用:向数据流中写一个double(64位)类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value Double(Number) 双精度浮点数,因为有精度损失问题,不推荐使用该类型

返回数据:void

writeString

函数定义:[stream].OutputStream.writeString(tag, value)

函数作用:向数据流中写一个String类型的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value String 表示该变量的值,字符串编码字符集为UTF8

返回数据:void

writeStruct

函数定义:writeStruct(tag, value)

函数作用:向数据流中写一个自定义结构体的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value 自定义结构体 结构体必须是使用tars2node转换而成的,否则可能会因缺少辅助函数而导致编解码失败

返回数据:void

writeBytes

函数定义:[stream].OutputStream.writeBytes(tag, value)

函数作用:向数据流中写一个类型为 char * 或者 vector<char> 的变量

输入参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value [stream].BinBuffer BinBuffer是对NodeJs中的Buffer类的封装,同时集成了编解码需要用到的辅助函数

返回数据:void

writeList

函数定义:[stream].OutputStream.writeList(tag, value)

函数作用:向数据流中写一个类型为 vector<T>(T不可为byte)的变量

函数参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value [stream].List(T) 该变量的类型原型

返回数据:void

writeMap

函数定义:[stream].OutputStream.writeMap(tag, value)

函数作用:向数据流中写一个类型为 map<T, V> 类型的字段。

函数参数:

参数 数据类型 描述
tag UInt8 表示该变量的数字标识,取值范围[0, 255]
value [stream].Map(T, V) 该变量的类型原型

返回数据:void

10 - 解码工具 - InputStream的使用方法说明

构造函数

函数定义:[stream].InputStream(binBuffer)

函数作用:声明一个输入流对象

输入参数:

binBuffer 欲解码的二进制数据流,该值类型必须为[stream].BinBuffer,而不能是NodeJs中实现的Buffer类。

使用示例:var is = new [stream].InputStream(new [stream].BinBuffer(Node.Buffer))

readBoolean

函数定义:var value = [stream].InputStream.readBoolean(tag, require, default)

函数作用:从数据流读取一个Boolean类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default Boolean 表示读取变量不成功时的返回值,取值范围{false, true}

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:Boolean,取值范围{false, true}

readInt8

函数定义:[stream].InputStream.readInt8(tag, require, default)

函数作用:从数据流读取一个Int8类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default Int8 表示读取变量不成功时的返回值,取值范围[-128, 127]

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:Int8,取值范围[-128, 127]

readInt16

函数定义:[stream].InputStream.readInt16(tag, require, default)

函数作用:从数据流读取一个Int16类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default Int16 表示读取变量不成功时的返回值,取值范围[-32768, 32767]

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:Int16,取值范围[-32768, 32767]

readInt32

函数定义:[stream].InputStream.readInt32(tag, require, default)

函数作用:从数据流读取一个Int32类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default Int32 表示读取变量不成功时的返回值,取值范围[-2147483648, 2147483647]

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:Int32,取值范围[-2147483648, 2147483647]

readInt64

函数定义:[stream].InputStream.readInt64(tag, require, default)

函数作用:从数据流读取一个Int64类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default Int64 表示读取变量不成功时的返回值,取值范围[-9223372036854775808, 9223372036854775807]

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:Int64(Number),取值范围[-9223372036854775808, 9223372036854775807]

readUInt8

函数定义:[stream].InputStream.readUInt8(tag, require, default)

函数作用:从数据流读取一个UInt8类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default UInt8 表示读取变量不成功时的返回值,取值范围[0, 255]

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:UInt8(Number),取值范围[0, 255]

readUInt16

函数定义:[stream].InputStream.readUInt16(tag, require, default)

函数作用:从数据流读取一个UInt16类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default UInt8 表示读取变量不成功时的返回值,取值范围[0, 65535]

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:UInt16(Number),取值范围[0, 65535]

readUInt32

函数定义:[stream].InputStream.readUInt32(tag, require, default)

函数作用:从数据流读取一个UInt32类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default UInt8 表示读取变量不成功时的返回值,取值范围[0, 4294967295]

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:UInt32(Number),取值范围[0, 4294967295]

readFloat

函数定义:[stream].InputStream.readFloat(tag, require, default)

函数作用:从数据流读取一个Float(32位,单精度浮点数)类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default Float 表示读取变量不成功时的返回值

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:Float(Number)

readDouble

函数定义:[stream].InputStream.readFloat(tag, require, default)

函数作用:从数据流读取一个Double(64位,双精度浮点数)类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default Double 表示读取变量不成功时的返回值

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:Double(Number)

readString

函数定义:[stream].InputStream.readString(tag, require, default)

函数作用:从数据流读取一个String(UTF8编码)类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
default String 表示读取变量不成功时的返回值

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回变量的默认值default;

返回数据:String(UTF8编码)

readStruct

函数定义:[stream].InputStream.readStruct(tag, require, TYPE_T)

函数作用:从数据流读取一个自定义结构体类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
TYPE_T 自定义结构体的类型原型 表示该变量的类型原型

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回一个空的结构体的实例;

返回数据:自定义结构体的实例

readBytes

函数定义:[stream].InputStream.readBytes(tag, require, TYPE_T)

函数作用:从数据流读取一个 [stream].BinBuffer 类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
TYPE_T [stream].BinBuffer 表示该变量的类型原型

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回一个空的[stream].BinBuffer的实例;

返回数据:[stream].BinBuffer

readList

函数定义:[stream].InputStream.readList(tag, require, TYPE_T)

函数作用:从数据流读取一个 [stream].List<T> 类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
TYPE_T [stream].List 表示该变量的类型原型

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回一个空的[stream].List(T)的实例;

返回数据:[stream].List(T)

readMap

函数定义:[stream].InputStream.readMap(tag, require, TYPE_T)

函数作用:从数据流读取一个 [stream].Map<T, V> 类型的数值

输入参数:

参数 数据类型 描述
tag UInt8 表示欲读取变量的数字标识,取值范围[0, 255]
require Boolean 表示当前变量是否为必须值,取值范围{false, true}
TYPE_T [stream].Map(T, V) 表示该变量的类型原型

对require的说明:

require === true 时, 如果当前变量不在数据流中,系统将抛出一个读取数据不存在的异常;

require === false 时,如果当前变量不在数据流中,系统将返回一个空的[stream].Map(T, V)的实例;

返回数据:[stream].Map(T, V)