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

Generated on Fri Apr 22 06:56:19 2011 for SFB by doxygen 1.5.9