Trait foxbox_taxonomy::api::API [−] [src]

pub trait API: Send {
    type WatchGuard;
    fn get_services(&self, Vec<ServiceSelector>) -> Vec<Service>;
    fn add_service_tags(&self, selectors: Vec<ServiceSelector>, tags: Vec<Id<TagId>>) -> usize;
    fn remove_service_tags(&self, selectors: Vec<ServiceSelector>, tags: Vec<Id<TagId>>) -> usize;
    fn get_getter_channels(&self, selectors: Vec<GetterSelector>) -> Vec<Channel<Getter>>;
    fn get_setter_channels(&self, selectors: Vec<SetterSelector>) -> Vec<Channel<Setter>>;
    fn add_getter_tags(&self, selectors: Vec<GetterSelector>, tags: Vec<Id<TagId>>) -> usize;
    fn add_setter_tags(&self, selectors: Vec<SetterSelector>, tags: Vec<Id<TagId>>) -> usize;
    fn remove_getter_tags(&self, selectors: Vec<GetterSelector>, tags: Vec<Id<TagId>>) -> usize;
    fn remove_setter_tags(&self, selectors: Vec<SetterSelector>, tags: Vec<Id<TagId>>) -> usize;
    fn fetch_values(&self, Vec<GetterSelector>, user: User) -> ResultMap<Id<Getter>, Option<Value>, Error>;
    fn send_values(&self, TargetMap<SetterSelector, Value>, user: User) -> ResultMap<Id<Setter>, (), Error>;
    fn watch_values(&self, watch: TargetMap<GetterSelector, Exactly<Range>>, on_event: Box<ExtSender<WatchEvent>>) -> Self::WatchGuard;
}

A handle to the public API.

Associated Types

`type WatchGuard`

A value that causes a disconnection once it is dropped.

Required Methods

`fn get_services(&self, Vec<ServiceSelector>) -> Vec<Service>`

Get the metadata on services matching some conditions.

A call to API::get_services(vec![req1, req2, ...]) will return the metadata on all services matching either req1 or req2 or ...

REST API

GET /api/v1/services

JSON

This call accepts as JSON argument a vector of ServiceSelector. See the documentation of ServiceSelector for more details.

Example: Select all doors in the entrance (tags door, entrance) that support setter channel OpenClosed


let source = r#"[{
  "tags": ["entrance", "door"],
  "getters": [
    {
      "kind": "OpenClosed"
    }
  ]
}]"#;

Errors

In case of syntax error, Error 400, accompanied with a somewhat human-readable JSON string detailing the error.

Success

A JSON representing an array of Service. See the implementation of Service for details.

Example

r#"[{
  "tags": ["entrance", "door", "somevendor"],
  "id: "some-service-id",
  "getters": [],
  "setters": [
    "tags": ["tag 1", "tag 2"],
    "id": "some-channel-id",
    "service": "some-service-id",
    "updated": "2014-11-28T12:00:09+00:00",
    "mechanism": "setter",
    "kind": "OnOff"
  ]
}]"#;

`fn add_service_tags(&self, selectors: Vec<ServiceSelector>, tags: Vec<Id<TagId>>) -> usize`

Label a set of services with a set of tags.

A call to API::put_service_tag(vec![req1, req2, ...], vec![tag1, ...]) will label all the services matching either req1 or req2 or ... with tag1, ... and return the number of services matching any of the selectors.

Some of the services may already be labelled with tag1, or tag2, ... They will not change state. They are counted in the resulting usize nevertheless.

Note that this call is not live. In other words, if services are added after the call, they will not be affected.

REST API

POST /api/v1/services/tag

JSON

A JSON object with the following fields: - services: array - an array of ServiceSelector; - tags: array - an array of string


r#"{
  "services": [{"id": "id 1"}, {"id": "id 2"}],
  "tags": ["tag 1", "tag 2"]
}"#;

Errors

In case of syntax error, Error 400, accompanied with a somewhat human-readable JSON string detailing the error.

Success

A JSON string representing a number.

`fn remove_service_tags(&self, selectors: Vec<ServiceSelector>, tags: Vec<Id<TagId>>) -> usize`

Remove a set of tags from a set of services.

A call to API::delete_service_tag(vec![req1, req2, ...], vec![tag1, ...]) will remove from all the services matching either req1 or req2 or ... all of the tags tag1, ... and return the number of services matching any of the selectors.

Some of the services may not be labelled with tag1, or tag2, ... They will not change state. They are counted in the resulting usize nevertheless.

Note that this call is not live. In other words, if services are added after the call, they will not be affected.

REST API

DELETE /api/v1/services/tag

JSON

A JSON object with the following fields: - services: array - an array of ServiceSelector; - tags: array - an array of string



r#"{
  "services": [{"id": "id 1"}, {"id": "id 2"}],
  "tags": ["tag 1", "tag 2"]
}"#;

Errors

In case of syntax error, Error 400, accompanied with a somewhat human-readable JSON string detailing the error.

Success

A JSON string representing a number.

`fn get_getter_channels(&self, selectors: Vec<GetterSelector>) -> Vec<Channel<Getter>>`

Get a list of getters matching some conditions

REST API

GET /api/v1/channels/getters

JSON

This call accepts as JSON argument a vector of GetterSelector. See the documentation of GetterSelector for more details.

Example: Select all doors in the entrance (tags door, entrance) that support setter channel OpenClosed


let source = r#"[{
  "tags": ["entrance", "door"],
  "kind": "OpenClosed"
}]"#;

Errors

In case of syntax error, Error 400, accompanied with a somewhat human-readable JSON string detailing the error.

Success

A JSON representing an array of Service. See the implementation of Service for details.

Example

r#"[{
  "tags": ["entrance", "door", "somevendor"],
  "id: "some-getter-id",
  "service": "some-service-id",
  "updated": "2014-11-28T12:00:09+00:00",
  "mechanism": "getter",
  "kind": "OnOff"
}]"#;

`fn get_setter_channels(&self, selectors: Vec<SetterSelector>) -> Vec<Channel<Setter>>`

Get a list of getters matching some conditions

REST API

GET /api/v1/channels

`fn add_getter_tags(&self, selectors: Vec<GetterSelector>, tags: Vec<Id<TagId>>) -> usize`

Label a set of channels with a set of tags.

A call to API::put_{getter, setter}_tag(vec![req1, req2, ...], vec![tag1, ...]) will label all the channels matching either req1 or req2 or ... with tag1, ... and return the number of channels matching any of the selectors.

Some of the channels may already be labelled with tag1, or tag2, ... They will not change state. They are counted in the resulting usize nevertheless.

Note that this call is not live. In other words, if channels are added after the call, they will not be affected.

REST API

POST /api/v1/channels/tag

Requests

Any JSON that can be deserialized to

{
  set: Vec<GetterSelector>,
  tags: Vec<Id<TagId>>,
}

or ignore { set: Vec<SetterSelector>, tags: Vec<Id<TagId>>, }

Errors

In case of syntax error, Error 400, accompanied with a somewhat human-readable JSON string detailing the error.

Success

A JSON representing a number.

`fn add_setter_tags(&self, selectors: Vec<SetterSelector>, tags: Vec<Id<TagId>>) -> usize`

`fn remove_getter_tags(&self, selectors: Vec<GetterSelector>, tags: Vec<Id<TagId>>) -> usize`

Remove a set of tags from a set of channels.

A call to API::delete_{getter, setter}_tag(vec![req1, req2, ...], vec![tag1, ...]) will remove from all the channels matching either req1 or req2 or ... all of the tags tag1, ... and return the number of channels matching any of the selectors.

Some of the channels may not be labelled with tag1, or tag2, ... They will not change state. They are counted in the resulting usize nevertheless.

Note that this call is not live. In other words, if channels are added after the call, they will not be affected.

REST API

DELETE /api/v1/channels/tag

Requests

Any JSON that can be deserialized to

{
  set: Vec<GetterSelector>,
  tags: Vec<Id<TagId>>,
}

or ignore { set: Vec<SetterSelector>, tags: Vec<Id<TagId>>, }

Errors

In case of syntax error, Error 400, accompanied with a somewhat human-readable JSON string detailing the error.

Success

A JSON representing a number.

`fn remove_setter_tags(&self, selectors: Vec<SetterSelector>, tags: Vec<Id<TagId>>) -> usize`

`fn fetch_values(&self, Vec<GetterSelector>, user: User) -> ResultMap<Id<Getter>, Option<Value>, Error>`

Read the latest value from a set of channels

REST API

GET /api/v1/channels/get

This call supports one or more GetterSelector.



// The following argument will fetch a value from to a single getter:
r#"{"id": "my-getter"}"#;

Errors

In case of syntax error, Error 400, accompanied with a somewhat human-readable JSON string detailing the error.

Success

The results, per getter.

`fn send_values(&self, TargetMap<SetterSelector, Value>, user: User) -> ResultMap<Id<Setter>, (), Error>`

Send a bunch of values to a set of channels.

Sending values to several setters of the same service in a single call will generally be much faster than calling this method several times.

REST API

PUT /api/v1/channels/set

JSON

This call supports one or more objects with the following fields: - select (Service Selector | array of ServiceSelector) - the setters to which the value must be sent - value (Value) - the value to send



// The following argument will send `On` to a single setter:
r#"{
  "select": {"id": "my-setter"},
  "value": {"OnOff": "On"}
}"#;


// The following argument will send `On` to two setters and `Unit` to everything
// that supports `Ready`.
r#"[{
  "select": [{"id": "my-setter 1"}, {"id": "my-setter 2"}],
  "value": {"OnOff": "On"}
}, {
  "select": {"kind": "Ready"},
  "value": {"Unit": null}
}]"#;

Errors

In case of syntax error, Error 400, accompanied with a somewhat human-readable JSON string detailing the error.

Success

The results, per setter.

`fn watch_values(&self, watch: TargetMap<GetterSelector, Exactly<Range>>, on_event: Box<ExtSender<WatchEvent>>) -> Self::WatchGuard`

Watch for changes from channels.

This method registers a closure to watch over events on a set of channels. Argument watch specifies which channels to watch and which events are of interest.

If argument Exactly<Range> is Exactly::Exactly(range), the watch is interested in values coming from these channels, if they fall within range. This is the most common case. In this case, on_event receives WatcherEvent::GetterAdded, WatcherEvent::GetterRemoved and WatcherEvent::Value, whenever a new value is available in the range. Values that do not have the same type as range are dropped silently.
If argument Exactly<Range> is Exactly::Never, the watch is not interested in the values coming from these channels, only in connection/disconnection events. Argument on_event receives WatchEvent::GetterAdded and WatchEvent::GetterRemoved.
If the Exactly<Range> argument is Exactly::Always, the watch is interested in receiving every single value coming from the channels. This is very rarely a good idea. Many devices may reject such requests.

The watcher is disconnected once the WatchGuard returned by this method is dropped.

WebSocket API

/api/v1/channels/watch

Implementors

impl API for AdapterManager