PacketBuffer¶
Overview¶
PacketBuffer provides a basic set of functions for the creation, manipulation and accessing of a managed type for byte arrays used to hold network data packets. It is often beneficial in both wired and wireless communication protocols to send and receive data in a raw format, viewed as an ordered sequence of bytes.
uBit.radio provides direct micro:bit to micro:bit communication and can interface directly with PacketBuffers.
Note
This is a managed type. This means that it will automatically use and release memory as needed. There is no need for you to explicitly free or release memory when you're done - the memory will be freed as soon as the last piece of code stops using the data.
Creating PacketBuffers¶
It is simple to create a PacketBuffer - just create them like a variable, and provide the size (in bytes) of the buffer you want to create.
PacketBuffer b(16);
Alternatively, if you already have an array of bytes allocated, then you can simply refer to that using a slightly different form:
1 2 | |
Using PacketBuffers¶
Manipulating¶
Once created, the data inside a PacketBuffer can be freely changed at any time. The simplest way to do this is through the array operators [ and ].
You can read or write bytes to the buffer by simply dereferencing it with square bracket.
For example, to create, set and send a PacketBuffer on the micro:bit radio, you could do the following:
Example
1 2 3 4 5 | |
You can also directly assign a received value to a PacketBuffer:
1 2 | |
Buffer to bytes¶
If you need more granular access, the getBytes function provides direct access to the memory buffer, presented as a byte array:
1 2 3 4 | |
Extracting signal strength¶
It is possible to extract the received signal strength of a packet from a PacketBuffer.
This can provide both a rough indication of the reliability of the link, and a crude but moderately effective mechanism to estimate the distance between two micro:bits.
1 2 3 4 | |
API¶
operator=¶
ManagedString operator=( const ManagedString & s)
Description
Copy assign operation.
Called when one ManagedString is assigned the value of another.
If the ManagedString being assigned is already referring to a character buffer, decrement the reference count and free up the buffer as necessary.
Then, update our character buffer to refer to that of the supplied ManagedString , and increase its reference count.
Parameters
const ManagedString &s - The ManagedString to copy.
Example
ManagedString s("abcd");
ManagedString p("efgh");
p = s // p now points to s, s' ref is incremented
operator==¶
bool operator==( const ManagedString & s)
Description
Equality operation.
Called when one ManagedString is tested to be equal to another using the '==' operator.
Parameters
const ManagedString &s - The ManagedString to test ourselves against.
Returns
true if this ManagedString is identical to the one supplied, false otherwise.
Example
DeviceDisplay display;
ManagedString s("abcd");
ManagedString p("efgh");
if(p == s)
display.scroll("We are the same!");
else
display.scroll("We are different!"); //p is not equal to s - this will be called
operator!=¶
bool operator!=( const ManagedString & s)
Description
Inequality operation.
Called when one ManagedString is tested to be not equal using the '!=' operator.
Parameters
const ManagedString &s - The ManagedString to test ourselves against.
Returns
true if this ManagedString is identical to the one supplied, false otherwise.
Example
DeviceDisplay display;
ManagedString s("abcd");
ManagedString p("efgh");
if(p != s)
display.scroll("We are different!");
else
display.scroll("We are the same!");
operator<¶
bool operator<( const ManagedString & s)
Description
Inequality operation.
Called when one ManagedString is tested to be less than another using the '<' operator.
Parameters
const ManagedString &s - The ManagedString to test ourselves against.
Returns
true if this ManagedString is alphabetically less than to the one supplied, false otherwise.
Example
DeviceDisplay display;
ManagedString s("a");
ManagedString p("b");
if(s < p)
display.scroll("a is before b!"); //a is before b
else
display.scroll("b is before a!");
operator>¶
bool operator>( const ManagedString & s)
Description
Inequality operation.
Called when one ManagedString is tested to be greater than another using the '>' operator.
Parameters
const ManagedString &s - The ManagedString to test ourselves against.
Returns
true if this ManagedString is alphabetically greater than to the one supplied, false otherwise.
Example
DeviceDisplay display;
ManagedString s("a");
ManagedString p("b");
if(p>a)
display.scroll("b is after a!"); //b is after a
else
display.scroll("a is after b!");
substring¶
ManagedString substring( int16_t start, int16_t length)
Description
Extracts a ManagedString from this string, at the position provided.
Parameters
int16_tstart - The index of the first character to extract, indexed from zero.int16_tlength - The number of characters to extract from the start position
Returns
a ManagedString representing the requested substring.
Example
DeviceDisplay display;
ManagedString s("abcdefg");
display.scroll(s.substring(0,2)) // displays "ab"
charAt¶
char charAt( int16_t index)
Description
Provides a character value at a given position in the string, indexed from zero.
Parameters
int16_tindex - The position of the character to return.
Returns
the character at posisiton index, zero if index is invalid.
Example
DeviceDisplay display;
ManagedString s("abcd");
display.scroll(s.charAt(1)) // scrolls "b"
toCharArray¶
const char * toCharArray()
Description
Provides an immutable 8 bit wide character buffer representing this string.
Returns
a pointer to the character buffer.
length¶
int16_t length()
Description
Determines the length of this ManagedString in characters.
Returns
the length of the string in characters.
Example
DeviceDisplay display;
ManagedString s("abcd");
display.scroll(s.length()) // scrolls "4"
Component Constructor¶
Advanced users only
Do not use this unless you really know what you're doing. It's usually best to use uBit.
friend ManagedString( codal::operator+ )
Description
Concatenates two strings.
Parameters
codal::operator+
Returns
a new ManagedString representing the joined strings.
Example
DeviceDisplay display;
ManagedString s("abcd");
ManagedString p("efgh")
display.scroll(s + p) // scrolls "abcdefgh"