ESP32 WebServer Library – headers()

Home / References / ESP32 Library / WebServer Library

Description

The headers() method is used to retrieve the total number of HTTP request headers that have been collected by the ESP32 WebServer from the current client request. This method returns an integer value representing the count of headers that were successfully parsed and stored by the server. The count only includes headers that have been explicitly configured for collection using either the collectHeaders() method for specific headers or the collectAllHeaders() method for comprehensive header collection. This method is essential for iterating through headers, implementing dynamic header processing, and validating that the expected number of headers have been received. It’s commonly used in conjunction with header() and headerName() methods to access individual header information by index.

Syntax and Usage

The headers() method has a simple usage pattern:

Get header count: server.headers() – Returns the total number of collected headers from the current request. This method takes no parameters and provides a quick way to determine how many headers are available for processing.

Arguments

The headers() method does not require any arguments. It is a parameterless method that returns the current header count.

Return Value

The headers() method returns an int value representing the total number of HTTP request headers that have been collected and are available for access. The returned value will be 0 if no headers have been collected or if header collection was not configured properly.

Example Codes

Example: Basic Header Count Usage

This example demonstrates the fundamental usage of headers() to count and iterate through all collected headers, providing a foundation for header processing logic.

How to use this example: Upload this code to your ESP32 and replace the WiFi credentials. After connecting, visit the ESP32’s IP address in your browser. The server will display the total number of headers and list each one. Test with different clients: curl commands like curl -H "Custom-Header: test-value" -H "X-API-Key: 12345" http://ESP32_IP, different browsers, or with various header combinations to see how the count changes.

/*
 * Author: Avant Maker
 * Date: June 17, 2025
 * Version: 1.0
 * License: MIT 
 * 
 * Description: 
 * This example demonstrates the fundamental usage of headers() to count
 * and iterate through all collected headers, providing a foundation
 * for header processing logic.
 * 
 * How to use this example: 
 * Upload this code to your ESP32 and replace the WiFi credentials.
 * After connecting, visit the ESP32's IP address in your browser.
 * The server will display the total number of headers and list each one.
 * Test with different clients: curl commands like
 * curl -H "Custom-Header: test-value" -H "X-API-Key: 12345" http://ESP32_IP,
 * different browsers, or with various header combinations to see how the count changes.
 *
 * Code Source:
 * This example code is sourced from the Comprehensive Guide
 * to the ESP32 Arduino Core Library, accessible on AvantMaker.com.
 * For additional code examples and in-depth documentation related to
 * the ESP32 Arduino Core Library, please visit:
 *
 * https://avantmaker.com/home/all-about-esp32-arduino-core-library/
 *
 * AvantMaker.com, your premier destination for all things
 * DIY, AI, IoT, Smart Home, and STEM projects. We are dedicated
 * to empowering makers, learners, and enthusiasts with
 * the resources they need to bring their nnovative ideas to life.
 */

#include <WiFi.h>
#include <WebServer.h>

const char* ssid = "taichimaker";
const char* password = "ZAQ1xsw2cde3VFR4";

WebServer server(80);

void handleRoot() {
  String message = "AvantMaker ESP32 Header Count Analysis\n";
  message += "===========================\n\n";
  
  // Get the total number of headers
  int headerCount = server.headers();
  
  message += "Total headers collected: " + String(headerCount) + "\n\n";
  
  if (headerCount > 0) {
    message += "Header Details:\n";
    message += "---------------\n";
    
    // Use headers() method to safely iterate through all available headers
    for (int i = 0; i < headerCount; i++) {
      String headerName = server.headerName(i);
      String headerValue = server.header(i);
      
      message += String(i + 1) + ". " + headerName + ": " + headerValue + "\n";
    }
    
    message += "\nHeader Analysis:\n";
    message += "----------------\n";
    message += "Header count: " + String(headerCount) + "\n";
    message += "Index range: 0 to " + String(headerCount - 1) + "\n";
    
    // Calculate average header name length
    int totalNameLength = 0;
    for (int i = 0; i < headerCount; i++) {
      totalNameLength += server.headerName(i).length();
    }
    float avgNameLength = (float)totalNameLength / headerCount;
    message += "Average header name length: " + String(avgNameLength, 1) + " characters\n";
    
  } else {
    message += "No headers were collected!\n";
    message += "Possible reasons:\n";
    message += "- collectHeaders() or collectAllHeaders() not called\n";
    message += "- No headers sent by client\n";
    message += "- Header collection not configured properly\n";
  }
  
  server.send(200, "text/plain", message);
}

void setup() {
  Serial.begin(115200);
  
  // Connect to WiFi
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connecting to WiFi...");
  }
  
  // Configure server to collect ALL headers for demonstration
  server.collectAllHeaders();
  
  // Set up route handler
  server.on("/", handleRoot);
  
  // Start server
  server.begin();
  Serial.println("HTTP server started");
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());
  Serial.println("Server configured to collect ALL headers");
}

void loop() {
  server.handleClient();
}

/*
 * Author: Avant Maker
 * Date: June 17, 2025
 * Version: 1.0
 * License: MIT 
 * 
 * Description: 
 * This example demonstrates the fundamental usage of headers() to count
 * and iterate through all collected headers, providing a foundation
 * for header processing logic.
 * 
 * How to use this example: 
 * Upload this code to your ESP32 and replace the WiFi credentials.
 * After connecting, visit the ESP32's IP address in your browser.
 * The server will display the total number of headers and list each one.
 * Test with different clients: curl commands like
 * curl -H "Custom-Header: test-value" -H "X-API-Key: 12345" http://ESP32_IP,
 * different browsers, or with various header combinations to see how the count changes.
 *
 * Code Source:
 * This example code is sourced from the Comprehensive Guide
 * to the ESP32 Arduino Core Library, accessible on AvantMaker.com.
 * For additional code examples and in-depth documentation related to
 * the ESP32 Arduino Core Library, please visit:
 *
 * https://avantmaker.com/home/all-about-esp32-arduino-core-library/
 *
 * AvantMaker.com, your premier destination for all things
 * DIY, AI, IoT, Smart Home, and STEM projects. We are dedicated
 * to empowering makers, learners, and enthusiasts with
 * the resources they need to bring their nnovative ideas to life.
 */

#include <WiFi.h>
#include <WebServer.h>

const char* ssid = "taichimaker";
const char* password = "ZAQ1xsw2cde3VFR4";

WebServer server(80);

void handleRoot() {
  String message = "AvantMaker ESP32 Header Count Analysis\n";
  message += "===========================\n\n";
  
  // Get the total number of headers
  int headerCount = server.headers();
  
  message += "Total headers collected: " + String(headerCount) + "\n\n";
  
  if (headerCount > 0) {
    message += "Header Details:\n";
    message += "---------------\n";
    
    // Use headers() method to safely iterate through all available headers
    for (int i = 0; i < headerCount; i++) {
      String headerName = server.headerName(i);
      String headerValue = server.header(i);
      
      message += String(i + 1) + ". " + headerName + ": " + headerValue + "\n";
    }
    
    message += "\nHeader Analysis:\n";
    message += "----------------\n";
    message += "Header count: " + String(headerCount) + "\n";
    message += "Index range: 0 to " + String(headerCount - 1) + "\n";
    
    // Calculate average header name length
    int totalNameLength = 0;
    for (int i = 0; i < headerCount; i++) {
      totalNameLength += server.headerName(i).length();
    }
    float avgNameLength = (float)totalNameLength / headerCount;
    message += "Average header name length: " + String(avgNameLength, 1) + " characters\n";
    
  } else {
    message += "No headers were collected!\n";
    message += "Possible reasons:\n";
    message += "- collectHeaders() or collectAllHeaders() not called\n";
    message += "- No headers sent by client\n";
    message += "- Header collection not configured properly\n";
  }
  
  server.send(200, "text/plain", message);
}

void setup() {
  Serial.begin(115200);
  
  // Connect to WiFi
  WiFi.begin(ssid, password);
  while (WiFi.status() != WL_CONNECTED) {
    delay(1000);
    Serial.println("Connecting to WiFi...");
  }
  
  // Configure server to collect ALL headers for demonstration
  server.collectAllHeaders();
  
  // Set up route handler
  server.on("/", handleRoot);
  
  // Start server
  server.begin();
  Serial.println("HTTP server started");
  Serial.print("IP address: ");
  Serial.println(WiFi.localIP());
  Serial.println("Server configured to collect ALL headers");
}

void loop() {
  server.handleClient();
}

ESP32 Library Index

ESP32 Arduino Core Library

ESP32 WiFi Library
ESP32 WiFiClient Library
ESP32 HTTPClient Library
ESP32 WiFiClientSecure Library
ESP32 AsyncUDP Librarry
ESP32 WebServer Library
- Server Operation
  - begin()
  - close()
  - stop()
- Client Hnadling
- Routing and Handlers
  - on()
  - onNotFound()
  - onFileUpload()
  - serveStatic()
  - addHandler()
  - removeHandler()
- Authentication
- Request Information
  - uri()
  - method()
  - clientContentLength()
  - arg()
  - argName()
  - args()
  - hasArg()
  - hostHeader()
  - version()
  - client()
  - upload()
- Request Header Management
- Response Information
- Server Configuration

FAQ

Ready to experiment and explore more about ESP32? Visit our website’s All About ESP32 Resources Hub, packed with tutorials, guides, and tools to inspire your maker journey. Experiment, explore, and elevate your skills with everything you need to master this powerful microcontroller platform!