Diff: request.h

Revision:

24:8319d71d6749

Parent:

7:1bed29e1b0a4

Child:

25:7adc1d174b74

--- a/request.h	Wed Oct 21 15:13:08 2015 +0000
+++ b/request.h	Wed Oct 21 15:41:11 2015 +0000
@@ -2,11 +2,76 @@
 
 #include "cantcoap.h"
 
+
+/** Coap Request class
+ * This class contains the coap request. It let's all the information from the request to process a response.
+ */
 class Request : protected CoapPDU
 {
     public:
+    /**  Memory-managed constructor. Buffer for PDU is dynamically sized and allocated by the object.
+     * When using this constructor, the CoapPDU class will allocate space for the PDU.
+     * Contrast this with the parameterized constructors, which allow the use of an external buffer.
+     *
+     * Note, the PDU container and space can be reused by issuing a CoapPDU::reset(). If the new PDU exceeds the 
+     * space of the previously allocated memory, then further memory will be dynamically allocated.
+     *
+     * Deleting the object will free the Object container and all dynamically allocated memory.
+     *
+     * \note It would have been nice to use something like UDP_CORK or MSG_MORE, to allow separate buffers 
+     * for token, options, and payload but these FLAGS aren't implemented for UDP in LwIP so stuck with one buffer for now.
+     *
+     * CoAP version defaults to 1.
+     *
+     * \sa CoapPDU::CoapPDU(uint8_t *pdu, int pduLength), CoapPDU::CoapPDU::(uint8_t *buffer, int bufferLength, int pduLength), 
+     * CoapPDU:CoapPDU()~
+     *
+     */
     Request();
+    
+    /** Memory-managed constructor. Buffer for PDU is dynamically sized and allocated by the object.
+     * When using this constructor, the CoapPDU class will allocate space for the PDU.
+     * Contrast this with the parameterized constructors, which allow the use of an external buffer.
+     *
+     * Note, the PDU container and space can be reused by issuing a CoapPDU::reset(). If the new PDU exceeds the 
+     * space of the previously allocated memory, then further memory will be dynamically allocated.
+     *
+     * Deleting the object will free the Object container and all dynamically allocated memory.
+     *
+     * \note It would have been nice to use something like UDP_CORK or MSG_MORE, to allow separate buffers 
+     * for token, options, and payload but these FLAGS aren't implemented for UDP in LwIP so stuck with one buffer for now.
+     *
+     * CoAP version defaults to 1.
+     *
+     * \sa CoapPDU::CoapPDU(uint8_t *pdu, int pduLength), CoapPDU::CoapPDU::(uint8_t *buffer, int bufferLength, int pduLength), 
+     * CoapPDU:CoapPDU()~
+     *
+     */
     Request(uint8_t *pdu, int pduLength);
+
+    /** Construct a PDU using an external buffer. No copy of the buffer is made.
+     * This constructor is normally used where a PDU has been received over the network, and it's length is known.
+     * In this case the CoapPDU object is probably going to be used as a temporary container to access member values.
+     *
+     * It is assumed that \b pduLength is the length of the actual CoAP PDU, and consequently the buffer will also be this size,
+     * contrast this with CoapPDU::CoapPDU(uint8_t *buffer, int bufferLength, int pduLength) which allows the buffer to 
+     * be larger than the PDU.
+     *
+     * A PDU constructed in this manner must be validated with CoapPDU::validate() before the member variables will be accessible.
+     *
+     * \warning The validation call parses the PDU structure to set some internal parameters. If you do
+     * not validate the PDU, then the behaviour of member access functions will be undefined.
+     * 
+     * The buffer can be reused by issuing a CoapPDU::reset() but the class will not change the size of the buffer. If the
+     * newly constructed PDU exceeds the size of the buffer, the function called (for example CoapPDU::addOption) will fail.
+     *
+     * Deleting this object will only delete the Object container and will not delete the PDU buffer.
+     *
+     * @param pdu A pointer to an array of bytes which comprise the CoAP PDU
+     * @param pduLength The length of the CoAP PDU pointed to by \b pdu
+    
+     * \sa CoapPDU::CoapPDU(), CoapPDU::CoapPDU(uint8_t *buffer, int bufferLength, int pduLength)
+     */
     Request(uint8_t *buffer, int bufferLength, int pduLength);
     
     using CoapPDU::Type;
@@ -15,8 +80,19 @@
     using CoapPDU::getType;
     using CoapPDU::getCode;
     
+    /** Get the payload content send with the request
+     *  @return Pointer to the content
+     */
     char* getContent();
+    
+    /** Get the lenght of the content
+     *  @return integer containing the length of the content
+     */
     int getContentLength();
+    
+    /** Check if the request has content
+     *  @return boolean value depending on if the request contains any content
+     */
     int hasContent();
     
     /*