forked from jshiffer/go-xmpp
81 lines
2.5 KiB
Markdown
81 lines
2.5 KiB
Markdown
|
# 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.
|