Exampple.Xmpp.Stanza behaviour (exampple v0.7.2)

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

Link to this function

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>"
Link to this function

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 ID let us to generate an ID based on UUID v4.

Link to this function

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>"
Link to this function

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>"
Link to this function

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>"
Link to this function

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\"/>"
Link to this function

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\"/>"
Link to this function

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>"
Link to this function

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=\"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>"
Link to this function

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>"
Link to this function

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\"/>"
Link to this function

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\"/>"
Link to this function

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>"
Link to this function

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>"
Link to this function

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

Specs

render(map()) :: Exampple.Xml.Xmlel.t()