BOTA Recipient API

Table of contents Table of contents

Detailed Description

Data Structures

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

Typedef Documentation

◆ BotaOnTransferStartedCallback

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

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 or can mark that the transfer has already been received.

To accept the transfer this callback should:

  1. fill in the BotaDestinationMemory structure passed in as the memory argument
  2. return BOTA_TRANSFER_REACTION_ACCEPT Once the transfer is accepted the BOTA protocol will use the provided definition of the destination memory to handle and save the incoming data. The memory should have sufficient capacity to store the transfer data, otherwise the transfer will be aborted.

To reject the transfer this callback should return BOTA_TRANSFER_REACTION_REJECT In this case the transfer will be marked as rejected in the sender. The transfer will not be started on the recipient side.

To mark the transfer as already received this callback should return BOTA_TRANSFER_REACTION_MARK_AS_RECEIVED. In this case the transfer will be marked as succeeded in the sender. The transfer will not be started on the recipient side.

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)
[out]destinationMemorydestination memory structure that should be filled if the user accepts the transfer (otherwise leave it untouched)
Return values
BOTA_TRANSFER_REACTION_ACCEPTif the transfer should be accepted
BOTA_TRANSFER_REACTION_REJECTif the transfer should be rejected
BOTA_TRANSFER_REACTION_MARK_AS_RECEIVEDif the transfer should be marked as already received

◆ 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

◆ BotaOnTransferDataMissingCallback

typedef void(* BotaOnTransferDataMissingCallback) (BotaTransferId transferId, size_t receivedSize, size_t totalSize, const void *transferInfo, size_t transferInfoSize)

Type defining a function that will be called when an incoming BOTA transfer is missing too much data to continue.

Parameters
[in]transferIdid of the transfer
[in]receivedSizetotal transfer size
[in]totalSizetotal transfer size
[in]transferInfouser-defined data associated with the transfer
[in]transferInfoSizesize of the user-defined data associated with the transfer (number of bytes)

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_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.

BOTA_ABORT_REASON_DESTINATION_MEMORY_ERROR 

The BOTA transfer was aborted due to incorrect destination memory provided (check the onTransferStartedCallback)

BOTA_ABORT_REASON_TOO_MUCH_DATA_MISSING 

The BOTA transfer was aborted because too much data was missing in the transfer.

BOTA_ABORT_REASON_USER 

The BOTA transfer was aborted by the user.

◆ BotaRecipientTransferState

Possible states of a single transfer.

Enumerator
BOTA_RECIPIENT_TRANSFER_STATE_UNKNOWN 

The state of the transfer is unknown.

BOTA_RECIPIENT_TRANSFER_STATE_ACCEPTED 

The transfer has been accepted by the user.

BOTA_RECIPIENT_TRANSFER_STATE_REJECTED 

The transfer is rejected by the user.

BOTA_RECIPIENT_TRANSFER_STATE_RECEIVING_DATA 

The transfer is in the process of receiving data packets.

BOTA_RECIPIENT_TRANSFER_STATE_RECEIVED 

The transfer is received.

BOTA_RECIPIENT_TRANSFER_STATE_HALTED 

The transfer is halted.

Function Documentation

◆ BOTA_RECIPIENT_Init()

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

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. Consider using BOTA_DEFAULT_PORT value.
[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.
[in]onTransferDataMissingcallback that will be called when the transfer missed too much data to be able to continue. 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_Start()

BotaResult BOTA_RECIPIENT_Start ( BotaRecipient botaRecipient)

Starts the BOTA Recipient service.

This function starts the BOTA Recipient service. It is typically called in reaction to the event that the node has joined a network.

Parameters
[in]botaRecipientBOTA recipient instance
Return values
BOTA_RESULT_OKif the service was initialized successfully
BOTA_RESULT_INVALID_INPUT_ARGUMENTif at least one of the input arguments was invalid

◆ BOTA_RECIPIENT_Stop()

BotaResult BOTA_RECIPIENT_Stop ( BotaRecipient botaRecipient)

Stops the BOTA Recipient service.

This function stops the BOTA Recipient service. It is typically called in reaction to the event that the node has left a network. Call this function will cause all the ongoing transfers to be halted. A halted transfer is be picked up when the BOTA Sender restarts such transfer. The service can be restarted by a call to BOTA_RECIPIENT_Start.

Parameters
[in]botaRecipientBOTA recipient instance
Return values
BOTA_RESULT_OKif the service was initialized successfully
BOTA_RESULT_INVALID_INPUT_ARGUMENTif at least one of the input arguments was invalid

◆ 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()

BotaRecipientTransferStatus 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 at the recipient

◆ BOTA_RECIPIENT_AbortTransfer()

void BOTA_RECIPIENT_AbortTransfer ( BotaRecipient botaRecipient,
BotaTransferId  transferId 
)

Aborts the ongoing transfer in the recipient.

This function allows to abort the ongoing transfer. It can be called from within the read and write functions of the destination memory (BotaDestinationMemory::read, BotaDestinationMemory::write). This function can also be used from other callbacks such as onTransferStarted as long as it aborts some other transfer, and not the one the given callback refers to. Aborting the transfer from its own onTransferStarted, onTransferReceived or onTransferAborted callback makes no sense and is not supported (may lead to undefined behavior).

Calling this function invokes the onTransferAborted callback (if it was provided).

Parameters
[in]botaRecipientBOTA recipient instance
[in]transferIdid of the transfer to be aborted