Exampple.Xmpp.Stanza behaviour (exampple v0.7.8)
Provides functions to create stanzas.
Link to this section Summary
Functions
Agnostic to the type of stanza it generates an error
(provided as second
parameter) for the incoming stanza (provided as first parameter as xmlel
or
conn
).
Returns an error tag based on the error
provided as parameter.
The codes available are the following ones
Gen ID let us to generate an ID based on UUID v4.
Creates IQ stanzas based on the information provided by the parameters:
the payload
gives the content as a list of strings and/or
Exampple.Xml.Xmlel
structs, the from
and to
parameters configures
who send and receive the message, respectively, as bare or full JID in
string format. The id
provides the ID for the stanza. Finally, the
type
provides the type for the stanza depending on if it's message,
presence or iq the content of type could be different. Usually for normal
chat messages the type is chat, for normal IQ requests is get and for
presences indicating the user is available, it's available.
Taken an IQ stanza (xmlel
), it generates an error based on error
parameter. The codes available are the following ones
Generates an error IQ stanza passing the payload
, from
JID, id
and
to
JID. The codes available are the following ones
Taking an IQ stanza, it generates a response swapping from and to and
changing the type to "result". If a payload
is provided (not nil) it
will replace the payload using the second parameter.
Generates a result IQ stanza passing the payload
, from
JID, id
and to
JID.
Creates message stanzas passing the payload
, from
JID, id
, to
JID,
and optionally the type
.
Creates a response error message based on the error
indicated as second
parameter and the stanza as first parameter and in conn
or xmlel
format.
Creates error message stanzas based on the payload
, error
, from
JID,
id
and to
JID passed as parameters.
Creates a response message inside of the Router.Conn struct (response).
This is indeed not a response but a way to simplify the send to a message
to who was sending us something. We are providing a payload
as second
parameter for the response and conn
as the first parameter.
Creates presence stanzas based on the payload
, from
JID, id
,
to
JID, and optionally the type
passed as parameters.
Creates a response error presence (indicated error
as second parameter)
inside of the Exampple.Router.Conn struct (response) or sending back
directly the XML struct if Exampple.Xml.Xmlel is used. It is depending
on the first parameter xmlel
or conn
.
Creates error presence stanzas based on the payload
, error
, from
JID,
id
and to
JID passed as parameters.
Generates an stanza passed the stanza type (iq, presence or message), the from
and to
for sender and recipient respectively, the id
for the stanza, the
type
which depends on the stanza type it could be set, get or result for iq,
available, unavailable, probe, subscribe, subscribed, ... for presence or
chat, groupchat, normal or head for message. And we set also the payload
as
a list of elements to be included inside of the stanza.
Link to this section Functions
error(xmlel, error)
Agnostic to the type of stanza it generates an error
(provided as second
parameter) for the incoming stanza (provided as first parameter as xmlel
or
conn
).
The supported types are: iq, presence and message.
Examples:
iex> Exampple.Xmpp.Stanza.stanza([], "presence", nil, nil, nil, nil)
iex> |> Exampple.Xmpp.Stanza.error("forbidden")
iex> |> to_string()
"<presence type=\"error\"><error type=\"auth\"><forbidden xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></presence>"
iex> Exampple.Xmpp.Stanza.stanza([], "message", nil, nil, nil, nil)
iex> |> Exampple.Xmpp.Stanza.error("forbidden")
iex> |> to_string()
"<message type=\"error\"><error type=\"auth\"><forbidden xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></message>"
iex> Exampple.Xmpp.Stanza.stanza([], "iq", nil, "42", nil, nil)
iex> |> Exampple.Xmpp.Stanza.error("forbidden")
iex> |> to_string()
"<iq id=\"42\" type=\"error\"><error type=\"auth\"><forbidden xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></iq>"
error_tag(error)
Returns an error tag based on the error
provided as parameter.
The codes available are the following ones:
- bad-request
- forbidden
- item-not-found
- not-acceptable
- internal-server-error
- service-unavailable
- feature-not-implemented
see more here: https://xmpp.org/extensions/xep-0086.html
You can also use a 3-elements tuple to send {error, lang, text}, this way you can create a rich error like this:
<error type="cancel">
<item-not-found xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
<text lang="en" xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">item was not found in database</text>
</error>
Examples:
iex> Exampple.Xmpp.Stanza.error_tag("item-not-found") |> to_string()
"<error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error>"
iex> Exampple.Xmpp.Stanza.error_tag({"item-not-found", "en", "item was not found in database"}) |> to_string()
"<error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/><text lang=\"en\" xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\">item was not found in database</text></error>"
gen_uuid()
Gen ID let us to generate an ID based on UUID v4.
iq(payload, from, id, to, type)
Creates IQ stanzas based on the information provided by the parameters:
the payload
gives the content as a list of strings and/or
Exampple.Xml.Xmlel
structs, the from
and to
parameters configures
who send and receive the message, respectively, as bare or full JID in
string format. The id
provides the ID for the stanza. Finally, the
type
provides the type for the stanza depending on if it's message,
presence or iq the content of type could be different. Usually for normal
chat messages the type is chat, for normal IQ requests is get and for
presences indicating the user is available, it's available.
Check the RFC-6121 in the sections 4.7.1 for presence, 5.2.2 for message and 6 for IQs.
Examples:
iex> payload = [Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})]
iex> alice = "alice@example.com"
iex> bob = "bob@example.com"
iex> Exampple.Xmpp.Stanza.iq(payload, alice, "1", bob, "get")
iex> |> to_string()
"<iq from=\"alice@example.com\" id=\"1\" to=\"bob@example.com\" type=\"get\"><query xmlns=\"jabber:iq:roster\"/></iq>"
iq_error(xmlel, error)
Taken an IQ stanza (xmlel
), it generates an error based on error
parameter. The codes available are the following ones:
- bad-request
- forbidden
- item-not-found
- not-acceptable
- internal-server-error
- service-unavailable
- feature-not-implemented
see more here: https://xmpp.org/extensions/xep-0086.html
You can also use a 3-elements tuple to send {error, lang, text}, this way you can create a rich error like this:
<error type="cancel">
<item-not-found xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
<text lang="en" xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">item was not found in database</text>
</error>
Examples:
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com", "id" => "1", "type" => "get"}
iex> payload = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> xmlel = Exampple.Xml.Xmlel.new("iq", attrs, [payload])
iex> Exampple.Xmpp.Stanza.iq_error(xmlel, "item-not-found")
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"error\"><query xmlns=\"jabber:iq:roster\"/><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></iq>"
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com", "id" => "1", "type" => "get"}
iex> payload = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> xmlel = Exampple.Xml.Xmlel.new("iq", attrs, [payload])
iex> conn = Exampple.Router.Conn.new(xmlel)
iex> |> Exampple.Xmpp.Stanza.iq_error("item-not-found")
iex> conn.response
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"error\"><query xmlns=\"jabber:iq:roster\"/><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></iq>"
iq_error(payload, error, from, id, to)
Generates an error IQ stanza passing the payload
, from
JID, id
and
to
JID. The codes available are the following ones:
- bad-request
- forbidden
- item-not-found
- not-acceptable
- internal-server-error
- service-unavailable
- feature-not-implemented
see more here: https://xmpp.org/extensions/xep-0086.html
You can also use a 3-elements tuple to send {error, lang, text}, this way you can create a rich error like this:
<error type="cancel">
<item-not-found xmlns="urn:ietf:params:xml:ns:xmpp-stanzas"/>
<text lang="en" xmlns="urn:ietf:params:xml:ns:xmpp-stanzas">item was not found in database</text>
</error>
Examples:
iex> from = "bob@example.com"
iex> to = "alice@example.com"
iex> id = "1"
iex> payload = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> Exampple.Xmpp.Stanza.iq_error([payload], "item-not-found", from, id, to)
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"error\"><query xmlns=\"jabber:iq:roster\"/><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></iq>"
iq_resp(xmlel_or_conn, payload \\ nil)
Taking an IQ stanza, it generates a response swapping from and to and
changing the type to "result". If a payload
is provided (not nil) it
will replace the payload using the second parameter.
If the first paramenter (xmlel_or_conn
) is a Router.Conn
it keeps
the flow. Stores the response inside of the Router.Conn
and return it.
Examples:
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com", "id" => "1", "type" => "get"}
iex> payload = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> xmlel = Exampple.Xml.Xmlel.new("iq", attrs, [payload])
iex> Exampple.Xmpp.Stanza.iq_resp(xmlel)
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"result\"><query xmlns=\"jabber:iq:roster\"/></iq>"
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com", "id" => "1", "type" => "get"}
iex> payload = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> xmlel = Exampple.Xml.Xmlel.new("iq", attrs, [payload])
iex> Exampple.Xml.Xmlel.new("item", %{"id" => "1"}, ["contact 1"])
iex> payload_resp = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> Exampple.Xmpp.Stanza.iq_resp(xmlel, [payload_resp])
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"result\"><query xmlns=\"jabber:iq:roster\"/></iq>"
iex> attrs = %{
iex> "from" => "alice@example.com",
iex> "to" => "bob@example.com",
iex> "id" => "1"
iex> }
iex> payload = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> iq = Exampple.Xml.Xmlel.new("iq", attrs, [payload])
iex> conn = Exampple.Router.Conn.new(iq)
iex> |> Exampple.Xmpp.Stanza.iq_resp()
iex> conn.response
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"result\"><query xmlns=\"jabber:iq:roster\"/></iq>"
iex> attrs = %{
iex> "from" => "alice@example.com",
iex> "to" => "bob@example.com",
iex> "id" => "1"
iex> }
iex> payload = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> iq = Exampple.Xml.Xmlel.new("iq", attrs, [payload])
iex> conn = Exampple.Router.Conn.new(iq)
iex> |> Exampple.Xmpp.Stanza.iq_resp([])
iex> conn.response
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"result\"/>"
iq_resp(payload \\ [], from, id, to)
Generates a result IQ stanza passing the payload
, from
JID, id
and to
JID.
Examples:
iex> from = "bob@example.com"
iex> to = "alice@example.com"
iex> id = "1"
iex> payload = Exampple.Xml.Xmlel.new("query", %{"xmlns" => "jabber:iq:roster"})
iex> Exampple.Xmpp.Stanza.iq_resp([payload], from, id, to)
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"result\"><query xmlns=\"jabber:iq:roster\"/></iq>"
iex> from = "bob@example.com"
iex> to = "alice@example.com"
iex> id = "1"
iex> Exampple.Xmpp.Stanza.iq_resp(from, id, to)
iex> |> to_string()
"<iq from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"result\"/>"
message(payload, from, id, to, type \\ nil)
Creates message stanzas passing the payload
, from
JID, id
, to
JID,
and optionally the type
.
Examples:
iex> payload = [Exampple.Xml.Xmlel.new("body", %{}, ["hello world!"])]
iex> alice = "alice@example.com"
iex> bob = "bob@example.com"
iex> Exampple.Xmpp.Stanza.message(payload, alice, "1", bob, "chat")
iex> |> to_string()
"<message from=\"alice@example.com\" id=\"1\" to=\"bob@example.com\" type=\"chat\"><body>hello world!</body></message>"
iex> payload = [Exampple.Xml.Xmlel.new("composing")]
iex> alice = "alice@example.com"
iex> bob = "bob@example.com"
iex> Exampple.Xmpp.Stanza.message(payload, alice, "1", bob)
iex> |> to_string()
"<message from=\"alice@example.com\" id=\"1\" to=\"bob@example.com\"><composing/></message>"
message_error(conn, error)
Creates a response error message based on the error
indicated as second
parameter and the stanza as first parameter and in conn
or xmlel
format.
Examples:
iex> payload = [Exampple.Xml.Xmlel.new("body", %{}, ["hello world!"])]
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com", "id" => "1"}
iex> Exampple.Xml.Xmlel.new("message", attrs, payload)
iex> |> Exampple.Xmpp.Stanza.message_error("item-not-found")
iex> |> to_string()
"<message from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"error\"><body>hello world!</body><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></message>"
iex> payload = [Exampple.Xml.Xmlel.new("body", %{}, ["hello world!"])]
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com", "id" => "1"}
iex> message = Exampple.Xml.Xmlel.new("message", attrs, payload)
iex> conn = Exampple.Router.Conn.new(message)
iex> |> Exampple.Xmpp.Stanza.message_error("item-not-found")
iex> conn.response
iex> |> to_string()
"<message from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"error\"><body>hello world!</body><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></message>"
message_error(payload, error, from, id, to)
Creates error message stanzas based on the payload
, error
, from
JID,
id
and to
JID passed as parameters.
Examples:
iex> payload = [Exampple.Xml.Xmlel.new("body", %{}, ["hello world!"])]
iex> alice = "alice@example.com"
iex> bob = "bob@example.com"
iex> Exampple.Xmpp.Stanza.message_error(payload, "item-not-found", alice, "1", bob)
iex> |> to_string()
"<message from=\"alice@example.com\" id=\"1\" to=\"bob@example.com\" type=\"error\"><body>hello world!</body><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></message>"
message_resp(conn, payload)
Creates a response message inside of the Router.Conn struct (response).
This is indeed not a response but a way to simplify the send to a message
to who was sending us something. We are providing a payload
as second
parameter for the response and conn
as the first parameter.
Examples:
iex> payload = [Exampple.Xml.Xmlel.new("body", %{}, ["hello world!"])]
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com", "id" => "1", "type" => "chat"}
iex> message = Exampple.Xml.Xmlel.new("message", attrs, payload)
iex> conn = Exampple.Router.Conn.new(message)
iex> |> Exampple.Xmpp.Stanza.message_resp([])
iex> conn.response
iex> |> to_string()
"<message from=\"bob@example.com\" id=\"1\" to=\"alice@example.com\" type=\"chat\"/>"
presence(payload, from, id \\ nil, to \\ nil, type \\ nil)
Creates presence stanzas based on the payload
, from
JID, id
,
to
JID, and optionally the type
passed as parameters.
Examples:
iex> alice = "alice@example.com"
iex> Exampple.Xmpp.Stanza.presence([], alice)
iex> |> to_string()
"<presence from=\"alice@example.com\"/>"
presence_error(conn, error)
Creates a response error presence (indicated error
as second parameter)
inside of the Exampple.Router.Conn struct (response) or sending back
directly the XML struct if Exampple.Xml.Xmlel is used. It is depending
on the first parameter xmlel
or conn
.
Examples:
iex> payload = [Exampple.Xml.Xmlel.new("status", %{}, ["away"])]
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com"}
iex> presence = Exampple.Xml.Xmlel.new("presence", attrs, payload)
iex> conn = Exampple.Router.Conn.new(presence)
iex> |> Exampple.Xmpp.Stanza.presence_error("item-not-found")
iex> conn.response
iex> |> to_string()
"<presence from=\"alice@example.com\" to=\"bob@example.com\" type=\"error\"><status>away</status><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></presence>"
iex> payload = [Exampple.Xml.Xmlel.new("status", %{}, ["away"])]
iex> attrs = %{"from" => "alice@example.com", "to" => "bob@example.com"}
iex> Exampple.Xml.Xmlel.new("presence", attrs, payload)
iex> |> Exampple.Xmpp.Stanza.presence_error("item-not-found")
iex> |> to_string()
"<presence from=\"alice@example.com\" to=\"bob@example.com\" type=\"error\"><status>away</status><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></presence>"
presence_error(payload, error, from, id, to)
Creates error presence stanzas based on the payload
, error
, from
JID,
id
and to
JID passed as parameters.
Examples:
iex> payload = [Exampple.Xml.Xmlel.new("status", %{}, ["away"])]
iex> alice = "alice@example.com"
iex> bob = "bob@example.com"
iex> Exampple.Xmpp.Stanza.presence_error(payload, "item-not-found", alice, nil, bob)
iex> |> to_string()
"<presence from=\"alice@example.com\" to=\"bob@example.com\" type=\"error\"><status>away</status><error type=\"cancel\"><item-not-found xmlns=\"urn:ietf:params:xml:ns:xmpp-stanzas\"/></error></presence>"
stanza(payload, stanza_type, from, id, to, type)
Generates an stanza passed the stanza type (iq, presence or message), the from
and to
for sender and recipient respectively, the id
for the stanza, the
type
which depends on the stanza type it could be set, get or result for iq,
available, unavailable, probe, subscribe, subscribed, ... for presence or
chat, groupchat, normal or head for message. And we set also the payload
as
a list of elements to be included inside of the stanza.
Examples:
iex> Exampple.Xmpp.Stanza.stanza([], "presence", nil, nil, nil, nil)
iex> |> to_string()
"<presence/>"
Link to this section Callbacks
render(map)
Specs
render(map()) :: Exampple.Xml.Xmlel.t()