go-xmpp/stanza/README.md
2019-06-27 10:21:33 +02:00

2.5 KiB

XMPP Stanza

XMPP stanza package is use to parse, marshall and and unmarshal XMPP stanzas and nonzas.

Stanza creation

When creating stanzas, you can use two approaches:

  1. You can create IQ, Presence or Message structs, set the fields and manually prepare extensions struct to add to the stanza.
  2. You can use stanza Builder providing

The methods are equivalent and you can use whatever suits you best. The Builder will generate the same type of struct that you can build by hand.

Composing stanzas manually with structs

Here is for example how you would generate an IQ discovery result:

iqResp := stanza.NewIQ(stanza.Attrs{Type: "result", From: iq.To, To: iq.From, Id: iq.Id, Lang: "en"})
identity := stanza.Identity{
	Name:     opts.Name,
	Category: opts.Category,
	Type:     opts.Type,
}
payload := stanza.DiscoInfo{
	XMLName: xml.Name{
		Space: stanza.NSDiscoInfo,
		Local: "query",
	},
	Identity: identity,
	Features: []stanza.Feature{
		{Var: stanza.NSDiscoInfo},
		{Var: stanza.NSDiscoItems},
		{Var: "jabber:iq:version"},
		{Var: "urn:xmpp:delegation:1"},
	},
}
iqResp.Payload = &payload

Using Builder

Here is for example how you would generate an IQ discovery result using Builder:

b := stanza.NewBuilder()
iq := b.IQ(stanza.Attrs{Type: "get", To: "service.localhost", Id: "disco-get-1"})

payload := b.DiscoInfo()
identity := b.Identity("Test Component", "gateway", "service")
payload.SetFeatures(stanza.NSDiscoInfo, stanza.NSDiscoItems, "jabber:iq:version", "urn:xmpp:delegation:1").
	SetIdentities(identity)

iq.Payload = payload

Payload and extensions

Message

Presence

IQ

IQ (Information Queries) contain a payload associated with the request and possibly an error. The main difference with Message and Presence extension is that you can only have one payload per IQ. The XMPP specification does not support having multiple payloads.

Here is the list of structs implementing IQPayloads:

  • BindBind
  • Pubsub

Finally, when the payload of the parsed stanza is unknown, the parser will provide the unknown payload as a generic Node element. You can also use the Node struct to add custom information on stanza generation. However, in both cases, you may also consider adding your own custom extensions on stanzas.

Adding your own custom extensions on stanzas

Extensions are registered on launch using the Registry. It can be used to register you own custom payload. You may want to do so to support extensions we did not yet implement, or to add your own custom extensions to your XMPP stanzas.