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.

Blinks:

E_API_NULL_POINTER if format is null.

Blinks:

E_API_BAD_FACE if face is not a valid (physical, extended, or defiend 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.)

facePrintf() performs simple formatted printing, in the same general style as the C language printf functions, but with many restrictions -- for example, 'field widths' are not supported -- as well as 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).

XXX Still undocumented: The '#' modifier; formatting details; examples.

Examples:

brn.cpp, and log.cpp.

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

Formatted reading from a packet into individual variables.

XXX FINISH ME

With the exceptions of %s and %f, which are not supported, packetScanf supports the same format codes as facePrintf prints. packetScanf returns the number of successful matches it made, where a match counts as either a successful '% conversion' or a successful match of a literal byte of the format string. E.g., given a packet containing "f123g", packetScanf(packet,"f%dg",&u32var) will return 3 -- one for the 'f', one for the '%d', and one for the 'g'. (But watch out! Given the same packet, packetScanf(packet,"f%dg\n",&u32var) will return 4 -- including one for the successful matching of the end-of-packet!)

Examples:

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.