1 | # The top-level structure is a 'define'. This defines either a building-block -- |
---|
2 | # a 'struct' which can get pulled into the various SNACs -- or a SNAC. SNACs have |
---|
3 | # family and subtype, and optionally a channel. |
---|
4 | # |
---|
5 | # 'ref' is like #include. There are some basic structures, like userinfo, which appear |
---|
6 | # inside multiple SNACs. |
---|
7 | # |
---|
8 | # Then there are the data types: |
---|
9 | # Numeric types: byte (8-bit), word (16-bit), dword (32-bit). |
---|
10 | # Raw character data: data |
---|
11 | # This can have a 'length prefix' attached to it. |
---|
12 | # The length prefix is a numeric type. The value of the length prefix |
---|
13 | # is the number of bytes of character data. The existence of this |
---|
14 | # length prefix is why it might be useful for data to have sub-data. |
---|
15 | # Data types can have 'counts'. A count of -1 represents an infinite count. |
---|
16 | # Counted data is passed around as a listref. For instance, a capabilities block |
---|
17 | # is a series of 16-byte values, so by attaching count=-1 to that data item, |
---|
18 | # you can pass in a listref with the individual capabilities. There is also |
---|
19 | # fixed-length character data, specified via the length attribute on the data element. |
---|
20 | # Data can be null-terminated and padded. The value for the pad attribute specifies |
---|
21 | # the octet value to use for padding. |
---|
22 | # |
---|
23 | # There are also enums, which are exactly like numeric types except the raw numeric |
---|
24 | # values gets translated into some other values, so if you have a message-type |
---|
25 | # word, you can have 1 => "foo", and you'll get a "foo" when decoding a 1 and a |
---|
26 | # 1 when encoding a "foo". |
---|
27 | # |
---|
28 | # Things that have, or can have, length prefixes, take an optional 'default_generate' |
---|
29 | # attribute. If set to yes, this will give them a default value of "present but empty". |
---|
30 | # |
---|
31 | # Note that if you have counted character data, you will get a listref of hashrefs. |
---|
32 | # For instance: |
---|
33 | # <data count="-1"> |
---|
34 | # <word name="foo" /> |
---|
35 | # <word name="bar" /> |
---|
36 | # </data> |
---|
37 | # Will give you: |
---|
38 | # [ |
---|
39 | # { foo => 1, bar => 2 }, |
---|
40 | # { foo => 1, bar => 4 }, |
---|
41 | # ] |
---|
42 | # |
---|
43 | # You can also have tlvchains and TLVs... |
---|
44 | # |
---|
45 | # If you attach a name to a TLV, as opposed to elements within that TLV, |
---|
46 | # presence of that name in the data hash will correspond with presence of |
---|
47 | # that TLV in the TLV chain, without regard to the value of said TLV. |
---|
48 | # |
---|
49 | # |
---|
50 | # family=0 is a global fallback SNAC family. That is: |
---|
51 | # <define family="0" subtype="1" /> |
---|
52 | # will get picked up on for all SNACs of subtype 1 where there is no define for |
---|
53 | # that specific family. |
---|
54 | |
---|
55 | <!ELEMENT oscar (define)+> |
---|
56 | |
---|
57 | <!ELEMENT define (ref|byte|word|dword|data|tlvchain|enum)+> |
---|
58 | <!ATTLIST define |
---|
59 | name ID #REQUIRED |
---|
60 | channel CDATA #IMPLIED |
---|
61 | family CDATA #IMPLIED |
---|
62 | subtype CDATA #IMPLIED |
---|
63 | flags1 CDATA #IMPLIED |
---|
64 | flags2 CDATA #IMPLIED |
---|
65 | > |
---|
66 | |
---|
67 | <!ELEMENT ref (EMPTY)> |
---|
68 | <!ATTLIST ref |
---|
69 | name IDREF #REQUIRED |
---|
70 | > |
---|
71 | |
---|
72 | <!ELEMENT byte (#PCDATA)> |
---|
73 | <!ATTLIST byte |
---|
74 | name CDATA #IMPLIED |
---|
75 | count CDATA #IMPLIED |
---|
76 | > |
---|
77 | <!ELEMENT word (#PCDATA)> |
---|
78 | <!ATTLIST word |
---|
79 | name CDATA #IMPLIED |
---|
80 | order (network|vax) #DEFAULT network |
---|
81 | count CDATA #IMPLIED |
---|
82 | > |
---|
83 | <!ELEMENT dword (#PCDATA)> |
---|
84 | <!ATTLIST dword |
---|
85 | name CDATA #IMPLIED |
---|
86 | order (network|vax) #DEFAULT network |
---|
87 | count CDATA #IMPLIED |
---|
88 | > |
---|
89 | <!ELEMENT data (ref|byte|word|dword|data|tlvchain|enum)+> |
---|
90 | <!ATTLIST data |
---|
91 | name CDATA #IMPLIED |
---|
92 | prefix_order (network|vax) #DEFAULT network |
---|
93 | length_prefix (byte|word|dword) #IMPLIED |
---|
94 | length CDATA #IMPLIED |
---|
95 | count CDATA #IMPLIED |
---|
96 | default_generate (yes|no) #DEFAULT no |
---|
97 | null_terminated (yes|no) #DEFAULT no |
---|
98 | pad CDATA #IMPLIED |
---|
99 | > |
---|
100 | <!ELEMENT enum (edef+)> |
---|
101 | <!ATTLIST enum |
---|
102 | type (byte|word|dword) #REQUIRED |
---|
103 | name CDATA #implied |
---|
104 | order (network|vax) #DEFAULT network |
---|
105 | count CDATA #implied |
---|
106 | > |
---|
107 | <!ELEMENT edef (EMPTY)> |
---|
108 | <!ATTLIST edef |
---|
109 | default (yes|no) #DEFAULT no |
---|
110 | name CDATA #REQUIRED |
---|
111 | value CDATA #REQUIRED |
---|
112 | > |
---|
113 | <!ELEMENT tlvchain (tlv*)> |
---|
114 | <!ATTLIST tlvchain |
---|
115 | subtyped (yes|no) #DEFAULT no <!-- A 'subtyped' TLV is type/subtype/length/value, where subtype and length are both bytes. It's used in extended status. --> |
---|
116 | count_prefix (byte|word|dword) #IMPLIED |
---|
117 | length_prefix (byte|word|dword) #IMPLIED |
---|
118 | prefix_order (network|vax) #DEFAULT network |
---|
119 | length CDATA #IMPLIED |
---|
120 | default_generate (yes|no) #DEFAULT no |
---|
121 | > |
---|
122 | |
---|
123 | <!ELEMENT tlv (ref|byte|word|dword|data|tlvchain|enum)+> |
---|
124 | <!ATTLIST tlv |
---|
125 | type CDATA #REQUIRED |
---|
126 | subtype CDATA #IMPLIED <!-- For subtyped TLVs --> |
---|
127 | |
---|
128 | default_generate (yes|no) #DEFAULT no |
---|
129 | <!-- |
---|
130 | If the TLV has a name, that key being present in the data will |
---|
131 | correspond to the existance of that TLV, without regard to its value |
---|
132 | --> |
---|
133 | name CDATA #IMPLIED |
---|
134 | <!-- |
---|
135 | If the TLV has a count, it will get listified. |
---|
136 | Behavior of TLVs which have a count but not a name is undefined. |
---|
137 | --> |
---|
138 | count CDATA #IMPLIED |
---|
139 | > |
---|