EXT — Management of extension modules

Flockwave server implementations may be built in a modular manner such that certain parts of its functionality are provided by extension modules. Messages in this group provide facilities for loading, unloading and reconfiguring extensions.

Note that Flockwave server implementations MUST provide handlers for these messages even if the server itself does not provide extensions. In such cases, requests for the list of extensions MUST return an empty list, and all other messages referring to specific extensions can simply return an error code.

EXT-CFG - Retrieve the current configuration of extensions

A client sends this request to the server to obtain information about the configuration of extensions with IDs specified in the request.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of extension IDs whose configuration the client requests.

Response fields

Name Required? Type Description

status

no

object

Object that contains the configuration for each requested extension ID.

error

no

object

Object mapping extension IDs to error messages about why the request failed for these IDs.

Example request

{
  "type": "EXT-CFG",
  "ids": ["beer", "ssdp", "system_clock"]
}

Example response

{
  "type": "EXT-CFG",
  "status": {
    "system_clock": {},
    "ssdp": {
      "multicast_group": "239.255.255.250",
      "port": 1900,
      "label": "My awesome server"
    }
  },
  "error": {
    "beer": "No such extension. Unfortunately."
  }
}

EXT-INF - Retrieve details about an extension

A client sends this request to the server to obtain the details of the extensions with IDs specified in the request.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of extension IDs whose details the client requests.

Response fields

Name Required? Type Description

status

no

object

Object that contains the available information for each requested extension ID. The structure of this object is described by the ExtensionInfo complex type.

error

no

object

Object mapping extension IDs to error messages about why the request failed for these IDs.

Example request

{
  "type": "EXT-INF",
  "ids": ["beer", "ssdp", "system_clock"]
}

Example response

{
  "type": "EXT-INF",
  "status": {
    "system_clock": {
      "id": "system_clock",
      "name": "System clock",
      "loaded": true
    },
    "ssdp": {
      "id": "ssdp",
      "name": "SSDP discovery service",
      "loaded": false
    }
  },
  "error": {
    "beer": "No such extension. Unfortunately."
  }
}

EXT-LIST — List of loaded and unloaded extensions

A client sends this request to the server to retrieve the list of extensions that are currently loaded as well as the list of extensions that are not loaded but could be loaded.

Request fields

This request has no fields.

Response fields

Name Required? Type Description

loaded

yes

list of strings

List containng the identifiers of the extensions that are currently loaded and used by the server

available

yes

list of strings

List containng the identifiers of the extensions that are currently not loaded by the server but could be loaded upon request

Example request

{
  "type": "EXT-LIST"
}

Example response

{
  "type": "EXT-LIST",
  "loaded": ["foo", "bar"],
  "available": ["baz"]
}

EXT-LOAD - Load an extension

A client sends this request to the server to load the extensions with IDs specified in the request.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of extension IDs which the client requests to load.

Response fields

Name Required? Type Description

status

no

object

Object that contains empty objects for each requested extension that was successfully loaded.

error

no

object

Object mapping extension IDs to error messages about why the request failed for these IDs.

Example request

{
  "type": "EXT-LOAD",
  "ids": ["ssdp", "beer"]
}

Example response

{
  "type": "EXT-LOAD",
  "status": {
    "ssdp": {}
  },
  "error": {
    "beer": "No such extension. Unfortunately."
  }
}

EXT-RELOAD - Reload an extension

A client sends this request to the server to reload the extensions with IDs specified in the request.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of extension IDs which the client requests to reload.

Response fields

Name Required? Type Description

status

no

object

Object that contains empty objects for each requested extension that was successfully reloaded.

error

no

object

Object mapping extension IDs to error messages about why the request failed for these IDs.

Example request

{
  "type": "EXT-RELOAD",
  "ids": ["ssdp", "beer"]
}

Example response

{
  "type": "EXT-RELOAD",
  "status": {
    "ssdp": {}
  },
  "error": {
    "beer": "No such extension. Unfortunately."
  }
}

EXT-SETCFG - Set the current configuration of extensions

A client sends this request to the server to set the desired configuration for extensions with IDs specified in the request.

It should be noted, that the new configuration values do NOT take effect until the affected extensions are reloaded.

Request fields

Name Required? Type Description

ids

yes

object

Object that specifies new configuration values for each extension identified by their respective IDs.

Response fields

Name Required? Type Description

status

no

object

Object that contains empty objects for each requested extension that was successfully configured.

error

no

object

Object mapping extension IDs to error messages about why the request failed for these IDs.

Example request

{
  "type": "EXT-SETCFG",
  "ids": {
    "ssdp": {
      "multicast_group": "239.255.255.250",
      "port": 1900,
      "label": "My awesome server"
    },
    "beer": {
      "type": "IPA"
    }
  }
}

Example response

{
  "type": "EXT-SETCFG",
  "status": {
    "ssdp": {}
  },
  "error": {
    "beer": "No such extension. Unfortunately."
  }
}

EXT-UNLOAD - Unload an extension

A client sends this request to the server to unload the extensions with IDs specified in the request.

Request fields

Name Required? Type Description

ids

yes

list of strings

The list of extension IDs which the client requests to unload.

Response fields

Name Required? Type Description

status

no

object

Object that contains empty objects for each requested extension that was successfully unloaded.

error

no

object

Object mapping extension IDs to error messages about why the request failed for these IDs.

Example request

{
  "type": "EXT-UNLOAD",
  "ids": ["ssdp", "beer"]
}

Example response

{
  "type": "EXT-UNLOAD",
  "status": {
    "ssdp": {}
  },
  "error": {
    "beer": "No such extension. Unfortunately."
  }
}