Receiving binary data with Cellular Common APIs

Receive binary data command relies on the port to indicate start and length of the binary data in the input stream.

Take the socket receive command of reference port BG96 for example:

AT+QIRD=11,1500         // Read data received from incoming connection.
+QIRD: 4                // Actual data length is 4 bytes.
test                    // The binary data returns from the modem
OK                      // The success result code

The binary data "test" should not be parsed by cellular interface. The port needs to indicate the start of binary data and the length in data prefix callback function.

_Cellular_TimeoutAtcmdDataRecvRequestWithCallback is cellular common API to receive binary data from modem. BG96 port make use of this API to receive binary data with the following parameters:

static CellularPktStatus_t socketRecvDataPrefix( void * pCallbackContext,   /* Not used in this example. */
                                                 char * pLine,              /* The input buffer with response from cellular modem. */
                                                 uint32_t lineLength,       /* The length of pLine. */
                                                 char ** ppDataStart,       /* Start address of the binary data in pLine. */
                                                 uint32_t * pDataLength );  /* The length of the binary data. */
 
static CellularPktStatus_t _Cellular_RecvFuncData( CellularContext_t * pContext,                    /* The cellular module context. */
                                                   const CellularATCommandResponse_t * pAtResp,     /* The response from cellular modem. */
                                                   void * pData,                                    /* Point to dataRecv in this example. */
                                                   uint16_t dataLen );                              /* The length of the buffer pointed by &pData. */
 
CellularAtReq_t atReqSocketRecv =
{
    .pAtCmd = cmdBuf,                               /* In this example, AT+QIRD=11,1500. */
    .atCmdType = CELLULAR_AT_MULTI_DATA_WO_PREFIX,  /* The command expects multiple line or data received. */
    .pAtRspPrefix = "+QIRD",                        /* The response prefix for this command. */
    .respCallback = _Cellular_RecvFuncData,         /* The callback function to parse the response from modem. */
    .pData = ( void * ) &dataRecv,                  /* The data pointer in the callback function. */
    .dataLen = bufferLength                         /* The length of the data pointer. */
};
 
pktStatus = _Cellular_TimeoutAtcmdDataRecvRequestWithCallback( pContext,                /* The cellular context pointer. */
                                                               atReqSocketRecv,         /* The AT command structure. */
                                                               recvTimeout,             /* Timeout value for this AT command. */
                                                               socketRecvDataPrefix,    /* The data prefix callback function. */
                                                               NULL );                  /* The context of the data prefix callback. */

The data receive callback CellularATCommandDataPrefixCallback_t, socketRecvDataPrefix in this example, can return the following value to cellular interface library:

• CELLULAR_PKT_STATUS_OK : Cellular interface libary should keep process the input buffer. The following data in the input buffer will be regarded as binary data when ppDataStart and pDataLength is set in the function.

  pLine
  0	1	2	3	4	5	6	7	8	9	10	11	12	13	14	15	16	17	18	19
  +	Q	I	R	D	:		4	\r	\n	t	e	s	t	\r	\n	O	K	\r	\n
  										^ ppDataStart point to this address in pLine with pDataLength is set to 4.

  The binary data will be stored in the response and passed to the AT command response callback function.
• CELLULAR_PKT_STATUS_SIZE_MISMATCH : The callback function needs more data to decide the start and length of the binary data.
• Other error : Indicate that the moden returns unexpected response.

Cellular interface library calls the response callback function, _Cellular_RecvFuncData in this example, when it successfully receives the binary data from cellular modem. The CellularATCommandResponse_t pAtResp parameter of _Cellular_RecvFuncData contains the following list in this example:

Structure    | CellularATCommandResponse_t     CellularATCommandLine_t      CellularATCommandLine_t
Name         | pAtResp                         pAtResp->pItm                pAtResp->pNext->pItm
-------------| ---------------------------     -------------------------    -------------------------
Member       | pItm                         -> pNext                     -> pNext
             |                                 pLine = "+QIRD: 4"           pLine = "test"