Merge pull request #16 from Tomxiaobai/master

java sdk update

Author: weijunyi

README_EN.md

@@ -0,0 +1,33 @@
+## Note
+This project is the java implementation of tls-sig-api-v2. Previous asymmetric keys cannot use APIs of this version. To enable them to use APIs of this version,[see here](https://github.com/tencentyun/tls-sig-api-java).
+## Integration
+### maven
+``` xml
+<dependencies>
+    <dependency>
+        <groupId>com.github.tencentyun</groupId>
+        <artifactId>tls-sig-api-v2</artifactId>
+        <version>2.0</version>
+    </dependency>
+</dependencies>
+```
+
+### gradle
+```
+dependencies {
+    compile 'com.github.tencentyun:tls-sig-api-v2:2.0'
+}
+```
+
+### source code
+``` shell
+./gradlew -b user_build.gradle build
+```
+The generated jar can be found under `build/libs`. You can download it by yourself by relying on org.json.
+## use
+``` java
+import com.tencentyun.TLSSigAPIv2;
+
+TLSSigAPIv2 api = new TLSSigAPIv2(1400000000, "5bd2850fff3ecb11d7c805251c51ee463a25727bddc2385f3fa8bfee1bb93b5e");
+System.out.print(api.genSig("xiaojun", 180*86400));
+```

src/main/java/com/tencentyun/TLSSigAPIv2.java

@@ -30,6 +30,16 @@ public TLSSigAPIv2(long sdkappid, String key) {
      * @param expire - UserSig 票据的过期时间，单位是秒，比如 86400 代表生成的 UserSig 票据在一天后就无法再使用了。
      * @return usersig -生成的签名
      */
+
+    /**
+     * Function: Used to issue UserSig that is required by the TRTC and IM services.
+     * <p>
+     * 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.
+     * @return usersig - Generated signature.
+     */ 
     public String genUserSig(String userid, long expire) {
         return genUserSig(userid, expire, null);
     }
@@ -60,6 +70,33 @@ public String genUserSig(String userid, long expire) {
      *                     - privilegeMap == 0010 1010 == 42  代表该 userid 拥有加入房间和接收音视频数据的权限，但不具备其他权限。
      * @return usersig - 生成带userbuf的签名
      */
+
+    /**
+     * 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 roomid - 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.
+     * @return usersig - Generate signature with userbuf
+     */
     public String genPrivateMapKey(String userid, long expire, long roomid, long privilegeMap) {
         byte[] userbuf = genUserBuf(userid, roomid, expire, privilegeMap, 0, "");  //生成userbuf
         return genUserSig(userid, expire, userbuf);
@@ -91,6 +128,34 @@ public String genPrivateMapKey(String userid, long expire, long roomid, long pri
      *                     - privilegeMap == 0010 1010 == 42  代表该 userid 拥有加入房间和接收音视频数据的权限，但不具备其他权限。
      * @return usersig - 生成带userbuf的签名
      */
+
+    /**
+     * 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 roomid - 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.
+     * @return usersig - Generate signature with userbuf
+     */
     public String genPrivateMapKeyWithStringRoomID(String userid, long expire, String roomstr, long privilegeMap) {
         byte[] userbuf = genUserBuf(userid, 0, expire, privilegeMap, 0, roomstr);  //生成userbuf
         return genUserSig(userid, expire, userbuf);
@@ -160,6 +225,18 @@ public byte[] genUserBuf(String account, long dwAuthID, long dwExpTime,
          dwPrivilegeMap  unsigned int/4  权限位，主播0xff，观众0xab
          dwAccountType   unsigned int/4  第三方帐号类型
          */
+
+         //The fields required for the video check digit are placed in buf according to the network byte order.
+        /*
+         cVer    unsigned char/1 Version number, fill in 0
+         wAccountLen unsigned short /2   Third party's own account length
+         account wAccountLen Third party's own account characters
+         dwSdkAppid  unsigned int/4  sdkappid
+         dwAuthID    unsigned int/4  group number
+         dwExpTime   unsigned int/4  Expiration time , use the filled value directly
+         dwPrivilegeMap  unsigned int/4  Permission bits, host 0xff, audience 0xab
+         dwAccountType   unsigned int/4  Third-party account type
+        */
         int accountLength = account.length();
         int roomStrLength = RoomStr.length();
         int offset = 0;
@@ -192,12 +269,14 @@ public byte[] genUserBuf(String account, long dwAuthID, long dwExpTime,
         userbuf[offset++] = (byte) (sdkappid & 0x000000FF);
 
         //dwAuthId,房间号
+        //dwAuthId, room number
         userbuf[offset++] = (byte) ((dwAuthID & 0xFF000000) >> 24);
         userbuf[offset++] = (byte) ((dwAuthID & 0x00FF0000) >> 16);
         userbuf[offset++] = (byte) ((dwAuthID & 0x0000FF00) >> 8);
         userbuf[offset++] = (byte) (dwAuthID & 0x000000FF);
 
         //expire，过期时间,当前时间 + 有效期（单位：秒）
+        //expire,Expiration time, current time + validity period (unit: seconds)
         long currTime = System.currentTimeMillis() / 1000;
         long expire = currTime + dwExpTime;
         userbuf[offset++] = (byte) ((expire & 0xFF000000) >> 24);
@@ -206,12 +285,14 @@ public byte[] genUserBuf(String account, long dwAuthID, long dwExpTime,
         userbuf[offset++] = (byte) (expire & 0x000000FF);
 
         //dwPrivilegeMap，权限位
+        //dwPrivilegeMap，Permission bits
         userbuf[offset++] = (byte) ((dwPrivilegeMap & 0xFF000000) >> 24);
         userbuf[offset++] = (byte) ((dwPrivilegeMap & 0x00FF0000) >> 16);
         userbuf[offset++] = (byte) ((dwPrivilegeMap & 0x0000FF00) >> 8);
         userbuf[offset++] = (byte) (dwPrivilegeMap & 0x000000FF);
 
         //dwAccountType，账户类型
+        //dwAccountType，account type
         userbuf[offset++] = (byte) ((dwAccountType & 0xFF000000) >> 24);
         userbuf[offset++] = (byte) ((dwAccountType & 0x00FF0000) >> 16);
         userbuf[offset++] = (byte) ((dwAccountType & 0x0000FF00) >> 8);