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

Included in @xmpp/client and @xmpp/component.

Caller

Implements the caller side of iq semantics.

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.

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 but accepts/returns a child element instead of an iq.

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 but accepts/returns a child element instead of an iq.

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.

import { client } from "@xmpp/client"; // or component

const xmpp = client(...);
const {iqCallee} = xmpp;

get

Add a get handler.

iqCallee.get("foo:bar", "foo", (ctx) => {
  return xml("foo", { xmlns: "foo:bar" });
});

set

Add a set handler.

iqCallee.set("foo:bar", "foo", (ctx) => {
  return xml("foo", { xmlns: "foo:bar" });
});

References

RFC 6120 IQ Semantics