EventSource API Object

The EventSource object is used in conjunction with functions in the voltmx.net namespace to send requests to any resource on the network and fetch the response. The EventSource object provides the following API elements.

• Config Properties
• Retry Config Properties
• Methods
• Events Handlers
• Error Codes

Config Properties

Property	Type	Default	Description	Platforms
method	String	GET	The HTTP method to use for the request ("GET", "POST", etc.).	iOS, Android, Desktop Web, SPA, Desktop Native
headers	Object	{}	Key-value pairs of HTTP request headers to include.	iOS, Android, Desktop Web, SPA, Desktop Native
body	String | Object	null	The request body. Objects are automatically serialized to JSON.	iOS, Android, Desktop Web, SPA, Desktop Native
requestTimeout	Number	3000	Timeout in ms for request/connection.	iOS and Android
retry	Object	-	Retry behavior configuration. See Retry Config below.	iOS, Android, Desktop Web, SPA, Desktop Native

Retry Config Properties

Property	Type	Default	Description	Platforms
enable	Boolean	true	Whether to automatically retry the connection on error. Set to false to disable reconnection.	iOS, Android, Desktop Web, SPA, Desktop Native
interval	Number	100ms	Initial retry delay (ms); often uses backoff.	Desktop Web, SPA, Desktop Native: Default is 1000 (not changeable); iOS and Android
maxInterval	Number	300ms	Maximum retry delay (ms).	iOS and Android
verifyNoContent	Boolean	false	When true, a 204 No Content HTTP response is treated as a clean, intentional server close (triggers onClose instead of error).	iOS, Android, Desktop Web, SPA, Desktop Native

Methods

.open()

Initiates the SSE connection (call after registering handlers).

Syntax:

eventSource.open();

.close()

Closes the connection and cancels reconnection attempts.

Syntax:

eventSource.close();

Events Handlers

All callbacks must be assigned before calling open().

Property	Syntax	Description	Assigned Function Receives
onOpen	eventSource.onOpen = function(event) { ... };	Invoked when the SSE connection is successfully established and the server responds with a valid text/event-stream content type.	res (response-like object, e.g. { event: 'open', status? })
onMessage	eventSource.onMessage = function(event) { ... };	Invoked each time a new event message is received from the server.	res (message object: { event?, id?, data })
onError	eventSource.onError = function(event) { ... };	Invoked when a network error, HTTP error, or unexpected failure occurs. If retry.enable is true, reconnection attempts are made automatically.	err (error object/string)
onClose	eventSource.onClose = function(event) { ... };	Invoked when the connection is closed — either explicitly via close() or when the server ends the stream.	(no arg or simple object like { event: 'close' })

Error Codes

voltmx.net.EventSource provides consistent error handling across Web, Android, and iOS platforms using a standardized error object.

Common Error Object

All errors follow the following structure:

{
  "errorName": "string",
  "errorMessage": "string",
  "errorCode": "number",
  "errorInfo": "string"
}

• errorName: Category of the error (used for programmatic checks).
• errorMessage: Human-readable error description.
• errorCode: Numeric code for easy handling and logging.
• errorInfo: Optional additional details (e.g., HTTP status, raw exception message, debug information).

1. API Validation Errors

These errors are thrown synchronously when creating the voltmx.net.EventSource instance or calling .open() with invalid parameters.

errorName	errorCode	errorMessage	Platforms
INVALID_INPUT_EXCEPTION	101	"url is required and must be a non-empty string"	All
INVALID_INPUT_EXCEPTION	101	"config must be an object"	All
INVALID_INPUT_EXCEPTION	101	"method must be a valid HTTP method (GET, POST, etc.)"	All
INVALID_INPUT_EXCEPTION	101	"headers must be an object"	All
INVALID_INPUT_EXCEPTION	101	"body must be a string, object, or null"	All
INVALID_INPUT_EXCEPTION	101	"requestTimeout must be a positive number"	iOS and Android only
INVALID_INPUT_EXCEPTION	101	"retry must be an object"	All
INVALID_INPUT_EXCEPTION	101	"retry.interval and retry.maxInterval must be positive numbers"	iOS and Android only

2. Runtime Errors (Delivered to onError)

These errors are passed asynchronously to the onError handler during connection lifecycle.

Type	errorName	errorCode	errorMessage (Example)	errorInfo (Typical Content)	Platforms
IO / Network	IO_EXCEPTION	102	"Connection Error"	"timeout", "no internet", SSL details	All
HTTP	HTTP_EXCEPTION	Http status code	"Unauthorized Connection"	HTTP status code + " " + error info	All
HTTP	INVALID_SSE_RESPONSE_EXCEPTION	104	"Invalid SSE response: Content-Type is not text/event-stream"	Actual Content-Type received	All
Unknown	UNKNOWN_EXCEPTION	103	"An unexpected error occurred"	Full underlying error / stack trace (debug)	All