Differences

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

--- en:user_management_api [2020/11/26 17:51]
kkshin [BS2UserSetting]
+++ en:user_management_api [2023/03/02 14:30]
@@ Line 1: / Line 1: @@
-====== User Management API ======
-API that provides functions to enroll and delete users.
-\\
-  * [[BS2_GetUserList]]: Gets the enrolled user ID list.
-  * [[BS2_RemoveUser]]: Deletes user.
-  * [[BS2_RemoveAllUser]]: Deletes all users.
-  * [[BS2_GetUserInfos]]: Gets the user information of the given user ID.
-  * [[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.
-===== Structure =====
-==== BS2User ====
-<code cpp>
-typedef struct {
-    char userID[BS2_USER_ID_SIZE];
-    uint8_t formatVersion;
-    uint8_t flag;
-    uint16_t version;
-    uint8_t numCards;
-    uint8_t numFingers;
-    uint8_t numFaces;
-    uint8_t reserved2[1];
-    uint32_t authGroupID;
-    uint32_t faceChecksum;
-} BS2User;
-</code>
-**1. //userID//** \\
-User ID provided as string, and has a range of 1 ~ 4294967295. \\ \\
-**2. //formatVersion//** \\
-Not Used. \\ \\
-**3. //flag//** \\
-Flag that shows the user's status. OR operation is available and the mask value is listed below.\\
-<WRAP group 50%>
-^Value  ^Description  ^
-|0x00  |None  |
-|0x01  |User enrolled  |
-|0x02  |User updated  |
-|0x04  |User deleted  |
-|0x80  |User disabled  |
-</WRAP>
-**4. //version//** \\
-Not Used. \\ \\
-**5. //numCards//** \\
-Number of cards mapped to user. \\ \\
-**6. //numFingers//** \\
-Number of fingerprint templates mapped to user. \\ \\
-**7. //numFaces//** \\
-Number of face templates mapped to user. \\ \\
-**8. //authGroupID//** \\
-ID of group when face group matching is enabled. \\ \\
-**9. //faceChecksum//** \\
-Not Used. \\
-\\
-==== BS2UserSetting ====
-<WRAP tip 70%>
-**Tip**\\
-<wrap em>Other than FaceStation F2</wrap> \\
-Please use [[user management api#BS2UserSettingEx|BS2UserSettingEx]] for <wrap em>FaceStation F2</wrap>.
-</WRAP>
-<code cpp>
-typedef struct {
-    uint32_t startTime;
-    uint32_t endTime;
-    uint8_t fingerAuthMode;
-    uint8_t cardAuthMode;
-    uint8_t idAuthMode;
-    uint8_t securityLevel;
-} BS2UserSetting;
-</code>
-**1. //startTime//** \\
-Start time that a user can identify. When the value is 0, there are no limitations. \\ \\
-**2. //endTime//** \\
-End time that that a user can identify. When the value is 0, there are no limitations.  \\ \\
-**3. //fingerAuthMode//** \\
-Finger authentication mode for user authentication. \\
-<WRAP group 50%>
-^Value  ^Description  ^
-|0 |Uses only fingerprint authentication  |
-|1 |Uses fingerprint and PIN authentication  |
-|254 |Cannot use  |
-|255 |Undefined(Operates as defined in system)  |
-</WRAP>
-**4. //cardAuthMode//** \\
-Card authentication mode for user authentication. \\
-<WRAP group 50%>
-^Value  ^Description  ^
-|2 |Uses only card authentication |
-|3 |Uses card and fingerprint authentication  |
-|4 |Uses card and PIN authentication  |
-|5 |Uses fingerprint or PIN after card authentication  |
-|6 |Uses card, fingerprint, and PIN authentication  |
-|254 |Cannot use  |
-|255 |Undefined(Operates as defined in system)  |
-</WRAP>
-**5. //idAuthMode//** \\
-ID authentication mode for user authentication. \\
-<WRAP group 50%>
-^Value  ^Description  ^
-|7 |Uses fingerprint authentication after entering user ID  |
-|8 |Uses PIN authentication after entering user ID  |
-|9 |Uses fingerprint or PIN authentication after entering user ID  |
-|10 |Uses fingerprint and PIN authentication after entering user ID  |
-|254 |Cannot use  |
-|255 |Undefined(Operates as defined in system)  |
-</WRAP>
-**6. //securityLevel//** \\
-Security level for fingerprint identification or face recognition. \\
-<WRAP group 50%>
-^Value  ^Description  ^
-|0 |Default value defined in system  |
-|1 |Lowest security level  |
-|2 |Low security level  |
-|3 |Normal security level  |
-|4 |High security level  |
-|5 |Highest security level  |
-</WRAP>
-\\
-==== BS2UserPhoto ====
-<code cpp>
-typedef struct {
-    uint32_t size;
-    uint8_t data[BS2_USER_PHOTO_SIZE];
-} BS2UserPhoto;
-</code>
-. //size// \\
-Size of the user profile image data. \\ \\
-. //data// \\
-Data of the profile image, which can be stored up to 16kb. \\
-==== BS2UserBlob ====
-<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];
-} BS2UserBlob;
-</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. \\ 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//** \\
-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.\\ \\
-==== BS2Job====
-<code cpp>
-typedef struct {
-	uint8_t numJobs;
-	uint8_t reserved[3];
-	struct {
-		BS2_JOB_CODE code;
-		BS2_JOB_LABEL label;
-	} jobs[BS2_MAX_JOB_SIZE];
-} BS2Job;
-</code>
-. //numJobs// \\
-Number of job codes allocated to the user. \\ \\
-. //reserved// \\
-Reserved Space.\\ \\
-. //jobs// \\
-List of jobs. \\
-==== BS2UserBlobEx ====
-<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];
-} BS2UserBlobEx;
-</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. (only in FS2 FW 1.0.0 or higher) \\ \\
-**11. //accessGroupId//** \\
-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. (only in FS2 FW 1.0.0 or higher)  \\ \\
-**11. //accessGroupId//** \\
-List of access groups where users belong to which can be configured up to 16 groups.\\ \\
-==== BS2UserSettingEx ====
-<WRAP tip 70%>
-**Tip**\\
-<wrap em>FaceStation F2 Only</wrap>  \\
-Please use [[user management api#BS2UserSetting|BS2UserSetting]] <wrap em>other than</wrap> FaceStation F2.
-</WRAP>
-<code cpp>
-typedef struct {
-    uint8_t faceAuthMode;
-    uint8_t fingerprintAuthMode;
-    uint8_t cardAuthMode;
-    uint8_t idAuthMode;
-    uint8_t reserved[28];
-} BS2UserSettingEx;
-</code>
-. //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>
-. //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>
-. //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>
-. //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>
-. //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>
-. //user// \\
-Basic user information defined structure \\ \\
-. //setting// \\
-Basic user setting defined structure \\ \\
-. //name// \\
-User name (Encoding : UTF-8) \\ \\
-. //photo// \\
-User profile image (Only support jpeg) \\ \\
-. //pin// \\
-PIN, must be filled with a return of API //BS2_MakePinCode//
-. //cardObjs// \\
-Card list for user authentication, there must be as many as **user.numCards**. Refer to [[Smartcard API]] for data format. \\ \\
-. //fingerObjs// \\
-Fingerprint template list for user authentication, there must be as many as **user.numFingers**. Refer to [[Fingerprint API]] for data format. \\ \\
-. //faceObjs// \\
-''FaceStation2'', ''FaceLite'' Face template list for user authentication, there must be as many as **user.numFaces**. Refer to [[Face API]] for data format. \\ \\
-. //job// \\
-Job code in T&A mode \\ \\
-. //phrase// \\
-Personal message displayed on the device UI when authentication. (FS2 FW 1.0.0 or higher only) \\ \\
-. //accessGroupId// \\
-List of access group of the user assigned, maximum is 16. \\ \\
-. //settingEx// \\
-''FaceStation F2'' Sets private authentication. It is now possible to combine more various authentication modes by combining fingerprints and faces. \\ \\
-. //faceExObjs// \\
-''FaceStation F2'' Face template list for user authentication, there must be as many as **user.numFaces**. Refer to [[Face API]] for data format. \\ \\