BOTA Recipient API

Detailed Description

Data Structures

struct  BotaDestinationMemory
 
struct  BotaRecipientMissingChunk
 Structure describing a missing chunk of data. More...
 
struct  BotaRecipientTransfer
 Structure describing a single BOTA transfer at the recipient side. More...
 
struct  BotaRecipient
 

Macro Definition Documentation

◆ BOTA_MAX_TRANSFERS

#define BOTA_MAX_TRANSFERS   10

Maximum number of simultaneous transfers that is supported.

◆ BOTA_MAX_MISSING_CHUNKS

#define BOTA_MAX_MISSING_CHUNKS   10

Maximum number of missing data chunks that can be tracked at once per transfer.

Typedef Documentation

◆ BotaOnTransferStartedCallback

typedef BotaDestinationMemory(* BotaOnTransferStartedCallback) (BotaTransferId transferId, const EMBENET_IPV6 *senderAddr, size_t bulkSize, const void *transferInfo, size_t transferInfoSize)

Type defining a function that will be called when a new incoming BOTA transfer is started in the recipient.

This callback will be called when the node receives a new (incoming) BOTA transfer from the specified sender. The node can accept or reject the transfer by producing a valid or invalid callback result.

In order to accept the transfer this function should return a structure describing the destination memory where the bulk data will be stored. This memory must have capacity greater or equal the size of the incoming bulk data (bulkSize).

In order to reject the transfer the capacity in the returned structure should be less than the size of the incoming bulk data (bulkSize) - for example it can be set to zero. In such case the other fields in the returned structure are ignored.

Once the transfer is accepted the BOTA protocol will use the provided definition of the destination memory to handle and save the incoming data.

Parameters
[in]transferIdid of the transfer
[in]senderAddraddress of the sender
[in]bulkSizesize of the incoming bulk transfer
[in]transferInfouser-defined data associated with the transfer
[in]transferInfoSizesize of the user-defined data associated with the transfer (number of bytes)
Returns
descriptor of the destination memory, where the bulk data will be stored. This result defines if the transfer will be accepted or rejected.

◆ BotaOnTransferReceivedCallback

typedef void(* BotaOnTransferReceivedCallback) (BotaTransferId transferId, const BotaDestinationMemory *memory, size_t size, const void *transferInfo, size_t transferInfoSize)

Type defining a function that will be called when an incoming BOTA transfer is received.

Parameters
[in]transferIdid of the transfer
[in]memorystructure describing the memory where the transfer data was stored
[in]sizetotal transfer size
[in]transferInfouser-defined data associated with the transfer
[in]transferInfoSizesize of the user-defined data associated with the transfer (number of bytes)

◆ BotaOnTransferAbortedCallback

typedef void(* BotaOnTransferAbortedCallback) (BotaTransferId transferId, const BotaDestinationMemory *memory, size_t size, const void *transferInfo, size_t transferInfoSize, BotaAbortReason abortReason)

Type defining a function that will be called when an incoming BOTA transfer is aborted.

Parameters
[in]transferIdid of the transfer
[in]memorystructure describing the memory where the transfer data was stored
[in]sizetotal transfer size
[in]transferInfouser-defined data associated with the transfer
[in]transferInfoSizesize of the user-defined data associated with the transfer (number of bytes)
[in]abortReasonreason why the transfer was aborted

Enumeration Type Documentation

◆ BotaAbortReason

Possible reasons for aborting the transfer.

Enumerator
BOTA_ABORT_REASON_TIMEOUT 

The BOTA transfer was aborted due to timeout.

BOTA_ABORT_REASON_TOO_MUCH_DATA_MISSING 

The BOTA transfer was aborted due the fact that too much data was missing and BOTA was unable to track it anymore.

BOTA_ABORT_REASON_CRC_MISMATCH 

The BOTA transfer was aborted due to CRC mismatch during transfer validation.

BOTA_ABORT_REASON_REUSED_ID 

The BOTA transfer was aborted due to the fact that a new transfer with the same transferId was detected.

Function Documentation

◆ BOTA_RECIPIENT_Init()

BotaResult BOTA_RECIPIENT_Init ( BotaRecipient botaRecipient,
uint16_t  port,
BotaTimeFunc  timeFunc,
BotaOnTransferStartedCallback  onTransferStarted,
BotaOnTransferReceivedCallback  onTransferReceived,
BotaOnTransferAbortedCallback  onTransferAborted 
)

Initializes the BOTA protocol instance for the recipient.

Parameters
[in]botaRecipientBOTA recipient instance
[in]portUDP port number used for BOTA transfers. This number should be the same in all BOTA-enabled devices.
[in]timeFunccallback function that will provide time for the BOTA protocol instance
[in]onTransferStartedcallback that will be called when a new incoming transfer is started. This callback is mandatory.
[in]onTransferReceivedcallback that will be called when an incoming transfer is successfully received. This callback is optional.
[in]onTransferAbortedcallback that will be called when an incoming transfer is aborted. This callback is optional.

◆ BOTA_RECIPIENT_Deinit()

void BOTA_RECIPIENT_Deinit ( BotaRecipient botaRecipient)

Deinitializes the BOTA protocol instance in the recipient.

Parameters
[in]botaRecipientBOTA recipient instance

◆ BOTA_RECIPIENT_Proc()

void BOTA_RECIPIENT_Proc ( BotaRecipient botaRecipient)

Runs the BOTA protocol instance in the recipient.

Parameters
[in]botaRecipientBOTA recipient instance

◆ BOTA_RECIPIENT_GetTransferStatus()

BotaTransferStatus BOTA_RECIPIENT_GetTransferStatus ( BotaRecipient botaRecipient,
BotaTransferId  transferId 
)

Gets the status of the incoming BOTA transfer.

Parameters
[in]botaRecipientBOTA recipient instance
[in]transferIdid of the transfer
Returns
structure describing the status of the transfer
Go to Top