Update project files and headers: ensure consistency and maintainability across the codebase.
This commit is contained in:
+76
-85
@@ -1,129 +1,120 @@
|
||||
/**
|
||||
* @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;
|
||||
|
||||
char *name;
|
||||
char *surname;
|
||||
uint32_t department;
|
||||
|
||||
time_t last_time_event;
|
||||
time_t total;
|
||||
|
||||
BYTE available;
|
||||
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;
|
||||
struct node *next;
|
||||
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;
|
||||
pthread_mutex_t lock;
|
||||
|
||||
node_t *head; ///< List head
|
||||
pthread_mutex_t lock; ///< Mutex for access synchronization
|
||||
} list_t;
|
||||
|
||||
/**
|
||||
* @brief Generates a unique identifier (UUID) for a new node in the linked list.
|
||||
*
|
||||
* This function traverses the linked list starting from the given head node
|
||||
* and generates a unique 16-bit unsigned integer identifier that does not
|
||||
* conflict with any existing UUIDs in the list.
|
||||
*
|
||||
* @param _head Pointer to the head node of the linked list.
|
||||
* @return A 16-bit unsigned integer representing the generated UUID.
|
||||
* @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 Searches for a UUID associated with a user by their name and surname.
|
||||
*
|
||||
* This function traverses a linked list of nodes to find a user whose name
|
||||
* and surname match the provided parameters. If a match is found, it returns
|
||||
* a pointer to the UUID associated with that user.
|
||||
*
|
||||
* @param _head Pointer to the head of the linked list.
|
||||
* @param _name Pointer to a string containing the user's first name.
|
||||
* @param _surname Pointer to a string containing the user's surname.
|
||||
* @return Pointer to the UUID of the user if found, or 0 if no match is found.
|
||||
* @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 Searches for a person in a linked list by their UUID.
|
||||
*
|
||||
* This function traverses a linked list starting from the given head node
|
||||
* and searches for a node that matches the specified UUID.
|
||||
*
|
||||
* @param _head Pointer to the head node of the linked list.
|
||||
* @param _uuid The UUID of the person to search for.
|
||||
* @return Pointer to the node containing the person with the matching UUID,
|
||||
* or NULL if no such person is 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 Adds a new person to the linked list.
|
||||
*
|
||||
* This function creates a new person and appends it to the end of the linked list.
|
||||
* It dynamically allocates memory for the new person and initializes their details.
|
||||
* If memory allocation fails or the input parameters are invalid, the function returns an error.
|
||||
*
|
||||
* @param _head Pointer to the head of the linked list (node_t **).
|
||||
* @param _name Pointer to a string containing the person's first name.
|
||||
* @param _surname Pointer to a string containing the person's last name.
|
||||
* @param _department The department number to which the person belongs.
|
||||
*
|
||||
* @return int Returns 1 if the person was successfully added, otherwise 0 on failure.
|
||||
*
|
||||
* @note Memory for the name and surname is dynamically allocated. It is the caller's
|
||||
* responsibility to free the memory for the entire list to avoid memory leaks.
|
||||
*
|
||||
* @example
|
||||
* ```c
|
||||
* node_t *head = NULL;
|
||||
* if (addPersonToList(&head, "John", "Doe", 101)) {
|
||||
* printf("Person successfully added.\n");
|
||||
* } else {
|
||||
* printf("Error adding person.\n");
|
||||
* }
|
||||
* ```
|
||||
* @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 Adds a time event to the specified person's event list.
|
||||
*
|
||||
* This function associates a time-based event with the given person node.
|
||||
*
|
||||
* @param _person A pointer to the node_t structure representing the person
|
||||
* to whom the time event will be added.
|
||||
*
|
||||
* @return An integer indicating the success or failure of the operation.
|
||||
* Typically, 1 for success and a 0 for failure.
|
||||
* @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 Removes a person node from a linked list.
|
||||
*
|
||||
* This function removes the node pointed to by _person from the linked list
|
||||
* whose head is pointed to by _head. Both parameters are double pointers to
|
||||
* allow modification of the head pointer and the node pointer.
|
||||
*
|
||||
* @param _head Double pointer to the head of the linked list.
|
||||
* @param _person Double pointer to the node representing the person to remove.
|
||||
* @return int Returns 0 on success, or a negative value on failure.
|
||||
* @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
|
||||
Reference in New Issue
Block a user