X-Git-Url: https://www.flypig.org.uk/git/?p=libcontrac.git;a=blobdiff_plain;f=src%2Frpi.c;h=dce9f44ba486d8bb360c2354eab4003d50b00ca3;hp=abef1bd6074719c73a0ebb683c998bde988bfc67;hb=e48c390a86b448137a87d0d0a5863c202ba66abd;hpb=f8c83387f5abffa94e59332382441a71f5b95545

diff --git a/src/rpi.c b/src/rpi.c
index abef1bd..dce9f44 100644
--- a/src/rpi.c
+++ b/src/rpi.c
@@ -1,19 +1,26 @@
-/** \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
+ *  @{
+ */
+
 // Includes
 
 #include <stdlib.h>
@@ -33,10 +40,25 @@
 
 // Defines
 
+/**
+ * Used internally.
+ *
+ * This is the prefix for the Info parameter provided to the HMAC and used to
+ * generate the RPI.
+ */
 #define RPI_INFO_PREFIX "CT-RPI"
 
 // Structures
 
+/**
+ * @brief The structure used to represent a Rolling Proximity Identifier.
+ *
+ * This is an opaque structure that contains information about the RPI..
+ *
+ * This must be passed as the first parameter of every non-static function.
+ *
+ * The structure typedef is in dtk.h
+ */
 struct _Rpi {
 	// Rolling proximity identifier
 	unsigned char rpi[RPI_SIZE];
@@ -47,6 +69,11 @@ struct _Rpi {
 
 // Function definitions
 
+/**
+ * Creates a new instance of the class.
+ *
+ * @return The newly created object.
+ */
 Rpi * rpi_new() {
 	Rpi * data;
 	
@@ -55,6 +82,11 @@ Rpi * rpi_new() {
 	return data;
 }
 
+/**
+ * Deletes an instance of the class, freeing up the memory allocated to it.
+ *
+ * @param data The instance to free.
+ */
 void rpi_delete(Rpi * data) {
 	if (data) {
 		// Clear the data for security
@@ -64,6 +96,21 @@ void rpi_delete(Rpi * data) {
 	}
 }
 
+/**
+ * Generates a Rolling Proximity Identifier based on the time interval number
+ * provided.
+ *
+ * The operation may fail under certain circumstances, such as if the
+ * HMAC operation fails for some reason.
+ *
+ * For internal use. It generally makes more sense to use the
+ * contrac_set_time_interval_number() function instead.
+ *
+ * @param data The context object to work with.
+ * @param time_interval_number The time interval number to use to generate the
+ *        key.
+ * @return true if the operation completed successfully, false otherwise.
+ */
 bool rpi_generate_proximity_id(Rpi * data, Dtk const * dtk, uint8_t time_interval_number) {
 	int result = 1;
 	unsigned char encode[sizeof(RPI_INFO_PREFIX) + sizeof(time_interval_number)];
@@ -110,20 +157,72 @@ bool rpi_generate_proximity_id(Rpi * data, Dtk const * dtk, uint8_t time_interva
 	return (result > 0);
 }
 
-const unsigned char * rpi_get_proximity_id(Rpi const * data) {
+/**
+ * Gets the Rolling Proximity Identifier for the device in binary format.
+ *
+ * For internal use. It generally makes more sense to use the
+ * contrac_get_proximity_id() function instead.
+ *
+ * This allows the Rolling Proximity Identifier to be extracted. The Rolling
+ * Proximity Identifier is public, in the sense that it is usual to broadcast
+ * the value in Bluetooth beacons.
+ *
+ * The buffer returned will contain exactly RPI_SIZE (16) bytes of data in
+ * binary format. This may therefore contain null bytes, and the buffer will not
+ * necessarily be null terminated. Future operations may cause the data to
+ * change, so the caller should make a copy of the buffer rather than keeping
+ * a pointer to it.
+ *
+ * @param data The context object to work with.
+ * @return The Rolling Proximity Identifier in binary format, not null
+ *         terminated.
+ */
+unsigned char const * rpi_get_proximity_id(Rpi const * data) {
 	return data->rpi;
 }
 
+/**
+ * Gets the time interval number that applies to the current RPI.
+ *
+ * For internal use. It generally makes more sense to use the
+ * contrac_set_time_interval_number() function instead.
+ *
+ * @param data The context object to work with.
+ * @return The time interval number stored in the object.
+ */
 uint8_t rpi_get_time_interval_number(Rpi const * data) {
 	return data->time_interval_number;
 }
 
-
+/**
+ * Populates the data structure.
+ *
+ * Allows the RPI and time interval number values of the object to be set
+ * explicitly.
+ *
+ * For internal use. To set the RPI it generally makes more sense to use one of
+ * eiher contrac_set_time_interval_number() or contrac_update_current_time()
+ * instead.
+ *
+ * The rpi_bytes buffer passed in must contain exactly RPI_SIZE (16) bytes of
+ * data. It doen't have to be null terminated.
+ *
+ * @param data The context object to work with.
+ * @param rpi_bytes The RPI value to set, in binary format.
+ * @param day_number The time interval number to associate with this RPI.
+ */
 void rpi_assign(Rpi * data, unsigned char const * rpi_bytes, uint8_t time_interval_number) {
 	memcpy(data->rpi, rpi_bytes, RPI_SIZE);
 	data->time_interval_number = time_interval_number;
 }
 
+/**
+ * Compares two RPI values.
+ *
+ * @param data The RPI to compare with.
+ * @param comparitor The RPI to compare against.
+ * @return true if the two RPIs are the same, false otherwise.
+ */
 bool rpi_compare(Rpi const * data, Rpi const * comparitor) {
 	unsigned char left[RPI_SIZE_BASE64 + 1];
 	unsigned char right[RPI_SIZE_BASE64 + 1];
@@ -138,4 +237,5 @@ bool rpi_compare(Rpi const * data, Rpi const * comparitor) {
 	return (memcmp(data, comparitor, RPI_SIZE) == 0);
 }
 
+/** @} addtogroup RandomProximityIdentifier */