source: perl/modules/AIM/lib/Net/OSCAR/XML/Protocol.dtd @ a1c2f06

barnowl_perlaim
Last change on this file since a1c2f06 was 7a1c90d, checked in by Geoffrey Thomas <geofft@mit.edu>, 16 years ago
Skeleton AIM module, and Net::OSCAR 1.925
  • Property mode set to 100644
File size: 4.5 KB
Line 
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>
Note: See TracBrowser for help on using the repository browser.