r954: Start working on typedef parsing.
[ira/wip.git] / source4 / build / pidl / NOTES.txt
1 midl types
2 ----------
3
4 pidl uses slightly different types to midl by default. The following
5 defines in your MS IDL may make things easier to use the same IDL on
6 both platforms.
7
8 #define unistr [string] wchar_t *
9 #define uint8 char
10 #define uint16 short
11 #define uint32 long
12 #define HYPER_T hyper
13
14
15 Let's look at the mutliple ways you can encode an array.
16
17 CONFORMANT ARRAYS
18 -----------------
19
20 A conformant array is one with that ends in [*] or []. The strange
21 things about conformant arrays are:
22
23  * they can only appear as the last element of a structure
24
25  * the array size appears before the structure itself on the wire. 
26
27 So, in this example:
28
29         typedef struct {
30                 long abc;
31                 long count;     
32                 long foo;
33                 [size_is(count)] long s[*];
34         } Struct1;
35
36 it appears like this:
37
38 [size_is] [abc] [count] [foo] [s...]
39
40 the first [size_is] field is the allocation size of the array, and
41 occurs before the array elements and even before the structure
42 alignment.
43
44 Note that size_is() can refer to a constant, but that doesn't change
45 the wire representation. It does not make the array a fixed array.
46
47 midl.exe would write the above array as the following C header:
48
49        typedef struct {
50                 long abc;
51                 long count;     
52                 long foo;
53                 long s[1];
54         } Struct1;
55
56 pidl takes a different approach, and writes it like this:
57
58        typedef struct {
59                 long abc;
60                 long count;     
61                 long foo;
62                 long *s;
63         } Struct1;
64
65
66
67 VARYING ARRAYS
68 --------------
69
70 A varying array looks like this:
71
72         typedef struct {
73                 long abc;
74                 long count;     
75                 long foo;
76                 [size_is(count)] long *s;
77         } Struct1;
78
79 This will look like this on the wire:
80
81 [abc] [count] [foo] [PTR_s]    [count] [s...]
82
83
84 FIXED ARRAYS
85 ------------
86
87 A fixed array looks like this:
88
89     typedef struct {
90             long s[10];
91     } Struct1;
92
93 The NDR representation looks just like 10 separate long
94 declarations. The array size is not encoded on the wire.
95
96 pidl also supports "inline" arrays, which are not part of the IDL/NDR
97 standard. These are declared like this:
98
99     typedef struct {
100             uint32 foo;
101             uint32 count;
102             uint32 bar;
103             long s[count];
104     } Struct1;
105
106 This appears like this:
107
108 [foo] [count] [bar] [s...]
109
110 Fixed arrays are an extension added to support some of the strange
111 embedded structures in security descriptors and spoolss. 
112
113 Supported MIDL-compatible properties (attributes is the MIDL term)
114 ------------------------------------
115 in
116 out
117 ref
118 public
119 length_is
120 switch_is
121 size_is
122 uuid
123 case
124 default
125 string
126 unique
127
128 PIDL Specific properties 
129 ---------------
130 noprint
131 value
132 relative
133 subcontext
134 flag
135
136 Unsupported MIDL properties
137 ---------------------------
138 aggregatable
139 appobject
140 async_uuid
141 bindable
142 call_as
143 coclass
144 control
145 cpp_quote
146 defaultbind
147 defaultcollelem
148 defaultvalue
149 defaultvtable
150 dispinterface
151 displaybind
152 dual
153 entry
154 first_is
155 helpcontext
156 helpfile
157 helpstringcontext
158 helpstringdll
159 helpstring
160 hidden
161 idl_module
162 idl_quote
163 id
164 iid_is
165 immediatebind
166 importlib
167 import
168 include
169 includelib
170 last_is
171 lcid
172 licensed
173 local
174 max_is
175 module
176 ms_union
177 no_injected_text
178 nonbrowsable
179 noncreatable
180 nonextensible
181 object
182 odl
183 oleautomation
184 optional
185 pointer_default
186 pragma
187 progid
188 propget
189 propputref
190 propput
191 ptr
192 range
193 readonly
194 requestedit
195 restricted
196 retval
197 source
198 switch_type
199 transmit_as
200 uidefault
201 usesgetlasterror
202 v1_enum
203 vararg
204 vi_progid
205 wire_marshal
206
207 [public] property
208 -----------------
209
210 The [public] property on a structure or union is a pidl extension that
211 forces the generated pull/push functions to be non-static. This allows
212 you to declare types that can be used between modules. If you don't
213 specify [public] then pull/push functions for other than top-level
214 functions are declared static.
215
216 [relative] property
217 -------------------
218
219 The [relative] property can be supplied on a pointer. When it is used
220 it declares the pointer as a spoolss style "relative" pointer, which
221 means it appears on the wire as an offset within the current
222 encapsulating structure. This is not part of normal IDL/NDR, but it is
223 a very useful extension as it avoids the manual encoding of many
224 complex structures.
225
226
227 [noprint] property
228 ------------------
229
230 The [noprint] property is a pidl extension that allows you to specify
231 that pidl should not generate a ndr_print_*() function for that
232 structure or union. This is used when you wish to define your own
233 print function that prints a structure in a nicer manner. A good
234 example is the use of [noprint] on dom_sid, which allows the
235 pretty-printing of SIDs.
236
237 [value] property
238 ----------------
239
240 The [value(expression)] property is a pidl extension that allows you
241 to specify the value of a field when it is put on the wire. This
242 allows fields that always have a well-known value to be automatically
243 filled in, thus making the API more programmer friendly. The
244 expression can be any C expression, although if you refer to variables
245 in the current structure you will need to dereference them with
246 r->. See samr_Name as a good example.
247
248
249 [nodiscriminant] property
250 -------------------------
251
252 The [nodiscriminant] property on a union means that the usual uint16
253 discriminent field at the start of the union on the wire is
254 omitted. This is not normally allowed in IDL/NDR, but is used for some
255 spoolss structures.
256
257
258 VALIDATOR
259 ---------
260
261 We need to write an IDL validator, so we know that we are writing
262 valid IDL. Right now the compiler sails on regardless in many cases
263 even if the IDL is invalid (for example, I don't check that conformant
264 arrays are always the last element in any structure). There are dozens
265 of rules that should be checked.