Events and callback functions
Library uses events to notify application layer for (possible, but not limited to) unexpected events. This concept is used aswell for commands with longer executing time, such as scanning access points or when application starts new connection as client mode.
There are 3 types of events/callbacks available:
Global event callback function, assigned when initializing library
Connection specific event callback function, to process only events related to connection, such as connection error, data send, data receive, connection closed
API function call based event callback function
Every callback is always called from protected area of middleware (when exclusing access is granted to single thread only),
and it can be called from one of these 3 threads:
Producing thread
Processing thread
Input thread, when
LWCELL_CFG_INPUT_USE_PROCESSis enabled andlwcell_input_process()function is called
Tip
Check Inter thread communication for more details about Producing and Processing thread.
Global event callback
Global event callback function is assigned at library initialization. It is used by the application to receive any kind of event, except the one related to connection:
GSM station successfully connected to access point
GSM physical device reset has been detected
Restore operation finished
New station has connected to access point
and many more..
Tip
Check Event management section for different kind of events
By default, global event function is single function.
If the application tries to split different events with different callback functions,
it is possible to do so by using lwcell_evt_register() function to register a new,
custom, event function.
Tip
Implementation of Netconn API leverages lwcell_evt_register() to
receive event when station disconnected from wifi access point.
Check its source file for actual implementation.
1/**
2 * \file lwcell_netconn.c
3 * \brief API functions for sequential calls
4 */
5
6/*
7 * Copyright (c) 2026 Tilen MAJERLE
8 *
9 * Permission is hereby granted, free of charge, to any person
10 * obtaining a copy of this software and associated documentation
11 * files (the "Software"), to deal in the Software without restriction,
12 * including without limitation the rights to use, copy, modify, merge,
13 * publish, distribute, sublicense, and/or sell copies of the Software,
14 * and to permit persons to whom the Software is furnished to do so,
15 * subject to the following conditions:
16 *
17 * The above copyright notice and this permission notice shall be
18 * included in all copies or substantial portions of the Software.
19 *
20 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
21 * EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
22 * OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
23 * AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
24 * HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
25 * WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
26 * FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
27 * OTHER DEALINGS IN THE SOFTWARE.
28 *
29 * This file is part of LwCELL - Lightweight cellular modem AT library.
30 *
31 * Author: Tilen MAJERLE <tilen@majerle.eu>
32 * Version: v0.1.1
33 */
34#include "lwcell/lwcell_netconn.h"
35#include "lwcell/lwcell_conn.h"
36#include "lwcell/lwcell_mem.h"
37#include "lwcell/lwcell_private.h"
38
39#if LWCELL_CFG_NETCONN || __DOXYGEN__
40
41/* Check conditions */
42#if !LWCELL_CFG_CONN
43#error "LWCELL_CFG_CONN must be enabled for NETCONN API!"
44#endif /* !LWCELL_CFG_CONN */
45
46#if LWCELL_CFG_NETCONN_RECEIVE_QUEUE_LEN < 2
47#error "LWCELL_CFG_NETCONN_RECEIVE_QUEUE_LEN must be greater or equal to 2"
48#endif /* LWCELL_CFG_NETCONN_RECEIVE_QUEUE_LEN < 2 */
49
50/**
51 * \brief Sequential API structure
52 */
53typedef struct lwcell_netconn {
54 struct lwcell_netconn* next; /*!< Linked list entry */
55
56 lwcell_netconn_type_t type; /*!< Netconn type */
57
58 size_t rcv_packets; /*!< Number of received packets so far on this connection */
59 lwcell_conn_p conn; /*!< Pointer to actual connection */
60
61 lwcell_sys_mbox_t mbox_receive; /*!< Message queue for receive mbox */
62
63 lwcell_linbuff_t buff; /*!< Linear buffer structure */
64
65 uint16_t conn_timeout; /*!< Connection timeout in units of seconds when
66 netconn is in server (listen) mode.
67 Connection will be automatically closed if there is no
68 data exchange in time. Set to `0` when timeout feature is disabled. */
69
70#if LWCELL_CFG_NETCONN_RECEIVE_TIMEOUT || __DOXYGEN__
71 uint32_t rcv_timeout; /*!< Receive timeout in unit of milliseconds */
72#endif
73} lwcell_netconn_t;
74
75static uint8_t recv_closed = 0xFF;
76static lwcell_netconn_t* netconn_list; /*!< Linked list of netconn entries */
77
78/**
79 * \brief Flush all mboxes and clear possible used memories
80 * \param[in] nc: Pointer to netconn to flush
81 * \param[in] protect: Set to 1 to protect against multi-thread access
82 */
83static void
84flush_mboxes(lwcell_netconn_t* nc, uint8_t protect) {
85 lwcell_pbuf_p pbuf;
86 if (protect) {
87 lwcell_core_lock();
88 }
89 if (lwcell_sys_mbox_isvalid(&nc->mbox_receive)) {
90 while (lwcell_sys_mbox_getnow(&nc->mbox_receive, (void**)&pbuf)) {
91 if (pbuf != NULL && (uint8_t*)pbuf != (uint8_t*)&recv_closed) {
92 lwcell_pbuf_free_s(&pbuf); /* Free received data buffers */
93 }
94 }
95 lwcell_sys_mbox_delete(&nc->mbox_receive); /* Delete message queue */
96 lwcell_sys_mbox_invalid(&nc->mbox_receive); /* Invalid handle */
97 }
98 if (protect) {
99 lwcell_core_unlock();
100 }
101}
102
103/**
104 * \brief Callback function for every server connection
105 * \param[in] evt: Pointer to callback structure
106 * \return Member of \ref lwcellr_t enumeration
107 */
108static lwcellr_t
109netconn_evt(lwcell_evt_t* evt) {
110 lwcell_conn_p conn;
111 lwcell_netconn_t* nc = NULL;
112 uint8_t close = 0;
113
114 conn = lwcell_conn_get_from_evt(evt); /* Get connection from event */
115 switch (lwcell_evt_get_type(evt)) {
116 /*
117 * A new connection has been active
118 * and should be handled by netconn API
119 */
120 case LWCELL_EVT_CONN_ACTIVE: { /* A new connection active is active */
121 if (lwcell_conn_is_client(conn)) { /* Was connection started by us? */
122 nc = lwcell_conn_get_arg(conn); /* Argument should be already set */
123 if (nc != NULL) {
124 nc->conn = conn; /* Save actual connection */
125 } else {
126 close = 1; /* Close this connection, invalid netconn */
127 }
128 } else {
129 LWCELL_DEBUGF(LWCELL_CFG_DBG_NETCONN | LWCELL_DBG_TYPE_TRACE | LWCELL_DBG_LVL_WARNING,
130 "[LWCELL NETCONN] Closing connection, it is not in client mode!\r\n");
131 close = 1; /* Close the connection at this point */
132 }
133
134 /* Decide if some events want to close the connection */
135 if (close) {
136 if (nc != NULL) {
137 lwcell_conn_set_arg(conn, NULL); /* Reset argument */
138 lwcell_netconn_delete(nc); /* Free memory for API */
139 }
140 lwcell_conn_close(conn, 0); /* Close the connection */
141 close = 0;
142 }
143 break;
144 }
145
146 /*
147 * We have a new data received which
148 * should have netconn structure as argument
149 */
150 case LWCELL_EVT_CONN_RECV: {
151 lwcell_pbuf_p pbuf;
152
153 nc = lwcell_conn_get_arg(conn); /* Get API from connection */
154 pbuf = lwcell_evt_conn_recv_get_buff(evt); /* Get received buff */
155
156 lwcell_conn_recved(conn, pbuf); /* Notify stack about received data */
157
158 lwcell_pbuf_ref(pbuf); /* Increase reference counter */
159 if (nc == NULL || !lwcell_sys_mbox_isvalid(&nc->mbox_receive)
160 || !lwcell_sys_mbox_putnow(&nc->mbox_receive, pbuf)) {
161 LWCELL_DEBUGF(LWCELL_CFG_DBG_NETCONN, "[LWCELL NETCONN] Ignoring more data for receive!\r\n");
162 lwcell_pbuf_free_s(&pbuf); /* Free pbuf */
163 return lwcellOKIGNOREMORE; /* Return OK to free the memory and ignore further data */
164 }
165 ++nc->rcv_packets; /* Increase number of received packets */
166 LWCELL_DEBUGF(LWCELL_CFG_DBG_NETCONN | LWCELL_DBG_TYPE_TRACE,
167 "[LWCELL NETCONN] Received pbuf contains %d bytes. Handle written to receive mbox\r\n",
168 (int)lwcell_pbuf_length(pbuf, 0));
169 break;
170 }
171
172 /* Connection was just closed */
173 case LWCELL_EVT_CONN_CLOSE: {
174 nc = lwcell_conn_get_arg(conn); /* Get API from connection */
175
176 /*
177 * In case we have a netconn available,
178 * simply write pointer to received variable to indicate closed state
179 */
180 if (nc != NULL && lwcell_sys_mbox_isvalid(&nc->mbox_receive)) {
181 lwcell_sys_mbox_putnow(&nc->mbox_receive, (void*)&recv_closed);
182 }
183
184 break;
185 }
186 default: return lwcellERR;
187 }
188 return lwcellOK;
189}
190
191/**
192 * \brief Global event callback function
193 * \param[in] evt: Callback information and data
194 * \return \ref lwcellOK on success, member of \ref lwcellr_t otherwise
195 */
196static lwcellr_t
197lwcell_evt(lwcell_evt_t* evt) {
198 switch (lwcell_evt_get_type(evt)) {
199 default: break;
200 }
201 return lwcellOK;
202}
203
204/**
205 * \brief Create new netconn connection
206 * \param[in] type: Netconn connection type
207 * \return New netconn connection on success, `NULL` otherwise
208 */
209lwcell_netconn_p
210lwcell_netconn_new(lwcell_netconn_type_t type) {
211 lwcell_netconn_t* a;
212 static uint8_t first = 1;
213
214 /* Register only once! */
215 lwcell_core_lock();
216 if (first) {
217 first = 0;
218 lwcell_evt_register(lwcell_evt); /* Register global event function */
219 }
220 lwcell_core_unlock();
221 a = lwcell_mem_calloc(1, sizeof(*a)); /* Allocate memory for core object */
222 if (a != NULL) {
223 a->type = type; /* Save netconn type */
224 a->conn_timeout = 0; /* Default connection timeout */
225 if (!lwcell_sys_mbox_create(&a->mbox_receive, LWCELL_CFG_NETCONN_RECEIVE_QUEUE_LEN)) { /* Allocate memory for
226 receiving message box
227 */
228 LWCELL_DEBUGF(LWCELL_CFG_DBG_NETCONN | LWCELL_DBG_TYPE_TRACE | LWCELL_DBG_LVL_DANGER, "[LWCELL NETCONN] "
229 "Cannot create "
230 "receive MBOX\r\n");
231 goto free_ret;
232 }
233 lwcell_core_lock();
234 if (netconn_list == NULL) { /* Add new netconn to the existing list */
235 netconn_list = a;
236 } else {
237 a->next = netconn_list; /* Add it to beginning of the list */
238 netconn_list = a;
239 }
240 lwcell_core_unlock();
241 }
242 return a;
243free_ret:
244 if (lwcell_sys_mbox_isvalid(&a->mbox_receive)) {
245 lwcell_sys_mbox_delete(&a->mbox_receive);
246 lwcell_sys_mbox_invalid(&a->mbox_receive);
247 }
248 if (a != NULL) {
249 lwcell_mem_free_s((void**)&a);
250 }
251 return NULL;
252}
253
254/**
255 * \brief Delete netconn connection
256 * \param[in] nc: Netconn handle
257 * \return \ref lwcellOK on success, member of \ref lwcellr_t enumeration otherwise
258 */
259lwcellr_t
260lwcell_netconn_delete(lwcell_netconn_p nc) {
261 LWCELL_ASSERT(nc != NULL);
262
263 lwcell_core_lock();
264 flush_mboxes(nc, 0); /* Clear mboxes */
265
266 /* Remove netconn from linkedlist */
267 if (netconn_list == nc) {
268 netconn_list = netconn_list->next; /* Remove first from linked list */
269 } else if (netconn_list != NULL) {
270 lwcell_netconn_p tmp, prev;
271 /* Find element on the list */
272 for (prev = netconn_list, tmp = netconn_list->next; tmp != NULL; prev = tmp, tmp = tmp->next) {
273 if (nc == tmp) {
274 prev->next = tmp->next; /* Remove tmp from linked list */
275 break;
276 }
277 }
278 }
279 lwcell_core_unlock();
280
281 lwcell_mem_free_s((void**)&nc);
282 return lwcellOK;
283}
284
285/**
286 * \brief Connect to server as client
287 * \param[in] nc: Netconn handle
288 * \param[in] host: Pointer to host, such as domain name or IP address in string format
289 * \param[in] port: Target port to use
290 * \return \ref lwcellOK if successfully connected, member of \ref lwcellr_t otherwise
291 */
292lwcellr_t
293lwcell_netconn_connect(lwcell_netconn_p nc, const char* host, lwcell_port_t port) {
294 lwcellr_t res;
295
296 LWCELL_ASSERT(nc != NULL);
297 LWCELL_ASSERT(host != NULL);
298 LWCELL_ASSERT(port > 0);
299
300 /*
301 * Start a new connection as client and:
302 *
303 * - Set current netconn structure as argument
304 * - Set netconn callback function for connection management
305 * - Start connection in blocking mode
306 */
307 res = lwcell_conn_start(NULL, (lwcell_conn_type_t)nc->type, host, port, nc, netconn_evt, 1);
308 return res;
309}
310
311/**
312 * \brief Write data to connection output buffers
313 * \note This function may only be used on TCP or SSL connections
314 * \param[in] nc: Netconn handle used to write data to
315 * \param[in] data: Pointer to data to write
316 * \param[in] btw: Number of bytes to write
317 * \return \ref lwcellOK on success, member of \ref lwcellr_t enumeration otherwise
318 */
319lwcellr_t
320lwcell_netconn_write(lwcell_netconn_p nc, const void* data, size_t btw) {
321 size_t len, sent;
322 const uint8_t* d = data;
323 lwcellr_t res;
324
325 LWCELL_ASSERT(nc != NULL);
326 LWCELL_ASSERT(nc->type == LWCELL_NETCONN_TYPE_TCP || nc->type == LWCELL_NETCONN_TYPE_SSL);
327 LWCELL_ASSERT(lwcell_conn_is_active(nc->conn));
328
329 /*
330 * Several steps are done in write process
331 *
332 * 1. Check if buffer is set and check if there is something to write to it.
333 * 1. In case buffer will be full after copy, send it and free memory.
334 * 2. Check how many bytes we can write directly without need to copy
335 * 3. Try to allocate a new buffer and copy remaining input data to it
336 * 4. In case buffer allocation fails, send data directly (may affect on speed and effectivenes)
337 */
338
339 /* Step 1 */
340 if (nc->buff.buff != NULL) { /* Is there a write buffer ready to accept more data? */
341 len = LWCELL_MIN(nc->buff.len - nc->buff.ptr, btw); /* Get number of bytes we can write to buffer */
342 if (len > 0) {
343 LWCELL_MEMCPY(&nc->buff.buff[nc->buff.ptr], data, len); /* Copy memory to temporary write buffer */
344 d += len;
345 nc->buff.ptr += len;
346 btw -= len;
347 }
348
349 /* Step 1.1 */
350 if (nc->buff.ptr == nc->buff.len) {
351 res = lwcell_conn_send(nc->conn, nc->buff.buff, nc->buff.len, &sent, 1);
352
353 lwcell_mem_free_s((void**)&nc->buff.buff);
354 if (res != lwcellOK) {
355 return res;
356 }
357 } else {
358 return lwcellOK; /* Buffer is not yet full yet */
359 }
360 }
361
362 /* Step 2 */
363 if (btw >= LWCELL_CFG_CONN_MAX_DATA_LEN) {
364 size_t rem;
365 rem = btw % LWCELL_CFG_CONN_MAX_DATA_LEN; /* Get remaining bytes for max data length */
366 res = lwcell_conn_send(nc->conn, d, btw - rem, &sent, 1); /* Write data directly */
367 if (res != lwcellOK) {
368 return res;
369 }
370 d += sent; /* Advance in data pointer */
371 btw -= sent; /* Decrease remaining data to send */
372 }
373
374 if (btw == 0) { /* Sent everything? */
375 return lwcellOK;
376 }
377
378 /* Step 3 */
379 if (nc->buff.buff == NULL) { /* Check if we should allocate a new buffer */
380 nc->buff.buff = lwcell_mem_malloc(sizeof(*nc->buff.buff) * LWCELL_CFG_CONN_MAX_DATA_LEN);
381 nc->buff.len = LWCELL_CFG_CONN_MAX_DATA_LEN; /* Save buffer length */
382 nc->buff.ptr = 0; /* Save buffer pointer */
383 }
384
385 /* Step 4 */
386 if (nc->buff.buff != NULL) { /* Memory available? */
387 LWCELL_MEMCPY(&nc->buff.buff[nc->buff.ptr], d, btw); /* Copy data to buffer */
388 nc->buff.ptr += btw;
389 } else { /* Still no memory available? */
390 return lwcell_conn_send(nc->conn, data, btw, NULL, 1); /* Simply send directly blocking */
391 }
392 return lwcellOK;
393}
394
395/**
396 * \brief Extended version of \ref lwcell_netconn_write with additional
397 * option to set custom flags.
398 *
399 * \note It is recommended to use this for full features support
400 *
401 * \param[in] nc: Netconn handle used to write data to
402 * \param[in] data: Pointer to data to write
403 * \param[in] btw: Number of bytes to write
404 * \param flags: Bitwise-ORed set of flags for netconn.
405 * Flags start with \ref LWCELL_NETCONN_FLAG_xxx
406 * \return \ref lwcellOK on success, member of \ref lwcellr_t enumeration otherwise
407 */
408lwcellr_t
409lwcell_netconn_write_ex(lwcell_netconn_p nc, const void* data, size_t btw, uint16_t flags) {
410 lwcellr_t res = lwcell_netconn_write(nc, data, btw);
411 if (res == lwcellOK) {
412 if (flags & LWCELL_NETCONN_FLAG_FLUSH) {
413 res = lwcell_netconn_flush(nc);
414 }
415 }
416 return res;
417}
418
419/**
420 * \brief Flush buffered data on netconn \e TCP/SSL connection
421 * \note This function may only be used on \e TCP/SSL connection
422 * \param[in] nc: Netconn handle to flush data
423 * \return \ref lwcellOK on success, member of \ref lwcellr_t enumeration otherwise
424 */
425lwcellr_t
426lwcell_netconn_flush(lwcell_netconn_p nc) {
427 LWCELL_ASSERT(nc != NULL);
428 LWCELL_ASSERT(nc->type == LWCELL_NETCONN_TYPE_TCP || nc->type == LWCELL_NETCONN_TYPE_SSL);
429 LWCELL_ASSERT(lwcell_conn_is_active(nc->conn));
430
431 /*
432 * In case we have data in write buffer,
433 * flush them out to network
434 */
435 if (nc->buff.buff != NULL) { /* Check remaining data */
436 if (nc->buff.ptr > 0) { /* Do we have data in current buffer? */
437 lwcell_conn_send(nc->conn, nc->buff.buff, nc->buff.ptr, NULL, 1); /* Send data */
438 }
439 lwcell_mem_free_s((void**)&nc->buff.buff);
440 }
441 return lwcellOK;
442}
443
444/**
445 * \brief Send data on \e UDP connection to default IP and port
446 * \param[in] nc: Netconn handle used to send
447 * \param[in] data: Pointer to data to write
448 * \param[in] btw: Number of bytes to write
449 * \return \ref lwcellOK on success, member of \ref lwcellr_t enumeration otherwise
450 */
451lwcellr_t
452lwcell_netconn_send(lwcell_netconn_p nc, const void* data, size_t btw) {
453 LWCELL_ASSERT(nc != NULL);
454 LWCELL_ASSERT(nc->type == LWCELL_NETCONN_TYPE_UDP);
455 LWCELL_ASSERT(lwcell_conn_is_active(nc->conn));
456
457 return lwcell_conn_send(nc->conn, data, btw, NULL, 1);
458}
459
460/**
461 * \brief Send data on \e UDP connection to specific IP and port
462 * \note Use this function in case of UDP type netconn
463 * \param[in] nc: Netconn handle used to send
464 * \param[in] ip: Pointer to IP address
465 * \param[in] port: Port number used to send data
466 * \param[in] data: Pointer to data to write
467 * \param[in] btw: Number of bytes to write
468 * \return \ref lwcellOK on success, member of \ref lwcellr_t enumeration otherwise
469 */
470lwcellr_t
471lwcell_netconn_sendto(lwcell_netconn_p nc, const lwcell_ip_t* ip, lwcell_port_t port, const void* data, size_t btw) {
472 LWCELL_ASSERT(nc != NULL);
473 LWCELL_ASSERT(nc->type == LWCELL_NETCONN_TYPE_UDP);
474 LWCELL_ASSERT(lwcell_conn_is_active(nc->conn));
475
476 return lwcell_conn_sendto(nc->conn, ip, port, data, btw, NULL, 1);
477}
478
479/**
480 * \brief Receive data from connection
481 * \param[in] nc: Netconn handle used to receive from
482 * \param[in] pbuf: Pointer to pointer to save new receive buffer to.
483 * When function returns, user must check for valid pbuf value `pbuf != NULL`
484 * \return \ref lwcellOK when new data ready,
485 * \return \ref lwcellCLOSED when connection closed by remote side,
486 * \return \ref lwcellTIMEOUT when receive timeout occurs
487 * \return Any other member of \ref lwcellr_t otherwise
488 */
489lwcellr_t
490lwcell_netconn_receive(lwcell_netconn_p nc, lwcell_pbuf_p* pbuf) {
491 LWCELL_ASSERT(nc != NULL);
492 LWCELL_ASSERT(pbuf != NULL);
493
494 *pbuf = NULL;
495#if LWCELL_CFG_NETCONN_RECEIVE_TIMEOUT
496 /*
497 * Wait for new received data for up to specific timeout
498 * or throw error for timeout notification
499 */
500 if (nc->rcv_timeout == LWCELL_NETCONN_RECEIVE_NO_WAIT) {
501 if (!lwcell_sys_mbox_getnow(&nc->mbox_receive, (void**)pbuf)) {
502 return lwcellTIMEOUT;
503 }
504 } else if (lwcell_sys_mbox_get(&nc->mbox_receive, (void**)pbuf, nc->rcv_timeout) == LWCELL_SYS_TIMEOUT) {
505 return lwcellTIMEOUT;
506 }
507#else /* LWCELL_CFG_NETCONN_RECEIVE_TIMEOUT */
508 /* Forever wait for new receive packet */
509 lwcell_sys_mbox_get(&nc->mbox_receive, (void**)pbuf, 0);
510#endif /* !LWCELL_CFG_NETCONN_RECEIVE_TIMEOUT */
511
512 /* Check if connection closed */
513 if ((uint8_t*)(*pbuf) == (uint8_t*)&recv_closed) {
514 *pbuf = NULL; /* Reset pbuf */
515 return lwcellCLOSED;
516 }
517 return lwcellOK; /* We have data available */
518}
519
520/**
521 * \brief Close a netconn connection
522 * \param[in] nc: Netconn handle to close
523 * \return \ref lwcellOK on success, member of \ref lwcellr_t enumeration otherwise
524 */
525lwcellr_t
526lwcell_netconn_close(lwcell_netconn_p nc) {
527 lwcell_conn_p conn;
528
529 LWCELL_ASSERT(nc != NULL);
530 LWCELL_ASSERT(nc->conn != NULL);
531 LWCELL_ASSERT(lwcell_conn_is_active(nc->conn));
532
533 lwcell_netconn_flush(nc); /* Flush data and ignore result */
534 conn = nc->conn;
535 nc->conn = NULL;
536
537 lwcell_conn_set_arg(conn, NULL); /* Reset argument */
538 lwcell_conn_close(conn, 1); /* Close the connection */
539 flush_mboxes(nc, 1); /* Flush message queues */
540 return lwcellOK;
541}
542
543/**
544 * \brief Get connection number used for netconn
545 * \param[in] nc: Netconn handle
546 * \return `-1` on failure, connection number between `0` and \ref LWCELL_CFG_MAX_CONNS otherwise
547 */
548int8_t
549lwcell_netconn_getconnnum(lwcell_netconn_p nc) {
550 if (nc != NULL && nc->conn != NULL) {
551 return lwcell_conn_getnum(nc->conn);
552 }
553 return -1;
554}
555
556#if LWCELL_CFG_NETCONN_RECEIVE_TIMEOUT || __DOXYGEN__
557
558/**
559 * \brief Set timeout value for receiving data.
560 *
561 * When enabled, \ref lwcell_netconn_receive will only block for up to
562 * \e timeout value and will return if no new data within this time
563 *
564 * \param[in] nc: Netconn handle
565 * \param[in] timeout: Timeout in units of milliseconds.
566 * Set to `0` to disable timeout feature. Function blocks until data receive or connection closed
567 * Set to `> 0` to set maximum milliseconds to wait before timeout
568 * Set to \ref LWCELL_NETCONN_RECEIVE_NO_WAIT to enable non-blocking receive
569 */
570void
571lwcell_netconn_set_receive_timeout(lwcell_netconn_p nc, uint32_t timeout) {
572 nc->rcv_timeout = timeout;
573}
574
575/**
576 * \brief Get netconn receive timeout value
577 * \param[in] nc: Netconn handle
578 * \return Timeout in units of milliseconds.
579 * If value is `0`, timeout is disabled (wait forever)
580 */
581uint32_t
582lwcell_netconn_get_receive_timeout(lwcell_netconn_p nc) {
583 return nc->rcv_timeout; /* Return receive timeout */
584}
585
586#endif /* LWCELL_CFG_NETCONN_RECEIVE_TIMEOUT || __DOXYGEN__ */
587
588#endif /* LWCELL_CFG_NETCONN || __DOXYGEN__ */
Connection specific event
This events are subset of global event callback. They work exactly the same way as global, but only receive events related to connections.
Tip
Connection related events start with LWCELL_EVT_CONN_*, such as LWCELL_EVT_CONN_RECV.
Check Event management for list of all connection events.
Connection events callback function is set when client (application starts connection) starts a new connection with lwcell_conn_start() function
1#include "client.h"
2#include "lwcell/lwcell.h"
3#include "lwcell/lwcell_network_api.h"
4
5#if LWCELL_CFG_CONN
6
7/* Host parameter */
8#define CONN_HOST "example.com"
9#define CONN_PORT 80
10
11static lwcellr_t conn_callback_func(lwcell_evt_t* evt);
12
13/**
14 * \brief Request data for connection
15 */
16static const uint8_t req_data[] = ""
17 "GET / HTTP/1.1\r\n"
18 "Host: " CONN_HOST "\r\n"
19 "Connection: close\r\n"
20 "\r\n";
21
22/**
23 * \brief Start a new connection(s) as client
24 */
25void
26client_connect(void) {
27 lwcellr_t res;
28
29 /* Attach to GSM network */
30 lwcell_network_request_attach();
31
32 /* Start a new connection as client in non-blocking mode */
33 if ((res = lwcell_conn_start(NULL, LWCELL_CONN_TYPE_TCP, "example.com", 80, NULL, conn_callback_func, 0))
34 == lwcellOK) {
35 printf("Connection to " CONN_HOST " started...\r\n");
36 } else {
37 printf("Cannot start connection to " CONN_HOST "!\r\n");
38 }
39}
40
41/**
42 * \brief Event callback function for connection-only
43 * \param[in] evt: Event information with data
44 * \return \ref lwcellOK on success, member of \ref lwcellr_t otherwise
45 */
46static lwcellr_t
47conn_callback_func(lwcell_evt_t* evt) {
48 lwcell_conn_p conn;
49 lwcellr_t res;
50 uint8_t conn_num;
51
52 conn = lwcell_conn_get_from_evt(evt); /* Get connection handle from event */
53 if (conn == NULL) {
54 return lwcellERR;
55 }
56 conn_num = lwcell_conn_getnum(conn); /* Get connection number for identification */
57 switch (lwcell_evt_get_type(evt)) {
58 case LWCELL_EVT_CONN_ACTIVE: { /* Connection just active */
59 printf("Connection %d active!\r\n", (int)conn_num);
60 res = lwcell_conn_send(conn, req_data, sizeof(req_data) - 1, NULL,
61 0); /* Start sending data in non-blocking mode */
62 if (res == lwcellOK) {
63 printf("Sending request data to server...\r\n");
64 } else {
65 printf("Cannot send request data to server. Closing connection manually...\r\n");
66 lwcell_conn_close(conn, 0); /* Close the connection */
67 }
68 break;
69 }
70 case LWCELL_EVT_CONN_CLOSE: { /* Connection closed */
71 if (lwcell_evt_conn_close_is_forced(evt)) {
72 printf("Connection %d closed by client!\r\n", (int)conn_num);
73 } else {
74 printf("Connection %d closed by remote side!\r\n", (int)conn_num);
75 }
76 break;
77 }
78 case LWCELL_EVT_CONN_SEND: { /* Data send event */
79 lwcellr_t res = lwcell_evt_conn_send_get_result(evt);
80 if (res == lwcellOK) {
81 printf("Data sent successfully on connection %d...waiting to receive data from remote side...\r\n",
82 (int)conn_num);
83 } else {
84 printf("Error while sending data on connection %d!\r\n", (int)conn_num);
85 }
86 break;
87 }
88 case LWCELL_EVT_CONN_RECV: { /* Data received from remote side */
89 lwcell_pbuf_p pbuf = lwcell_evt_conn_recv_get_buff(evt);
90 lwcell_conn_recved(conn, pbuf); /* Notify stack about received pbuf */
91 printf("Received %d bytes on connection %d..\r\n", (int)lwcell_pbuf_length(pbuf, 1), (int)conn_num);
92 break;
93 }
94 case LWCELL_EVT_CONN_ERROR: { /* Error connecting to server */
95 const char* host = lwcell_evt_conn_error_get_host(evt);
96 lwcell_port_t port = lwcell_evt_conn_error_get_port(evt);
97 printf("Error connecting to %s:%d\r\n", host, (int)port);
98 break;
99 }
100 default: break;
101 }
102 return lwcellOK;
103}
104
105#endif /* LWCELL_CFG_CONN */
API call event
API function call event function is special type of event and is linked to command execution. It is especially useful when dealing with non-blocking commands to understand when specific command execution finished and when next operation could start.
Every API function, which directly operates with AT command on physical device layer,
has optional 2 parameters for API call event:
Callback function, called when command finished
Custom user parameter for callback function
Below is an example code for SMS send. It uses custom API callback function to notify application when command has been executed successfully
1/* Somewhere in thread function */
2
3/* Get device hostname in blocking mode */
4/* Function returns actual result */
5if (lwcell_sms_send("+0123456789", "text", NULL, NULL, 1 /* 1 means blocking call */) == lwcellOK) {
6 /* At this point we have valid result from device */
7 printf("SMS sent successfully\r\n");
8} else {
9 printf("Error trying to send SMS..\r\n");
10}