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 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:
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.
[in] | transferId | id of the transfer |
[in] | senderAddr | address of the sender |
[in] | bulkSize | size of the incoming bulk transfer |
[in] | transferInfo | user-defined data associated with the transfer |
[in] | transferInfoSize | size of the user-defined data associated with the transfer (number of bytes) |
[out] | destinationMemory | destination memory structure that should be filled if the user accepts the transfer (otherwise leave it untouched) |
BOTA_TRANSFER_REACTION_ACCEPT | if the transfer should be accepted |
BOTA_TRANSFER_REACTION_REJECT | if the transfer should be rejected |
BOTA_TRANSFER_REACTION_MARK_AS_RECEIVED | if the transfer should be marked as already received |
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.
[in] | transferId | id of the transfer |
[in] | memory | structure describing the memory where the transfer data was stored |
[in] | size | total transfer size |
[in] | transferInfo | user-defined data associated with the transfer |
[in] | transferInfoSize | size of the user-defined data associated with the transfer (number of bytes) |
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.
[in] | transferId | id of the transfer |
[in] | memory | structure describing the memory where the transfer data was stored |
[in] | size | total transfer size |
[in] | transferInfo | user-defined data associated with the transfer |
[in] | transferInfoSize | size of the user-defined data associated with the transfer (number of bytes) |
[in] | abortReason | reason why the transfer was aborted |
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.
[in] | transferId | id of the transfer |
[in] | receivedSize | total transfer size |
[in] | totalSize | total transfer size |
[in] | transferInfo | user-defined data associated with the transfer |
[in] | transferInfoSize | size of the user-defined data associated with the transfer (number of bytes) |
enum BotaAbortReason |
Possible reasons for aborting the transfer.
Possible states of a single transfer.
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.
[in] | botaRecipient | BOTA recipient instance |
[in] | port | UDP port number used for BOTA transfers. This number should be the same in all BOTA-enabled devices. Consider using BOTA_DEFAULT_PORT value. |
[in] | timeFunc | callback function that will provide time for the BOTA protocol instance |
[in] | onTransferStarted | callback that will be called when a new incoming transfer is started. This callback is mandatory. |
[in] | onTransferReceived | callback that will be called when an incoming transfer is successfully received. This callback is optional. |
[in] | onTransferAborted | callback that will be called when an incoming transfer is aborted. This callback is optional. |
[in] | onTransferDataMissing | callback that will be called when the transfer missed too much data to be able to continue. This callback is optional. |
void BOTA_RECIPIENT_Deinit | ( | BotaRecipient * | botaRecipient | ) |
Deinitializes the BOTA protocol instance in the recipient.
[in] | botaRecipient | BOTA recipient instance |
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.
[in] | botaRecipient | BOTA recipient instance |
BOTA_RESULT_OK | if the service was initialized successfully |
BOTA_RESULT_INVALID_INPUT_ARGUMENT | if at least one of the input arguments was invalid |
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.
[in] | botaRecipient | BOTA recipient instance |
BOTA_RESULT_OK | if the service was initialized successfully |
BOTA_RESULT_INVALID_INPUT_ARGUMENT | if at least one of the input arguments was invalid |
void BOTA_RECIPIENT_Proc | ( | BotaRecipient * | botaRecipient | ) |
Runs the BOTA protocol instance in the recipient.
[in] | botaRecipient | BOTA recipient instance |
BotaRecipientTransferStatus BOTA_RECIPIENT_GetTransferStatus | ( | BotaRecipient * | botaRecipient, |
BotaTransferId | transferId | ||
) |
Gets the status of the incoming BOTA transfer.
[in] | botaRecipient | BOTA recipient instance |
[in] | transferId | id of the transfer |
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).
[in] | botaRecipient | BOTA recipient instance |
[in] | transferId | id of the transfer to be aborted |