This page documents the BOTA Sender service API in C language. The BOTA Sender is a service that allows to transfer large portions of data to multpile recipients. Each of the recipients is expected to run the BOTA Recipient service (see BOTA Recipient API).
Data Structures | |
struct | BotaSenderTransferStatus |
Structure describing the status of the transfer. More... | |
struct | BotaTransferRecipient |
Structure describing the status of the recipient. More... | |
struct | BotaSenderMissingChunk |
Structure describing a data chunk that was reported missing by at least one recipient. More... | |
struct | BotaSenderTransferPolicy |
Structure describing transfer policy. More... | |
struct | BotaTransfer |
Structure describing a single BOTA transfer. More... | |
struct | BotaSender |
Structure describing BOTA Sender instance. More... | |
typedef void(* BotaOnTransferAcceptedCallback) (BotaTransferId transferId, const EMBENET_IPV6 *recipientAddr) |
Function that will be called when the transfer is accepted by a recipient (callback).
[in] | transferId | transfer identifier |
[in] | recipientAddr | IPv6 address of the recipient that accepted the transfer |
typedef void(* BotaOnTransferFinishedCallback) (BotaTransferId transferId) |
Function that will be called when the transfer is finished (callback).
[in] | transferId | transfer identifier |
enum BotaRecipientState |
Type describing the state of the recipient.
Possible states of a single transfer.
BotaResult BOTA_SENDER_Init | ( | BotaSender * | botaSender, |
uint16_t | port, | ||
BotaTimeFunc | timeFunc ) |
Initializes the Bulk-Over-The-Air (BOTA) protocol Sender instance.
[in] | botaSender | BOTA Sender 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 | mandatory callback function that will provide time for the BOTA protocol instance |
BOTA_RESULT_OK | if Bota was initialized successfully |
BOTA_RESULT_FAILED_TO_REGISTER_UDP_SOCKET | if Bota was not initialized due to problem with UDP socket registration |
void BOTA_SENDER_Deinit | ( | BotaSender * | botaSender | ) |
Deinitializes the Bulk-Over-The-Air (BOTA) protocol Sender instance.
void BOTA_SENDER_Proc | ( | BotaSender * | botaSender | ) |
Runs the Bulk-Over-The-Air (BOTA) protocol instance for the sender.
[in] | botaSender | BOTA Sender instance |
size_t BOTA_SENDER_GetRequiredTransferSpaceSize | ( | size_t | maxNumberOfRecipients | ) |
Determines how much user memory is needed to handle the transfer to the given recipient/recipients.
In order to handle parallel transmissions to multiple recipients the BOTA protocol needs some temporary memory storage. This memory is called 'transfer space' and it is required for the user to provide such memory in order to run the BOTA transfer. This function returns the size of the transfer space that the user must provide in order to handle transfer to a given maximum number of recipients.
[in] | maxNumberOfRecipients | maximum number of expected recipients |
BotaResult BOTA_SENDER_StartTransfer | ( | BotaSender * | botaSender, |
BotaReadFunc | readFunc, | ||
BotaMemoryAddr | readAddr, | ||
size_t | size, | ||
const EMBENET_IPV6 * | recipientAddr, | ||
uint16_t | recipientPort, | ||
void const * | transferInfo, | ||
size_t | transferInfoSize, | ||
void * | transferSpace, | ||
size_t | transferSpaceSize, | ||
BotaSenderTransferPolicy * | transferPolicy, | ||
BotaOnTransferAcceptedCallback | onTransferAccepted, | ||
BotaOnTransferFinishedCallback | onTransferFinished, | ||
BotaTransferId * | transferId ) |
Starts a new BOTA transfer.
This function starts a new Bulk-Over-The-Air (BOTA) transfer.
[in] | botaSender | BOTA Sender instance |
[in] | readFunc | function to read the source bulk memory |
[in] | readAddr | address in the bulk memory where the source data starts |
[in] | size | size of the bulk data to send (number of bytes) |
[in] | recipientAddr | recipient address - group addressing is allowed |
[in] | recipientPort | recipient port number |
[in] | transferInfo | user-defined data that should describe the transfer contents to the recipient |
[in] | transferInfoSize | size of the transfer information (number of bytes) |
[in] | transferSpace | pointer to a operational memory space required to handle the transfer |
[in] | transferSpaceSize | size of the provided transfer memory (number of bytes) |
[in] | transferPolicy | optional structure defining policies for the transfer (see BotaSenderTransferPolicy) |
[in] | onTransferAccepted | optional callback function that will be called when the transfer is accepted by a node |
[in] | onTransferFinished | optional callback function that will be called when the transfer is finished |
[out] | transferId | optional place to store transfer identifier |
BOTA_RESULT_OK | - if the transfer was started successfully |
BOTA_RESULT_INVALID_INPUT_ARGUMENT | - if at least one of the input arguments was invalid |
BOTA_RESULT_FAILED_TO_REGISTER_NEW_TRANSFER | - if the transfer was not started because new transfer could not be registered (possibly too many transfers are ongoing) |
BotaSenderTransferStatus BOTA_SENDER_GetTransferStatus | ( | BotaSender * | botaSender, |
BotaTransferId | transferId ) |
Gets BOTA transfer status.
This function retrieves the status of an ongoing BOTA transfer. The returned structure describes the current status of the transfer.
Note, that if the BotaSenderTransferStatus::transferState field is set to BOTA_SENDER_TRANSFER_STATE_UNKNOWN then the transfer was not found in the senders transfer list. Perhaps it was ended or the provided transferId was invalid. In such case BotaSenderTransferStatus::totalBytes and BotaSenderTransferStatus::transferredBytes are set to 0.
[in] | botaSender | BOTA Sender instance |
[in] | transferId | transfer identifier, as returned by BOTA_SENDER_StartTransfer |
size_t BOTA_SENDER_GetRecipientCount | ( | BotaSender * | botaSender, |
BotaTransferId | transferId ) |
Gets the number of recipients for an ongoing BOTA transfer.
This function gets the number of nodes that participate as recipients in the ongoing BOTA transfer.
[in] | botaSender | BOTA Sender instance |
[in] | transferId | transfer identifier, as returned by BOTA_SENDER_StartTransfer |
BotaTransferRecipient * BOTA_SENDER_GetRecipient | ( | BotaSender * | botaSender, |
BotaTransferId | transferId, | ||
size_t | index ) |
Gets the status of a single BOTA transfer recipient.
[in] | botaSender | BOTA Sender instance |
[in] | transferId | transfer identifier, as returned by BOTA_SENDER_StartTransfer |
[in] | index | recipient index (must be less than the value returned by BOTA_SENDER_GetRecipientCount) |
BotaResult BOTA_SENDER_EndTransfer | ( | BotaSender * | botaSender, |
BotaTransferId | transferId ) |
Ends a BOTA transfer.
This function causes the given BOTA transfer to end.
If the transfer is finished (BOTA_SENDER_TRANSFER_STATE_FINISHED) or an error occurred (BOTA_SENDER_TRANSFER_STATE_ERROR) then this call removes the transfer from the BOTA transfer list, making space for other transfers.
If the transfer is ongoing then it is canceled.
[in] | botaSender | BOTA Sender instance |
[in] | transferId | transfer identifier, as returned by BOTA_SENDER_StartTransfer |
BOTA_RESULT_OK | - if the transfer was ended successfully |
BOTA_RESULT_INVALID_INPUT_ARGUMENT | - if at least one of the input arguments was invalid |
BotaResult BOTA_SENDER_RetryTransfer | ( | BotaSender * | botaSender, |
BotaTransferId | transferId ) |
Restarts a BOTA transfer.
This function causes the given BOTA transfer to be restarted.
When the transfer is finished (BOTA_SENDER_TRANSFER_STATE_FINISHED) but (for example) not all recipients received the data, then the transfer can be retried.
[in] | botaSender | BOTA Sender instance |
[in] | transferId | transfer identifier, as returned by BOTA_SENDER_StartTransfer |
BOTA_RESULT_OK | - if the transfer was retried successfully |
BOTA_RESULT_INVALID_INPUT_ARGUMENT | - if at least one of the input arguments was invalid |
Any question or remarks? Just write us a message!
Feel free to get in touch