exampple v0.3.0 Exampple.Xmpp.Stanza behaviour
Provides functions to create stanzas.
Link to this section Summary
Functions
Agnostic to the type of stanza it generates an error for the incoming stanza. The supported types are: iq, presence and message.
Returns an error tag based on the key provided as parameter. The codes available are the following ones
Creates IQ stanzas.
Taken an IQ stanza, 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.
Creates a response error message.
Creates error message stanzas.
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.
Creates presence stanzas.
Creates a response error presence inside of the Exampple.Router.Conn struct (response) or sending back directly the XML struct if Exampple.Xml.Xmlel is used.
Creates error presence stanzas.
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(xml, error)
Agnostic to the type of stanza it generates an error for the incoming stanza. 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, nil, nil, nil)
iex> |> Exampple.Xmpp.Stanza.error("forbidden")
iex> |> to_string()
"<iq 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 key 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>"
iq(payload, from, id, to, type)
Creates IQ stanzas.
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, 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 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.
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.
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=\"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>"
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=\"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_error(payload, error, from, id, to)
Creates error message stanzas.
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.
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=\"alice@example.com\" id=\"1\" to=\"bob@example.com\" type=\"chat\"/>"
presence(payload, from, id \\ nil, to \\ nil, type \\ nil)
Creates presence stanzas.
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 inside of the Exampple.Router.Conn struct (response) or sending back directly the XML struct if Exampple.Xml.Xmlel is used.
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.
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/>"