X-Git-Url: https://www.flypig.org.uk/git/?a=blobdiff_plain;f=include%2Fcontrac%2Frpi.h;h=133edf2c331276fa964d108f196291b6410d4fe1;hb=e48c390a86b448137a87d0d0a5863c202ba66abd;hp=9da8e627b13de23fb4d7a7c0d4a0f1242f077195;hpb=8515bbba069347de07a452586d7e49a2e8bdf151;p=libcontrac.git

diff --git a/include/contrac/rpi.h b/include/contrac/rpi.h
index 9da8e62..133edf2 100644
--- a/include/contrac/rpi.h
+++ b/include/contrac/rpi.h
@@ -1,17 +1,24 @@
-/** \ingroup contrac
+/** \ingroup RandomProximityIdentifier
  * @file
- * @author	David Llewellyn-Jones
+ * @author	David Llewellyn-Jones <david@flypig.co.uk>
  * @version	$(VERSION)
  *
  * @section LICENSE
  *
+ * Copyright David Llewellyn-Jones, 2020
+ * Released under the GPLv2.
  *
- *
- * @brief
+ * @brief Random Proximity Identifier functionality
  * @section DESCRIPTION
  *
+ * This class is used to generate and manage the Random Proximity Identifier
+ * (RPI). It's largely internal. The functionality from \ref Contrac should
+ * generally be used in preference to this.
  *
- *
+ */
+
+/** \addtogroup RandomProximityIdentifier
+ *  @{
  */
 
 #ifndef __RPI_H
@@ -24,12 +31,34 @@
 
 // Defines
 
+/**
+ * The size in bytes of an RPI in binary format.
+ *
+ */
 #define RPI_SIZE (16)
-#define RPI_INTERVAL_MAX (144)
+
+/**
+ * The size in bytes of an RPI in base64 format, not including the null
+ * terminator.
+ *
+ */
 #define RPI_SIZE_BASE64 (24)
 
+/**
+ * The maximum value a time interval number can take. Time interval numbers
+ * are measured from the start of the day and increment every 10 minutes, so
+ * must fall within the interval [0, 143].
+ *
+ */
+#define RPI_INTERVAL_MAX (144)
+
 // Structures
 
+/**
+ * An opaque structure for representing a DTK.
+ *
+ * The internal structure can be found in rpi.c
+ */
 typedef struct _Rpi Rpi;
 
 // Function prototypes
@@ -38,7 +67,7 @@ Rpi * rpi_new();
 void rpi_delete(Rpi * data);
 
 bool rpi_generate_proximity_id(Rpi * data, Dtk const * dtk, uint8_t time_interval_number);
-const unsigned char * rpi_get_proximity_id(Rpi const * data);
+unsigned char const * rpi_get_proximity_id(Rpi const * data);
 uint8_t rpi_get_time_interval_number(Rpi const * data);
 void rpi_assign(Rpi * data, unsigned char const * rpi_bytes, uint8_t time_interval_number);
 bool rpi_compare(Rpi const * data, Rpi const * comparitor);
@@ -47,4 +76,5 @@ bool rpi_compare(Rpi const * data, Rpi const * comparitor);
 
 #endif // __RPI_H
 
+/** @} addtogroup RandomProximityIdentifier */