SFBPrintf.h File Reference

Support for simple packet-customized printf- and scanf-like functions. More...

#include "SFBTypes.h"
#include <stdarg.h>

Include dependency graph for SFBPrintf.h:

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

Go to the source code of this file.

Enumerations

enum  {
  LOGLEVEL_NONE,
  LOGLEVEL_QUIET,
  LOGLEVEL_NORMAL,
  LOGLEVEL_VERBOSE,
  LOGLEVEL_DEBUG
}

Functions

void setLogLevel (int n)
int getLogLevel ()
void setLogFace (u8 face)
u8 getLogFace ()
void pprintf (const char *format,...)
 Convenience shorthand for printing to all available physical faces.
void facePrintf (u8 face, const char *format,...)
 Formatted printing to the specified face.
void vfacePrintf (u8 face, const char *format, va_list &ap)
 Formatted printing to the specified face, through a supplied va_list.
u32 packetScanf (u8 *packet, const char *format,...)
 Formatted reading from a packet into individual variables.
u32 vPacketScanf (u8 *packet, const char *format, va_list &ap)
void vfaceLogf (int includeTimestamp, int level, u8 face, const char *format, va_list &ap)
void logf (int level, const char *format,...)
void logNormal (const char *format,...)
void logVerbose (const char *format,...)
void logDebug (const char *format,...)
void logQuiet (const char *format,...)
void msgf (int level, const char *format,...)
void msgNormal (const char *format,...)
void msgVerbose (const char *format,...)
void msgDebug (const char *format,...)
void msgQuiet (const char *format,...)

Detailed Description

Support for simple packet-customized printf- and scanf-like functions.

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.

Function Documentation

void facePrintf ( u8  face,
const char *  format,
  ... 
)

Formatted printing to the specified face.

Parameters:
face the face code to which the printing shall be directed. This may be a "physical face" code like WEST, an "extended face" code like BRAIN or ALL_FACES or NO_FACES, or a sketch-defined "virtual face" code (such as produced by faceFindFreeFace() and faceSetPrinter()).
format a null-terminated string controlling what is to be printed; see below.
... a variable sequence of arguments of sufficient number and appropriate types to supply to all of the "% codes" in format with the data they need.
facePrintf() performs simple formatted printing, in the same general style as the C language printf functions, but with many restrictions -- for example, there is only limited support for 'field widths'. There are also a few SFB-specific extensions. This documentation presumes familiarity with the use of printf-like functions in general, and only documents the specifics of the SFB format codes.

Quick format reference. The following 'percent escape' codes are recognized:

  • %c: Print 8 bit character into exactly one output byte.
  • %h: Print 16 bit value into exactly two output bytes in 'big endian' network order.
  • %l: Print 32 bit value into exactly four output bytes in 'big endian' network order.
  • %b: Print 32 bit value in base 2 (using only the characters '0' and '1').
  • %o: Print 32 bit value in base 8 (using only the characters '0' through '7').
  • %d: Print 32 bit value in base 10 (using only the characters '0' through '9').
  • %x: Print 32 bit value in base 16 (using only the characters '0' through '9' and 'A' through 'F' for 10 to 15).
  • %t: Print 32 bit value in base 36 (using only the characters '0' through '9' and 'A' through 'Z' for 10 to 35).
  • %F: Print the 'face code' (e.g., 'N' for North) in one output byte
  • %f: Print double value in floating point with two decimal places.
  • %s: Print null-terminated string given a (const char *) pointer to the first byte
  • %p: Print a packet given a (const u8 *) pointer to the packet
  • %%: Print a percent sign
  • %\n: Print a checkbyte and then a newline (as by printlnCheckbyte).

The '#' modifier character may be added to certain conversions to achieve special purposes, as follows:

  • For the %d code, '#' causes the argument to be printed as an unsigned value rather than signed.
  • For the %b, %o, %x, and %t codes, '#' causes the argument to be printed as a signed value rather than unsigned.
  • For the %c code, '#' causes a 'non-printing' char arg to be printed as four bytes -- a '[', two hex digits, and a ']' -- rather than printing the char value directly.
  • For the %p code, '#' causes any 'non-printing' bytes (or '%' bytes) of the packet to be printed as three bytes each -- a '%', followed by two hex digits -- rather than printing the byte values directly.

Since 0.9.7, there is limited support for field widths (a.k.a. padding and filling), with the following restrictions:

  • Padding is supported only on the formatted integer conversions --%b, %o, %d, %x, and %t,
  • Only padding on the left is supported (so, only 'right-justified columns').
  • Padding is always either spaces or zeros; spaces are used unless the field width begins with a '0'.

XXX Still need formatting details; examples.

Blinks:
E_API_NULL_POINTER if format is null.
Blinks:
E_API_BAD_FACE if face is not a valid (physical, extended, or defined virtual) face.
Blinks:
E_API_BAD_FORMAT_CODE if an unrecognized "%" code is encountered in format. (Also occurs if a single "%" is the last character in format.)
Since:
0.9.7 for field widths
Examples:
brn.cpp, hallucination.cpp, and log.cpp.

u32 packetScanf ( u8 *  packet,
const char *  format,
  ... 
)

Formatted reading from a packet into individual variables.

Scanning starts at the current packetCursor() of packet, not necessarily at the beginning, and the packetCursor() of packet is advanced as scanning proceeds.

Parameters:
packet The packet that is to be scanned.
format a null-terminated string controlling what is to be printed; see below.
... a variable sequence of pointer arguments of sufficient number and appropriate types through which to store values for all the "% codes" in format that require arguments.
With the exceptions of %s, %f, and %p, which are not supported, packetScanf supports the same format codes as facePrintf prints, which see for further description of the format conversions. Note that the pointed-to variables must be appropriate (sizes at least) for the converted type! For example, 
  void MyBHandler(u8 * packet) {
    u32 fourBytes; u16 twoBytes; u8 oneByte;
    if (packetScanf(packet,"b%c%d%h",&oneByte,&fourBytes,&twoBytes) != 4) 
       return;
    ..
  }
is correct since the sizes of the oneByte, fourBytes, and twoBytes variables match the specified sizes of %c, %d, and %h, respectively.

Since 0.9.9, there is some support for field widths, limited to the %b, %o, %d, %x, and %t conversions only.

packetScanf returns the number of successful matches it made, where a 'match' counts as either a successful '% conversion' or a successful match of a single literal byte of the format string. E.g., given a packet containing "fg123h", packetScanf(packet,"fg%dh",&u32var) will return 4 -- one for the 'f', one for the 'g', one for the '%d', and one for the 'h'. (But watch out! Given the same packet, packetScanf(packet,"fg%dh\n",&u32var) will return 5 -- including one for the successful matching of the end-of-packet!)

XXX Still need formatting details; examples.

Since:
0.9.9 for field widths
Examples:
eeprom1.cpp, pingpong.cpp, and pingpong2.cpp.

void pprintf ( const char *  format,
  ... 
)

Convenience shorthand for printing to all available physical faces.

Equivalent to facePrintf(ALL_FACES, format, ...), which see for details of the possible format codes.

void vfacePrintf ( u8  face,
const char *  format,
va_list &  ap 
)

Formatted printing to the specified face, through a supplied va_list.

See facePrintf(u8 face, const char * format, ...) for details of arguments face and format.

Generated on Wed Nov 4 06:29:07 2009 for SFB by doxygen 1.5.9