# 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.

## Typedefs
typedef void(* | CustomPrintfHandler )(u8 face, void *arg, bool alt, int width, bool zerofill)
| The declaration of a function that can perform custom formatting during a printf(-family) formatting operation.
typedef bool(* | CustomPacketScanfHandler )(u8 *packet, void *arg, bool alt, int width)
| The declaration of a function that can perform custom input scanning during a packetScanf(-family) reading operation.
## Enumerations
enum | LoggingLevels { LOGLEVEL_NONE, LOGLEVEL_QUIET, LOGLEVEL_NORMAL, LOGLEVEL_VERBOSE, LOGLEVEL_DEBUG }
## Functions
void | setLogLevel (int n)
| Set the logging level to n.
int | getLogLevel ()
| Return the current logging level.
void | setLogFace (u8 face)
| Set the log face.
u8 | getLogFace ()
| Return the current log face.
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,...)
| If getLogLevel() is at least LOGLEVEL_NORMAL, print "Ln " plus a timestamp, plus as directed by format, to the current getLogFace().
void | logVerbose (const char *format,...)
| If getLogLevel() is at least LOGLEVEL_VERBOSE, print "Lv " plus a timestamp, plus as directed by format, to the current getLogFace().
void | logDebug (const char *format,...)
| If getLogLevel() is at least LOGLEVEL_DEBUG, print "Ld " plus a timestamp, plus as directed by format, to the current getLogFace().
void | logQuiet (const char *format,...)
| If getLogLevel() is at least LOGLEVEL_QUIET, print "Lq " plus a timestamp, plus as directed by format, to the current getLogFace().
void | msgf (int level, const char *format,...)
void | msgNormal (const char *format,...)
| If getLogLevel() is at least LOGLEVEL_NORMAL, print "Lq " plus as directed by format, to the current getLogFace().
void | msgVerbose (const char *format,...)
| If getLogLevel() is at least LOGLEVEL_VERBOSE, print "Lv " plus as directed by format, to the current getLogFace().
void | msgDebug (const char *format,...)
| If getLogLevel() is at least LOGLEVEL_DEBUG, print "Ld " plus as directed by format, to the current getLogFace().
void | msgQuiet (const char *format,...)
| If getLogLevel() is at least LOGLEVEL_QUIET, print "Lq " plus as directed by format, to the current getLogFace().

## 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.

## Typedef Documentation

typedef bool(* CustomPacketScanfHandler)(u8 *packet, void *arg, bool alt, int width)

The declaration of a function that can perform custom input scanning during a packetScanf(-family) reading operation.

A CustomPacketScanfHandler is established during any given packetScanf call by using the Z code and passing an argument of type CustomPacketScanfHandler. Once established, that CustomPacketScanfHandler is invoked via the z code and passing an argument of type void*, which will become the arg parameter to the CustomPacketScanfHandler function. When the CustomPacketScanfHandler is invoked, it reads from the supplied packet however it wishes to, either respecting, or not, the width and alt arguments, as it chooses.

If the return value from a CustomPacketScanfHandler is `true`, that means a successful z scan and store was performed, and the total matches returned by the packetScanf should be increased by 1, and the packet scanning should continue. If the return value is `false`, that means a scanning error occurred during the z processing, and the packetScanf should be stopped at this point.

The Z code may be used multiple times in a single packetScanf call, and the most-recent Z invocation determines what CustomPacketScanfHandler is called for any given z. It is an error if a z code is invoked without a prior Z code, or if the argument to the most recent prior Z is null, and the code will die blinking E_API_NULL_HANDLER.

See also CustomPrintfHandler.

Since:
  0.9.15

typedef void(* CustomPrintfHandler)(u8 face, void *arg, bool alt, int width, bool zerofill)

The declaration of a function that can perform custom formatting during a printf(-family) formatting operation.

A CustomPrintfHandler is established during any given printf call by using the Z code and passing an argument of type CustomPrintfHandler. Once established, that CustomPrintfHandler is invoked via the z code and passing an argument of type void*, which will become the arg parameter to the CustomPrintfHandler function. When the CustomPrintfHandler is invoked, it prints whatever it likes to face, either respecting, or not, the width, zerofill, and alt arguments, as it chooses.

Additional usage notes:

- The Z code may be used multiple times in a single printf call, in which case the most-recent Z invocation determines what CustomPrintfHandler is called.
- It is an error if a z code is invoked without a prior Z code, or if the argument to the most recent prior Z is null, and the code will die blinking E_API_NULL_HANDLER.
- An established CustomPrintfHandler association is local to the current printf invocation, lasting until the next Z code or to the end of the current format string is reached, whichever comes first.
- It is possible to call a printf(-family) function recursively from inside a CustomPrintfHandler function. Such a recursive call will have no CustomPrintfHandler established within it unless and until its format specifies one via its own Z code.

See also CustomPacketScanfHandler.

Since:
  0.9.15

## Enumeration Type Documentation

enum LoggingLevels

Enumerator:

  LOGLEVEL_NONE | When passed to setLogLevel(int), suppress all logging output.
  LOGLEVEL_QUIET | When passed to setLogLevel(int), allow less than normal logging output.
  LOGLEVEL_NORMAL | When passed to setLogLevel(int), allow normal logging output.
  LOGLEVEL_VERBOSE | When passed to setLogLevel(int), allow more than normal logging output.
  LOGLEVEL_DEBUG | When passed to setLogLevel(int), allow all logging output.

## 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, fifthdirection.cpp, hallucination.cpp, log.cpp, netled.cpp, zformat1.cpp, zformat2.cpp, and zformat3.cpp.

u8 getLogFace | ( |  | ) |

Return the current log face.

See setLogFace(u8) for details.

int getLogLevel | ( |  | ) |

Return the current logging level.

See setLogLevel(int) for details.

void logDebug | ( | const char * | format,
|  |  | ... |
| ) |  |  |

If getLogLevel() is at least LOGLEVEL_DEBUG, print "Ld " plus a timestamp, plus as directed by format, to the current getLogFace().

Otherwise do nothing.

void logNormal | ( | const char * | format,
|  |  | ... |
| ) |  |  |

If getLogLevel() is at least LOGLEVEL_NORMAL, print "Ln " plus a timestamp, plus as directed by format, to the current getLogFace().

Otherwise do nothing.

Examples:
  eeprom1.cpp, eeprom4.cpp, hallucination.cpp, profile2.cpp, profile3.cpp, reorder.cpp, sdcard1.cpp, sdcard2.cpp, sdcard3.cpp, speed4.cpp, trigger.cpp, zformat2.cpp, and zformat3.cpp.

void logQuiet | ( | const char * | format,
|  |  | ... |
| ) |  |  |

If getLogLevel() is at least LOGLEVEL_QUIET, print "Lq " plus a timestamp, plus as directed by format, to the current getLogFace().

Otherwise do nothing.

void logVerbose | ( | const char * | format,
|  |  | ... |
| ) |  |  |

If getLogLevel() is at least LOGLEVEL_VERBOSE, print "Lv " plus a timestamp, plus as directed by format, to the current getLogFace().

Otherwise do nothing.

void msgDebug | ( | const char * | format,
|  |  | ... |
| ) |  |  |

If getLogLevel() is at least LOGLEVEL_DEBUG, print "Ld " plus as directed by format, to the current getLogFace().

Otherwise do nothing.

void msgNormal | ( | const char * | format,
|  |  | ... |
| ) |  |  |

If getLogLevel() is at least LOGLEVEL_NORMAL, print "Lq " plus as directed by format, to the current getLogFace().

Otherwise do nothing.

void msgQuiet | ( | const char * | format,
|  |  | ... |
| ) |  |  |

If getLogLevel() is at least LOGLEVEL_QUIET, print "Lq " plus as directed by format, to the current getLogFace().

Otherwise do nothing.

void msgVerbose | ( | const char * | format,
|  |  | ... |
| ) |  |  |

If getLogLevel() is at least LOGLEVEL_VERBOSE, print "Lv " plus as directed by format, to the current getLogFace().

Otherwise do nothing.

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, netled.cpp, pingpong.cpp, pingpong2.cpp, reorder.cpp, sdcard3.cpp, speed2.cpp, speed3.cpp, speed4.cpp, zformat1.cpp, zformat2.cpp, and zformat3.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.

Examples:
  profile1.cpp, reorder.cpp, and sdcard3.cpp.

void setLogFace | ( | u8 | face | ) |

Set the log face.

Using this function, logging messages can be directed to any (physical or virtual) face. Default value: ALL_FACES

Examples:
  eeprom4.cpp, and trigger.cpp.

void setLogLevel | ( | int | n | ) |

Set the logging level to n.

Larger values produce more output, smaller values produce less. Initial value is LOGLEVEL_NORMAL.

Parameters:

  | n | Logging level. Can be any int, but only the values LOGLEVEL_NONE, LOGLEVEL_QUIET, LOGLEVEL_NORMAL, LOGLEVEL_VERBOSE, LOGLEVEL_DEBUG really make much sense.

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.