HTTP Service

Helper header: #include "brookesia/service_helper/network/http.hpp"
Helper class: esp_brookesia::service::helper::Http

Overview

brookesia_service_http provides HTTP and HTTPS client requests as Brookesia service functions and events.

Core Responsibilities

Wraps ESP-IDF HTTP client behavior behind service schemas.
Supports request submission, cancellation, memory responses, file downloads, progress, and completion events.
Used by apps and agents for package indexes, downloads, cloud configuration, and network resources.

Integration Position

This component is an independent ESP-Brookesia release component. It can be integrated through ESP-IDF component dependencies and combined with peer framework components as needed.

Standard Include / Helper Class

Standard include: #include \"brookesia/service_helper/network/http.hpp\"
Helper class: esp_brookesia::service::helper::Http

Service Interfaces

Functions

`Request`

Description

Submit an HTTP request and wait for the response.

Execution

Requires scheduler: Not required

Parameters

Request
- Type: Object
- Required: required
- Description: HTTP request object.

Return Value

Type: Object
Description: Example: {"request_id":1,"status_code":200,"headers":{},"body":"{"ok":true}","file_path":"","error":"Ok","error_message":""}

Schema JSON

Show raw JSON


{
  "name": "Request",
  "description": "Submit an HTTP request and wait for the response.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Request",
      "description": "HTTP request object.",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"request_id\":1,\"status_code\":200,\"headers\":{},\"body\":\"{\\\"ok\\\":true}\",\"file_path\":\"\",\"error\":\"Ok\",\"error_message\":\"\"}"
  }
}

CLI Command

svc_call Http Request {"Request":null}

`RequestAsync`

Description

Submit an HTTP request asynchronously.

Execution

Requires scheduler: Not required

Parameters

Request
- Type: Object
- Required: required
- Description: HTTP request object.

Return Value

Type: Number
Description: Request id number.

Schema JSON

Show raw JSON


{
  "name": "RequestAsync",
  "description": "Submit an HTTP request asynchronously.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "Request",
      "description": "HTTP request object.",
      "type": "Object",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "Number",
    "description": "Request id number."
  }
}

CLI Command

svc_call Http RequestAsync {"Request":null}

`CancelRequest`

Description

Cancel a pending or running HTTP request.

Execution

Requires scheduler: Not required

Parameters

RequestId
- Type: Number
- Required: required
- Description: Request id returned by RequestAsync.

Schema JSON

Show raw JSON


{
  "name": "CancelRequest",
  "description": "Cancel a pending or running HTTP request.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "RequestId",
      "description": "Request id returned by RequestAsync.",
      "type": "Number",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": null
}

CLI Command

svc_call Http CancelRequest {"RequestId":null}

`GetRequestState`

Description

Get HTTP request state.

Execution

Requires scheduler: Not required

Parameters

RequestId
- Type: Number
- Required: required
- Description: Request id returned by RequestAsync.

Return Value

Type: Object
Description: Example: {"request_id":1,"state":"Completed","error":"Ok","status_code":200,"downloaded":128,"total":128}

Schema JSON

Show raw JSON


{
  "name": "GetRequestState",
  "description": "Get HTTP request state.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [
    {
      "name": "RequestId",
      "description": "Request id returned by RequestAsync.",
      "type": "Number",
      "required": true,
      "default_value": null
    }
  ],
  "return_value": {
    "type": "Object",
    "description": "Example: {\"request_id\":1,\"state\":\"Completed\",\"error\":\"Ok\",\"status_code\":200,\"downloaded\":128,\"total\":128}"
  }
}

CLI Command

svc_call Http GetRequestState {"RequestId":null}

`ResetStatistics`

Description

Reset HTTP service statistics.

Execution

Requires scheduler: Not required

Parameters

No parameters.

Schema JSON

Show raw JSON


{
  "name": "ResetStatistics",
  "description": "Reset HTTP service statistics.",
  "require_scheduler": false,
  "default_timeout_ms": null,
  "parameters": [],
  "return_value": null
}

CLI Command

svc_call Http ResetStatistics

Events

`RequestStarted`

Description

HTTP request started.

Execution

Requires scheduler: Required

Items

RequestId
- Type: Number
- Description: Request id.
State
- Type: String
- Description: Request state.

Schema JSON

Show raw JSON


{
  "name": "RequestStarted",
  "description": "HTTP request started.",
  "require_scheduler": true,
  "items": [
    {
      "name": "RequestId",
      "description": "Request id.",
      "type": "Number"
    },
    {
      "name": "State",
      "description": "Request state.",
      "type": "String"
    }
  ]
}

CLI Command

svc_subscribe Http RequestStarted

`RequestProgress`

Description

HTTP request progress updated.

Execution

Requires scheduler: Required

Items

RequestId
- Type: Number
- Description: Request id.
Progress
- Type: Object
- Description: Progress object.

Schema JSON

Show raw JSON


{
  "name": "RequestProgress",
  "description": "HTTP request progress updated.",
  "require_scheduler": true,
  "items": [
    {
      "name": "RequestId",
      "description": "Request id.",
      "type": "Number"
    },
    {
      "name": "Progress",
      "description": "Progress object.",
      "type": "Object"
    }
  ]
}

CLI Command

svc_subscribe Http RequestProgress

`RequestCompleted`

Description

HTTP request completed.

Execution

Requires scheduler: Required

Items

RequestId
- Type: Number
- Description: Request id.
Response
- Type: Object
- Description: HTTP response object.

Schema JSON

Show raw JSON


{
  "name": "RequestCompleted",
  "description": "HTTP request completed.",
  "require_scheduler": true,
  "items": [
    {
      "name": "RequestId",
      "description": "Request id.",
      "type": "Number"
    },
    {
      "name": "Response",
      "description": "HTTP response object.",
      "type": "Object"
    }
  ]
}

CLI Command

svc_subscribe Http RequestCompleted

`RequestFailed`

Description

HTTP request failed.

Execution

Requires scheduler: Required

Items

RequestId
- Type: Number
- Description: Request id.
Response
- Type: Object
- Description: HTTP response object.

Schema JSON

Show raw JSON


{
  "name": "RequestFailed",
  "description": "HTTP request failed.",
  "require_scheduler": true,
  "items": [
    {
      "name": "RequestId",
      "description": "Request id.",
      "type": "Number"
    },
    {
      "name": "Response",
      "description": "HTTP response object.",
      "type": "Object"
    }
  ]
}

CLI Command

svc_subscribe Http RequestFailed

`RequestCanceled`

Description

HTTP request canceled.

Execution

Requires scheduler: Required

Items

RequestId
- Type: Number
- Description: Request id.
Response
- Type: Object
- Description: HTTP response object.

Schema JSON

Show raw JSON


{
  "name": "RequestCanceled",
  "description": "HTTP request canceled.",
  "require_scheduler": true,
  "items": [
    {
      "name": "RequestId",
      "description": "Request id.",
      "type": "Number"
    },
    {
      "name": "Response",
      "description": "HTTP response object.",
      "type": "Object"
    }
  ]
}

CLI Command

svc_subscribe Http RequestCanceled

`GeneralStateChanged`

Description

HTTP service general state changed.

Execution

Requires scheduler: Required

Items

State
- Type: String
- Description: General state.

Schema JSON

Show raw JSON


{
  "name": "GeneralStateChanged",
  "description": "HTTP service general state changed.",
  "require_scheduler": true,
  "items": [
    {
      "name": "State",
      "description": "General state.",
      "type": "String"
    }
  ]
}

CLI Command

svc_subscribe Http GeneralStateChanged

HTTP Service

Standard Include / Helper Class

Service Interfaces

Functions

Request

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

RequestAsync

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

CancelRequest

Description

Execution

Parameters

Schema JSON

CLI Command

GetRequestState

Description

Execution

Parameters

Return Value

Schema JSON

CLI Command

ResetStatistics

Description

Execution

Parameters

Schema JSON

CLI Command

Events

RequestStarted

Description

Execution

Items

Schema JSON

CLI Command

RequestProgress

Description

Execution

Items

Schema JSON

CLI Command

RequestCompleted

Description

Execution

Items

Schema JSON

CLI Command

RequestFailed

Description

Execution

Items

Schema JSON

CLI Command

RequestCanceled

Description

Execution

Items

Schema JSON

CLI Command

GeneralStateChanged

Description

Execution

Items

Schema JSON

CLI Command

Related Types and Configs

`Request`

`RequestAsync`

`CancelRequest`

`GetRequestState`

`ResetStatistics`

`RequestStarted`

`RequestProgress`

`RequestCompleted`

`RequestFailed`

`RequestCanceled`

`GeneralStateChanged`