nl::Weave::Profiles::BDX_Development

This namespace includes all interfaces within Weave for the Bulk Data Transfer (BDX) profile that are actively under development and should not be used for production use.

Summary

Enumerations

@80 enum
@81 enum
@82 enum
@83 enum

Typedefs

BdxClient typedef
BdxServer typedef
ErrorHandler)(BDXTransfer *aXfer, WEAVE_ERROR anErrorCode) typedef
void(*
This handler is called any time a Weave error is encountered that cannot directly be returned via error codes to user-application-defined control flow.
GetBlockHandler)(BDXTransfer *aXfer, uint64_t *aLength, uint8_t **aDataBlock, bool *aLastBlock) typedef
void(*
Get a block of data to be transmitted.
PutBlockHandler)(BDXTransfer *aXfer, uint64_t aLength, uint8_t *aDataBlock, bool aLastBlock) typedef
void(*
Handle the block of data pointed to by aDataBlock of length aLength.
ReceiveAcceptHandler)(BDXTransfer *aXfer, ReceiveAccept *aReceiveAcceptMsg) typedef
Callback invoked when a previously sent ReceiveInit is accepted by the destination.
ReceiveInitHandler)(BDXTransfer *aXfer, ReceiveInit *aReceiveInitMsg) typedef
uint16_t(*
Callback invoked when receiving a ReceiveInit message.
RejectHandler)(BDXTransfer *aXfer, StatusReport *aReport) typedef
void(*
Invoked if one of the previous Init messages was rejected by the destination.
SendAcceptHandler)(BDXTransfer *aXfer, SendAccept *aSendAcceptMsg) typedef
Callback invoked when a previously sent SendInit is accepted by the destination.
SendInitHandler)(BDXTransfer *aXfer, SendInit *aSendInitMsg) typedef
uint16_t(*
Callback invoked when receiving a SendInit message.
XferDoneHandler)(BDXTransfer *aXfer) typedef
void(*
Handle cases where the transfer is finished.
XferErrorHandler)(BDXTransfer *aXfer, StatusReport *aXferError) typedef
void(*
Handle TransferError messages received or sent by BDX.

Functions

GetBDXAckFlag(ExchangeContext *anEc)
uint16_t
GetBDXAckFlag returns the appropriate flag for the RequestAck field depending on the exchange context's connection (no request ack for TCP), and based on compile time support for WRMP.

Classes

nl::Weave::Profiles::BDX_Development::BdxNode
nl::Weave::Profiles::BDX_Development::BlockAck

The BlockAck message is used to acknowledge a block of data.

nl::Weave::Profiles::BDX_Development::BlockAckV1

The BlockAckV1 message is used to acknowledge a block of data.

nl::Weave::Profiles::BDX_Development::BlockEOF

The BlockEOF message is used to transfer the last block of data from sender to receiver.

nl::Weave::Profiles::BDX_Development::BlockEOFAck

The BlockEOFAck message is used to acknowledge the last block of data.

nl::Weave::Profiles::BDX_Development::BlockEOFAckV1

The BlockEOFAckV1 message is used to acknowledge the last block of data.

nl::Weave::Profiles::BDX_Development::BlockEOFV1

The BlockEOFV1 message is used to transfer the last block of data from sender to receiver.

nl::Weave::Profiles::BDX_Development::BlockQuery

The BlockQuery message is used to request that a block of data be transferred from sender to receiver.

nl::Weave::Profiles::BDX_Development::BlockQueryV1

The BlockQueryV1 message is used to request that a block of data be transferred from sender to receiver.

nl::Weave::Profiles::BDX_Development::BlockSend

The BlockSend message is used to transfer a block of data from sender to receiver.

nl::Weave::Profiles::BDX_Development::BlockSendV1

The BlockSendV1 message is used to transfer a block of data from sender to receiver.

nl::Weave::Profiles::BDX_Development::ReceiveAccept

The ReceiveAccept message is used to accept a proposed exchange when the receiver is the initiator.

nl::Weave::Profiles::BDX_Development::ReceiveInit

The ReceiveInit message is used to start an exchange when the receiver is the initiator.

nl::Weave::Profiles::BDX_Development::ReceiveReject

The ReceiveReject message is used to reject a proposed exchange when the sender is the initiator.

nl::Weave::Profiles::BDX_Development::SendAccept

The SendAccept message is used to accept a proposed exchange when the sender is the initiator.

nl::Weave::Profiles::BDX_Development::SendInit

The SendInit message is used to start an exchange when the sender is the initiator.

nl::Weave::Profiles::BDX_Development::SendReject

The SendReject message is used to reject a proposed exchange when the sender is the initiator.

nl::Weave::Profiles::BDX_Development::TransferError

The Error message is used to report an error and abort an exchange.

Structs

nl::Weave::Profiles::BDX_Development::BDXHandlers
nl::Weave::Profiles::BDX_Development::BDXTransfer

This structure contains data members representing an active BDX transfer.

Namespaces

nl::Weave::Profiles::BDX_Development::BdxProtocol

Enumerations

@80

 @80

@81

 @81

@82

 @82

@83

 @83

Typedefs

BdxClient

BdxNode BdxClient

BdxServer

BdxNode BdxServer

ErrorHandler

void(* ErrorHandler)(BDXTransfer *aXfer, WEAVE_ERROR anErrorCode)

This handler is called any time a Weave error is encountered that cannot directly be returned via error codes to user-application-defined control flow.

That is, if an error occurs within another handler whose signature has return type void (e.g. in response to an incoming Weave message or even dispatched by the protocol), this handler will be called so that the user can determine whether the transfer can be recovered and continue or if they should call Shutdown(). Note that it is possible for an error to occur before a BDXTransfer is initialized (e.g. already too many allocated transfer objects). In such a case, said error will be logged by Weave and the protocol will handle cleaning up any necessary state that it allocated.

Details
Parameters
[in] aXfer
Pointer to the BDXTransfer associated with this transfer
[in] anErrorCode
The error code that we need to process

GetBlockHandler

void(* GetBlockHandler)(BDXTransfer *aXfer, uint64_t *aLength, uint8_t **aDataBlock, bool *aLastBlock)

Get a block of data to be transmitted.

The caller provides the buffering space (buffer and length of the buffer, passed in by reference). Callee (user application) SHOULD use the provided buffer, but for backward compatibility reasons, may return its own buffer. Callee must not provide more than the aLength of bytes. On return, aLength contains the actual number of bytes read into the buffer.

Details
Parameters
[in] aXfer
The BDXTransfer associated with this ongoing transfer
[in,out] aLength
The length of data read and stored in this block. On call to the function contains the length of the of the buffer passed in the aDataBlock. On return, the variable contains the length of data actually read.
[in,out] aDataBlock
The pointer to the block of data. On input, it contains the framework- provided buffer; the callee may use that space to fill the buffer, or provide its own buffering space (for backward compatibility applications). Applications using provided buffer must not assume any alignment.
[out] aLastBlock
True if the block should be sent as a BlockEOF and the transfer completed, false otherwise

PutBlockHandler

void(* PutBlockHandler)(BDXTransfer *aXfer, uint64_t aLength, uint8_t *aDataBlock, bool aLastBlock)

Handle the block of data pointed to by aDataBlock of length aLength.

Likely this will involve writing it to a file and closing said file if isLastBlock is true.

Details
Parameters
[in] aXfer
The BDXTransfer associated with this ongoing transfer
[in] aLength
The length of data read and stored in the specified block
[in] aDataBlock
The actual block of data
[in] aLastBlock
True if the block was received as a BlockEOF and the transfer completed, false otherwise. If true, the programmer should probably finalize any file handles, keeping in mind that the XferDoneHandler will be called after this

ReceiveAcceptHandler

WEAVE_ERROR(* ReceiveAcceptHandler)(BDXTransfer *aXfer, ReceiveAccept *aReceiveAcceptMsg)

Callback invoked when a previously sent ReceiveInit is accepted by the destination.

You may wish to use this opportunity to open files or allocate resources for the transfer if you did not do so when initiating it.

Details
Parameters
[in] aXfer
Pointer to the BDXTransfer associated with this transfer
[in] aReceiveAcceptMsg
Pointer to the ReceiveAccept message that we are processing

ReceiveInitHandler

uint16_t(* ReceiveInitHandler)(BDXTransfer *aXfer, ReceiveInit *aReceiveInitMsg)

Callback invoked when receiving a ReceiveInit message.

Its job is to determine if you want to accept the Receive and, if so, set aXfer->mIsAccepted=true so that the protocol will send an accept message to the initiator. The BDXTransfer object is initiated to default settings. This is a good place to attach any application-specific state (open file handles, etc.) to aXfer->mAppState. You should also attach the necessary handlers for e.g. block handling to the BDXTransfer object at this point. If an error code other than kStatus_Success is returned, the transfer is assumed to be rejected and the protocol will handle sending a reject message with the code.

Details
Parameters
[in] aXfer
Pointer to the BDXTransfer associated with this transfer
[in] aReceiveInitMsg
Pointer to the ReceiveInit message that we are processing

RejectHandler

void(* RejectHandler)(BDXTransfer *aXfer, StatusReport *aReport)

Invoked if one of the previous Init messages was rejected by the destination.

Details
Parameters
[in] aXfer
Pointer to the BDXTransfer associated with this transfer
[in] aReport
Pointer to the StatusReport message rejection that we are processing

SendAcceptHandler

WEAVE_ERROR(* SendAcceptHandler)(BDXTransfer *aXfer, SendAccept *aSendAcceptMsg)

Callback invoked when a previously sent SendInit is accepted by the destination.

You may wish to use this opportunity to open files or allocate resources for the transfer if you did not do so when initiating it.

Details
Parameters
[in] aXfer
Pointer to the BDXTransfer associated with this transfer
[in] aSendAcceptMsg
Pointer to the SendAccept message that we are processing

SendInitHandler

uint16_t(* SendInitHandler)(BDXTransfer *aXfer, SendInit *aSendInitMsg)

Callback invoked when receiving a SendInit message.

Its job is to determine if you want to accept the SendInit and, if so, set aXfer->mIsAccepted=true so that the protocol will send an accept message to the initiator. The BDXTransfer object is initiated to default settings. This is a good place to attach any application-specific state (open file handles, etc.) to aXfer->mAppState. You should also attach the necessary handlers for e.g. block handling to the BDXTransfer object at this point. If an error code other than WEAVE_NO_ERROR is returned, the transfer is assumed to be rejected and the protocol will handle sending a reject message with the code.

Details
Parameters
[in] aXfer
Pointer to the BDXTransfer associated with this transfer
[in] aSendInitMsg
Pointer to the SendInit message that we are processing

XferDoneHandler

void(* XferDoneHandler)(BDXTransfer *aXfer)

Handle cases where the transfer is finished.

Details
Parameters
[in] aXfer
Pointer to the BDXTransfer associated with this transfer

XferErrorHandler

void(* XferErrorHandler)(BDXTransfer *aXfer, StatusReport *aXferError)

Handle TransferError messages received or sent by BDX.

Note:The BDX transfer is presumed to be potentially recoverable (possibly temporary e.g. out of PacketBuffers at the moment) and so the option of calling Shutdown() is left to the application programmer and the callbacks they define. TODO: verify this and reconcile it with the language in the BDX document, which states: "[A TransferError] Can be sent at any time by either party to prematurely end the bulk data transfer."

Details
Parameters
[in] aXfer
Pointer to the BDXTransfer associated with this transfer
[in] aXferError
Pointer to the StatusReport message error that we are processing

Functions

GetBDXAckFlag

uint16_t GetBDXAckFlag(
  ExchangeContext *anEc
)

GetBDXAckFlag returns the appropriate flag for the RequestAck field depending on the exchange context's connection (no request ack for TCP), and based on compile time support for WRMP.

Details
Parameters
[in] anEc
The exchange context we should get the flag based on
Returns
0 or kSendFlag_RequestAck