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 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 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

Link to this function

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

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

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

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>"
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 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.

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.

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.

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.

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

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

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

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>"
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