weAut_01 / weAutSys    R 2.2.1
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Defines
Files | Data Structures | Defines | Functions
Streams
+ + Application (layer) support + +

Overview

weAut_01' devices for communication input/output supported by weAutSys can be used directly and via the respective modules / functions. Additionally some of those devices are offered (wrapped) as standard (or stdio.h) streams. In the reset default state stdin/err/out go to or come from the UART.

The reasons for using such streams instead of direct I/O programming / usage are

The last point is strongly deprecated. printf, scanf and cognates are quite resource hungry. For a small µController (in a resource saving appliance) and in a non preemptive (Protothreads) runtime this will quickly get a problem and shall be restricted to debugging and may be initialisation before the real (time) work. Using weAutSys' formatting and parsing functions instead will reduce the memory and processor usage by factors five and more.


Files

file  log_streams.h
 

Buffered log stream (definitions)


file  streams.h
 

Streams (definitions)


Data Structures

struct  streamClassDescript_t
 Extra stream (type) specific data. More...

Defines

#define AVAILABLE_UNKNOWN   0xFFFF
 Available input unknown.
#define LAN_IS_STDOUT
 stdout is the LAN stream output (Ethernet, uIP)
#define SER_IS_STDOUT
 stdout is the serial output (UART)
#define USE_AVR_GCC_FILE   1
 use AVR FILE type internals

The buffered log streams

FILE bufLogStreams
 The stream "device" being a buffer for logging.
struct thr_data_tbufLogCons
 The consumer of buffered log streams output (text) data.
void bufLogStreamsInit (void)
 Initialise the buffered log streams.
void bufLogStreamsOpen (void)
 Open the buffered log streams.
uint16_t bufLogInBufferd (FILE *streams)
 The number of characters buffered in buffered log streams for input.
int bufLogGetC (void)
 Get one byte from buffered stream input.
uint16_t bufLogGetChars (char *dst, uint16_t n)
 Get a number of bytes from buffered stream input.
uint8_t uartPutLogBuf (void)
 Put characters from buffered log streams to serial output.
uint16_t bufLogStreamsOutSpace (FILE *streams) __attribute__((pure))
 The buffer space available for buffered log streams output.
uint8_t bufLogCheckOutSpace (uint16_t const reqSpace, FILE *const streams)
 Check the space available buffered log streams output.
void bufLogPutC (char const c)
 Put one byte to buffered stream output.
void bufLogPut2C (char const c1, char const c2)
 Put two bytes to buffered stream output.
int bufLogGetChar (FILE *const stream)
 Get one byte from buffered stream input.
int bufLogPutChar (char c, FILE *const stream)
 Put one byte to buffered stream output.
int bufLogPutSt (char *src, FILE const *const stream)
 Put a RAM string (some characters) to buffered stream output.
int bufLogPutSt_P (char *src, FILE const *const stream)
 Put some characters from program space to buffered stream output.
#define BUF_STREAMS_CAP   2047
 The buffered log streams capacity.
#define bufLogConsIsUART
 The UART is the consumer of buffered log streams output (text) data.
#define bufLogSetConsumer(tD)
 Set the consumer of buffered log streams output (text) data.
#define bufLogSetUART()
 Set the UART as consumer of buffered log streams output.
#define BufLogInBufferd
 The number of characters buffered in buffered log streams for input.

Common stream handling definitions

typedef uint16_t(* str2InBufferd )(const FILE *stream)
 Function pointer / type: number of characters buffered for input.
typedef uint16_t(* str2OutSpace )(const FILE *stream)
 Function pointer / type: buffer space available for output.
typedef uint8_t(* str2CheckOutSpace )(uint16_t reqSpace, const FILE *stream)
 Function pointer / type: checking the space available for output.
typedef int(* str2PutS )(char *src, const FILE *stream)
 Function pointer / type: writing a RAM string to output.
typedef int(* str2PutS_P )(prog_char *src, const FILE *stream)
 Function pointer / type: writing a flash memory string to output.
typedef struct
streamClassDescript_t 
streamClassDescript_s
 Extra stream (type) specific data (structure)
uint16_t inBufferd (const FILE *stream)
 Number of characters buffered for input.
uint16_t outSpace (const FILE *stream)
 Buffer space available for output.
uint8_t checkOutSpace (uint16_t reqSpace, const FILE *stream)
 Checking the space available for output.
int putSt (char *src, const FILE *stream)
 Write a RAM string to output.
int putSt_P (char const *src, const FILE *stream)
 Write a flash memory string to output.
#define PT_YIELD_OUT_SPACE(pt, requSpace, streams)
 Set standard I/O and exit or yield for requested output space.
#define PT_WAIT_OUT_SPACE(pt, requSpace, streams)
 Set standard I/O and exit or wait for requested output space.

The serial streams

FILE serStreams
 The stream "device" connected to the serial IO / UART(0)
void serStreamsOpen (void)
 Open the serial (UART) streams.
uint16_t serStreamsOutSpace (FILE *streams)
 The buffer space available for serial output.
uint8_t serCheckOutSpace (uint16_t reqSpace, FILE *streams)
 Check the space available for serial output.
int serPutChar (char c, FILE *stream)
 Put one byte to serial output.

Recommended standard I/O functions

void stdPutC (char c)
 Write a character to stdout.
void logStackS (uint8_t maxBytes)
 Log the stack frame to stdout.
#define stdPutS(src)
 Write a RAM string to stdout.
#define stdPutS_P(src)
 Write a flash memory string to stdout.

The Ethernet / LAN streams

FILE lanStreams
 The stream "device" connected to the Ethernet (uIP)
void lanStreamsInit (void)
 Initialise the Ethernet / LAN streams.
void lanStreamsEcho (void)
 Set the Ethernet / LAN streams to echo input.
void lanStreamsOpen (void)
 Open the Ethernet / LAN streams.
void lanStreamSend (void)
 Sends the LAN streams data (over the Ethernet)
uint16_t lanStreamsOutSpace (FILE *streams)
 The buffer space available for Ethernet / LAN streams output.
uint8_t lanCheckOutSpace (uint16_t reqSpace, FILE *streams)
 Check the space available Ethernet / LAN streams output.
uint16_t lanInBufferd (FILE *streams)
 The number of characters buffered from LAN (stream) input.
int lanGetC (void)
 Get one byte from LAN stream input.
void lanPutC (char c)
 Put one byte to LAN stream output.
int lanGetChar (FILE *stream)
 Get one byte from LAN stream input.
int lanPutChar (char c, FILE *stream)
 Put one byte to LAN stream output.
int lanPutChars (char *src, uint16_t n)
 Put some characters to LAN stream output.
int lanPutSt (char *src, const FILE *stream)
 Put a RAM string (some characters) to LAN stream output.
int lanPutSt_P (char *src, const FILE *stream)
 Put some characters from program space to LAN stream output.

The nul device

FILE nulStreams
 The stream "device" connected to the nul device.
void nulStreamsOpen (void)
 Open the nul streams.
uint16_t nulStreamsOutSpace (FILE *streams)
 The buffer space available for nul output.
uint8_t nulCheckOutSpace (uint16_t reqSpace, FILE *streams)
 Check the space available for nul streams output.
uint16_t nulInBufferd (FILE *streams)
 The number of characters buffered from nul input.
int nulGetC (void)
 Get one byte from nul stream input.
void nulPutC (char c)
 Put one byte to nul stream output.
int nulPutChar (char c, FILE *stream)
 Put one byte to nul stream output.
int nulGetChar (FILE *stream)
 Get one byte from nul stream input.
int nulPutSt (char *const src, const FILE *stream)
 Put a string (some characters) to nul stream output.

Functions

void initStdStreams (FILE *initStream)
 Initialise the standard streams.
void streamsClose (void)
 Close other standard streams.
uint8_t switchStdStreams (FILE *toStream)
 Switch the standard streams to another stream.

Define Documentation

#define BUF_STREAMS_CAP   2047

The buffered log streams capacity.

The value must be (a power of 2 - 1) and at least 255.

The UART is the consumer of buffered log streams output (text) data.

This evaluates to true if the serial output is to consume the buffered logs.

#define bufLogSetConsumer (   tD)

Set the consumer of buffered log streams output (text) data.

If the consumer is set to 0 or NULL there is no consumer and all output will go to the log streams (except the last BUF_STREAMS_CAP bytes will be forgotten).
A value of 1 means the serial interface is the consumer. This presupposes the UART being connected to a (human readable) text mode device.
Any other value must be a pointer to a thread data structure. A suitable thread function has to recognise this and handle the buffered log output. weAutSys' Telnet server e.g. does this.

At any given moment there can be just one or none (0) consumer for the buffered log streams output.

Parameters:
tDpointer to the consumer's thread data structure or 0 or 1
See also:
bufLogCons
bufLogConsIsUART
bufLogSetUART
#define bufLogSetUART ( )

Set the UART as consumer of buffered log streams output.

This sets the UART as consumer of log output. This presupposes the UART being connected to a (human readable) text mode device.

If this pre-condition is met this may be called by user software's initialisation (phase 2) to prevent the first active Telnet client from automatically get that role. This may be mandatory if Telnet debugging is on.

See also:
bufLogCons
bufLogConsIsUART
bufLogSetConsumer
Examples:
main.c.
#define BufLogInBufferd

The number of characters buffered in buffered log streams for input.

See also:
bufLogInBufferd
#define PT_YIELD_OUT_SPACE (   pt,
  requSpace,
  streams 
)

Set standard I/O and exit or yield for requested output space.

This is a macro to be used inside a protothread.

It sets a re-entry point for the next schedule of pt (after eventually yielding or waiting). Then it switches the standard output to streams and exits the calling thread pt (returning PT_EXITED) if that is not possible (cause streams is NULL e.g.).

If the switching to / opening of streams was feasible this macro then

  • does nothing else (just yields once), if the requested space is immediately available, or if the availability can't be determined. Anyhow PT_YIELDED is returned at first entry.

Otherwise the opening of streams is un-done and

  • yields the protothread pt, if the requested space may become available in the future by just waiting
  • just blocks the protothread pt, if the requested space will not become available by yielding / waiting but may be by other's activities.
  • exits and resets the protothread, if the requested space will never become available for the current (set) standard output stream (connection) or if streams is not usable or NULL
Parameters:
ptthe pointer to the protothread control structure.
requSpacethe requested output space
streamsthe stream to use and switch stdout to
See also:
checkOutSpace()
PT_OR_YIELD_REENTER
Examples:
main.c.
#define PT_WAIT_OUT_SPACE (   pt,
  requSpace,
  streams 
)

Set standard I/O and exit or wait for requested output space.

This is a macro to be used inside a protothread.

It sets a re-entry point for the next schedule of pt (after eventually yielding or waiting). Then it switches the standard output to streams and exits the calling thread pt (returning PT_EXITED) if that is not possible (cause streams is NULL e.g.).

If the switching to / opening of streams was feasible this macro then

  • does nothing else (just goes ahead), if the requested space is immediately available, or if the availability can't be determined.

Otherwise the opening of streams is un-done and

  • yields the protothread pt, if the requested space may become available in the future by just waiting
  • just blocks the protothread pt, if the requested space will not become available by yielding / waiting but may be by other's activities.
  • exits and resets the protothread, if the requested space will never become available for the current (set) standard output stream (connection) or if streams is not usable or NULL
Parameters:
ptthe pointer to the protothread control structure.
requSpacethe requested output space
streamsthe stream to use and switch stdout to
See also:
checkOutSpace()
PT_OR_YIELD_REENTER
#define SER_IS_STDOUT

stdout is the serial output (UART)

This evaluates to true, if stdout goes to the UART.

#define LAN_IS_STDOUT

stdout is the LAN stream output (Ethernet, uIP)

This evaluates to true, if stdout goes via uIP to the Ethernet.

#define stdPutS (   src)

Write a RAM string to stdout.

This is an abbreviation for putSt(src, stdout).

Examples:
main.c.
#define stdPutS_P (   src)

Write a flash memory string to stdout.

This is an abbreviation for putSt_P(src, stdout).


Typedef Documentation

typedef uint16_t(* str2InBufferd)(const FILE *stream)

Function pointer / type: number of characters buffered for input.

A function of this type returns the number of bytes that can be fetched from the stream's input without getting EOF.

For buffered devices with known state the answer will be correct.

In other cases the number of characters readable in one run without EOF is unknown. Then a large number with bit 15 set (0xFFFF AVAILABLE_UNKNOWN) is returned.

See also:
inBuffered
typedef uint16_t(* str2OutSpace)(const FILE *stream)

Function pointer / type: buffer space available for output.

A function of this type returns the number of bytes that can currently be output to the stream in one run without waiting or overflow.

For buffered devices with known state the answer will be correct.

In other cases a large number with bit 15 set (0xFFFF AVAILABLE_UNKNOWN) is returned.

See also:
str2CheckOutSpace()
outSpace
typedef uint8_t(* str2CheckOutSpace)(uint16_t reqSpace, const FILE *stream)

Function pointer / type: checking the space available for output.

A function of this type checks the requested space against the buffer space available.

If the stream is, for example the UART, its function checks the requested space against the UART buffer size or available space. Return values are 0, 2 or 4.

If the stream is the LAN respectively the currently handled IP connection the respective function checks the requested space against the actual connection's remaining output space. Return values are 0, 3 or 4.

For other devices with known state the correct / appropriate answer is given.
For an unknown device 1 is returned and for no (NULL) device 4.

Parameters:
reqSpacethe number of bytes requested for output in one complete step
streamthe stream
In Implementations for one single (singleton) concrete stream, this parameter is usually ignored.
Returns:

0: required space is available. I.e. go ahead with planned output.
1: may be available, but can't be determined for the given device / stream. I.e. blindly go ahead or give up;
2: is not available, but may become (automatically in the future, i.e. yielding / waiting is OK;
3: is not available, but may become by own activity (flushing, sending). I.e. just yielding / waiting would be endless. 4: will never be available. I.e. give up or request less space.
See also:
PT_YIELD_OUT_SPACE
checkOutSpace
typedef int(* str2PutS)(char *src, const FILE *stream)

Function pointer / type: writing a RAM string to output.

A function of this type writes the content of the string src to the stream. It will never block.

It returns the number of characters transferred. If not enough space is available the returned value will be smaller than the length of the string src. It may even be 0. In the latter case nothing was output.

Hence this operation should be (indirectly) guarded by outSpace() or PT_YIELD_OUT_SPACE .

The output stops after at the first 0 in src. By that this is a string output function. To send a (binary) 0 use stdPutC() or fputc().

Parameters:
srcthe characters to be output (pointer to RAM not NULL !)
streamthe destination stream
Returns:
the number of characters output
See also:
putSt
typedef int(* str2PutS_P)(prog_char *src, const FILE *stream)

Function pointer / type: writing a flash memory string to output.

A function of this writes the content of the string src to the stream. It will never block.

It returns the number of characters transferred. If not enough space is available the returned value will be smaller than the length of the string src. It may even be 0. In the latter case nothing was output.

Hence this operation should be (indirectly) guarded by outSpace() or PT_YIELD_OUT_SPACE .

The output stops after at the first 0 in src. By that this is a string output function. To send a (binary) 0 use stdPutC() or fputc().

Parameters:
srcthe characters to be output (pointer to flash memory not NULL !)
streamthe destination stream
Returns:
the number of characters output
See also:
putSt_P

Function Documentation

void bufLogStreamsInit ( void  )

Initialise the buffered log streams.

This function initialises and clears the bufLogStreams.

void bufLogStreamsOpen ( void  )

Open the buffered log streams.

This function sets the standard streams stdin/out/err to the bufLogStreams.
This "switching" will be rescinded by streamsClose() .

This function just (re-) opens leaving all else state un-changed.

uint16_t bufLogInBufferd ( FILE *  streams)

The number of characters buffered in buffered log streams for input.

This function returns the number of bytes that can be fetched from buffered log streams input by bufLogGetChar(FILE*) respectively bufLogGetC() without getting EOF.

The returned value is in the range 0 .. BUF_STREAMS_CAP. If 0 is returned nothing should be read.

int bufLogGetC ( void  )

Get one byte from buffered stream input.

This function never blocks. It returns a byte value read or EOF.

Returns:
a character 0..255 or EOF
uint16_t bufLogGetChars ( char *  dst,
uint16_t  n 
)

Get a number of bytes from buffered stream input.

This function never blocks. It reads up to n bytes from the buffered stream to the buffer dst.

This is mainly intended as helper function for consuming and forward the log output buffered so far.

Returns:
the number of characters transferred 0 ..n
uint8_t uartPutLogBuf ( void  )

Put characters from buffered log streams to serial output.

This function will put as much as possible characters from the buffered log streams to the UART. Returned is the number of characters transferred; its type is byte as long as we stick to UART buffers capacity below 256.

Returns:
the number of characters transferred
uint16_t bufLogStreamsOutSpace ( FILE *  streams)

The buffer space available for buffered log streams output.

Returns:
0 .. BUF_STREAMS_CAP
Examples:
main.c.
uint8_t bufLogCheckOutSpace ( uint16_t const  reqSpace,
FILE *const  streams 
)

Check the space available buffered log streams output.

This function might give a positive answer to repeated request for more characters than space available even if that might lead to loosing the oldest output. The rationale for this "lie" is that a standard programmed yielding for output space wont't hold a thread on logging (debug) output more than twice.

Returns:
The required space
4: will never be available cause asked for more than BUF_STREAMS_CAP. I.e. give up or request less space; 2: is not available, but may become (automatically) in the future, i.e. yielding / waiting is OK .
1: may be available, but can't be determined. I.e. blindly go ahead or give up. This answer is (wrongly) given on second request instead of 2; the third request will get 0.
0: is available or instead of 2 at third request or with no consumer. I.e. go ahead with planned output.
See also:
str2CheckOutSpace
void bufLogPutC ( char const  c)

Put one byte to buffered stream output.

This function never blocks and does the output. If there was no space in the buffer the "oldest" character there will be overwritten. Hence this operation should be (indirectly) guarded by bufLogStreamsOutSpace().

Parameters:
cthe character to be output
void bufLogPut2C ( char const  c1,
char const  c2 
)

Put two bytes to buffered stream output.

This function acts like two times bufLogPutC but is a bit more efficient (and readable).

Parameters:
c1the first character to be output
c2the second character to be output
int bufLogGetChar ( FILE *const  stream)

Get one byte from buffered stream input.

This function never blocks. It returns a byte value read or EOF.

This function may be used directly for input but then bufLogGetC() is a better choice. Usually this function is used indirectly via stdin of stdio.h as this functions signature is what stdio expects of underlying input streams.

Parameters:
stream(passed by stdio input) totally ignored by this function
Returns:
a character 0..255 or EOF
int bufLogPutChar ( char  c,
FILE *const  stream 
)

Put one byte to buffered stream output.

This function does exactly the the same as the preferable bufLogPutC() except for the extra parameter of type FILE * that is for sake of the standard I/O usage.

Parameters:
cthe character to be output
stream(passed by stdio output) totally ignored by this function
Returns:
c in case of success, EOF if output buffers full.
int bufLogPutSt ( char *  src,
FILE const *const  stream 
)

Put a RAM string (some characters) to buffered stream output.

This function never blocks. It returns the number of characters transferred. If not enough buffer space is available the returned value will be smaller than the length of the RAM string src. This space restriction applies to the size of the buffer and not to the free space. If the latter is insufficient this function will just overwrite the oldest output.

This operation should be (indirectly) guarded by bufLogStreamsOutSpace() or bufLogCheckOutSpace().

The output stops at the first 0 in src. By that this is a string output function. To send a (binary) 0 use bufLogPutC(0).

Parameters:
srcthe characters to be output
streamthe current stream (not used)
Returns:
the number of characters output
int bufLogPutSt_P ( char *  src,
FILE const *const  stream 
)

Put some characters from program space to buffered stream output.

This function never blocks. It returns the number of characters transferred. If not enough buffer space is available the returned value will be smaller than the length of the flash memory string src. This space restriction applies to the size of the buffer and not to the free space. If the latter is insufficient this function will just overwrite the oldest output.

This operation should be (indirectly) guarded by bufLogStreamsOutSpace() or bufLogCheckOutSpace().

The output stops at the first 0 in src. By that this is a string output function. To send a (binary) 0 use bufLogPutC(0).

Parameters:
srcthe characters to be output in flash memory
streamthe current stream (not used)
Returns:
the number of characters output
uint16_t inBufferd ( const FILE *  stream)

Number of characters buffered for input.

This is the common function implementing the standard behavior. It delegates all else cases (late binding) to the stream type specific function if such is set in the stream (type) specific data.

For this function's behavior see the description in its pointer / type.

uint16_t outSpace ( const FILE *  stream)

Buffer space available for output.

This is the common function implementing the standard behavior. It delegates all else cases (late binding) to the stream type specific function if such is set in the stream (type) specific data.

For this function's behavior see the description in its str2OutSpace()"pointer / type".

uint8_t checkOutSpace ( uint16_t  reqSpace,
const FILE *  stream 
)

Checking the space available for output.

This is the common function implementing the standard behavior. It delegates all else cases (late binding) to the stream type specific function if such is set in the stream (type) specific data.

For this function's behavior see the description in its str2CheckOutSpace()"pointer / type".

int putSt ( char *  src,
const FILE *  stream 
)

Write a RAM string to output.

This is the common function implementing the standard behavior. It delegates all normal cases (late binding) to the stream type specific function if such is set in the stream (type) specific data; if no such function is set it uses fputs().

For this function's behavior see the description in its pointer / type.

int putSt_P ( char const *  src,
const FILE *  stream 
)

Write a flash memory string to output.

This is the common function implementing the standard behavior. It delegates all else cases (late binding) to the stream type specific function if such is set in the stream (type) specific data; if no such function is set it uses fputs_P().

For this function's behavior see the description in its pointer / type.

void initStdStreams ( FILE *  initStream)

Initialise the standard streams.

This function is usually called once at system start up but might be called any time to change or assure the standard streams.

Anyway it will switch to the (then) actual standard streams acting hence effectively as streamsClose(). (Additionally all extra data for pre-defined streams will be reset / refreshed.) Do not call when these (side-) effects may be disturbing.

If the parameter is NULL and standard streams were set already they are just kept. Otherwise nulStreams are used as default.

Parameters:
initStreampointer to initial stream for standard streams
See also:
serStreams
lanStreams
nulStreams
Examples:
main.c.
uint8_t switchStdStreams ( FILE *  toStream)

Switch the standard streams to another stream.

This function sets the standard streams stdin/out/err to the toStream. If toStream is NULL nothing is done.

Parameters:
toStreampointer streams to switch the standard streams to
Returns:
0: toStream is NULL; 1: stdIO is or was set to toStream
void streamsClose ( void  )

Close other standard streams.

This function just reverses the (stream switching) effect of switchStdStreams() by setting back all standard streams to their initial standard source and destination.

void serStreamsOpen ( void  )

Open the serial (UART) streams.

This function sets the standard streams stdin/out/err to the serStreams if (and only if) not yet so set.
This "switching" will be rescinded by streamsClose() .

uint16_t serStreamsOutSpace ( FILE *  streams)

The buffer space available for serial output.

Same as uartOutSpace (other common signature).

uint8_t serCheckOutSpace ( uint16_t  reqSpace,
FILE *  streams 
)

Check the space available for serial output.

See also:
str2CheckOutSpace
int serPutChar ( char  c,
FILE *  stream 
)

Put one byte to serial output.

This function never blocks. It returns the byte c output if the operation was feasible or -1 resp. EOF if not. In the latter case c is not output.

Hence this operation should be (indirectly) guarded by uartOutSpace().

Parameters:
cthe character to be output
streamunused, irrelevant (signature required by stdio)
Returns:
c in case of success, EOF if output buffers full.
void stdPutC ( char  c)

Write a character to stdout.

If USE_AVR_GCC_FILE is defined with a not 0 value this function calls the stdout stream's character output implementation directly.

Without the direct call optimisation the following holds:

If the stdout is the UART or the current LAN this function just calls serPutChar(c, NULL) resp. lanPutC(c) directly.
For all other streams fputc(c, stdout) is used.

void logStackS ( uint8_t  maxBytes)

Log the stack frame to stdout.

Parameters:
maxBytesthe max. number of bytes logged including the stack frame
void lanStreamsInit ( void  )

Initialise the Ethernet / LAN streams.

This function initialises the lanStreams for usage with uip_appdata newly received or to be sent and additionally opens it.

void lanStreamsEcho ( void  )

Set the Ethernet / LAN streams to echo input.

This function should be called after inititialising the lanStreams and before the first output.
The received data will then be set as beginning of the data to be sent. This will be a 1:1 echo if nothing else is output.

void lanStreamsOpen ( void  )

Open the Ethernet / LAN streams.

This function sets the standard streams stdin/out/err to the lanStreams.
This "switching" will be rescinded by streamsClose() .

This function just (re-) opens leaving all else state (like buffer indices) un-changed. For a first open use lanStreamsInit() .

void lanStreamSend ( void  )

Sends the LAN streams data (over the Ethernet)

This function sends the LAN streams data written so far and closes the LAN streams.

uint8_t lanCheckOutSpace ( uint16_t  reqSpace,
FILE *  streams 
)

Check the space available Ethernet / LAN streams output.

See also:
str2CheckOutSpace
uint16_t lanInBufferd ( FILE *  streams)

The number of characters buffered from LAN (stream) input.

This function returns the number of bytes that can be fetched from LAN (stream) input by lanGetChar(FILE*) respectively lanGetC() without getting EOF.

The returned value is in the range 0 .. uip_datalen(). If 0 is returned nothing should be read.

int lanGetC ( void  )

Get one byte from LAN stream input.

This function never blocks. It returns a byte value read or EOF.
Hence this operation should be (indirectly) guarded by lanInBufferd().

Returns:
a character 0..255 or EOF
void lanPutC ( char  c)

Put one byte to LAN stream output.

This function never blocks even if no output operation is feasible. Hence this operation should be (indirectly) guarded by lanStreamsOutSpace().

This function will be used by stdio as output driver entry indirectly by lanPutChar(char c, FILE *stream). It may as well be used directly for output to the current IP connection.

Parameters:
cthe character to be output
int lanGetChar ( FILE *  stream)

Get one byte from LAN stream input.

This function never blocks. It returns a byte value read or EOF.
Hence this operation should be (indirectly) guarded by lanInBufferd().

This function may be used directly for input but then lanGetC(() is a better choice. Usually this function is used indirectly via stdin of stdio.h as this functions signature is what stdio expects of underlying input streams.

Parameters:
stream(passed by stdio input) totally ignored by this function
Returns:
a character 0..255 or EOF
int lanPutChar ( char  c,
FILE *  stream 
)

Put one byte to LAN stream output.

This function does exactly the the same as the preferable lanPutC() except for the extra parameter of type FILE * that is for sake of the standard I/O usage.

Parameters:
cthe character to be output
stream(passed by stdio output) totally ignored by this function
Returns:
c in case of success, EOF if output buffers full.
int lanPutChars ( char *  src,
uint16_t  n 
)

Put some characters to LAN stream output.

This function never blocks. It returns the number of characters transferred. If not enough space is available the returned value will be smaller than n or than the length of the string src. It may even be 0. In the latter case nothing was output.

Hence this operation should be (indirectly) guarded by lanStreamsOutSpace().

The output stops after n (or space permitting) characters or at the first 0 in src. By that this is a string output function. To send a (binary) 0 use lanPutC(char c).

Parameters:
srcthe characters to be output
nthe maximum number of characters to be output
Returns:
the number of characters output
int lanPutSt ( char *  src,
const FILE *  stream 
)

Put a RAM string (some characters) to LAN stream output.

This function never blocks. It returns the number of characters transferred. If not enough space is available the returned value will be smaller than the length of the string src. It may even be 0. In the latter case nothing was output.

Hence this operation should be (indirectly) guarded by lanStreamsOutSpace().

The output stops after at the first 0 in src. By that this is a string output function. To send a (binary) 0 use lanPutC(char c).

Parameters:
srcthe characters to be output (0 terminated)
streamthe current Ethernet connection as stream (not used)
Returns:
the number of characters output
int lanPutSt_P ( char *  src,
const FILE *  stream 
)

Put some characters from program space to LAN stream output.

This function never blocks. It returns the number of characters transferred. If not enough space is available the returned value will be smaller than the length of the string src. It may even be 0. In the latter case nothing was output.

Hence this operation should be (indirectly) guarded by lanStreamsOutSpace().

Parameters:
srcthe characters to be output in flash memory (0 terminated)
streamthe current Ethernet connection as stream (not used)
Returns:
the number of characters output
void nulStreamsOpen ( void  )

Open the nul streams.

This function sets the standard streams stdin/out/err to the nulStreams.
This "switching" will be rescinded by streamsClose() .

uint16_t nulStreamsOutSpace ( FILE *  streams)

The buffer space available for nul output.

This function always says 4095. It is provided to implement a stream that swallows and forgets all output.

uint8_t nulCheckOutSpace ( uint16_t  reqSpace,
FILE *  streams 
)

Check the space available for nul streams output.

This function always returns 0 i.e. available. It is provided to implement a stream that swallows unlimited amount of output (by just forgetting it).

uint16_t nulInBufferd ( FILE *  streams)

The number of characters buffered from nul input.

This function returns always 0 as there will be no input from nul. It is provided to implement an input stream that will never deliver anything respectively be always empty.

int nulGetC ( void  )

Get one byte from nul stream input.

This function is provided to implement an input stream that will never deliver anything respectively be always empty.

Returns:
EOF (always)
void nulPutC ( char  c)

Put one byte to nul stream output.

This function never blocks and does nothing. It is provided to implement a stream that swallows unlimited amount of output (by just forgetting it).

All other output functions to nul do have no effect, also.

Parameters:
cthe character to be output
int nulPutChar ( char  c,
FILE *  stream 
)

Put one byte to nul stream output.

This function never blocks. It returns the byte c provided as parameter value and does nothing else. It is provided to implement a stream that swallows and forgets all output.

Parameters:
cthe character to be output
streamunused, irrelevant (signature required by stdio)
Returns:
c
int nulGetChar ( FILE *  stream)

Get one byte from nul stream input.

This function returns EOF. It is provided to implement an input stream that will never deliver anything respectively always be empty.

Parameters:
stream(passed by stdio input) totally ignored by this function
Returns:
EOF
int nulPutSt ( char *const  src,
const FILE *  stream 
)

Put a string (some characters) to nul stream output.

This function never blocks. It returns 1 no matter the parameters and does nothing else. It is provided to implement a stream that swallows unlimited amount of output (by just forgetting it).

As the pointer to the characters to output src is not de-referenced this function works for RAM and program (flash) memory strings as well.

Parameters:
srcthe characters to be output (not used)
stream(not used)
Returns:
1 if src is not null or 0 else

Variable Documentation

The stream "device" being a buffer for logging.

This stream is a buffer (or pipe or decorator) for output. Its intended use is as buffered log output to humans.

The buffered content is available by input or by bulk copying out of the buffered text to be consumed and send forth by an appropriate device respectively application, be it the UART or one Telnet connection.

Every usage of the log buffered stream device via standard streams shall be embraced by bufLogStreamsOpen() and streamsClose().

Examples:
main.c.

The consumer of buffered log streams output (text) data.

This (16 bit) value points to the state data structure of the application to regularly consume (and send forward) the bufLogStreams text buffered so far.

Special values are:
NULL or 0 : no consuming device or application <br > 1 : the UART shall output all buffered text.

See also:
bufLogSetConsumer
FILE serStreams

The stream "device" connected to the serial IO / UART(0)

On (default) initialisation this stream will be used for the standard streams.

Examples:
main.c.
FILE lanStreams

The stream "device" connected to the Ethernet (uIP)

This stream shall only be used while handling Ethernet messages, i.e. directly or indirectly in uip_appcall(), uipAppcall() or udp_appcall(). It will work on uip_appdata, i.e. use it as buffer for both directions.

Output functions must not be used before uip_appdata as input (message) is fully processed.

Every usage shall be embraced by lanStreamsOpen() and streamsClose() if used via standard streams.

FILE nulStreams

The stream "device" connected to the nul device.

This stream shall only be used as initial standard streams if no other character / byte oriented I/O is permanently available (from reset on). That usually means the UART is reserved for other purposes.

This streams shall be set respectively opened as standard I/O (stdio) whenever no other stream is available therefore. The rationale is any (user) thread might use standard I/O (stdio) any time.

The "device" features all in/output functions optimised for doing nothing. It is always available, i.e. from reset phase 1 on until shutdown.