Sifteo::BluetoothPipe< tSendCapacity, tReceiveCapacity > Struct Template Reference

A memory buffer for bidirectional Bluetooth communications. More...

#include <sifteo/bluetooth.h>

Public Member Functions
void	attach ()
	Attach this pipe to the system. More...
void	detach ()
	Detach all pipes from the system. More...
bool	read (BluetoothPacket &buffer)
	If a packet is available in the queue, read it. More...
unsigned	readAvailable () const
	How many packets are available to read from this queue right now?
bool	write (const BluetoothPacket &buffer)
	Write one packet to the send queue, if space is available. More...
unsigned	writeAvailable () const
	How many free buffers are available for writing right now?

Public Attributes
BluetoothQueue< tReceiveCapacity >	receiveQueue
	Queue for packets that have been received but not yet processed.
BluetoothQueue< tSendCapacity >	sendQueue
	Queue for packets we're waiting to send.

Detailed Description

template<unsigned tSendCapacity = 4, unsigned tReceiveCapacity = 4>
struct Sifteo::BluetoothPipe< tSendCapacity, tReceiveCapacity >

A memory buffer for bidirectional Bluetooth communications.

This is a pair of FIFO buffers which can be used for bidirectional communication over Bluetooth. When the pipe is "attached", this Base becomes available to send and receive application-specific packets over Bluetooth.

When the pipe is not attached or no pipe has been allocated, the Sifteo Bluetooth API will throw an error if application-specific packets are sent. However the Bluetooth API provides generic functionality which can be used even without a BluetoothPipe.

If the BluetoothPipe's receiveQueue is full, the Sifteo Bluetooth API will not be allowed to transmit more packets until our receiveQueue has room. Packets will not be dropped if the buffer fills up.

Some applications may desire lower-level access to the data queues we use. Those applications may access 'sendQueue' and 'receiveQueue' directly, and use the methods on those BluetoothQueue objects.

Applications that do not need this level of control can use the read() and write() methods on this object directly.

Bluetooth packets do not have guaranteed delivery like TCP sockets. Instead, they have low latency but it's possible for data to be lost, more like UDP sockets. To summarize the guarantees made by BluetoothPipe:

1. Does NOT guarantee that a packet is ever delivered. Packets can always be dropped.
2. Does NOT provide end-to-end flow control. Packets received while the receive queue is full will be dropped.
3. DOES provide data integrity, through the Bluetooth protocol's standard CRC. If a packet arrives at all, it's very unlikely to be corrupted.
4. DOES guarantee in-order delivery, if packets are ever delivered.
5. DOES provide local transmit flow control, so it's easy to write at the radio's max transmit rate.

Member Function Documentation

template<unsigned tSendCapacity = 4, unsigned tReceiveCapacity = 4>

void Sifteo::BluetoothPipe< tSendCapacity, tReceiveCapacity >::attach ( )

inline

Attach this pipe to the system.

When a pipe is "attached", the system will write incoming packets to our receiveQueue and it will be looking for transmittable packets in our sendQueue.

This buffer must stay allocated as long as it's attached to the system. If you plan on recycling or freeing this memory, make sure to detach() it first.

If there was already a different pipe attached, this one replaces it. The previous pipe is automatically detached.

This method clears the send and receive queues. Both queues will be empty when they're first attached to the system.

template<unsigned tSendCapacity = 4, unsigned tReceiveCapacity = 4>

void Sifteo::BluetoothPipe< tSendCapacity, tReceiveCapacity >::detach ( )

inline

Detach all pipes from the system.

After this call, the Sifteo Bluetooth API will throw an error if application-specific packets are sent to us. The BluetoothPipe may be recycled or freed.

template<unsigned tSendCapacity = 4, unsigned tReceiveCapacity = 4>

bool Sifteo::BluetoothPipe< tSendCapacity, tReceiveCapacity >::read ( BluetoothPacket &  buffer )

inline

If a packet is available in the queue, read it.

If a packet is available, copies it to 'buffer' and returns 'true'. If no packets are waiting, returns 'false'.

template<unsigned tSendCapacity = 4, unsigned tReceiveCapacity = 4>

bool Sifteo::BluetoothPipe< tSendCapacity, tReceiveCapacity >::write ( const BluetoothPacket &  buffer )

inline

Write one packet to the send queue, if space is available.

This copies the provided packet into our send queue and returns 'true' if space is available. If the queue is full, returns 'false'.

For more detailed control over the queue, see the methods on our 'sendQueue' member.

---

The documentation for this struct was generated from the following file:

• bluetooth.h