103 lines
2.5 KiB
Markdown
103 lines
2.5 KiB
Markdown
# iq
|
|
|
|
> Info/Query, or IQ, is a "request-response" mechanism, similar in some ways to the Hypertext Transfer Protocol [HTTP]. The semantics of IQ enable an entity to make a request of, and receive a response from, another entity.
|
|
|
|
[XMPP Core: IQ Semantics](https://xmpp.org/rfcs/rfc6120.html#stanzas-semantics-iq)
|
|
|
|
Included in `@xmpp/client` and `@xmpp/component`.
|
|
|
|
## Caller
|
|
|
|
Implements the caller side of iq semantics.
|
|
|
|
```js
|
|
import { client } from "@xmpp/client"; // or component
|
|
|
|
const xmpp = client(...);
|
|
const {iqCaller} = xmpp;
|
|
```
|
|
|
|
### request
|
|
|
|
Sends an iq and returns a promise.
|
|
|
|
- Resolves with the response when it is received.
|
|
- Rejects with `StanzaError` when an error is received
|
|
- Rejects with `TimeoutError` if a reply wasn't received within the specified or default timeout
|
|
- Rejects with `Error` for anything else
|
|
|
|
* The request `id` attribute is optional and will be added if omitted.
|
|
* The request `to` attribute is optional and will default to the server.
|
|
|
|
```js
|
|
const response = await iqCaller.request(
|
|
xml("iq", { type: "get" }, xml("foo", "foo:bar")),
|
|
30 * 1000, // 30 seconds timeout - default
|
|
);
|
|
const foo = response.getChild("foo", "foo:bar");
|
|
console.log(foo);
|
|
```
|
|
|
|
### get
|
|
|
|
A convenient method to send a `get` request. Behaves like [request](#request) but accepts/returns a child element instead of an `iq`.
|
|
|
|
```js
|
|
const foo = await iqCaller.get(
|
|
xml("foo", "foo:bar"),
|
|
to, // "to" attribute, optional
|
|
timeout, // 30 seconds timeout - default
|
|
);
|
|
console.log(foo);
|
|
```
|
|
|
|
### set
|
|
|
|
A convenient method to send a `set` request. Behaves like [request](#request) but accepts/returns a child element instead of an `iq`.
|
|
|
|
```js
|
|
const foo = await iqCaller.set(
|
|
xml("foo", "foo:bar"),
|
|
to, // "to" attribute, optional
|
|
timeout, // 30 seconds timeout - default
|
|
);
|
|
console.log(foo);
|
|
```
|
|
|
|
## Callee
|
|
|
|
Implements the callee side of iq semantics.
|
|
|
|
You can think of this as http routing except there are only 2 methods; `get` and `set` and you would pass a namespace and a tag name instead of an url. The return value of the handler will be the child element of the response sent to the caller.
|
|
|
|
```js
|
|
import { client } from "@xmpp/client"; // or component
|
|
|
|
const xmpp = client(...);
|
|
const {iqCallee} = xmpp;
|
|
```
|
|
|
|
## get
|
|
|
|
Add a `get` handler.
|
|
|
|
```js
|
|
iqCallee.get("foo:bar", "foo", (ctx) => {
|
|
return xml("foo", { xmlns: "foo:bar" });
|
|
});
|
|
```
|
|
|
|
## set
|
|
|
|
Add a `set` handler.
|
|
|
|
```js
|
|
iqCallee.set("foo:bar", "foo", (ctx) => {
|
|
return xml("foo", { xmlns: "foo:bar" });
|
|
});
|
|
```
|
|
|
|
## References
|
|
|
|
[RFC 6120 IQ Semantics](https://xmpp.org/rfcs/rfc6120.html#stanzas-semantics-iq)
|