src/dtk_list.c

   1 /** \ingroup KeyGeneration
   2  * @file
   3  * @author      David Llewellyn-Jones <david@flypig.co.uk>
   4  * @version     $(VERSION)
   5  *
   6  * @section LICENSE
   7  *
   8  * Copyright David Llewellyn-Jones, 2020
   9  * Released under the GPLv2.
  10  *
  11  * @brief Provides a list of DTKs
  12  * @section DESCRIPTION
  13  *
  14  * This class allows the simplified management of lists of Dtk objects. This is
  15  * useful when checking DTKs received from a Diagnosis Server with RPIs
  16  * captured over Bluetooth. Combined with the \ref RpiList class the two can
  17  * be easily stored and passed into the \ref match_list_find_matches() function.
  18  *
  19  */
  20
  21 /** \addtogroup Containers
  22  *  @{
  23  */
  24
  25 // Includes
  26
  27 #include <stdlib.h>
  28 #include <string.h>
  29 #include <stddef.h>
  30 #include <stdint.h>
  31
  32 #include "contrac/contrac.h"
  33 #include "contrac/utils.h"
  34 #include "contrac/log.h"
  35
  36 #include "contrac/dtk_list.h"
  37
  38 // Defines
  39
  40 // Structures
  41
  42 /**
  43  * @brief A DTK list element
  44  *
  45  * This is an opaque structure that represents a single item in the list and
  46  * contains a Dtk instance.
  47  *
  48  * The structure typedef is in dtk_list.h
  49  */
  50 struct _DtkListItem {
  51         Dtk * dtk;
  52         DtkListItem * next;
  53 };
  54
  55 /**
  56  * @brief The head of a DTK list
  57  *
  58  * This is an opaque structure that represents the head of a list of Dtk
  59  * items.
  60  *
  61  * This is the object usually passed as the first parameter of every non-static
  62  * function.
  63  *
  64  * The structure typedef is in dtk_list.h
  65  */
  66 struct _DtkList {
  67         DtkListItem * first;
  68         DtkListItem * last;
  69 };
  70
  71 // Function prototypes
  72
  73 // Function definitions
  74
  75 /**
  76  * Creates a new instance of the class.
  77  *
  78  * @return The newly created object.
  79  */
  80 DtkList * dtk_list_new() {
  81         DtkList * data;
  82
  83         data = calloc(sizeof(DtkList), 1);
  84
  85         return data;
  86 }
  87
  88 /**
  89  * Deletes an instance of the class, freeing up the memory allocated to it.
  90  *
  91  * This will also delete all items contained in the list.
  92  *
  93  * @param data The instance to free.
  94  */
  95 void dtk_list_delete(DtkList * data) {
  96         DtkListItem * item;
  97         DtkListItem * next;
  98
  99         if (data) {
 100                 item = data->first;
 101                 while (item) {
 102                         next = item->next;
 103                         dtk_delete(item->dtk);
 104                         free(item);
 105                         item = next;
 106                 }
 107
 108                 free(data);
 109         }
 110 }
 111
 112 /**
 113  * Adds an item to the list.
 114  *
 115  * This adds a Dtk item to the list. It's primarily for internal use and when
 116  * adding DTKs to the list it's usually more appropriate to use the
 117  * \ref dtk_list_add_diagnosis() function.
 118  *
 119  * @param data The list to append to.
 120  * @param dtk The DTK to append.
 121  */
 122 void dtk_list_append(DtkList * data, Dtk * dtk) {
 123         DtkListItem * item;
 124
 125         item = calloc(sizeof(DtkListItem), 1);
 126         item->dtk = dtk;
 127
 128         if (data->last == NULL) {
 129                 data->first = item;
 130                 data->last = item;
 131         }
 132         else {
 133                 data->last->next = item;
 134                 data->last = item;
 135         }
 136 }
 137
 138 /**
 139  * Returns the first item in the list.
 140  *
 141  * Useful for iterating through the items in the list.
 142  *
 143  * @param data The list to operate on.
 144  * @return The first item of the list.
 145  */
 146 DtkListItem const * dtk_list_first(DtkList const * data) {
 147         return data->first;
 148 }
 149
 150 /**
 151  * Returns the next item in the list.
 152  *
 153  * Useful for iterating through the items in the list.
 154  *
 155  * @param data The current item in the list.
 156  * @return The next item in the list following the current item.
 157  */
 158 DtkListItem const * dtk_list_next(DtkListItem const * data) {
 159         return data->next;
 160 }
 161
 162 /**
 163  * Returns the Dtk item contained in this list item.
 164  *
 165  * @param data The current item in the list.
 166  * @return The Dtk instance stored in the list element.
 167  */
 168 Dtk const * dtk_list_get_dtk(DtkListItem const * data) {
 169         return data->dtk;
 170 }
 171
 172 /**
 173  * Adds Dtk data to the list.
 174  *
 175  * The dtk_bytes buffer passed in must contain exactly DTK_SIZE (16) bytes of
 176  * data. It doen't have to be null terminated.
 177  *
 178  * @param data The current list to operate on.
 179  * @param dtk_bytes The DTK value to add, in binary format.
 180  * @param day_number The day number to associate with the DTK.
 181  */
 182 void dtk_list_add_diagnosis(DtkList * data, unsigned char const * dtk_bytes, uint32_t day_number) {
 183         Dtk * dtk = dtk_new();
 184         dtk_assign(dtk, dtk_bytes, day_number);
 185         dtk_list_append(data, dtk);
 186 }
 187
 188 /** @} addtogroup Containers*/
 189