README.md

   1 # libcontrac ReadMe
   2
   3 libcontrac is an implementation of the Contact Traing API.
   4
   5 ## Install
   6
   7 If you have autoconf you can install as follows.
   8
   9 ````
  10 ./configure
  11 make
  12 make check
  13 make install
  14 ```
  15
  16 ## Usage
  17
  18 Include header files.
  19 ```
  20 #include "contrac/contrac.h"
  21 #include "contrac/rpi.h"
  22 #include "contrac/dtk.h"
  23 #include "contrac/rpi_list.h"
  24 #include "contrac/rpi_list.h"
  25 #include "contrac/matches.h"
  26 ```
  27
  28 ### Broadcasting and uploading keys
  29
  30 Most of the functionality revolves around the Conrac structure.
  31
  32 Create and initialise the structure as follows. The day and interval number
  33 should be set appropriately.
  34 ```
  35 Contrac * contrac = contrac_new();
  36 contrac_generate_tracing_key(contrac);
  37 contrac_set_day_number(contrac, 23);
  38 contrac_set_time_interval_number(contrac, 76);
  39 ```
  40
  41 Get the Rolling Proxmity Identifier for broadcast in Bluetooth beacons.
  42 ```
  43 // Returns a buffer containing RPI_SIZE bytes of data
  44 const unsigned char * rpi = contrac_get_proximity_id(contrac);
  45 ```
  46
  47 Get the Daily Tracing Key to upload to a Diagnosis Server in case of a positive
  48 test result.
  49 ```
  50 // Returns a buffer containing DTK_SIZE bytes of data
  51 const unsigned char * dtk = contrac_get_daily_key(contrac);
  52 ```
  53
  54 ### Receiving and matching keys
  55
  56 Add RPIs captured via Bluetooth to an RPI list.
  57 ```
  58 RpiList * rpis = rpi_list_new();
  59 Rpi * rpi = rpi_new();
  60
  61 // Add captured bytes at given time
  62 rpi_assign(rpi, captured_bytes, time_interval_number);
  63 rpi_list_append(rpis, rpi);
  64 ```
  65
  66 Construct a list of DTKs from data downloaded from a Diagnosis Server.
  67 ```
  68 DtkList * dtks = dtk_list_new();
  69 Dtk * dtk = dtk_new();
  70
  71 // Add data downloaded from the server
  72 dtk_assign(dtk, dtk_bytes, day_number);
  73 dtk_list_append(dtks, dtk);
  74 ```
  75
  76 Having collected these two lists any matches can be tested for as follows.
  77
  78 ```
  79 MatchList * matches = match_list_new();
  80 match_list_find_matches(matches, rpis, dtks);
  81
  82 if (match_list_count(matches) > 0) {
  83         printf("Exposure identified, follow medical advice\n");
  84 }
  85 ```
  86
  87 ### Cleaning up
  88
  89 Finally, clean up.
  90 ```
  91 match_list_delete(matches);
  92 rpi_list_delete(rpis);
  93 dtk_list_delete(dtks);
  94 contrac_delete(contrac);
  95 ```
  96
  97 ## Licence
  98
  99 Copyright (c) David Llewellyn-Jones, 2020
 100
 101 libcontrac is released under the GPL v2 Licence. Read COPYING for information on the license.
 102
 103 ## Contact and Links
 104
 105 More information can be found at: https://www.flypig.co.uk/contrac
 106
 107 The source code can be obtained from git:
 108
 109 git clone git@www.flypig.org.uk:libcontrac
 110
 111 I can be contacted via one of the following.
 112
 113  * My website: https://www.flypig.co.uk
 114  * Email: at david@flypig.co.uk
 115