/**
 * @file users.h
 * @brief User list management for LightTAM.
 *
 * Contains structures and functions for working with the user linked list,
 * including synchronization using a mutex.
 */

#include "main.h"

#ifndef __USERS_H__
#define __USERS_H__

/**
 * @struct person
 * @brief Structure representing a single user.
 */
typedef struct person
{
    uint16_t uuid;           ///< Unique user identifier
    char *name;              ///< First name
    char *surname;           ///< Last name
    uint32_t department;     ///< Department number
    time_t last_time_event;  ///< Last event timestamp
    time_t total;            ///< Total presence time
    BYTE available;          ///< Presence state (TRUE/FALSE)
} person_t;

/**
 * @struct node
 * @brief Node of the user linked list.
 */
typedef struct node
{
    person_t user;       ///< User data
    struct node *next;   ///< Pointer to the next node
} node_t;

/**
 * @struct list
 * @brief User linked list with a mutex for synchronization.
 */
typedef struct list
{
    node_t *head;            ///< List head
    pthread_mutex_t lock;    ///< Mutex for access synchronization
} list_t;

/**
 * @brief Generate a unique UUID not used in the list.
 * @param _list Pointer to the user list
 * @return New UUID
 */
uint16_t generateUUID(list_t *_list);

/**
 * @brief Find all UUIDs by name and surname.
 * @param _list Pointer to the user list
 * @param _name First name
 * @param _surname Last name
 * @param _uuids_found Pointer to an array of found UUIDs (allocated inside the function)
 * @return Number of found UUIDs
 */
uint16_t searchUUIDByName(list_t *_list, char *_name, char *_surname, uint16_t **_uuids_found);

/**
 * @brief Find a user by UUID.
 * @param _list Pointer to the user list
 * @param _uuid Searched UUID
 * @return Pointer to the found node, or NULL if not found
 */
node_t *searchPersonByUUID(list_t *_list, uint16_t _uuid);

/**
 * @brief Add a new user to the list.
 * @param _list Pointer to the user list
 * @param _name First name
 * @param _surname Last name
 * @param _department Department
 * @return 1 on success, 0 on error
 */
int addPersonToList(list_t *_list, char *_name, char *_surname, uint32_t _department);

/**
 * @brief Load a user into the list (e.g. when loading from file).
 * @param _list Pointer to the user list
 * @param _uuid UUID
 * @param _name First name
 * @param _surname Last name
 * @param _department Department
 * @param _last_event Last event time
 * @param _total Total time
 * @param _available Presence state
 * @return 1 on success, 0 on error
 */
int loadPersonToList(list_t *_list, uint16_t _uuid, char *_name, char *_surname, uint32_t _department, time_t _last_event, time_t _total, BYTE _available);

/**
 * @brief Add a time event for a user (arrival/departure).
 * @param _person Pointer to the user node
 * @param _list Pointer to the user list
 * @return Event type (1 = arrival, 2 = departure)
 */
int addTimeEvent(node_t *_person, list_t *_list);

/**
 * @brief Remove a user from the list.
 * @param _list Pointer to the user list
 * @param _person Pointer to the pointer to the node to remove
 * @return 1 on success, 0 on error
 */
int removePersonFromList(list_t *_list, node_t **_person);

/**
 * @brief Free the entire user list from memory.
 * @param _list Pointer to the pointer to the user list
 */
void freePersonList(list_t ** _list);

#endif