1 /*!
2  * \file      LoRaMacConfirmQueue.h
3  *
4  * \brief     LoRa MAC confirm queue implementation
5  *
6  * \copyright Revised BSD License, see section \ref LICENSE.
7  *
8  * \code
9  *                ______                              _
10  *               / _____)             _              | |
11  *              ( (____  _____ ____ _| |_ _____  ____| |__
12  *               \____ \| ___ |    (_   _) ___ |/ ___)  _ \
13  *               _____) ) ____| | | || |_| ____( (___| | | |
14  *              (______/|_____)_|_|_| \__)_____)\____)_| |_|
15  *              (C)2013 Semtech
16  *
17  *               ___ _____ _   ___ _  _____ ___  ___  ___ ___
18  *              / __|_   _/_\ / __| |/ / __/ _ \| _ \/ __| __|
19  *              \__ \ | |/ _ \ (__| ' <| _| (_) |   / (__| _|
20  *              |___/ |_/_/ \_\___|_|\_\_| \___/|_|_\\___|___|
21  *              embedded.connectivity.solutions===============
22  *
23  * \endcode
24  *
25  * \author    Miguel Luis ( Semtech )
26  *
27  * \author    Gregory Cristian ( Semtech )
28  *
29  * \author    Daniel Jaeckle ( STACKFORCE )
30  *
31  * \defgroup  LORAMACCONFIRMQUEUE LoRa MAC confirm queue implementation
32  *            This module specifies the API implementation of the LoRaMAC confirm queue.
33  *            The confirm queue is implemented with as a ring buffer. The number of
34  *            elements can be defined with \ref LORA_MAC_MLME_CONFIRM_QUEUE_LEN. The
35  *            current implementation does not support multiple elements of the same
36  *            Mlme_t type.
37  * \{
38  */
39 #ifndef __LORAMAC_CONFIRMQUEUE_H__
40 #define __LORAMAC_CONFIRMQUEUE_H__
41 
42 #ifdef __cplusplus
43 extern "C"
44 {
45 #endif
46 
47 #include <stdbool.h>
48 #include <stdint.h>
49 
50 #include "LoRaMac.h"
51 
52 /*!
53  * LoRaMac MLME-Confirm queue length
54  */
55 #define LORA_MAC_MLME_CONFIRM_QUEUE_LEN             5
56 
57 /*!
58  * Structure to hold multiple MLME request confirm data
59  */
60 typedef struct sMlmeConfirmQueue
61 {
62     /*!
63      * Holds the previously performed MLME-Request
64      */
65     Mlme_t Request;
66     /*!
67      * Status of the operation
68      */
69     LoRaMacEventInfoStatus_t Status;
70     /*!
71      * Set to true, if the request is ready to be handled
72      */
73     bool ReadyToHandle;
74     /*!
75      * Set to true, if it is not permitted to set the ReadyToHandle variable
76      * with a function call to LoRaMacConfirmQueueSetStatusCmn.
77      */
78     bool RestrictCommonReadyToHandle;
79 }MlmeConfirmQueue_t;
80 
81 /*!
82  * \brief   Initializes the confirm queue
83  *
84  * \param   [IN] primitives - Pointer to the LoRaMac primitives.
85  */
86 void LoRaMacConfirmQueueInit( LoRaMacPrimitives_t* primitive );
87 
88 /*!
89  * \brief   Adds an element to the confirm queue.
90  *
91  * \param   [IN] mlmeConfirm - Pointer to the element to add.
92  *
93  * \retval  [true - operation was successful, false - operation failed]
94  */
95 bool LoRaMacConfirmQueueAdd( MlmeConfirmQueue_t* mlmeConfirm );
96 
97 /*!
98  * \brief   Removes the last element which was added into the queue.
99  *
100  * \retval  [true - operation was successful, false - operation failed]
101  */
102 bool LoRaMacConfirmQueueRemoveLast( void );
103 
104 /*!
105  * \brief   Removes the first element which was added to the confirm queue.
106  *
107  * \retval  [true - operation was successful, false - operation failed]
108  */
109 bool LoRaMacConfirmQueueRemoveFirst( void );
110 
111 /*!
112  * \brief   Sets the status of an element.
113  *
114  * \param   [IN] status - The status to set.
115  *
116  * \param   [IN] request - The related request to set the status.
117  */
118 void LoRaMacConfirmQueueSetStatus( LoRaMacEventInfoStatus_t status, Mlme_t request );
119 
120 /*!
121  * \brief   Gets the status of an element.
122  *
123  * \param   [IN] request - The request to query the status.
124  *
125  * \retval  The status of the related MlmeRequest.
126  */
127 LoRaMacEventInfoStatus_t LoRaMacConfirmQueueGetStatus( Mlme_t request );
128 
129 /*!
130  * \brief   Sets a common status for all elements in the queue.
131  *
132  * \param   [IN] status - The status to set.
133  */
134 void LoRaMacConfirmQueueSetStatusCmn( LoRaMacEventInfoStatus_t status );
135 
136 /*!
137  * \brief   Gets the common status of all elements.
138  *
139  * \retval  The common status of all elements.
140  */
141 LoRaMacEventInfoStatus_t LoRaMacConfirmQueueGetStatusCmn( void );
142 
143 /*!
144  * \brief   Verifies if a request is in the queue and active.
145  *
146  * \param   [IN] request - The request to verify.
147  *
148  * \retval  [true - element is in the queue, false - element is not in the queue].
149  */
150 bool LoRaMacConfirmQueueIsCmdActive( Mlme_t request );
151 
152 /*!
153  * \brief   Handles all callbacks of active requests
154  *
155  * \param   [IN] mlmeConfirm - Pointer to the generic mlmeConfirm structure.
156  */
157 void LoRaMacConfirmQueueHandleCb( MlmeConfirm_t* mlmeConfirm );
158 
159 /*!
160  * \brief   Query number of elements in the queue.
161  *
162  * \retval  Number of elements.
163  */
164 uint8_t LoRaMacConfirmQueueGetCnt( void );
165 
166 /*!
167  * \brief   Verify if the confirm queue is full.
168  *
169  * \retval  [true - queue is full, false - queue is not full].
170  */
171 bool LoRaMacConfirmQueueIsFull( void );
172 
173 #ifdef __cplusplus
174 }
175 #endif
176 
177 #endif // __LORAMAC_CONFIRMQUEUE_H__
178