Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
en:user_management_api [2018/07/05 10:50]
michael [User Management API]
en:user_management_api [2023/02/03 09:36] (current)
Line 6: Line 6:
  
   * [[BS2_GetUserList]]:​ Gets the enrolled user ID list.   * [[BS2_GetUserList]]:​ Gets the enrolled user ID list.
-  * [[BS2_GetUserInfos]]:​ Gets the user information of the given user ID. 
-  * [[BS2_EnrolUser]]:​ Enrolls new user. 
   * [[BS2_RemoveUser]]:​ Deletes user.   * [[BS2_RemoveUser]]:​ Deletes user.
   * [[BS2_RemoveAllUser]]:​ Deletes all users.   * [[BS2_RemoveAllUser]]:​ Deletes all users.
-  * [[BS2_GetUserInfosEx]]:​ Gets the user information of the given user ID. (Applies only for v2.4 FW group or above+  ​* [[BS2_GetUserInfos]]:​ Gets the user information of the given user ID. 
-  * [[BS2_EnrolUserEx]]: Enrolls new user. (Applies only for v2.4 FW group or above)+  ​* [[BS2_GetUserInfosEx]]: ​[+ 2.4.0] ​Gets the user information of the given user ID. (including Job code and User phrase) 
 +  * [[BS2_EnrolUser]]:​ Enrolls new user. 
 +  * [[BS2_EnrolUserEx]]:​ [+ 2.4.0] Enrolls new user. (including Job code and User phrase
 +  * [[BS2_EnrollUser]]: [+ 2.6.3] Enrolls new user. 
 +  * [[BS2_EnrollUserEx]]:​ [+ 2.6.3] ​Enrolls new user. (including Job code and User phrase) 
 +  * [[BS2_GetUserDatas]]:​​ Gets selected data of user. 
 +  * [[BS2_GetUserDatasEx]]:​​ [+ 2.5.0] Gets selected data of user. (including Job code, User phrase) 
 +  * [[BS2_GetSupportedUserMask]]:​ Gets user settings supported by the device. 
 +  * [[BS2_EnrollUserSmall]]:​ [+ 2.6.3] Enrolls new user with efficient use of memory. 
 +  * [[BS2_EnrollUserSmallEx]]:​ [+ 2.6.3] Enrolls new user with efficient use of memory. 
 +  * [[BS2_GetUserSmallInfos]]:​ [+ 2.6.3] Gets the user information of the given user ID with efficient use of memory. 
 +  * [[BS2_GetUserSmallInfosEx]]:​ [+ 2.6.3] Gets the user information of the given user ID with efficient use of memory. 
 +  * [[BS2_GetUserSmallDatas]]:​ [+ 2.6.3] Gets selected data of user with efficient use of memory. 
 +  * [[BS2_GetUserSmallDatasEx]]:​ [+ 2.6.3] Gets selected data of user with efficient use of memory. 
 +  * [[BS2_EnrollUserFaceEx]]:​ [+ 2.7.1] ''​FaceStation F2''​ Enrolls new user. 
 +  * [[BS2_GetUserInfosFaceEx]]:​ [+ 2.7.1] ''​FaceStation F2''​ Gets the user information of the given user ID. 
 +  * [[BS2_GetUserDatasFaceEx]]:​ [+ 2.7.1] ''​FaceStation F2''​ Gets selected data of user. 
 + 
  
  
Line 26: Line 42:
     uint8_t numFingers;     uint8_t numFingers;
     uint8_t numFaces;     uint8_t numFaces;
-    uint8_t ​reserved2[1];+    uint8_t ​infoMask;
     uint32_t authGroupID;​     uint32_t authGroupID;​
     uint32_t faceChecksum;​     uint32_t faceChecksum;​
Line 54: Line 70:
 **7. //​numFaces//​** \\  **7. //​numFaces//​** \\ 
 Number of face templates mapped to user. \\ \\  Number of face templates mapped to user. \\ \\ 
-**8. //authGroupID//** \\  +**8. //infoMask//** \\ 
-ID of group when face group matching is enabled. \\ \\  +[+ 2.8.3] This indicates what information the user has. By changing the information at infoMask and sending the information to change to the device, it is possible to partially change the selected user’s information. \\ 
-**9. //​faceChecksum//​** \\ +At this moment, Partial Update families ​of functions([[BS2_PartialUpdateUser]],​ [[BS2_PartialUpdateUserEx]],​ [[BS2_PartialUpdateUserSmall]],​ [[BS2_PartialUpdateUserSmallEx]],​ [[BS2_PartialUpdateUserFaceEx]]) and user mask argument must match (refer to the table below). \\ 
 + 
 +<​WRAP ​group 50%> 
 +^Value ​ ^Description ​ ^ 
 +|0x01  |BS2_USER_INFO_MASK_PHRASE ​ | 
 +|0x02  |BS2_USER_INFO_MASK_JOB_CODE ​ | 
 +|0x04  |BS2_USER_INFO_MASK_NAME ​ | 
 +|0x08  |BS2_USER_INFO_MASK_PHOTO ​ | 
 +|0x10  |BS2_USER_INFO_MASK_PIN ​ | 
 +|0x20  |BS2_USER_INFO_MASK_CARD ​ | 
 +|0x40  |BS2_USER_INFO_MASK_FINGER ​ | 
 +|0x80  |BS2_USER_INFO_MASK_FACE ​ | 
 +</​WRAP>​ 
 +**''​Get user information''​** \\ 
 +The infoMask indicates what information is allocated to the current user when getting the user information. \\ \\ 
 +<WRAP group 50%> 
 +^User information ​ ^BS2_USER_MASK ​ ^infoMask ​ ^ 
 +|Partial removal ​ |unmasking ​ |unmasking ​ | 
 +|Partial edit  |masking ​ |masking ​ | 
 +|Default setting ​ |unmasking ​ |masking ​ | 
 +</​WRAP>​ 
 +**''​Partial removal of user information''​** \\ 
 +Choose unmasking for the information to be removed at all sections (infoMask, Partial Update families of functions, and user mask agreements). \\ \\ 
 +**''​Partial edit of user information''​** \\ 
 +Choose masking for the information to be edited at all sections (infoMask, Partial Update families of functions, and user mask agreements). \\ \\ 
 +**''​Default setting of user information''​** \\ 
 +Choose masking for infoMask and unmasking for Partial Update familes of functions and user mask agreements. \\ \\  
 +**''​Changing credential information (Card/​Fingerprint/​Face)''​** \\ 
 +It checks if the credential information is allocated or not such as [numCards, numFingers, or numFaces is 0], [fingerObjs,​ cardObjs, faceObjs, or faceExObjs is NULL]. Plus, it checks infoMask. \\ 
 +If the input information at card/​fingerprint/​face is greater than 0 and the mask at infoMask is set, the device credential information can be changed. \\ 
 +For example, when the device has two fingerprints for a user, select masking at infoMask’s BS2_USER_INFO_MASK_FINGER,​ numFingers =1, and assign a fingerprint at fingerObjs. Then the device will have only one newly assigned fingerprint. \\ 
 +To add a new fingerprint,​ three fingerprints must be assigned which includes the two previously stored fingerprints and the new fingerprint. \\ \\ 
 +**''​Keeping the credential information (Card/​Fingerprint/​Face)''​** \\ 
 +The device keeps the original credential information if the credential information at card/​fingerprint/​face is set to 0 and the infoMask is set to masking. \\ \\ 
 +**''​Removing the credential information (Card/​Fingerprint/​Face)''​** \\ 
 +If the credential information at card/​fingerprint/​face is set to 0 and the infoMask is set to unmasking, the device erases the corresponding information assigned to each credential. \\ \\ 
 +**9. //​authGroupID//​** \\  
 +The group ID the user is assigned to when face group matching is enabled. \\ \\  
 +**10. //​faceChecksum//​** \\ 
 Not Used. \\  Not Used. \\ 
  
Line 62: Line 116:
 \\ \\
 ==== BS2UserSetting ==== ==== BS2UserSetting ====
 +<WRAP tip 70%> 
 +**Tip**\\ 
 +Please use [[user management api#​BS2UserSettingEx|BS2UserSettingEx]] to set <wrap em>the personal authentication mode</​wrap>​ of <wrap em>​FaceStation F2, BioStation 3</​wrap>​. 
 +</​WRAP>​
 <code cpp> <code cpp>
 typedef struct { typedef struct {
Line 74: Line 131:
 </​code>​ </​code>​
 **1. //​startTime//​** \\  **1. //​startTime//​** \\ 
-Start time that a user can identify. ​When the value is 0, there are no limitations. \\ \\ +Start time that a user can identify. ​\\ 
 +<wrap em>​A ​value greater than 978307200 (01 January 2001, 00:​00:​00)</​wrap>​ must be entered, <wrap em>If set 0</​wrap>​it means that there is <wrap em>no limit</​wrap>​. \\ \\  
 **2. //​endTime//​** \\  **2. //​endTime//​** \\ 
-End time that that a user can identify. ​When the value is 0, there are no limitations \\ \\ +End time that that a user can identify. ​\\ 
 +<wrap em>​A ​value smaller than 1924991999 (31 December 2030, 23:​59:​59)</​wrap>​ must be entered, <wrap em>If set 0</​wrap>​it means that there is <wrap em>no limit</​wrap>​. \\ \\ 
 **3. //​fingerAuthMode//​** \\  **3. //​fingerAuthMode//​** \\ 
 Finger authentication mode for user authentication. \\  Finger authentication mode for user authentication. \\ 
Line 159: Line 219:
 Personal Identification Number(PIN). It should be entered through //​BS_MakePinCode//​ function. \\ \\  Personal Identification Number(PIN). It should be entered through //​BS_MakePinCode//​ function. \\ \\ 
 **6. //​cardObjs//​** \\  **6. //​cardObjs//​** \\ 
-Card list for user authentication that needs to exist as much as **user.numCards**. Refer to [[Smartcard API]] for data format. \\ \\ +Card list for user authentication that needs to exist as much as **user.numCards**. Refer to [[Smartcard API]] for data format. \\ In case of Secure Crendential card, cardObjs array of BS2UserBlob structure should be filled and the user should be updated after Secure Crendential card issuing. \\ \\
 **7. //​fingerObjs//​** \\  **7. //​fingerObjs//​** \\ 
 Fingerprint template for user authentication that needs to exist as much as **user.numFingers**. Refer to [[Fingerprint API]] for data format. \\ \\ Fingerprint template for user authentication that needs to exist as much as **user.numFingers**. Refer to [[Fingerprint API]] for data format. \\ \\
Line 203: Line 263:
     BS2_USER_PHRASE phrase;     BS2_USER_PHRASE phrase;
     uint32_t accessGroupId[BS2_MAX_NUM_OF_ACCESS_GROUP_PER_USER];​     uint32_t accessGroupId[BS2_MAX_NUM_OF_ACCESS_GROUP_PER_USER];​
-BS2UserBlob;+BS2UserBlobEx;
 </​code>​ </​code>​
 **1. //user//** \\  **1. //user//** \\ 
Line 224: Line 284:
 Job code that will be allocated to user. \\ \\ Job code that will be allocated to user. \\ \\
 **10. //​phrase//​** \\  **10. //​phrase//​** \\ 
-Private message that will be displayed when the user authenticates. ​(FaceStation 2 Only) \\ \\+Private message that will be displayed when the user authenticates. \\ 
 +<WRAP group 30%> 
 +^Model ​ ^Supported Ver.  ^ 
 +|FaceStation 2  |V1.0.0 or higher ​ | 
 +|FaceStation F2  |V1.0.0 or higher ​ | 
 +|X-Station 2  |V1.0.0 or higher ​ | 
 +|BioStation 3  |V1.0.0 or higher ​ | 
 +</​WRAP>​
 **11. //​accessGroupId//​** \\  **11. //​accessGroupId//​** \\ 
 List of access groups where users belong to which can be configured up to 16 groups.\\ \\  List of access groups where users belong to which can be configured up to 16 groups.\\ \\ 
 +
 +
 +
 +==== BS2UserSmallBlob ====
 +<code cpp>
 +typedef struct {
 +    BS2User user;
 +    BS2UserSetting setting;
 +    uint8_t name[BS2_USER_NAME_SIZE];​
 +    BS2UserPhoto* photo;
 +    uint8_t pin[BS2_PIN_HASH_SIZE];​
 +    BS2CSNCard* cardObjs;
 +    BS2Fingerprint* fingerObjs;
 +    BS2Face* faceObjs; ​   ​
 +    uint32_t accessGroupId[BS2_MAX_NUM_OF_ACCESS_GROUP_PER_USER];​
 +} BS2UserSmallBlob;​
 +</​code>​
 +**1. //user//** \\ 
 +Structure that defines the basic user information.\\ \\ 
 +**2. //​setting//​** \\ 
 +Structure that defines the configuration value for user identification. \\ \\ 
 +**3. //name//** \\ 
 +User name having UTF-8 for string encoding. \\ \\
 +**4. //photo//** \\ 
 +User profile image, which supports only Jpeg images. \\ \\ 
 +**5. //pin//** \\ 
 +Personal Identification Number(PIN). It should be entered through //​BS_MakePinCode//​ function. \\ \\ 
 +**6. //​cardObjs//​** \\ 
 +Card list for user authentication that needs to exist as much as **user.numCards**. Refer to [[Smartcard API]] for data format. \\ \\ 
 +**7. //​fingerObjs//​** \\ 
 +Fingerprint template for user authentication that needs to exist as much as **user.numFingers**. Refer to [[Fingerprint API]] for data format. \\ \\
 +**8. //​faceObjs//​** \\ 
 +Face template for user authentication that needs to exist as much as **user.numFaces**. Refer to [[Face API]] for data format. \\ \\
 +**9. //​accessGroupId//​** \\ 
 +List of access groups where users belong to which can be configured up to 16 groups.\\ \\ 
 +
 +
 +==== BS2UserSmallBlobEx ====
 +<code cpp>
 +typedef struct {
 +    BS2User user;
 +    BS2UserSetting setting;
 +    uint8_t name[BS2_USER_NAME_SIZE];​
 +    BS2UserPhoto* photo;
 +    uint8_t pin[BS2_PIN_HASH_SIZE];​
 +    BS2CSNCard* cardObjs;
 +    BS2Fingerprint* fingerObjs;
 +    BS2Face* faceObjs;
 +    BS2Job job;
 +    BS2_USER_PHRASE phrase;
 +    uint32_t accessGroupId[BS2_MAX_NUM_OF_ACCESS_GROUP_PER_USER];​
 +} BS2UserSmallBlobEx;​
 +</​code>​
 +**1. //user//** \\ 
 +Structure that defines the basic user information.\\ \\ 
 +**2. //​setting//​** \\ 
 +Structure that defines the configuration value for user identification. \\ \\ 
 +**3. //name//** \\ 
 +User name having UTF-8 for string encoding. \\ \\
 +**4. //photo//** \\ 
 +User profile image, which supports only Jpeg images. \\ \\ 
 +**5. //pin//** \\ 
 +Personal Identification Number(PIN). It should be entered through //​BS_MakePinCode//​ function. \\ \\ 
 +**6. //​cardObjs//​** \\ 
 +Card list for user authentication that needs to exist as much as **user.numCards**. Refer to [[Smartcard API]] for data format. \\ \\ 
 +**7. //​fingerObjs//​** \\ 
 +Fingerprint template for user authentication that needs to exist as much as **user.numFingers**. Refer to [[Fingerprint API]] for data format. \\ \\
 +**8. //​faceObjs//​** \\ 
 +Face template for user authentication that needs to exist as much as **user.numFaces**. Refer to [[Face API]] for data format. \\ \\
 +**9. //job//** \\ 
 +Job code that will be allocated to user. \\ \\
 +**10. //​phrase//​** \\ 
 +Private message that will be displayed when the user authenticates. \\
 +<WRAP group 30%>
 +^Model ​ ^Supported Ver.  ^
 +|FaceStation 2  |V1.0.0 or higher ​ |
 +|FaceStation F2  |V1.0.0 or higher ​ |
 +|X-Station 2  |V1.0.0 or higher ​ |
 +</​WRAP>​
 +**11. //​accessGroupId//​** \\ 
 +List of access groups where users belong to which can be configured up to 16 groups.\\ \\ 
 +
 +
 +
 +==== BS2UserSettingEx ====
 +<WRAP tip 70%>
 +**Tip**\\
 +Please use [[user management api#​BS2UserSetting|BS2UserSetting]] to set <wrap em>the personal authentication mode</​wrap>​ for devices other than <wrap em>​FaceStation F2 and BioStation 3</​wrap>​.
 +</​WRAP>​
 +<code cpp>
 +typedef struct {
 +    uint8_t faceAuthMode;​
 +    uint8_t fingerprintAuthMode;​
 +    uint8_t cardAuthMode;​
 +    uint8_t idAuthMode;
 +    uint8_t reserved[28];​
 +} BS2UserSettingEx;​
 +</​code>​
 +1. //​faceAuthMode//​ \\ 
 +User facial authentication mode \\
 +<WRAP group 60%>
 +^Value ​ ^Level 1 ^Level 2  ^Level 3  ^Level 4  ^
 +|11 |Face |      |  |
 +|12 |Face  |Fingerprint ​ |  |
 +|13 |Face  |PIN   ​| ​ |
 +|14 |Face  |Fingerprint or PIN  |  |
 +|15 |Face  |Fingerprint ​ |PIN  |
 +|254 |Cannot use  |  |  |
 +|255 |Not defined(System defined mode)  |  |  |
 +</​WRAP>​
 +2. //​fingerprintAuthMode//​ \\ 
 +User fingerprint authentication mode \\ 
 +<WRAP group 60%>
 +^Value ​ ^Level 1  ^Level 2  ^Level 3  ^Level 4  ^
 +|16 |Fingerprint ​ |      |  |
 +|17 |Fingerprint ​ |Face  |  |
 +|18 |Fingerprint ​ |PIN   ​| ​ |
 +|19 |Fingerprint ​ |Face or PIN  |  |
 +|20 |Fingerprint ​ |Face  |PIN  |
 +|254 |Cannot use  |  |  |
 +|255 |Not defined(System defined mode)  |  |  |
 +</​WRAP>​
 +3. //​cardAuthMode//​ \\ 
 +User card authentication mode  \\ 
 +<WRAP group 60%>
 +^Value ​ ^Level 1  ^Level 2  ^Level 3  ^Level 4  ^
 +|21  |Card  |      |   |
 +|22  |Card  |Face  |   |
 +|23  |Card  |Fingerprint ​ |   |
 +|24  |Card  |PIN  |   |
 +|25  |Card  |Face or Fingerprint ​ |   |
 +|26  |Card  |Face or PIN  |   |
 +|27  |Card  |Fingerprint or PIN  |   |
 +|28  |Card  |Face or Fingerprint or PIN  |   |
 +|29  |Card  |Face  |Fingerprint ​ |
 +|30  |Card  |Face  |PIN  |
 +|31  |Card  |Fingerprint ​ |Face  |
 +|32  |Card  |Fingerprint ​ |PIN  |
 +|33  |Card  |Face or Fingerprint ​ |PIN  |
 +|34  |Card  |Face  |Fingerprint or PIN  |
 +|35  |Card  |Fingerprint ​ |Face or PIN  |
 +|254 |Cannot use  |  |  |
 +|255 |Not defined(System defined mode)  |  |  |
 +</​WRAP>​
 +4. //​idAuthMode//​ \\ 
 +User ID authentication mode \\ 
 +<WRAP group 60%>
 +^Value ​ ^Level 1  ^Level 2  ^Level 3  ^Level 4  ^
 +|36  |ID  |Face  |   |
 +|37  |ID  |Fingerprint ​ |   |
 +|38  |ID  |PIN  |   |
 +|39  |ID  |Face or Fingerprint ​ |   |
 +|40  |ID  |Face or PIN  |   |
 +|41  |ID  |Fingerprint or PIN  |   |
 +|42  |ID  |Face or Fingerprint or PIN  |   |
 +|43  |ID  |Face  |Fingerprint ​ |
 +|44  |ID  |Face  |PIN  |
 +|45  |ID  |Fingerprint ​ |Face  |
 +|46  |ID  |Fingerprint ​ |PIN  |
 +|47  |ID  |Face or Fingerprint ​ |PIN  |
 +|48  |ID  |Face  |Fingerprint or PIN  |
 +|49  |ID  |Fingerprint ​ |Face or PIN  |
 +|254 |Cannot use  |  |  |
 +|255 |Not defined(System defined mode)  |  |  |
 +</​WRAP>​
 +5. //​reserved//​ \\ 
 +Reserved \\ \\ 
 +
 +==== BS2UserFaceExBlob ====
 +<code cpp>
 +typedef struct
 +{
 +    BS2User user;
 +    BS2UserSetting setting;
 +    BS2_USER_NAME user_name;
 +    BS2UserPhoto* user_photo_obj;​
 +    BS2_USER_PIN pin;
 +    BS2CSNCard* cardObjs;
 +    BS2Fingerprint* fingerObjs;
 +    BS2Face* faceObjs; ​                 // FS2, FL
 +    BS2Job job;
 +    BS2_USER_PHRASE phrase;
 +    BS2_ACCESS_GROUP_ID accessGroupId[BS2_MAX_NUM_OF_ACCESS_GROUP_PER_USER];​
 +
 +    BS2UserSettingEx settingEx; ​        // F2
 +    BS2FaceEx* faceExObjs; ​             // F2
 +} BS2UserFaceExBlob;​
 +</​code>​
 +1. //user// \\ 
 +Basic user information defined structure \\ \\ 
 +2. //setting// \\ 
 +Basic user setting defined structure \\ \\ 
 +3. //name// \\ 
 +User name (Encoding : UTF-8) \\ \\ 
 +4. //photo// \\ 
 +User profile image (Only support jpeg) \\ \\
 +5. //pin// \\ 
 +PIN, must be filled with a return of API //​BS2_MakePinCode// ​
 +6. //​cardObjs//​ \\ 
 +Card list for user authentication,​ there must be as many as **user.numCards**. Refer to [[Smartcard API]] for data format. \\ \\ 
 +7. //​fingerObjs//​ \\ 
 +Fingerprint template list for user authentication,​ there must be as many as **user.numFingers**. Refer to [[Fingerprint API]] for data format. \\ \\ 
 +8. //​faceObjs//​ \\ 
 +''​FaceStation2'',​ ''​FaceLite''​ Face template list for user authentication,​ there must be as many as **user.numFaces**. Refer to [[Face API]] for data format. \\ \\ 
 +9. //job// \\ 
 +Job code in T&A mode \\ \\ 
 +10. //phrase// \\ 
 +Private message that will be displayed when the user authenticates. \\
 +<WRAP group 30%>
 +^Model ​ ^Supported Ver.  ^
 +|FaceStation 2  |V1.0.0 or higher ​ |
 +|FaceStation F2  |V1.0.0 or higher ​ |
 +|X-Station 2  |V1.0.0 or higher ​ |
 +</​WRAP>​
 +11. //​accessGroupId//​ \\ 
 +List of access group of the user assigned, maximum is 16. \\ \\ 
 +12. //​settingEx//​ \\ 
 +''​FaceStation F2''​ Sets private authentication. It is now possible to combine more various authentication modes by combining fingerprints and faces. \\ \\ 
 +13. //​faceExObjs//​ \\ 
 +''​FaceStation F2''​ Face template list for user authentication,​ there must be as many as **user.numFaces**. Refer to [[Face API]] for data format. \\ \\ 
 +
 +==== BS2UserStatistic ====
 +<code cpp>
 +typedef struct {
 +    uint32_t numUsers;
 +    uint32_t numCards;
 +    uint32_t numFingerprints;​
 +    uint32_t numFaces;
 +    uint32_t numNames;
 +    uint32_t numImages;
 +    uint32_t numPhrases;
 +} BS2UserStatistic;​
 +</​code>​
 +
 +1. //​numUsers//​ \\
 +Number of registered users. \\ \\
 +2. //​numCards//​ \\
 +Number of registered cards. \\ \\
 +3. //​numFingerprints//​ \\
 +Number of fingerprints registered. \\ \\
 +4. //​numFaces//​ \\
 +Number of registered faces. \\ \\
 +5. //​numNames//​ \\
 +Number of registered user names. \\ \\
 +6. //​numImages//​ \\
 +Number of images registered. \\ \\
 +7. //​numPhrases//​ \\
 +Number of registered personal messages. \\ \\