forked from jshiffer/go-xmpp
77 lines
2.6 KiB
Markdown
77 lines
2.6 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` build helper to be guided when creating the stanza, and have more controls performed on the
|
|
final stanza.
|
|
|
|
The methods are equivalent and you can use whatever suits you best. The helpers will finally 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: []stanza.Identity{identity},
|
|
Features: []stanza.Feature{
|
|
{Var: stanza.NSDiscoInfo},
|
|
{Var: stanza.NSDiscoItems},
|
|
{Var: "jabber:iq:version"},
|
|
{Var: "urn:xmpp:delegation:1"},
|
|
},
|
|
}
|
|
iqResp.Payload = &payload
|
|
|
|
### Using helpers
|
|
|
|
Here is for example how you would generate an IQ discovery result using Builder:
|
|
|
|
iq := stanza.NewIQ(stanza.Attrs{Type: "get", To: "service.localhost", Id: "disco-get-1"})
|
|
disco := iq.DiscoInfo()
|
|
disco.AddIdentity("Test Component", "gateway", "service")
|
|
disco.AddFeatures(stanza.NSDiscoInfo, stanza.NSDiscoItems, "jabber:iq:version", "urn:xmpp:delegation:1")
|
|
|
|
## 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.
|