User API

Overview

BioStar devices manage user information in several parts such as header, authentication settings, and credentials.

User Header

Specify the most basic information of a user.

message UserHdr {
  string ID;
  int32 numOfCard;
  int32 numOfFinger;
  int32 numOfFace;
  uint32 authGroupID; 
}
ID
Maximum 32 bytes. 0 is not allowed as an ID. For alphanumeric ID, check if it is supported by the device using CapabilityInfo.alphanumericIDSupported, and configure it using SystemConfig.useAlphanumericID.
numOfCard
Maximum 8 cards can be assigned to a user.
numOfFinger
Maximum 10 fingerprints can be registered to a user.
numOfFace
Maximum 5 faces can be registered to a user.
authGroupID
Used only for group matching of face. Refer to Face.AuthGroup.

User Setting

You can specify the effective and expiry time of a user using startTime and endTime. You can also specify the private authentication modes of the user using fingerAuthMode, cardAuthMode, and IDAuthMode. For the available modes, refer to authentication modes. Since FaceStation F2 provides different authentication modes, you have to use faceAuthExtMode, fingerAuthExtMode, cardAuthExtMode, and IDAuthExtMode for it.

The private authentication modes will be applied only when AuthConfig.usePrivateAuth is true.

message UserSetting {
  uint32 startTime;
  uint32 endTime;

  uint32 biometricAuthMode;
  uint32 cardAuthMode;
  uint32 IDAuthMode;
  uint32 securityLevel;

  // Only for FaceStation F2
  uint32 faceAuthExtMode;
  uint32 fingerAuthExtMode;
  uint32 cardAuthExtMode;
  uint32 IDAuthExtMode;  
}
startTime
The user will be valid only after this time. If 0, no restriction. In Unix format.
endTime
The user will be valid only until this time. If 0, no restriction. In Unix format.
biometricAuthMode
AUTH_MODE_BIOMETRIC_ONLY Fingerprint or Face
AUTH_MODE_BIOMETRIC_PIN (Fingerprint or Face) + PIN
0xFE Not permitted
0xFF Undefined. Use the settings of AuthConfig
cardAuthMode
AUTH_MODE_CARD_ONLY Card
AUTH_MODE_CARD_BIOMETRIC Card + (Fingerprint or Face)
AUTH_MODE_CARD_PIN Card + PIN
AUTH_MODE_CARD_BIOMETRIC_OR_PIN Card + (Fingerprint or Face or PIN)
AUTH_MODE_CARD_BIOMETRIC_PIN Card + (Fingerprint or Face) + PIN
0xFE Not permitted
0xFF Undefined. Use the settings of AuthConfig
idAuthMode
AUTH_MODE_ID_BIOMETRIC ID + (Fingerprint or Face)
AUTH_MODE_ID_PIN ID + PIN
AUTH_MODE_ID_BIOMETRIC_OR_PIN ID + (Fingerprint or Face or PIN)
AUTH_MODE_ID_BIOMETRIC_PIN ID + (Fingerprint or Face) + PIN
0xFE Not permitted
0xFF Undefined. Use the settings of AuthConfig
securityLevel
Specify the security level for fingerprint and face verification.
0 Undefined. Use the settings of FingerConfig and FaceConfig
1 Least secure
2 Less secure
3 Normal
4 More secure
5 Most secure
faceAuthExtMode
FaceStation F2 only
AUTH_EXT_MODE_FACE_ONLY Face
AUTH_EXT_MODE_FACE_FINGERPRINT Face + Fingerprint
AUTH_EXT_MODE_FACE_PIN Face + PIN
AUTH_EXT_MODE_FACE_FINGERPRINT_OR_PIN Face + (Fingerprint or PIN)
AUTH_EXT_MODE_FACE_FINGERPRINT_PIN Face + Fingerprint + PIN
0xFE Not permitted
0xFF Undefined. Use the settings of AuthConfig
fingerAuthExtMode
FaceStation F2 only
AUTH_EXT_MODE_FINGERPRINT_ONLY Fingerprint
AUTH_EXT_MODE_FINGERPRINT_FACE Fingerprint + Face
AUTH_EXT_MODE_FINGERPRINT_PIN Fingerprint + PIN
AUTH_EXT_MODE_FINGERPRINT_FACE_OR_PIN Fingerprint + (Face or PIN)
AUTH_EXT_MODE_FINGERPRINT_FACE_PIN Fingerprint + Face + PIN
0xFE Not permitted
0xFF Undefined. Use the settings of AuthConfig
cardAuthExtMode
FaceStation F2 only
AUTH_EXT_MODE_CARD_ONLY Card
AUTH_EXT_MODE_CARD_FACE Card + Face
AUTH_EXT_MODE_CARD_FINGERPRINT Card + Fingerprint
AUTH_EXT_MODE_CARD_PIN Card + PIN
AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT Card + (Face or Fingerprint)
AUTH_EXT_MODE_CARD_FACE_OR_PIN Card + (Face or PIN)e
AUTH_EXT_MODE_CARD_FINGERPRINT_OR_PIN Card + (Fingerprint or PIN)
AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT_OR_PIN Card + (Face or Fingerprint or PIN)
AUTH_EXT_MODE_CARD_FACE_FINGERPRINT Card + Face + Fingerprint
AUTH_EXT_MODE_CARD_FACE_PIN Card + Face + PIN
AUTH_EXT_MODE_CARD_FINGERPRINT_FACE Card + Fingerprint + Face
AUTH_EXT_MODE_CARD_FINGERPRINT_PIN Card + Fingerprint + PIN
AUTH_EXT_MODE_CARD_FACE_OR_FINGERPRINT_PIN Card + (Face or Fingerprint) + PIN
AUTH_EXT_MODE_CARD_FACE_FINGERPRINT_OR_PIN Card + Face + (Fingerprint or PIN)
AUTH_EXT_MODE_CARD_FINGERPRINT_FACE_OR_PIN Card + Fingerprint + (Face or PIN)
0xFE Not permitted
0xFF Undefined. Use the settings of AuthConfig
IDAuthExtMode
FaceStation F2 only
AUTH_EXT_MODE_ID_FACE ID + Face
AUTH_EXT_MODE_ID_FINGERPRINT ID + Fingerprint
AUTH_EXT_MODE_ID_PIN ID + PIN
AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT ID + (Face or Fingerprint)
AUTH_EXT_MODE_ID_FACE_OR_PIN ID + (Face or PIN)e
AUTH_EXT_MODE_ID_FINGERPRINT_OR_PIN ID + (Fingerprint or PIN)
AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT_OR_PIN ID + (Face or Fingerprint or PIN)
AUTH_EXT_MODE_ID_FACE_FINGERPRINT ID + Face + Fingerprint
AUTH_EXT_MODE_ID_FACE_PIN ID + Face + PIN
AUTH_EXT_MODE_ID_FINGERPRINT_FACE ID + Fingerprint + Face
AUTH_EXT_MODE_ID_FINGERPRINT_PIN ID + Fingerprint + PIN
AUTH_EXT_MODE_ID_FACE_OR_FINGERPRINT_PIN ID + (Face or Fingerprint) + PIN
AUTH_EXT_MODE_ID_FACE_FINGERPRINT_OR_PIN ID + Face + (Fingerprint or PIN)
AUTH_EXT_MODE_ID_FINGERPRINT_FACE_OR_PIN ID + Fingerprint + (Face or PIN)
0xFE Not permitted
0xFF Undefined. Use the settings of AuthConfig

User Information

message UserInfo {
  UserHdr hdr;
  UserSetting setting;
  string name;
  repeated card.CSNCardData cards;
  repeated finger.FingerData fingers;
  repeated face.FaceData faces;
  repeated uint32 accessGroupIDs;
  repeated tna.JobCode jobCodes;
  bytes PIN;
  bytes photo;
}
hdr
UserHdr.
setting
UserSetting.
name
Maximum 48 characters in UTF-8 encoding.
cards
Cards assigned to the user. Refer to CSNCardData. You can assign cards using SetCard or SetCardMulti.
fingers:
Fingers registered to the user. Refer to FingerData. You can register fingerprints using SetFinger or SetFingerMulti.
faces
Faces registered to the user. Refer to FaceData. You can register faces using SetFace or SetFaceMulti.
accessGroupIDs
Access group IDs to which the user belongs. Refer to AccessGroup. A user can belong to maximum 16 access groups. You can assign access groups using SetAccessGroup or SetAccessGroupMulti.
jobCodes
Job codes assigned to the user. Refer to JobCode. You can assign job codes using SetJobCode or SetJobCodeMulti.
PIN
PIN is maximum 16 bytes. For security, PIN is stored as a hash value. Refer to GetPINHash.
photo
A profile image can be stored per user. The maximum size is 16KB.

Information

GetList

Get the list of users registered to a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
Response
Parameter Type Description
hdrs UserHdr[] The header information of users registered to the device

Get

Get the user information with specific user IDs.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userIDs string[] The IDs of the users
Response
Parameter Type Description
users UserInfo[] The user information of the specified user IDs

GetPartial

Get the partial user information with specific user IDs. For example, if you need only the card and fingerprint information, you can specify the infoMask as USER_MASK_CARD | USER_MASK_FINGER. If the infoMask is USER_MASK_ALL, it is same with Get.

enum InfoMask {
  USER_MASK_ID_ONLY = 0x0000;
  USER_MASK_HDR	= 0x0001;
  USER_MASK_SETTING = 0x0002;
  USER_MASK_NAME = 0x0004;
  USER_MASK_PHOTO	= 0x0008;
  USER_MASK_PIN = 0x0010;
  USER_MASK_CARD = 0x0020;
  USER_MASK_FINGER = 0x0040;
  USER_MASK_FACE = 0x0080;
  USER_MASK_ACCESS_GROUP = 0x0100;
  USER_MASK_JOB = 0x0200;
  USER_MASK_ALL	= 0xFFFF;
}
Request
Parameter Type Description
deviceID uint32 The ID of the device
userIDs string[] Array of user IDs
infoMask uint32 Mask for the required information
Response
Parameter Type Description
users UserInfo[] The user information of the specified user IDs with the mask

Enroll

Enroll

Enroll users to a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
users UserInfo[] The information of the users to be enrolled
overwrite bool If true, overwrite the existing users with the same IDs. If false, return an error

EnrollMulti

Enroll users to multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
users UserInfo[] The information of the users to be enrolled
overwrite bool If true, overwrite the existing users with the same IDs. If false, return an error

Delete

Delete

Delete users from a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userIDs string[] The IDs of the users to be deleted

DeleteMulti

Delete users from multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
userIDs string[] The IDs of the users to be deleted

DeleteAll

Delete all users from a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device

DeleteAllMulti

Delete all users from multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices

Card

message UserCard {
  string userID;
  repeated card.CSNCardData cards;
}
cards
You can read a card using Card.Scan.

GetCard

Get the card information of the specified users.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userIDs string[] The IDs of the users whose card information will be returned
Response
Parameter Type Description
userCards UserCard[] The card information of the specified users

SetCard

Assign cards to users on a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userCards UserCard[] The card information to be stored in the device

SetCardMulti

Assign cards to users on multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
userCards UserCard[] The card information to be stored in the devices

Finger

message UserFinger {
  string userID;
  repeated finger.FingerData fingers;
}
fingers
You can acquire fingerprint templates using Finger.Scan.

GetFinger

Get the fingerprint information of the specified users.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userIDs string[] The IDs of the users whose fingerprint information will be returned
Response
Parameter Type Description
userFingers UserFinger[] The fingerprint information of the specified users

SetFinger

Register fingerprints to users on a device.

Parameter Type Description
deviceID uint32 The ID of the device
userFingers UserFinger[] The fingerprint information to be stored in the device

SetFingerMulti

Register fingerprints to users on multiple devices.

Parameter Type Description
deviceIDs uint32[] The IDs of the devices
userFingers UserFinger[] The fingerprint information to be stored in the devices

Face

message UserFace {
  string userID;
  repeated face.FaceData faces;
}
faces
You can get the face templates using Face.Scan.

GetFace

Get the face information of the specified users.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userIDs string[] The IDs of the users whose face information will be returned
Response
Parameter Type Description
userFaces UserFace[] The face information of the specified users

SetFace

Register face templates to users on a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userFaces UserFace[] The face information to be stored in the device

SetFaceMulti

Register face templates to users on multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
userFaces UserFace[] The face information to be stored in the devices

Access group

You can specify which doors are accessible to specific users by AccessGroup.

message UserAccessGroup {
  string userID;
  repeated uint32 accessGroupIDs;
}
accessGroupIDs
IDs of the access groups the user belongs to. Refer to AccessGroup.

GetAccessGroup

Get the access group IDs of the specified users.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userIDs string[] The IDs of the users whose access group IDs will be returned
Response
Parameter Type Description
userAccessGroups UserAccessGroup[] The access group IDs of the specified users

SetAccessGroup

Assign access groups to users on a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userAccessGroups UserAccessGroup[] The access group information to be stored in the device

SetAccessGroupMulti

Assign access groups to users on multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
userAccessGroups UserAccessGroup[] The access group information to be stored in the devices

Job code

Check CapabilityInfo.jobCodeSupported of the device first. You have to set the SystemConfig.useJobCode to true for recording job codes.

message UserJobCode {
  string userID;
  repeated tna.JobCode jobCodes;
}
jobCodes
Refer to TNA.JobCode.

GetJobCode

Get the job codes of the specified users.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userIDs string[] The IDs of the users whose job codes will be returned
Response
Parameter Type Description
userJobCodes UserJobCode[] The job code information of the specified users

SetJobCode

Assign job codes to users on a device.

Request
Parameter Type Description
deviceID uint32 The ID of the device
userJobCodes UserJobCode[] The job code information to be stored in the device

SetJobCodeMulti

Assign job codes to users on multiple devices.

Request
Parameter Type Description
deviceIDs uint32[] The IDs of the devices
userJobCodes UserJobCode[] The job code information to be stored in the devices

Utility

GetPINHash

For security, PIN is stored as a hash value. GetPINHash converts a pin to 32 byte hash value.

Request
Parameter Type Description
PIN string Maximum 16 bytes PIN
Response
Parameter Type Description
hashVal byte[] 32 bytes hash value of the PIN