NetBurner 3.5.6
PDF Version
FDBuffer

NetBurner FDBuffer Example

Overview

This example demonstrates how to use the NetBurner FDBuffer class to capture and manipulate data from file descriptors (fd) that would normally be used for direct I/O operations. The FDBuffer class allows you to intercept data streams and store them in a local buffer for debugging, logging, or further processing.

Purpose

Many NetBurner libraries utilize file descriptors for data input/output transmission, including:

  • TCP connections
  • WebSockets
  • HTTP communications
  • FTP transfers
  • Email operations
  • Serial communications
  • Configuration system

This example shows how to capture I/O data from an fd to a buffer instead of using the fd as originally intended by a library. This technique is particularly useful for:

  • Debugging network communications
  • Logging system data
  • Capturing configuration information
  • Storing data for later transmission or processing

How It Works

The application demonstrates capturing the system's configuration JSON object using an FDBuffer:

  1. Initialization: The application initializes the network stack and starts the HTTP server
  2. Buffer Setup: Creates an FDBuffer object and associated data buffer
  3. Data Capture: Uses the config system to write JSON data to the FDBuffer instead of directly to a socket or serial port
  4. Data Retrieval: Reads the captured data from the FDBuffer into a local buffer
  5. Data Output: Displays the captured JSON configuration data via serial output

Key Components

FDBuffer Class

  • Defined in fd_adapter.h
  • Associates a buffer with a file descriptor
  • Supports standard file descriptor functions: read(), write(), close()
  • By default, can dynamically allocate up to 20 pool buffers
  • Each pool buffer stores ETHER_BUFFER_SIZE (1548) bytes
  • Total default storage capacity: 30,960 bytes
  • Storage limit can be increased by modifying MAX_FDBUFFER_FIFO_BUFFERS macro

Application Features

  • Pretty Print Option: Toggle between formatted JSON (with indentation) and compact single-line output
  • Buffer Management: Proper allocation, usage, and cleanup of file descriptors
  • Error Handling: Checks buffer size constraints and provides appropriate error messages
  • Dual Output Methods: Demonstrates both direct fd writing and printf-style output

Code Structure

Main Functions

  1. UserMain(): Primary application entry point
    • Initializes network stack and HTTP server
    • Sets up FDBuffer and data buffer
    • Captures config JSON data
    • Outputs captured data to serial port
  2. Buffer Operations:
    • myFdBufferObject.GetActiveFD(): Allocates file descriptor
    • root.RenderToFd(): Writes config JSON to FDBuffer
    • myFdBufferObject.SpaceUsed(): Returns stored data size
    • read(): Reads data from FDBuffer to local buffer
    • close(): Releases file descriptor back to pool

Configuration Variables

  • dataBufferSize: Size of local data buffer (4096 bytes)
  • prettyPrint: Boolean flag for JSON formatting style

Usage Examples

Basic Usage

The application automatically captures and displays the system configuration JSON when started.

Alternative Streaming Method

The code includes an alternative approach that streams directly to stdout without using a local buffer:

int stdout_fd = CurrentStdioFD(1);
myFdBufferObject.StreamTo(stdout_fd);
CurrentStdioFD
int CurrentStdioFD(int stdio_fd)
Returns the current file descriptor mapped to the stdio file descriptor.

Build Requirements

  • NetBurner NNDK (Network Development Kit)
  • Compatible NetBurner hardware platform
  • Standard NetBurner libraries and headers

Key Headers Required

Error Handling

The application includes error checking for:

  • Buffer size limitations
  • File descriptor allocation
  • Data read/write operations
  • Network initialization timeouts

Best Practices Demonstrated

  1. Memory Management: Proper clearing of buffers and FDBuffer objects
  2. Resource Cleanup: Closing file descriptors after use to return them to the pool
  3. Error Checking: Validating buffer sizes and operation return values
  4. Documentation: Clear comments explaining each operation

Potential Applications

This technique can be extended for:

  • Network packet inspection
  • Configuration backup to persistent storage (flash, SD card)
  • Remote data transmission (email, syslog, FTP)
  • Real-time debugging and monitoring
  • Data logging and analysis