[7a1c90d] | 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 | > |
---|