Merge pull request #6588 from hasnainvirk/base_structs

[IOTCELL-741] Separating public data structures

Author: Cruz Monrreal

features/lorawan/LoRaWANBase.h

@@ -19,8 +19,8 @@
 #ifndef LORAWAN_BASE_H_
 #define LORAWAN_BASE_H_
 
-#include "system/lorawan_data_structures.h"
 #include "events/EventQueue.h"
+#include "lorawan_types.h"
 
 class LoRaWANBase {
 
@@ -286,38 +286,6 @@ class LoRaWANBase {
     virtual int16_t receive(uint8_t* data, uint16_t length, uint8_t& port, int& flags) = 0;
 
     /** Add application callbacks to the stack.
-     *
-     * 'lorawan_app_callbacks_t' is a structure that holds pointers to the application
-     * provided methods which are needed to be called in response to certain
-     * requests. The structure is default constructed to set all pointers to NULL.
-     * So if the user does not provide the pointer, a response will not be posted.
-     * However, the 'lorawan_events' callback is mandatory to be provided as it
-     * contains essential events.
-     *
-     * Events that can be posted to user via 'lorawan_events' are:
-     *
-     * CONNECTED            - When the connection is complete
-     * DISCONNECTED         - When the protocol is shut down in response to disconnect()
-     * TX_DONE              - When a packet is sent
-     * TX_TIMEOUT,          - When stack was unable to send packet in TX window
-     * TX_ERROR,            - A general TX error
-     * TX_CRYPTO_ERROR,     - If MIC fails, or any other crypto relted error
-     * TX_SCHEDULING_ERROR, - When stack is unable to schedule packet
-     * RX_DONE,             - When there is something to receive
-     * RX_TIMEOUT,          - Not yet mapped
-     * RX_ERROR             - A general RX error
-     *
-     * Other responses to certain standard requests are an item for the future.
-     * For example, a link check request could be sent whenever the device tries
-     * to send a message and if the network server responds with a link check resposne,
-     * the stack notifies the application be calling the appropriate method. For example,
-     * 'link_check_resp' callback could be used to collect a response for a link check
-     * request MAC command and the result is thus transported to the application
-     * via callback function provided.
-     *
-     * As can be seen from declaration, mbed::Callback<void(uint8_t, uint8_t)> *link_check_resp)
-     * carries two parameters. First one is Demodulation Margin and the second one
-     * is number of gateways involved in the path to network server.
      *
      * An example of using this API with a latch onto 'lorawan_events' could be:
      *
@@ -352,6 +320,9 @@ class LoRaWANBase {
      *
      * @param callbacks         A pointer to the structure containing application
      *                          callbacks.
+     *
+     * @return                  LORAWAN_STATUS_OK on success, a negative error
+     *                          code on failure.
      */
     virtual lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks) = 0;
 

features/lorawan/LoRaWANInterface.h

@@ -383,73 +383,44 @@ class LoRaWANInterface: public LoRaWANBase {
     virtual int16_t receive(uint8_t* data, uint16_t length, uint8_t& port, int& flags);
 
     /** Add application callbacks to the stack.
-       *
-       * 'lorawan_app_callbacks' is a structure that holds pointers to the application
-       * provided methods which are needed to be called in response to certain
-       * requests. The structure is default constructed to set all pointers to NULL.
-       * So if the user does not provide the pointer, a response will not be posted.
-       * However, the 'lorawan_events' callback is mandatory to be provided as it
-       * contains essential events.
-       *
-       * Events that can be posted to user via 'lorawan_events' are:
-       *
-       * CONNECTED            - When the connection is complete
-       * DISCONNECTED         - When the protocol is shut down in response to disconnect()
-       * TX_DONE              - When a packet is sent
-       * TX_TIMEOUT,          - When stack was unable to send packet in TX window
-       * TX_ERROR,            - A general TX error
-       * TX_CRYPTO_ERROR,     - If MIC fails, or any other crypto relted error
-       * TX_SCHEDULING_ERROR, - When stack is unable to schedule packet
-       * RX_DONE,             - When there is something to receive
-       * RX_TIMEOUT,          - Not yet mapped
-       * RX_ERROR             - A general RX error
-       *
-       * Other responses to certain standard requests are an item for the future.
-       * For example, a link check request could be sent whenever the device tries
-       * to send a message and if the network server responds with a link check resposne,
-       * the stack notifies the application be calling the appropriate method. For example,
-       * 'link_check_resp' callback could be used to collect a response for a link check
-       * request MAC command and the result is thus transported to the application
-       * via callback function provided.
-       *
-       * As can be seen from declaration, mbed::Callback<void(uint8_t, uint8_t)> *link_check_resp)
-       * carries two parameters. First one is Demodulation Margin and the second one
-       * is number of gateways involved in the path to network server.
-       *
-       * An example of using this API with a latch onto 'lorawan_events' could be:
-       *
-       * LoRaWANInterface lorawan(radio);
-       * lorawan_app_callbacks cbs;
-       * static void my_event_handler();
-       *
-       * int main()
-       * {
-       * lorawan.initialize(&queue);
-       *  cbs.events = mbed::callback(my_event_handler);
-       *  lorawan.add_app_callbacks(&cbs);
-       *  lorawan.connect();
-       * }
-       *
-       * static void my_event_handler(lora_events_t events)
-       * {
-       *  switch(events) {
-       *      case CONNECTED:
-       *          //do something
-       *          break;
-       *      case DISCONNECTED:
-       *          //do something
-       *          break;
-       *      case TX_DONE:
-       *          //do something
-       *          break;
-       *      default:
-       *          break;
-       *  }
-       * }
-       *
-       * @param callbacks         A pointer to the structure containing application
-       *                          callbacks.
-       */
+     *
+     * An example of using this API with a latch onto 'lorawan_events' could be:
+     *
+     * LoRaWANInterface lorawan(radio);
+     * lorawan_app_callbacks_t cbs;
+     * static void my_event_handler();
+     *
+     * int main()
+     * {
+     * lorawan.initialize();
+     *  cbs.lorawan_events = mbed::callback(my_event_handler);
+     *  lorawan.add_app_callbacks(&cbs);
+     *  lorawan.connect();
+     * }
+     *
+     * static void my_event_handler(lora_events_t events)
+     * {
+     *  switch(events) {
+     *      case CONNECTED:
+     *          //do something
+     *          break;
+     *      case DISCONNECTED:
+     *          //do something
+     *          break;
+     *      case TX_DONE:
+     *          //do something
+     *          break;
+     *      default:
+     *          break;
+     *  }
+     * }
+     *
+     * @param callbacks         A pointer to the structure containing application
+     *                          callbacks.
+     *
+     * @return                  LORAWAN_STATUS_OK on success, a negative error
+     *                          code on failure.
+     */
     virtual lorawan_status_t add_app_callbacks(lorawan_app_callbacks_t *callbacks);
 
     /** Change device class