1# Development Guidelines<a name="EN-US_TOPIC_0000001123763635"></a> 2 3- [Available APIs](#section158501652121514) 4- [How to Develop](#section783435801510) 5- [Development Example](#section460018317164) 6 - [Example Description](#section2148236125814) 7 - [Sample Code](#section121451047155716) 8 - [Verification](#section2742182082117) 9 10 11## Available APIs<a name="section158501652121514"></a> 12 13<a name="table10903105695114"></a> 14<table><thead align="left"><tr id="row1293645645110"><th class="cellrowborder" valign="top" width="23.56%" id="mcps1.1.4.1.1"><p id="p59361562512"><a name="p59361562512"></a><a name="p59361562512"></a>Category</p> 15</th> 16<th class="cellrowborder" valign="top" width="24.29%" id="mcps1.1.4.1.2"><p id="p1393665645118"><a name="p1393665645118"></a><a name="p1393665645118"></a>API</p> 17</th> 18<th class="cellrowborder" valign="top" width="52.15%" id="mcps1.1.4.1.3"><p id="p119363564516"><a name="p119363564516"></a><a name="p119363564516"></a>Description</p> 19</th> 20</tr> 21</thead> 22<tbody><tr id="row1693665613516"><td class="cellrowborder" rowspan="2" valign="top" width="23.56%" headers="mcps1.1.4.1.1 "><p id="p193675615514"><a name="p193675615514"></a><a name="p193675615514"></a>Creating or deleting a message queue</p> 23</td> 24<td class="cellrowborder" valign="top" width="24.29%" headers="mcps1.1.4.1.2 "><p id="p11936115612514"><a name="p11936115612514"></a><a name="p11936115612514"></a>LOS_QueueCreate</p> 25</td> 26<td class="cellrowborder" valign="top" width="52.15%" headers="mcps1.1.4.1.3 "><p id="p1593620562517"><a name="p1593620562517"></a><a name="p1593620562517"></a>Creates a message queue. The system dynamically allocates the queue space.</p> 27</td> 28</tr> 29<tr id="row79361156175113"><td class="cellrowborder" valign="top" headers="mcps1.1.4.1.1 "><p id="p893615567517"><a name="p893615567517"></a><a name="p893615567517"></a>LOS_QueueDelete</p> 30</td> 31<td class="cellrowborder" valign="top" headers="mcps1.1.4.1.2 "><p id="p4936155695111"><a name="p4936155695111"></a><a name="p4936155695111"></a>Deletes the specified queue based on the queue ID. </p> 32</td> 33</tr> 34<tr id="row093614566519"><td class="cellrowborder" rowspan="3" valign="top" width="23.56%" headers="mcps1.1.4.1.1 "><p id="p1593685614513"><a name="p1593685614513"></a><a name="p1593685614513"></a>Reading or writing data in a queue (without the content contained in the address)</p> 35</td> 36<td class="cellrowborder" valign="top" width="24.29%" headers="mcps1.1.4.1.2 "><p id="p6936556155118"><a name="p6936556155118"></a><a name="p6936556155118"></a>LOS_QueueRead</p> 37</td> 38<td class="cellrowborder" valign="top" width="52.15%" headers="mcps1.1.4.1.3 "><p id="p11936556155118"><a name="p11936556155118"></a><a name="p11936556155118"></a>Reads data in the head node of the specified queue. The data in the queue node is an address.</p> 39</td> 40</tr> 41<tr id="row199369565518"><td class="cellrowborder" valign="top" headers="mcps1.1.4.1.1 "><p id="p393655620513"><a name="p393655620513"></a><a name="p393655620513"></a>LOS_QueueWrite</p> 42</td> 43<td class="cellrowborder" valign="top" headers="mcps1.1.4.1.2 "><p id="p12936256175120"><a name="p12936256175120"></a><a name="p12936256175120"></a>Writes the value of the input parameter <strong id="b13458132192018"><a name="b13458132192018"></a><a name="b13458132192018"></a>bufferAddr</strong> (buffer address) to the tail node of the specified queue.</p> 44</td> 45</tr> 46<tr id="row1293615635114"><td class="cellrowborder" valign="top" headers="mcps1.1.4.1.1 "><p id="p893625665119"><a name="p893625665119"></a><a name="p893625665119"></a>LOS_QueueWriteHead</p> 47</td> 48<td class="cellrowborder" valign="top" headers="mcps1.1.4.1.2 "><p id="p193620566515"><a name="p193620566515"></a><a name="p193620566515"></a>Writes the value of the input parameter <strong id="b20585155122116"><a name="b20585155122116"></a><a name="b20585155122116"></a>bufferAddr</strong> (buffer address) to the head node of the specified queue.</p> 49</td> 50</tr> 51<tr id="row593675635117"><td class="cellrowborder" rowspan="3" valign="top" width="23.56%" headers="mcps1.1.4.1.1 "><p id="p293675615111"><a name="p293675615111"></a><a name="p293675615111"></a>Reading or writing in a queue (with the content contained in the address)</p> 52</td> 53<td class="cellrowborder" valign="top" width="24.29%" headers="mcps1.1.4.1.2 "><p id="p14936356155113"><a name="p14936356155113"></a><a name="p14936356155113"></a>LOS_QueueReadCopy</p> 54</td> 55<td class="cellrowborder" valign="top" width="52.15%" headers="mcps1.1.4.1.3 "><p id="p11936155616510"><a name="p11936155616510"></a><a name="p11936155616510"></a>Reads data from the head node of the specified queue.</p> 56</td> 57</tr> 58<tr id="row093619569510"><td class="cellrowborder" valign="top" headers="mcps1.1.4.1.1 "><p id="p179361256175117"><a name="p179361256175117"></a><a name="p179361256175117"></a>LOS_QueueWriteCopy</p> 59</td> 60<td class="cellrowborder" valign="top" headers="mcps1.1.4.1.2 "><p id="p6936155616515"><a name="p6936155616515"></a><a name="p6936155616515"></a>Writes the data saved in the input parameter <strong id="b9859038152517"><a name="b9859038152517"></a><a name="b9859038152517"></a>bufferAddr</strong> to the tail node of the specified queue.</p> 61</td> 62</tr> 63<tr id="row16936856185111"><td class="cellrowborder" valign="top" headers="mcps1.1.4.1.1 "><p id="p49361156195113"><a name="p49361156195113"></a><a name="p49361156195113"></a>LOS_QueueWriteHeadCopy</p> 64</td> 65<td class="cellrowborder" valign="top" headers="mcps1.1.4.1.2 "><p id="p1193625675116"><a name="p1193625675116"></a><a name="p1193625675116"></a>Writes the data saved in the input parameter <strong id="b536221517269"><a name="b536221517269"></a><a name="b536221517269"></a>bufferAddr</strong> to the head node of the specified queue.</p> 66</td> 67</tr> 68<tr id="row1936756155114"><td class="cellrowborder" valign="top" width="23.56%" headers="mcps1.1.4.1.1 "><p id="p149371956105114"><a name="p149371956105114"></a><a name="p149371956105114"></a>Obtaining queue information</p> 69</td> 70<td class="cellrowborder" valign="top" width="24.29%" headers="mcps1.1.4.1.2 "><p id="p7937145613516"><a name="p7937145613516"></a><a name="p7937145613516"></a>LOS_QueueInfoGet</p> 71</td> 72<td class="cellrowborder" valign="top" width="52.15%" headers="mcps1.1.4.1.3 "><p id="p19371356175110"><a name="p19371356175110"></a><a name="p19371356175110"></a>Obtains information about the specified queue, including the queue ID, queue length, message node size, head node, tail node, number of readable nodes, number of writable nodes, tasks waiting for read operations, and tasks waiting for write operations.</p> 73</td> 74</tr> 75</tbody> 76</table> 77 78## How to Develop<a name="section783435801510"></a> 79 801. Call **LOS\_QueueCreate** to create a queue. The queue ID is returned when the queue is created. 812. Call **LOS\_QueueWrite** or **LOS\_QueueWriteCopy** to write messages to the queue. 823. Call **LOS\_QueueRead** or **LOS\_QueueReadCopy** to read messages from the queue. 834. Call **LOS\_QueueInfoGet** to obtain queue information. 845. Call **LOS\_QueueDelete** to delete the queue. 85 86> **NOTE:** 87>- The maximum number of queues supported by the system is the total number of queue resources of the system, not the number of queue resources available to users. For example, if the system software timer occupies one more queue resource, the number of queue resources available to users decreases by one. 88>- The input parameters queue name and flags passed when a queue is created are reserved for future use. 89>- The input parameter **timeOut** in the queue interface function is relative time. 90>- **LOS\_QueueReadCopy**, **LOS\_QueueWriteCopy**, and **LOS\_QueueWriteHeadCopy** are a group of APIs that must be used together. **LOS\_QueueRead**, **LOS\_QueueWrite**, and **LOS\_QueueWriteHead** are a group of APIs that must be used together. 91>- As **LOS\_QueueWrite**, **LOS\_QueueWriteHead**, and **LOS\_QueueRead** are used to manage data addresses, you must ensure that the memory directed by the pointer obtained by calling **LOS\_QueueRead** is not modified or released abnormally when the queue is being read. Otherwise, unpredictable results may occur. 92>- **LOS\_QueueWrite**, **LOS\_QueueWriteHead**, and **LOS\_QueueRead** are called to manage data addresses, which means that the actual data read or written is pointer data. Therefore, before using these APIs, ensure that the message node size is the pointer length during queue creation, to avoid waste and read failures. 93 94## Development Example<a name="section460018317164"></a> 95 96### Example Description<a name="section2148236125814"></a> 97 98Create a queue and two tasks. Enable task 1 to call the queue write API to send messages, and enable task 2 to receive messages by calling the queue read API. 99 1001. Create task 1 and task 2 by calling **LOS\_TaskCreate**. 1012. Create a message queue by calling **LOS\_QueueCreate**. 1023. Enable messages to be sent in task 1 by calling **SendEntry**. 1034. Enable messages to be received in task 2 by calling **RecvEntry**. 1045. Delete the queue by calling **LOS\_QueueDelete**. 105 106### Sample Code<a name="section121451047155716"></a> 107 108The sample code is as follows: 109 110``` 111#include "los_task.h" 112#include "los_queue.h" 113static UINT32 g_queue; 114#define BUFFER_LEN 50 115 116VOID SendEntry(VOID) 117{ 118 UINT32 ret = 0; 119 CHAR abuf[] = "test message"; 120 UINT32 len = sizeof(abuf); 121 122 ret = LOS_QueueWriteCopy(g_queue, abuf, len, 0); 123 if(ret != LOS_OK) { 124 printf("Failed to send the message. Error: %x\n", ret); 125 } 126} 127 128VOID RecvEntry(VOID) 129{ 130 UINT32 ret = 0; 131 CHAR readBuf[BUFFER_LEN] = {0}; 132 UINT32 readLen = BUFFER_LEN; 133 134 ret = LOS_QueueReadCopy(g_queue, readBuf, &readLen, 0); 135 if(ret != LOS_OK) { 136 printf("Failed to receive the message. Error: %x\n", ret); 137 } 138 139 printf("Message received: %s\n", readBuf); 140 141 ret = LOS_QueueDelete(g_queue); 142 if(ret != LOS_OK) { 143 printf("Failed to delete the queue. Error: %x\n", ret); 144 } 145 146 printf("Queue deleted.\n"); 147} 148 149UINT32 ExampleQueue(VOID) 150{ 151 printf("Start queue example.\n"); 152 UINT32 ret = 0; 153 UINT32 task1, task2; 154 TSK_INIT_PARAM_S initParam = {0}; 155 156 initParam.pfnTaskEntry = (TSK_ENTRY_FUNC)SendEntry; 157 initParam.usTaskPrio = 9; 158 initParam.uwStackSize = LOSCFG_BASE_CORE_TSK_DEFAULT_STACK_SIZE; 159 initParam.pcName = "SendQueue"; 160 161 LOS_TaskLock(); 162 ret = LOS_TaskCreate(&task1, &initParam); 163 if(ret != LOS_OK) { 164 printf("Failed to create task1. Error: %x\n", ret); 165 return ret; 166 } 167 168 initParam.pcName = "RecvQueue"; 169 initParam.pfnTaskEntry = (TSK_ENTRY_FUNC)RecvEntry; 170 initParam.usTaskPrio = 10; 171 ret = LOS_TaskCreate(&task2, &initParam); 172 if(ret != LOS_OK) { 173 printf("Failed to create task2. Error: %x\n", ret); 174 return ret; 175 } 176 177 ret = LOS_QueueCreate("queue", 5, &g_queue, 0, 50); 178 if(ret != LOS_OK) { 179 printf("Failed to create the queue. Error: %x\n", ret); 180 } 181 182 printf("Queue created.\n"); 183 LOS_TaskUnlock(); 184 return ret; 185} 186``` 187 188### Verification<a name="section2742182082117"></a> 189 190The development is successful if the return result is as follows: 191 192``` 193Start queue example. 194Queue created. 195Message received: test message. 196Queue deleted. 197``` 198 199
