node usersig 翻译

wesleytong · wesleytong · commit c57dc9f43ee7 · 2022-03-07T15:49:58.000+08:00
diff --git a/README_EN.md b/README_EN.md
@@ -0,0 +1,17 @@
+## npm integration
+```shell 
+npm i tls-sig-api-v2
+```
+
+## source code integration
+Just place the file `TLSSigAPIv2.js` in the desired path.
+
+## interface call
+```javascript
+var TLSSigAPIv2 = require('tls-sig-api-v2');
+// var TLSSigAPIv2 = require('./TLSSigAPIv2'); // 源码集成需要使用相对路径
+
+var api = new TLSSigAPIv2.Api(1400000000, "5bd2850fff3ecb11d7c805251c51ee463a25727bddc2385f3fa8bfee1bb93b5e");
+var sig = api.genSig("xiaojun", 86400*180);
+console.log(sig);
+```
diff --git a/TLSSigAPIv2.js b/TLSSigAPIv2.js
@@ -71,6 +71,20 @@ Api.prototype._hmacsha256 = function (identifier, currTime, expire, base64UserBu
  * @param roomstr 字符串房间号
  * @return userbuf  {string}  返回的userbuf
  */
+
+/**
+ * User-defined userbuf is used for the encrypted string of TRTC service entry permission
+ * @brief generate userbuf
+ * @param account username
+ * @param dwSdkappid sdkappid
+ * @param dwAuthID  digital room number
+ * @param dwExpTime Expiration time: The expiration time of the encrypted string of this permission. Expiration time = now+dwExpTime
+ * @param dwPrivilegeMap User permissions, 255 means all permissions
+ * @param dwAccountType User type, default is 0
+ * @param roomStr String room number
+ * @return userbuf string  returned userbuf
+ */
+
 Api.prototype._genUserbuf = function (account, dwAuthID, dwExpTime,
     dwPrivilegeMap, dwAccountType, roomstr) {
 
@@ -175,6 +189,14 @@ Api.prototype.genSig = function (userid, expire, userBuf) {
  * @param userid - 用户id，限制长度为32字节，只允许包含大小写英文字母（a-zA-Z）、数字（0-9）及下划线和连词符。
  * @param expire - UserSig 票据的过期时间，单位是秒，比如 86400 代表生成的 UserSig 票据在一天后就无法再使用了。
  */
+
+/**
+ * Function: Used to issue UserSig that is required by the TRTC and IM services.
+ *
+ * Parameter description:
+ * @param userid - User ID. The value can be up to 32 bytes in length and contain letters (a-z and A-Z), digits (0-9), underscores (_), and hyphens (-).
+ * @param expire - UserSig expiration time, in seconds. For example, 86400 indicates that the generated UserSig will expire one day after being generated.
+*/
 Api.prototype.genUserSig = function (userid, expire) {
     return this.genSig(userid, expire, null);
 };
@@ -203,6 +225,32 @@ Api.prototype.genUserSig = function (userid, expire) {
  *  - privilegeMap == 1111 1111 == 255 代表该 userid 在该 roomid 房间内的所有功能权限。
  *  - privilegeMap == 0010 1010 == 42  代表该 userid 拥有加入房间和接收音视频数据的权限，但不具备其他权限。
  */
+
+/**
+ * Function:
+ * Used to issue PrivateMapKey that is optional for room entry.
+ * PrivateMapKey must be used together with UserSig but with more powerful permission control capabilities.
+ *  - UserSig can only control whether a UserID has permission to use the TRTC service. As long as the UserSig is correct, the user with the corresponding UserID can enter or leave any room.
+ *  - PrivateMapKey specifies more stringent permissions for a UserID, including whether the UserID can be used to enter a specific room and perform audio/video upstreaming in the room.
+ * To enable stringent PrivateMapKey permission bit verification, you need to enable permission key in TRTC console > Application Management > Application Info.
+ *
+ * Parameter description:
+ * userid - User ID. The value can be up to 32 bytes in length and contain letters (a-z and A-Z), digits (0-9), underscores (_), and hyphens (-).
+ * roomid - ID of the room to which the specified UserID can enter.
+ * expire - PrivateMapKey expiration time, in seconds. For example, 86400 indicates that the generated PrivateMapKey will expire one day after being generated.
+ * privilegeMap - Permission bits. Eight bits in the same byte are used as the permission switches of eight specific features:
+ *  - Bit 1: 0000 0001 = 1, permission for room creation
+ *  - Bit 2: 0000 0010 = 2, permission for room entry
+ *  - Bit 3: 0000 0100 = 4, permission for audio sending
+ *  - Bit 4: 0000 1000 = 8, permission for audio receiving
+ *  - Bit 5: 0001 0000 = 16, permission for video sending
+ *  - Bit 6: 0010 0000 = 32, permission for video receiving
+ *  - Bit 7: 0100 0000 = 64, permission for substream video sending (screen sharing)
+ *  - Bit 8: 1000 0000 = 200, permission for substream video receiving (screen sharing)
+ *  - privilegeMap == 1111 1111 == 255: Indicates that the UserID has all feature permissions of the room specified by roomid.
+ *  - privilegeMap == 0010 1010 == 42: Indicates that the UserID has only the permissions to enter the room and receive audio/video data.
+ */
+
 Api.prototype.genPrivateMapKey = function (userid, expire, roomid, privilegeMap) {
     var userBuf = this._genUserbuf(userid, roomid, expire, privilegeMap, 0, null);
     return this.genSig(userid, expire, userBuf);
@@ -232,6 +280,31 @@ Api.prototype.genPrivateMapKey = function (userid, expire, roomid, privilegeMap)
  *  - privilegeMap == 1111 1111 == 255 代表该 userid 在该房间内的所有功能权限。
  *  - privilegeMap == 0010 1010 == 42  代表该 userid 拥有加入房间和接收音视频数据的权限，但不具备其他权限。
  */
+
+/**
+ * Function:
+ * Used to issue PrivateMapKey that is optional for room entry.
+ * PrivateMapKey must be used together with UserSig but with more powerful permission control capabilities.
+ *  - UserSig can only control whether a UserID has permission to use the TRTC service. As long as the UserSig is correct, the user with the corresponding UserID can enter or leave any room.
+ *  - PrivateMapKey specifies more stringent permissions for a UserID, including whether the UserID can be used to enter a specific room and perform audio/video upstreaming in the room.
+ * To enable stringent PrivateMapKey permission bit verification, you need to enable permission key in TRTC console > Application Management > Application Info.
+ *
+ * Parameter description:
+ * @param userid - User ID. The value can be up to 32 bytes in length and contain letters (a-z and A-Z), digits (0-9), underscores (_), and hyphens (-).
+ * @param roomstr - ID of the room to which the specified UserID can enter.
+ * @param expire - PrivateMapKey expiration time, in seconds. For example, 86400 indicates that the generated PrivateMapKey will expire one day after being generated.
+ * @param privilegeMap - Permission bits. Eight bits in the same byte are used as the permission switches of eight specific features:
+ *  - Bit 1: 0000 0001 = 1, permission for room creation
+ *  - Bit 2: 0000 0010 = 2, permission for room entry
+ *  - Bit 3: 0000 0100 = 4, permission for audio sending
+ *  - Bit 4: 0000 1000 = 8, permission for audio receiving
+ *  - Bit 5: 0001 0000 = 16, permission for video sending
+ *  - Bit 6: 0010 0000 = 32, permission for video receiving
+ *  - Bit 7: 0100 0000 = 64, permission for substream video sending (screen sharing)
+ *  - Bit 8: 1000 0000 = 200, permission for substream video receiving (screen sharing)
+ *  - privilegeMap == 1111 1111 == 255: Indicates that the UserID has all feature permissions of the room specified by roomid.
+ *  - privilegeMap == 0010 1010 == 42: Indicates that the UserID has only the permissions to enter the room and receive audio/video data.
+ */
 Api.prototype.genPrivateMapKeyWithStringRoomID = function (userid, expire, roomstr, privilegeMap) {
     var userBuf = this._genUserbuf(userid, 0, expire, privilegeMap, 0, roomstr);
     return this.genSig(userid, expire, userBuf);
