nl::Weave::Profiles::BDX_Development

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.

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.

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.

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.

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.

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

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.

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.

Handle cases where the transfer is finished.

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

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.