comparison: docs/character-classes/client.md
docs/character-classes/client.md
- changeset 166
- 5d39804f108b
equal
deleted
inserted
replaced
| 165:92e1733243d5 | 166:5d39804f108b |
|---|---|
| 1 # Client: XMPP client | |
| 2 | |
| 3 The `[Client]` class represents an XMPP client connection to a server. | |
| 4 | |
| 5 Example: | |
| 6 | |
| 7 ``` | |
| 8 [Client] Romeo | |
| 9 jid: romeo@example.com | |
| 10 password: s3cr3t! | |
| 11 ``` | |
| 12 | |
| 13 | |
| 14 ## Properties | |
| 15 | |
| 16 | Property | Description | | |
| 17 |:-------------|:------------------------------------| | |
| 18 | jid | The JID to connect to the server as | | |
| 19 | password | The password to connect with | | |
| 20 | connect_host | The server host, if not the default | | |
| 21 | connect_port | The server port, if not the default | | |
| 22 | |
| 23 ## Actions | |
| 24 | |
| 25 ### sends | |
| 26 | |
| 27 Sends a stanza to the XMPP server. | |
| 28 | |
| 29 Example: | |
| 30 | |
| 31 ``` | |
| 32 Romeo sends: | |
| 33 <iq type="get" id="123"> | |
| 34 <query xmlns="jabber:iq:roster"/> | |
| 35 </iq> | |
| 36 ``` | |
| 37 | |
| 38 ### receives | |
| 39 | |
| 40 Expects to receive a stanza from the server. | |
| 41 | |
| 42 Example: | |
| 43 | |
| 44 ``` | |
| 45 Romeo receives: | |
| 46 <iq type="result" id="123"> | |
| 47 <query xmlns="jabber:iq:roster"> | |
| 48 <item jid="juliet@example.com" subscription="both" /> | |
| 49 </query> | |
| 50 </iq> | |
| 51 ``` | |
| 52 | |
| 53 If no stanza is expected, the simple string 'nothing' may be used: | |
| 54 | |
| 55 ``` | |
| 56 Romeo receives: nothing | |
| 57 ``` | |
| 58 | |
| 59 #### Matching rules | |
| 60 | |
| 61 When a stanza is received from the server, it is matched against the one in the script. | |
| 62 If it does not match, the script will fail and abort. | |
| 63 | |
| 64 The matching has two modes, strict and non-strict. They require: | |
| 65 | |
| 66 Non-strict mode: | |
| 67 | |
| 68 - All attributes in the expected stanza must be present in the received stanza. Additional | |
| 69 attributes in the received stanza are ignored. | |
| 70 - All tags in the expected stanza must be present in the received stanza. Additional tags are ignored. Order is ignored. | |
| 71 | |
| 72 Strict mode: | |
| 73 | |
| 74 - All attributes in the expected stanza must be in the received stanza, and vice-versa. Additional attributes in the received stanza are not allowed. | |
| 75 - All tags in the expected stanza must be in the received stanza, additional tags are not allowed. Order must be the same. | |
| 76 | |
| 77 Both modes: | |
| 78 | |
| 79 - If an attribute value is `{scansion:any}` in the expected stanza, that attribute must be present in the received stanza, but | |
| 80 the value itself is ignored. This is useful for e.g. id attributes or other attributes that may vary unpredictably. | |
| 81 | |
| 82 By default tags in the default namespace are matched using the non-strict rules, but tags with their own namespace are matched using the | |
| 83 strict rules. You can override the matching behaviour for any tag by adding a `scansion:strict` attribute with a value of `true` or `false`: | |
| 84 | |
| 85 ``` | |
| 86 # By default this would match any message, by ignoring | |
| 87 # extra payloads. However we enable strict mode to ensure | |
| 88 # that it only matches a completely empty message stanza: | |
| 89 | |
| 90 Romeo receives: | |
| 91 <message scansion:strict="true"/> | |
| 92 ``` |
