Log Management API

API that controls the device log.

• BS2_GetLog: Gets certain amount of logs.
• BS2_GetFilteredLog: [Deprecated] Gets filtered logs.
• BS2_ClearLog: Deletes all logs.
• BS2_StartMonitoringLog: Starts Real-time log streaming.
• BS2_StartMonitoringLogEx: [+ V2.7.1] Starts Real-time log streaming including the temperature information.
• BS2_StopMonitoringLog: Stops Real-time log streaming.
• BS2_GetLogBlob: Gets certain amount of logs based on the event mask.
• BS2_GetFilteredLogSinceEventId: [Deprecated] Gets filtered logs.
• BS2_GetImageLog : Gets image logs using event ID.
• BS2_GetLogSmallBlob: [+ 2.6.4] Gets certain amount of logs based on the event mask in an efficient way.
• BS2_GetLogSmallBlobEx: [+ 2.7.1] Gets certain amount of logs based on the event mask in an efficient way, including the temperature information.

Callback function that is called when receiving a new log from the device.

typedef void (*OnLogReceived)(uint32_t deviceId, BS2Event* log);

1. deviceId
Device ID

2. log
New log information structure

[+ V2.7.1] Callback function that is called when receiving a new log from the device.
The temperature information is transferred as the 3rd parameter, and auditTemperature should be true in BS2FaceConfigExt.

typedef void (*OnLogReceivedEx)(uint32_t deviceId, BS2Event* log, uint32_t temperature);

1. deviceId
Device ID

2. log
New log information structure

3. temperature
Temperature information

typedef struct {
    uint32_t id;
    uint32_t dateTime;
    uint32_t deviceID;
    union {
        char userID[BS2_USER_ID_SIZE];
        uint32_t uid;
        uint32_t doorID;
        uint32_t liftID;
        uint32_t zoneID;
        struct {
            uint32_t ioDeviceID;
            uint16_t port;
            int8_t value;
            uint8_t reserved[25];
        };
        struct {
            uint32_t zoneID;
            uint32_t doorID;
            uint32_t ioDeviceID;
            uint16_t port;
            uint8_t reserved[18];
        } alarm;
        struct {
            uint32_t zoneID;
            uint32_t doorID[4];
            uint8_t reserved[12];
        } interlock;
        struct {
            uint16_t relayPort;
            uint16_t inputPort;
            uint8_t reserved[28];
        } relayAction;
        struct {
            BS2_DEVICE_ID deviceId;
            uint8_t data[28];
        } osdpStandard;
    };
    union {
        uint16_t code;
        struct {
            uint8_t subCode;
            uint8_t mainCode;
        };
    };
    uint8_t param;
#ifdef LESS_THAN_SDK_2_6_0
    BS2_BOOL image;         // Deprecated in V2.6.0
#else
    uint8_t image: 1;       // Supports image and DST by splitting bit unit
    uint8_t isDST: 1;
    uint8_t half: 1;
    uint8_t hour: 4;
    uint8_t negative: 1;
#endif
} BS2Event;

1. id
Log record ID which automatically increases from 1 when the log is generated.

2. dateTime
The time when the log has been generated. It means the seconds past from UTC until the current time.

3. deviceID
ID of the device that generated the log.

4. userID
User ID related to log. When the value is 0, the log is not relevant to user.

5. uid
You can refer to doorID regarding door log, zoneID regarding zone log. If you do not know exactly then you can refer to uid.
Since uid, doorID, liftID, zoneID are declared as union, basically it means information such as unordered list.

6. doorID
ID of the door that generated the log.

7. liftID
ID of the lift that generated the log.

8. zoneID
ID of the zone that generated the log.

9. ioDeviceID
Door or Input device ID. When the value is 0, the log is not relevant to Door or Input device.

10. port
Port for ioDeviceID.

11. value
Port value for ioDeviceID and means below.
BS2_PORT_VALUE_UNKNOWN : -1
BS2_PORT_VALUE_OPEN : 0
BS2_PORT_VALUE_CLOSED : 1
BS2_PORT_VALUE_SUPERVISED_SHORT : 2
BS2_PORT_VALUE_SUPERVISED_OPEN : 3

12. alarm.zoneID
Zone ID that makes intrusion alarm zone alarms.

13. alarm.doorID
Door ID that makes intrusion alarm zone alarms.

14. interlock.zoneID
Zone ID that makes interlock zone alarms.

15. interlock.doorID
Door ID that makes interlock zone alarms.

16. ​relayAction.relayPort
Relay port identifier when IM-120 RelayAction takes place.

17. ​relayAction.inputPort​
Relay port identifier when IM-120 RelayAction takes place.

18. osdpStandard.deviceId
Identifier of the OSDP standard device.

19. osdpStandard.data
This is notification structure information with a total size of 28 bytes generated from OSDP standard devices.
For detailed information about the structure, please refer to BS2OsdpStandardDeviceNotify.

20. subCode
Sub code value of log types. Use if the additional information is necessary.

21. mainCode
Main code value of log types.

22.param
It is used only when extra information on the device is needed. Usually, a time and attendance code, a port number of the door or input device is stored in the param argument. When a time and attendance code is stored, refer to the following values:

[+ 2.6.3] Additional feature of param
Only if the event code is relevant to the user.
If you add, modify or delete users directly from the device, param is 1, 0 if done through BioStar.
For example, if param was 1 with the event BS2_EVENT_USER_ENROLL_SUCCESS, it means the user was added directly on the device.
This feature is supported from the firmware version below.

23. image
Prior to SDK V2.6.0, it used the whole 1 byte and means below:
- Whether the image was included when the event occurred (true / false).

Since SDK V2.6.0, 1 byte has been changed to provide the following information by bit unit.
- Whether or not image is included. - Whether DST is applied

typedef struct {
    uint16_t eventMask;
    uint32_t id;
    BS2EventExtInfo info; 
    union
    {
	BS2_USER_ID userID;                       // valid if eventMask has BS2_EVENT_MASK_USER_ID
	uint8_t cardID[BS2_CARD_DATA_SIZE];       // valid if eventMask has BS2_EVENT_MASK_CARD_ID
	BS2_DOOR_ID doorID;                       // valid if eventMask has BS2_EVENT_MASK_DOOR_ID
	BS2_ZONE_ID zoneID;                       // valid if eventMask has BS2_EVENT_MASK_ZONE_ID
	BS2EventExtIoDevice ioDevice;             // valid if eventMask has BS2_EVENT_MASK_IODEVICE
    };
    uint8_t tnaKey;
    uint32_t jobCode;    
    uint16_t imageSize;
    uint8_t image[BS2_EVENT_MAX_IMAGE_SIZE];
    uint8_t reserved;
} BS2EventBlob;

1. eventMask
Event mask value. Logs will be retrieved based on the mask value such as user, card, door, or zone.

2. id
Log record ID which automatically increases from 1 when the log is generated.

3. info
BS2EventExtInfo structure information.

4. userID
User ID related to log. When the value is 0, the log is not relevant to user.

5. cardID
Card ID related to log. When the value is 0, the log is not relevant to card.
The device records card ID only for failure auth, it returns user ID when successful auth regardless of eventMask value.

6. doorID
Door ID related to log. When the value is 0, the log is not relevant to door.

7. zoneID
Zone ID related to log. When the value is 0, the log is not relevant to zone.

8. ioDevice
Door or input device ID related to log. When the value is 0, the log is not relevant to door or input. Refer to BS2EventExtIoDevice structure.

9. tnaKey
The T&A key that has been used for the authentication. When the value is 0, the log is not relevant to T&A key.

10. jobCode
The job code that has been used for the authentication. When the value is 0, the log is not relevant to job code.

11. imageSize
Size of the image when there is an image log.

12. image
Data of the image.

13. reserved
Reserved space.

typedef struct {
    uint32_t dateTime;
    uint32_t deviceID;    
    union {                                       ///< 2 bytes
		BS2_EVENT_CODE code;
		struct {
			uint8_t subCode;
			uint8_t mainCode;
		};
	};
	uint8_t reserved[2];
} BS2EventExtInfo;

1. dateTime
The time when the log has been generated. It means the seconds past from UTC until the current time.

2. deviceID
ID of the device that generated the log.

3. subCode
Sub code value of log types. Use if the additional information is necessary.

4. mainCode
Main code value of log types.

5. reserved
Reserved space.

typedef struct {
    uint32_t ioDeviceID;
    uint16_t port;    
    uint8_t value;
    uint8_t reserved[1];
} BS2EventExtInfo;

1. ioDeviceID
Door or input device ID related to log. When the value is 0, the log is not relevant to door or input.

2. port
Input port number.

3. value
Status of the input port.

4. reserved
Reserved space.

typedef struct {
    uint16_t eventMask;
    uint32_t id;
    BS2EventExtInfo info; 
    union
    {
	BS2_USER_ID userID;                       // valid if eventMask has BS2_EVENT_MASK_USER_ID
	uint8_t cardID[BS2_CARD_DATA_SIZE];       // valid if eventMask has BS2_EVENT_MASK_CARD_ID
	BS2_DOOR_ID doorID;                       // valid if eventMask has BS2_EVENT_MASK_DOOR_ID
	BS2_ZONE_ID zoneID;                       // valid if eventMask has BS2_EVENT_MASK_ZONE_ID
	BS2EventExtIoDevice ioDevice;             // valid if eventMask has BS2_EVENT_MASK_IODEVICE
    };
    uint8_t tnaKey;
    uint32_t jobCode;    
    uint16_t imageSize;
    uint8_t* imageObj;                        // valid if eventMask has BS2_EVENT_MASK_IMAGE
    uint8_t reserved;
} BS2EventSmallBlob;

1. eventMask
Event mask value. Logs will be retrieved based on the mask value such as user, card, door, or zone.

2. id
Log record ID which automatically increases from 1 when the log is generated.

3. info
BS2EventExtInfo structure information.

4. userID
User ID related to log. When the value is 0, the log is not relevant to user.

5. cardID
Card ID related to log. When the value is 0, the log is not relevant to card.
The device records card ID only for failure auth, it returns user ID when successful auth regardless of eventMask value.

6. doorID
Door ID related to log. When the value is 0, the log is not relevant to door.

7. zoneID
Zone ID related to log. When the value is 0, the log is not relevant to zone.

8. ioDevice
Door or input device ID related to log. When the value is 0, the log is not relevant to door or input. Refer to BS2EventExtIoDevice structure.

9. tnaKey
The T&A key that has been used for the authentication. When the value is 0, the log is not relevant to T&A key.

10. jobCode
The job code that has been used for the authentication. When the value is 0, the log is not relevant to job code.

11. imageSize
Size of the image when there is an image log.

12. imageObj
Data of the image.

13. reserved
Reserved space.

typedef struct {
    uint16_t eventMask;
    uint32_t id;
    BS2EventExtInfo info;                         // valid if eventMask has BS2_EVENT_MASK_INFO
    union
    {
        BS2_USER_ID userID;                       // valid if eventMask has BS2_EVENT_MASK_USER_ID
        uint8_t cardID[BS2_CARD_DATA_SIZE];       // valid if eventMask has BS2_EVENT_MASK_CARD_ID
        BS2_DOOR_ID doorID;                       // valid if eventMask has BS2_EVENT_MASK_DOOR_ID
        BS2_ZONE_ID zoneID;                       // valid if eventMask has BS2_EVENT_MASK_ZONE_ID
        BS2EventExtIoDevice ioDevice;             // valid if eventMask has BS2_EVENT_MASK_IODEVICE
    };
    uint8_t tnaKey;                               // valid if eventMask has BS2_EVENT_MASK_TNA_KEY
    uint32_t jobCode;                             // valid if eventMask has BS2_EVENT_MASK_JOB_CODE
    uint16_t imageSize;                           // valid if eventMask has BS2_EVENT_MASK_IMAGE
    uint8_t* imageObj;                            // valid if eventMask has BS2_EVENT_MASK_IMAGE
    uint8_t reserved;
    uint32_t temperature;                         // valid if eventMask has BS2_EVENT_MASK_TEMPERATURE
} BS2EventSmallBlobEx;

1. eventMask
Event mask value. Logs will be retrieved based on the mask value such as user, card, door, or zone.

2. id
Log record ID which automatically increases from 1 when the log is generated.

3. info
BS2EventExtInfo structure information.

4. userID
User ID related to log. When the value is 0, the log is not relevant to user.

5. cardID
Card ID related to log. When the value is 0, the log is not relevant to card.
The device records card ID only for failure auth, it returns user ID when successful auth regardless of eventMask value.

6. doorID
Door ID related to log. When the value is 0, the log is not relevant to door.

7. zoneID
Zone ID related to log. When the value is 0, the log is not relevant to zone.

8. ioDevice
Door or input device ID related to log. When the value is 0, the log is not relevant to door or input. Refer to BS2EventExtIoDevice structure.

9. tnaKey
The T&A key that has been used for the authentication. When the value is 0, the log is not relevant to T&A key.

10. jobCode
The job code that has been used for the authentication. When the value is 0, the log is not relevant to job code.

11. imageSize
Size of the image when there is an image log.

12. image
Data of the image.

13. temperature
Temperature information is set when there's a thermal camera installed and setting to record event logs. Refer to auditTemperature

14. reserved
Reserved.