Add initial documentation
This commit is contained in:
parent
3fa1a4b387
commit
0c7e4588c6
80
stanza/README.md
Normal file
80
stanza/README.md
Normal file
|
@ -0,0 +1,80 @@
|
||||||
|
# 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.
|
Loading…
Reference in a new issue