# SFBPrint.h File Reference

Support for basic formatted printing. More...

`#include "SFBConstants.h"`
`#include "SFBAlarm.h"`
`#include "SFBReactor.h"`
`#include "SFBFrame.h"`

Include dependency graph for SFBPrint.h:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

## Data Structures
struct | FacePrinter
| A FacePrinter is capable of performing low-level printing operations to some assigned (physical or 'virtual') face. More...
struct | PacketPrinterHeader
| Stores the information needed to use a virtual face to print a packet into a user-supplied buffer. More...
## Defines
#define | PACKET_PRINTER_BUFFER_OVERHEAD_BYTES (sizeof(PacketPrinterHeader)+sizeof(PacketHeader)+3+1)
| The number of bytes needed to store a PacketPrinterHeader plus other associated overhead.
#define | PACKET_PRINTER_PACKET_BUFFER_SIZE (PACKET_PRINTER_BUFFER_OVERHEAD_BYTES+MAX_PACKET_LENGTH)
| The number of bytes that guarantees a user buffer will have room to print a MAX_PACKET_LENGTH packet.
## Functions
void | print (const char *str)
| Same as facePrint(u8 face, const char * str) with `face` set to ALL_FACES.
void | print (const u8 *str, u32 len)
| Same as facePrint(u8 face, const u8 * str,u32 len) with `face` set to ALL_FACES.
void | print (int decimal)
| Same as facePrint(u8 face, int decimal) with `face` set to ALL_FACES.
void | print (unsigned int decimal)
| Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.
void | print (long decimal)
| Same as facePrint(u8 face, long decimal) with `face` set to ALL_FACES.
void | print (unsigned long decimal)
| Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.
void | print (long decimal, int code)
| Same as facePrint(u8 face, unsigned long decimal, int code) with `face` set to ALL_FACES.
void | print (double val)
| Same as facePrint(u8 face, double val) with `face` set to ALL_FACES.
void | printFace ()
| Same as facePrintFace(u8 face) with `face` set to ALL_FACES.
void | printPacket (u8 *packet)
| Same as facePrintPacket(u8 face, const u8 * packet) with `face` set to ALL_FACES.
void | println ()
| Same as facePrintln(u8 face) with `face` set to ALL_FACES.
void | println (const char *str)
| Same as facePrintln(u8 face, const char * str) with `face` set to ALL_FACES.
void | println (const u8 *str, u32 len)
| Same as facePrintln(u8 face, const u8 * str,u32 len) with `face` set to ALL_FACES.
void | println (int decimal)
| Same as facePrintln(u8 face, int decimal) with `face` set to ALL_FACES.
void | println (unsigned int decimal)
| Same as facePrintln(u8 face, unsigned long decimal) with `face` set to ALL_FACES.
void | println (long decimal)
| Same as facePrintln(u8 face, long decimal) with `face` set to ALL_FACES.
void | println (unsigned long decimal)
| Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.
void | println (long decimal, int code)
| Same as facePrintln(u8 face, unsigned long decimal, int code) with `face` set to ALL_FACES.
void | println (double val)
| Same as facePrint(u8 face, double val) with `face` set to ALL_FACES.
void | printlnCheckByte ()
| Same as facePrintlnCheckByte() with `face` set to ALL_FACES.
void | facePrint (u8 face, const char *str)
| Print the contents of a null-terminated string to the current xmit packet of face.
void | facePrint (u8 face, const u8 *str, u32 len)
| Print str, an array of bytes of length len, to the current xmit packet of face.
void | facePrint (u8 face, int decimal)
| Same as facePrint(u8 face, long decimal).
void | facePrint (u8 face, unsigned int decimal)
| Print decimal as an unsigned decimal number, to the current xmit packet of face.
void | facePrint (u8 face, long decimal)
| Print decimal as a signed decimal number, to the current xmit packet of face.
void | facePrint (u8 face, unsigned long decimal)
| Same as facePrint(u8 face, unsigned long decimal, int code) with `code` set to `DEC`.
void | facePrintBinary (u8 face, u64 value)
| Output num to face in binary (big-endian, network order), taking exactly 8 bytes.
void | facePrint (u8 face, unsigned long decimal, int code)
| Print num, in a format selected by code, to the current xmit packet of face.
void | facePrint (u8 face, unsigned long decimal, int code, bool printneg, int width, bool zerofill)
| Print as described in facePrint(u8 face, unsigned long num, int code), with the following modifications:.
void | facePrint (u8 face, double val)
| Print val in a floating-point ASCII representation, with two digits to the right of the right of the decimal point.
void | facePrintFace (u8 face)
| Print the 'face code' of face to the current xmit packet of face.
void | facePrintPacket (u8 face, const u8 *packet)
| Print an existing packet embedded within the the current xmit packet of face.
void | facePrintPacketHeader (u8 face, u32 packetLen, u8 sourceFace=NORTH, u8 cursor=0, u8 flags=0)
| Print a legal packet header without the actual packet data.
void | facePrintln (u8 face)
| Terminate the current xmit packet on face.
void | facePrintln (u8 face, const char *str)
| Same as facePrint(u8 face, const char * str) followed by facePrintln().
void | facePrintln (u8 face, const u8 *str, u32 len)
| Same as facePrint(u8 face, const u8 * str,u32 len) followed by facePrintln().
void | facePrintln (u8 face, int decimal)
| Same as facePrint(u8 face, int decimal) followed by facePrintln().
void | facePrintln (u8 face, unsigned int decimal)
| Same as facePrint(u8 face, unsigned int decimal) followed by facePrintln().
void | facePrintln (u8 face, long decimal)
| Same as facePrint(u8 face, long decimal) followed by facePrintln().
void | facePrintln (u8 face, unsigned long decimal)
| Same as facePrint(u8 face, unsigned long decimal) followed by facePrintln().
void | facePrintln (u8 face, unsigned long decimal, int code)
| Same as facePrint(u8 face, unsigned long decimal, int code) followed by facePrintln().
void | facePrintln (u8 face, double val)
| Same as facePrint(u8 face, double val) followed by facePrintln().
void | facePrintlnCheckByte (u8 face)
| Prints a 'packet check byte' and then terminates the packet via facePrintln(u8 face).
bool | faceHasPrinter (u8 face)
| `true` if this face has a FacePrinter.
const FacePrinter * | faceGetPrinter (u8 face)
| Get the FacePrinter associated with this face, if any.
bool | faceFindFreeFace (u8 &foundFace)
| Find an unused 'virtual face number', if any are available.
void | faceSetPrinter (u8 face, const FacePrinter *handler)
| Associate a given FacePrinter handler with an unused 'virtual face number' face.
void | faceUnsetPrinter (u8 face)
| Remove any FacePrinter association from the 'virtual face number' face.
void | packetPrinterStoreDataByte (PacketPrinterHeader *pph, u8 byte)
| Add byte to end of the packet following the pph packet printer header.
void | packetPrinterTerminatePacket (PacketPrinterHeader *pph)
| Terminate the packet following the pph packet printer header.
u8 * | packetPrinterPrintedPacket (PacketPrinterHeader *pph)
| Get a pointer to the beginning of the packet that has been (or is, or can be, or is in the process of being) printed after the pph packet printer header.
u8 * | makePacketPrinter (u8 &assignedFace, u8 *buffer, u32 bufferLength, u8 sourceFace)
| Define a virtual face that prints a packet into a user-supplied RAM buffer.
PacketPrinterHeader * | initializePacketPrinterBuffer (const FacePrinter *fp, u8 onFace, u8 *buffer, u32 bufferLength, u8 sourceFace)
void | print_startup_initialization ()

## Detailed Description

Support for basic formatted printing.

Author:
  David H. Ackley.

Date:
  (C) 2009 All rights reserved.

Code License:
  The GNU Lesser General Public License

License Note:
  All code samples shown in documentation are placed into the public domain.

## Define Documentation

#define PACKET_PRINTER_BUFFER_OVERHEAD_BYTES (sizeof(PacketPrinterHeader)+sizeof(PacketHeader)+3+1)

The number of bytes needed to store a PacketPrinterHeader plus other associated overhead.

(This is technically the minimum legal size for 'bufferLength' in a makePacketPrinter call; but normally the passed bufferLength would be substantially larger -- up to PACKET_PRINTER_PACKET_BUFFER_SIZE -- because with this minimum size only a zero length packet can be printed.

#define PACKET_PRINTER_PACKET_BUFFER_SIZE (PACKET_PRINTER_BUFFER_OVERHEAD_BYTES+MAX_PACKET_LENGTH)

The number of bytes that guarantees a user buffer will have room to print a MAX_PACKET_LENGTH packet.

See makePacketPrinter() for details.

Examples:
  hallucination.cpp.

## Function Documentation

bool faceFindFreeFace | ( | u8 & | foundFace | ) |

Find an unused 'virtual face number', if any are available.

Returns `true` and stores into the reference variable foundFace if an available virtual face number is found.

Note that even when this method returns `true`, it does not actually make the found virtual face be 'in use'. See faceSetPrinter() for that.

Returns:
  `true` if an unused virtual face number was found, and foundFace was set to its value; `false` if all virtual faces are already in use.

const FacePrinter* faceGetPrinter | ( | u8 | face | ) |

Get the FacePrinter associated with this face, if any.

Returns:
  A pointer to the FacePrinter associated with face, or 0 if there is none, or if face is out of range.

Since:
  0.9.7

bool faceHasPrinter | ( | u8 | face | ) |

`true` if this face has a FacePrinter.

Equivalent to faceGetPrinter(face)!=0

void facePrint | ( | u8 | face,
|  | double | val |
| ) |  |  |

Print val in a floating-point ASCII representation, with two digits to the right of the right of the decimal point.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | val | A double floating point value to be printed.

Side Effects:
  The currently xmit packet of face increases in length as needed to print val, if packet length and buffer space room is available.

Example:

        ...
          float fnum = 1.23;
          double dnum = 355/113.0;
          facePrint(WEST,fnum);      // Prints "1.23" (float expands to double)
          facePrint(WEST,dnum);      // Prints "3.14" (355/113 is an ancient approximation of pi!)
        ...

void facePrint | ( | u8 | face,
|  | unsigned long | num,
|  | int | code,
|  | bool | printneg,
|  | int | width,
|  | bool | zerofill |
| ) |  |  |

Print as described in facePrint(u8 face, unsigned long num, int code), with the following modifications:.

- If printneg is `true` and num is negative when interpreted as a signed `s32`, print the absolute value of num preceded by a leading '-'
- Print at least width bytes, filling on the left with ' ' or '0'
- If zerofill is `true`, fill any extra columns with '0', otherwise use ' '.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | num | A 32 bit number to be printed in a particular format.
  | code | What format to use (see above).
  | printneg | Whether to print signed or unsigned
  | width | Minimum number of bytes to print
  | zerofill | Whether to fill extra columns with ' 's or '0's.

void facePrint | ( | u8 | face,
|  | unsigned long | num,
|  | int | code |
| ) |  |  |

Print num, in a format selected by code, to the current xmit packet of face.

The possible format codes are:

- DEC: Print one to ten bytes containing the base-10 representation of the 32 bits of num, using the ASCII characters '0' through '9'. See the 'd' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `DEC`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- HEX: Print one to eight bytes containing the base-16 representation of the 32 bits of num, using the ASCII characters '0' through '9' to represent 0 through 9, and 'A' through 'F' to represent 10 through 15. See the 'x' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `HEX`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- OCT: Print one to eleven bytes containing the base-8 representation of the 32 bits of num, using the ASCII characters '0' through '7' to represent 0 through 7. See the 'x' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `OCT`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- BIN: Print one to 32 bytes containing the base-2 representation of the 32 bits of num, using the ASCII characters '0' and '1' to represent 0 and 1. See the 'b' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `BIN`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- B36: Print one to six bytes containing the base-36 representation of the 32 bits of num, using the ASCII characters '0' through '9' to represent 0 through 9, and 'A' through 'Z' to represent 10 through 35. See the 't' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `B36`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.
- BELONG: Print exactly four bytes containing the 32 bits of num, with the four bytes in 'big endian order', also known as 'network order'. See the 'l' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `BELONG`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation. ]

`BELONG` is called a 'binary' code, but it must not be confused with BIN. With `BELONG`, each of the four output bytes may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

- BESHORT: Print exactly two bytes containing the low-order 16 bits of num, with the two bytes in 'big endian order', also known as 'network order'. See the 'h' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `BESHORT`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.

`BESHORT` is called a 'binary' code, but it must not be confused with BIN. With `BESHORT`, each of the two output bytes may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

- BYTE: Print exactly one byte containing the low-order 8 bits of num. See the 'c' code in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with code `BYTE`, and in facePrintf(u8 face, const char * format,...) for an alternate way to print in this representation.

`BYTE` is called a 'binary' code, but it must not be confused with BIN. With `BYTE`, the output byte may each contain any possible bit pattern, whereas with code BIN each output byte is either the ASCII code for '0' or the ASCII code for '1'.

In addition to those codes, it is also possible to print in other bases between 2 and 36, if there is call to do so. For example, using a code value of 13 will select printing in base 13, using the ASCII characters '0' through '9' and 'A' through 'C'.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | num | A 32 bit number to be printed in a particular format.
  | code | What format to use (see above).

Blinks:
  E_API_FORMAT_ARG If code is an illegal code. The legal codes are BELONG, BESHORT or BYTE, or any value from 2 to 36 (which includes DEC, HEX, OCT, BIN, and B36).

Side Effects:
  The currently xmit packet of face increases in length as needed by the selected format, if packet length and buffer space room is available.

Sample all-ASCII printable packet generation:

Example:

        void myHandler(u8 *) {
          facePrint(SOUTH,"L 1234 in:");
          facePrint(SOUTH," base 10="); facePrint(SOUTH, 1234, DEC); // Prints 1234
          facePrint(SOUTH," base 16="); facePrint(SOUTH, 1234, HEX); // Prints 4D2
          facePrint(SOUTH," base 8=");  facePrint(SOUTH, 1234, OCT); // Prints 2322
          facePrint(SOUTH," base 2=");  facePrint(SOUTH, 1234, BIN); // Prints 10011010010
          facePrint(SOUTH," base 36="); facePrint(SOUTH, 1234, B36); // Prints YA
          facePrintln(SOUTH);
        }

Sample binary packet generation:

Example:

        void setup() { /\* nothing to do *\/ }
        void loop() {                                  // Print a packet containing exactly eight bytes:
          facePrint(ALL_FACES,"t");                    //  1 byte containing an ASCII 't'
          facePrint(ALL_FACES,millis(),BELONG);        // +4 bytes of board uptime in big endian
          facePrint(ALL_FACES,random(10000),BESHORT);  // +2 bytes of a random number 0..9999 in big endian
          facePrintln();                               // +1 byte containing an ASCII newline '\n'
          delay(1000);                                 // Wait a second, then do it again.
        }

void facePrint | ( | u8 | face,
|  | long | decimal |
| ) |  |  |

Print decimal as a signed decimal number, to the current xmit packet of face.

Compare to facePrint(u8 face, unsigned long decimal). If decimal is less than zero, prints a '-' followed by the value of `-decimal` (note this gives the wrong output for the 'most negative' possible number.)

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | decimal | A 32 bit number to be printed as a signed decimal value.

Side Effects:
  The currently xmit packet of face gets up to eleven bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 *) {
          long num = 123-456;               // Compute something. 'int' means 'signed 32 bit value'
          facePrint(EAST,"L answer=");     // Print some text to EastFace
          facePrintln(EAST,num);           // Prints '-333' and ends the packet
        }

void facePrint | ( | u8 | face,
|  | unsigned int | decimal |
| ) |  |  |

Print decimal as an unsigned decimal number, to the current xmit packet of face.

Compare to facePrint(u8 face, int decimal).

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | decimal | A 32 bit number to be printed as an unsigned decimal value.

Side Effects:
  The currently xmit packet of face gets up to ten bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 *) {
          u32 num = 123*456;             // Compute something. 'u32' means 'unsigned 32 bit value'
          facePrint(EAST,"L answer=");   // Print some text to EastFace
          facePrintln(EAST,num);         // Prints '56088' and ends the packet
        }

void facePrint | ( | u8 | face,
|  | const u8 * | str,
|  | u32 | len |
| ) |  |  |

Print str, an array of bytes of length len, to the current xmit packet of face.

Compare to facePrint(u8 face, const char * str). If str is a packet, you may want to consider the '%p' or '%#p' formats of facePrintf() as well.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | str | A pointer to the byte array to append. Must be of length (at least) len; does not need to be null-terminated.
  | len | The length of the byte array str to append.

Blinks:
  E_API_NULL_POINTER if str is null.

Side Effects:
  The currently xmit packet of face gets up to len bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 * packet) {
          facePrint(NORTH,"L I got a packet containing '");      // Print some text to NorthFace
          facePrint(NORTH,packet,packetLength(packet));          // Add entire contents of packet
          facePrintln(NORTH,"'");                                // Add an end quote then end the packet
        }

void facePrint | ( | u8 | face,
|  | const char * | str |
| ) |  |  |

Print the contents of a null-terminated string to the current xmit packet of face.

Compare to facePrint(u8 face, const u8 * str, u32 len).

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | str | A pointer to the null-terminate string to append.

Blinks:
  E_API_NULL_POINTER if str is null.

Side Effects:
  The currently xmit packet of face gets up to `strlen(str)` bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 * packet) {
          facePrint(NORTH,"L I received a packet of length "); // Print some text to NorthFace only
          facePrintln(NORTH,packetLength(packet), DEC);        // End packet after a decimal number
        }

Examples:
  tee.cpp, zformat1.cpp, and zformat2.cpp.

void facePrintBinary | ( | u8 | face,
|  | u64 | num |
| ) |  |  |

Output num to face in binary (big-endian, network order), taking exactly 8 bytes.

Value output is readable by packetRead(u8* packet, u64& result).

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | num | A 64 bit number to be output.

Side Effects:
  The currently xmit packet of face gets eight bytes longer, if packet length and buffer space room is available.

Since:
  0.9.20

void facePrintFace | ( | u8 | face | ) |

Print the 'face code' of face to the current xmit packet of face.

See also the 'F' format of facePrintf(u8 face, const char * format,...) for another way to perform this action, and in packetScanf(u8 * packet, const char * format,...) for a way to read in a value that was printed with this method.

Parameters:

  | face | A face code indicating which face(s) to print to. If face is NORTH, SOUTH, EAST, or WEST, then 'N', 'S', 'E', or 'W' is printed, respectively. If face is ALL_FACES, then for each eligible basic face, that face's own face code is printed to the corresponding face. If it is some other 'special' or 'virtual' face, then what is printed depends on the specific code involved.

Not so amazing sample:

Example:

        ...
          facePrintFace(NORTH);          // Prints 'N' to the NorthFace
          facePrintFace(WEST);           // Prints 'W' to the WestFace
        ...

Slightly more interesting sample:

Example:

        ...
          facePrint(ALL_FACES,"L You are my "); // These three lines print "L You are my N" to the NorthFace,
          facePrintFace(ALL_FACES);             // "L You are my S" to the SouthFace, "L You are my E" to the
          facePrintln(ALL_FACES);               // EastFace, and "L You are my W" to the WestFace (assuming
        ...                                     // they are all connected and processing packets).

void facePrintln | ( | u8 | face,
|  | double | val |
| ) |  |  |

Same as facePrint(u8 face, double val) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | unsigned long | decimal,
|  | int | code |
| ) |  |  |

Same as facePrint(u8 face, unsigned long decimal, int code) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | unsigned long | decimal |
| ) |  |  |

Same as facePrint(u8 face, unsigned long decimal) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | long | decimal |
| ) |  |  |

Same as facePrint(u8 face, long decimal) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | unsigned int | decimal |
| ) |  |  |

Same as facePrint(u8 face, unsigned int decimal) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | int | decimal |
| ) |  |  |

Same as facePrint(u8 face, int decimal) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | const u8 * | str,
|  | u32 | len |
| ) |  |  |

Same as facePrint(u8 face, const u8 * str,u32 len) followed by facePrintln().

void facePrintln | ( | u8 | face,
|  | const char * | str |
| ) |  |  |

Same as facePrint(u8 face, const char * str) followed by facePrintln().

void facePrintln | ( | u8 | face | ) |

Terminate the current xmit packet on face.

Normally the effect of this is to print an ASCII newline character, '
', but that behavior may be altered by the packet framing in use on the face.

Examples:
  forward.cpp, pingpong.cpp, pingpong2.cpp, qled1.cpp, and tee.cpp.

void facePrintlnCheckByte | ( | u8 | face | ) |

Prints a 'packet check byte' and then terminates the packet via facePrintln(u8 face).

A packet check byte is a single byte value that can optionally be placed as the last byte of a packet, to provide one measure of 'integrity check' that the packet data was not corrupted during transmission. The value of a packet check byte depends on on all the previous bytes in the packet, so if any bytes of the packet were garbled while in transit, it is fairly likely, though not guaranteed, that the check byte will fail to match so the error can be detected.

See the '%
' format of facePrintf(u8 face, const char * format,...) for another way to append a check byte to a packet, and see packetReadCheckByte(u8 * packet) or the '%
' format of packetScanf(u8 * packet, const char * format,...) for ways to read and verify a check byte that was appended to a packet.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).

Side Effects:
  The currently xmit packet of face increases in length by one byte containing the computed check byte, if packet length and buffer space room is available.

void facePrintPacket | ( | u8 | face,
|  | const u8 * | packet |
| ) |  |  |

Print an existing packet embedded within the the current xmit packet of face.

Embeds one complete packet inside another, assuming there is room to do so. Unless you are sure this is what you want, it probably isn't: If you just want to print the contents of an existing packet `pkt` into the current packet on `toFace`, use:

         facePrint(toFace,pkt,packetLength(pkt);

In contrast to that approach, this function embeds the entire packet -- information about its source, its flags, everything -- not just the packet contents. Consequently, the embedding process adds five bytes of overhead, and uses 'non-printable' characters such as null bytes, so the result will not be 'human readable'. The advantage of this function is that the result can be easily read back in with packetReadPacket() to produce a valid packet.

See also facePrintPacketHeader(u8,u32,u8,u8,u8), for another, more complicated, approach to producing an embedded subpacket.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | packet | A pointer to a valid existing packet.

Blinks:
  E_API_INVALID_PACKET if packet is null or invalid.

Side Effects:
  The currently xmit packet of face gets up to 5+packetLength(const u8 *) bytes longer, if packet length and buffer space room is available.

Example:

        void myHandler(u8 * packet) {
          if (packetSource(packet)!=NORTH) {   // If packet didn't come from NORTH
            facePrint(NORTH,"t");              // Start a 'tunnel' packet heading north
            facePrintPacket(NORTH,packet);     // Embed this packet inside the 'tunnel' packet
            facePrintln(NORTH);                // Finished
        }

Since:
  0.9.9

void facePrintPacketHeader | ( | u8 | face,
|  | u32 | packetLen,
|  | u8 | sourceFace,
|  | u8 | cursor,
|  | u8 | flags |
| ) |  |  |

Print a legal packet header without the actual packet data.

This function performs part of the task of embedding a subpacket within another packet without having first to produce the subpacket in memory, so long as the length of the subpacket is known in advance. To embed a packet in another packet, first print the packet header (with appropriate arguments) using this function, then print the packet contents itself, then print a trailing null byte.

E.g.,

         facePrintf(face,"qp");  // Start a 'q' packet, with some data for whatever
         u8 * subPacketData = "foobar";  // An 'f' packet we wish to embed in the q packet..
         u32 subLen = strlen(subPacketData);  // strlen safe only because subPacketData has no nulls..
         facePrintPacketHeader(face,subLen,WEST);  // Print header for a subLen length packet from WEST
         facePrint(face,subPacketData,subLen);     // Add the subpacket data
         facePrintln(face,0,BYTE);          // Add a trailing null byte, and terminate the q packet

The packet produced by that example could be parsed by a packet handler like this:

         void qhandler(u8 * packet) {
           u8 * subp;
           if (packetScanf(packet,"qp%P\n",&subp) != 4) return;  // Parse packet, get ptr to subpacket
           pprintf("%d\n",packetLength(subp));  // prints '6' (given above example)
           pprintf("%c\n",FACE_CODE(packetSource(subp)));  // prints 'W' (ditto)
           pprintf("%s\n",subp);                // prints 'foobar' (ditto)
        }

Note that the packet header and the trailing null are all considered parts of the packet, and are therefore consumed by the P conversion; they are not matched separately during the scanning.

Parameters:

  | face | A face code indicating which face(s) to print to. May be a 'basic face' like NORTH or WEST, a 'special face' like ALL_FACES, or even a 'virtual face' defined by the sketch (see faceSetPrinter()).
  | packetLen | the length of the packet data to be embedded. This length does not include the additional required trailing null byte!
  | sourceFace | [Optional, default NORTH] The value of the packetSource(u8*) of the embedded packet.
  | cursor | [Optional, default 0] The value of the read cursor of the embedded packet.
  | flags | [Optional, default 0] The value of the packet flags of the embedded packet.

Side Effects:
  The currently xmit packet of face gets up to 4 bytes longer, if packet length and buffer space room is available.

Blinks:
  E_API_BAD_FACE if face is not a valid (extended) face. Note that sourceFace is not checked for face validity, since it is conceivable the resulting packet will be handled in a place or time with different valid faces.

Blinks:
  E_API_MAX_RANGE if packetLen is larger than MAX_PACKET_LENGTH. Note this does not check whether the specified subpacket length will actually fit in the remaining space of the outer packet.

Since:
  0.9.20

void faceSetPrinter | ( | u8 | face,
|  | const FacePrinter * | handler |
| ) |  |  |

Associate a given FacePrinter handler with an unused 'virtual face number' face.

Inverted by faceUnsetPrinter.

Blinks:
  E_API_MAX_RANGE if face is not a legal (virtual) face number number.

Blinks:
  E_API_NULL_POINTER if handler is null

Blinks:
  E_API_ZERO if the virtual face number face is already in use

Blinks:
  E_API_ARGUMENT if the FacePrinter pointed-to by handler has one but not both of its `print` and `println` methods specified.

void faceUnsetPrinter | ( | u8 | face | ) |

Remove any FacePrinter association from the 'virtual face number' face.

Inverts the effect of a faceSetPrinter call; makes face available to be returned by findFreeFace. Has no effect if the given face does not currently have an associated FacePrinter.

Blinks:
  E_API_MAX_RANGE if face is not a legal (virtual) face number number.

u8* makePacketPrinter | ( | u8 & | assignedFace,
|  | u8 * | buffer,
|  | u32 | bufferLength,
|  | u8 | sourceFace |
| ) |  |  |

Define a virtual face that prints a packet into a user-supplied RAM buffer.

The normal packet printing functions print directly to the output of a given face (or all faces). But, sometimes it is desirable to build a packet in memory without immediately sending it off-board, and this function, while a bit complicated to use, makes that possible.

Note that only one packet can be stored at a time. After a packet has been terminated, it remains available until the first byte of another packet is printed, at which time the buffer is reset and a new packet construction begins.

This 'packet printer' functionality is built on top of the faceFindFreeFace and faceSetPrinter mechanisms. So if there is a need to destroy a packet printer created by makePacketPrinter (for example to use the buffer space for something else), the virtual face number originally returned in assignedFace should be freed by called faceUnsetPrinter().

Parameters:

  | assignedFace | The assigned virtual face number, stored into by this function if it returns `true` (and unaltered otherwise.)
  | buffer | The start of the user buffer space to use. Note that the resulting printed packet will NOT be located at this address! Its address is given by the return value from this function (if non-null).
  | bufferLength | The size of the buffer space pointed-to by buffer. Must be at least PACKET_PRINTER_BUFFER_OVERHEAD_BYTES plus the number of bytes in the largest packet the user intends to print; PACKET_PRINTER_PACKET_BUFFER_SIZE will allow a maximum length packet can be stored (and so any bufferLength value larger than that will simply waste memory.)
  | sourceFace | The source face to assign to the packets printed into the buffer. Must be one of NORTH, SOUTH, EAST, WEST, SPINE, WMEM, or BRAIN, and determines where the search for reflexes starts, if a packet printed into the buffer is passed to SFBReactor::trigger(). Depending on the intended uses of the resulting packet, it may be required that sourceFace be one of the 'physical' faces (NORTH, SOUTH, EAST, WEST); so when in doubt pick one of those.

Returns:
  0 if no virtual faces are available.

Blinks:
  E_API_NULL_POINTER if buffer is null, otherwise returns the pointer to the address where (each) printed packet will be stored.

Blinks:
  E_API_GREATER_EQUAL if bufferLength is less than PACKET_PRINTER_BUFFER_OVERHEAD_BYTES

Since:
  0.9.7

Examples:
  hallucination.cpp.

u8* packetPrinterPrintedPacket | ( | PacketPrinterHeader * | pph | ) |

Get a pointer to the beginning of the packet that has been (or is, or can be, or is in the process of being) printed after the pph packet printer header.

Since:
  0.9.18

void packetPrinterStoreDataByte | ( | PacketPrinterHeader * | pph,
|  | u8 | byte |
| ) |  |  |

Add byte to end of the packet following the pph packet printer header.

Handles details of packet length management, null-termination, and dumping overlength packets. Can be used by advanced FacePrinter functions to perform makePacketPrinter -like behavior while retaining processing control (especially at end-of-packets, see packetPrinterTerminatePacket). Intended for advanced or internal use only.

Since:
  0.9.18

void packetPrinterTerminatePacket | ( | PacketPrinterHeader * | pph | ) |

Terminate the packet following the pph packet printer header.

Can be used by advanced FacePrinter functions to perform makePacketPrinter -like behavior while retaining processing control. Intended for advanced or internal use only.

XXX NEED EXAMPLE!

Since:
  0.9.18

void print | ( | double | val | ) |

Same as facePrint(u8 face, double val) with `face` set to ALL_FACES.

void print | ( | long | decimal,
|  | int | code |
| ) |  |  |

Same as facePrint(u8 face, unsigned long decimal, int code) with `face` set to ALL_FACES.

void print | ( | unsigned long | decimal | ) |

Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.

void print | ( | long | decimal | ) |

Same as facePrint(u8 face, long decimal) with `face` set to ALL_FACES.

void print | ( | unsigned int | decimal | ) |

Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.

void print | ( | int | decimal | ) |

Same as facePrint(u8 face, int decimal) with `face` set to ALL_FACES.

void print | ( | const u8 * | str,
|  | u32 | len |
| ) |  |  |

Same as facePrint(u8 face, const u8 * str,u32 len) with `face` set to ALL_FACES.

void print | ( | const char * | str | ) |

Same as facePrint(u8 face, const char * str) with `face` set to ALL_FACES.

void printFace | ( |  | ) |

Same as facePrintFace(u8 face) with `face` set to ALL_FACES.

void println | ( | double | val | ) |

Same as facePrint(u8 face, double val) with `face` set to ALL_FACES.

void println | ( | long | decimal,
|  | int | code |
| ) |  |  |

Same as facePrintln(u8 face, unsigned long decimal, int code) with `face` set to ALL_FACES.

void println | ( | unsigned long | decimal | ) |

Same as facePrint(u8 face, unsigned long decimal) with `face` set to ALL_FACES.

void println | ( | long | decimal | ) |

Same as facePrintln(u8 face, long decimal) with `face` set to ALL_FACES.

void println | ( | unsigned int | decimal | ) |

Same as facePrintln(u8 face, unsigned long decimal) with `face` set to ALL_FACES.

void println | ( | int | decimal | ) |

Same as facePrintln(u8 face, int decimal) with `face` set to ALL_FACES.

void println | ( | const u8 * | str,
|  | u32 | len |
| ) |  |  |

Same as facePrintln(u8 face, const u8 * str,u32 len) with `face` set to ALL_FACES.

void println | ( | const char * | str | ) |

Same as facePrintln(u8 face, const char * str) with `face` set to ALL_FACES.

void println | ( |  | ) |

Same as facePrintln(u8 face) with `face` set to ALL_FACES.

Examples:
  alarm1.cpp, blinkySync.cpp, eeprom2.cpp, eeprom3.cpp, pingpong2.cpp, speed2.cpp, speed3.cpp, and timer2.cpp.

void printlnCheckByte | ( |  | ) |

Same as facePrintlnCheckByte() with `face` set to ALL_FACES.

void printPacket | ( | u8 * | packet | ) |

Same as facePrintPacket(u8 face, const u8 * packet) with `face` set to ALL_FACES.

Since:
  0.9.9