libreplace: fix coverity ID 517 - untangle close from open in test/os2_delete.c
[jelmer/samba4-debian.git] / prog_guide.txt
1
2
3 THIS IS INCOMPLETE! I'M ONLY COMMITING IT IN ORDER TO SOLICIT COMMENTS
4 FROM A FEW PEOPLE. DON'T TAKE THIS AS THE FINAL VERSION YET.
5
6
7 Samba4 Programming Guide
8 ------------------------
9
10 The internals of Samba4 are quite different from previous versions of
11 Samba, so even if you are an experienced Samba developer please take
12 the time to read through this document.
13
14 This document will explain both the broad structure of Samba4, and
15 some of the common coding elements such as memory management and
16 dealing with macros.
17
18
19 Coding Style
20 ------------
21
22 In past versions of Samba we have basically let each programmer choose
23 their own programming style. Unfortunately the result has often been
24 that code that other members of the team find difficult to read. For
25 Samba version 4 I would like to standardise on a common coding style
26 to make the whole tree more readable. For those of you who are
27 horrified at the idea of having to learn a new style, I can assure you
28 that it isn't as painful as you might think. I was forced to adopt a
29 new style when I started working on the Linux kernel, and after some
30 initial pain found it quite easy.
31
32 That said, I don't want to invent a new style, instead I would like to
33 adopt the style used by the Linux kernel. It is a widely used style
34 with plenty of support tools available. See Documentation/CodingStyle
35 in the Linux source tree. This is the style that I have used to write
36 all of the core infrastructure for Samba4 and I think that we should
37 continue with that style.
38
39 I also think that we should most definately *not* adopt an automatic
40 reformatting system in cvs (or whatever other source code system we
41 end up using in the future). Such automatic formatters are, in my
42 experience, incredibly error prone and don't understand the necessary
43 exceptions. I don't mind if people use automated tools to reformat
44 their own code before they commit it, but please do not run such
45 automated tools on large slabs of existing code without being willing
46 to spend a *lot* of time hand checking the results.
47
48 Finally, I think that for code that is parsing or formatting protocol
49 packets the code layout should strongly reflect the packet
50 format. That means ordring the code so that it parses in the same
51 order as the packet is stored on the wire (where possible) and using
52 white space to align packet offsets so that a reader can immediately
53 map any line of the code to the corresponding place in the packet.
54
55
56 Static and Global Data
57 ----------------------
58
59 The basic rule is "avoid static and global data like the plague". What
60 do I mean by static data? The way to tell if you have static data in a
61 file is to use the "size" utility in Linux. For example if we run::
62
63   size libcli/raw/*.o
64
65 in Samba4 then you get the following::
66
67    text    data     bss     dec     hex filename
68    2015       0       0    2015     7df libcli/raw/clikrb5.o
69     202       0       0     202      ca libcli/raw/clioplock.o
70      35       0       0      35      23 libcli/raw/clirewrite.o
71    3891       0       0    3891     f33 libcli/raw/clisession.o
72     869       0       0     869     365 libcli/raw/clisocket.o
73    4962       0       0    4962    1362 libcli/raw/clispnego.o
74    1223       0       0    1223     4c7 libcli/raw/clitransport.o
75    2294       0       0    2294     8f6 libcli/raw/clitree.o
76    1081       0       0    1081     439 libcli/raw/raweas.o
77    6765       0       0    6765    1a6d libcli/raw/rawfile.o
78    6824       0       0    6824    1aa8 libcli/raw/rawfileinfo.o
79    2944       0       0    2944     b80 libcli/raw/rawfsinfo.o
80     541       0       0     541     21d libcli/raw/rawioctl.o
81    1728       0       0    1728     6c0 libcli/raw/rawnegotiate.o
82     723       0       0     723     2d3 libcli/raw/rawnotify.o
83    3779       0       0    3779     ec3 libcli/raw/rawreadwrite.o
84    6597       0       0    6597    19c5 libcli/raw/rawrequest.o
85    5580       0       0    5580    15cc libcli/raw/rawsearch.o
86    3034       0       0    3034     bda libcli/raw/rawsetfileinfo.o
87    5187       0       0    5187    1443 libcli/raw/rawtrans.o
88    2033       0       0    2033     7f1 libcli/raw/smb_signing.o
89
90 notice that the "data" and "bss" columns are all zero? That is
91 good. If there are any non-zero values in data or bss then that
92 indicates static data and is bad (as a rule of thumb).
93
94 Lets compare that result to the equivalent in Samba3::
95
96    text    data     bss     dec     hex filename
97    3978       0       0    3978     f8a libsmb/asn1.o
98   18963       0     288   19251    4b33 libsmb/cliconnect.o
99    2815       0    1024    3839     eff libsmb/clidgram.o
100    4038       0       0    4038     fc6 libsmb/clientgen.o
101    3337     664     256    4257    10a1 libsmb/clierror.o
102   10043       0       0   10043    273b libsmb/clifile.o
103     332       0       0     332     14c libsmb/clifsinfo.o
104     166       0       0     166      a6 libsmb/clikrb5.o
105    5212       0       0    5212    145c libsmb/clilist.o
106    1367       0       0    1367     557 libsmb/climessage.o
107     259       0       0     259     103 libsmb/clioplock.o
108    1584       0       0    1584     630 libsmb/cliprint.o
109    7565       0     256    7821    1e8d libsmb/cliquota.o
110    7694       0       0    7694    1e0e libsmb/clirap.o
111   27440       0       0   27440    6b30 libsmb/clirap2.o
112    2905       0       0    2905     b59 libsmb/clireadwrite.o
113    1698       0       0    1698     6a2 libsmb/clisecdesc.o
114    5517       0       0    5517    158d libsmb/clispnego.o
115     485       0       0     485     1e5 libsmb/clistr.o
116    8449       0       0    8449    2101 libsmb/clitrans.o
117    2053       0       4    2057     809 libsmb/conncache.o
118    3041       0     256    3297     ce1 libsmb/credentials.o
119    1261       0    1024    2285     8ed libsmb/doserr.o
120   14560       0       0   14560    38e0 libsmb/errormap.o
121    3645       0       0    3645     e3d libsmb/namecache.o
122   16815       0       8   16823    41b7 libsmb/namequery.o
123    1626       0       0    1626     65a libsmb/namequery_dc.o
124   14301       0    1076   15377    3c11 libsmb/nmblib.o
125   24516       0    2048   26564    67c4 libsmb/nterr.o
126    8661       0       8    8669    21dd libsmb/ntlmssp.o
127    3188       0       0    3188     c74 libsmb/ntlmssp_parse.o
128    4945       0       0    4945    1351 libsmb/ntlmssp_sign.o
129    1303       0       0    1303     517 libsmb/passchange.o
130    1221       0       0    1221     4c5 libsmb/pwd_cache.o
131    2475       0       4    2479     9af libsmb/samlogon_cache.o
132   10768      32       0   10800    2a30 libsmb/smb_signing.o
133    4524       0      16    4540    11bc libsmb/smbdes.o
134    5708       0       0    5708    164c libsmb/smbencrypt.o
135    7049       0    3072   10121    2789 libsmb/smberr.o
136    2995       0       0    2995     bb3 libsmb/spnego.o
137    3186       0       0    3186     c72 libsmb/trustdom_cache.o
138    1742       0       0    1742     6ce libsmb/trusts_util.o
139     918       0      28     946     3b2 libsmb/unexpected.o
140
141 notice all of the non-zero data and bss elements? Every bit of that
142 data is a bug waiting to happen.
143
144 Static data is evil as it has the following consequences:
145 - it makes code much less likely to be thread-safe
146 - it makes code much less likely to be recursion-safe
147 - it leads to subtle side effects when the same code is called from
148   multiple places
149 - doesn't play well with shared libraries or plugins
150
151 Static data is particularly evil in library code (such as our internal
152 smb and rpc libraries). If you can get rid of all static data in
153 libraries then you can make some fairly strong guarantees about the
154 behaviour of functions in that library, which really helps.
155
156 Of course, it is possible to write code that uses static data and is
157 safe, it's just much harder to do that than just avoid static data in
158 the first place. We have been tripped up countless times by subtle
159 bugs in Samba due to the use of static data, so I think it is time to
160 start avoiding it in new code. Much of the core infrastructure of
161 Samba4 was specifically written to avoid static data, so I'm going to
162 be really annoyed if everyone starts adding lots of static data back
163 in.
164
165 So, how do we avoid static data? The basic method is to use context
166 pointers. When reading the Samba4 code you will notice that just about
167 every function takes a pointer to a context structure as its first
168 argument. Any data that the function needs that isn't an explicit
169 argument to the function can be found by traversing that context. 
170
171 Note that this includes all of the little caches that we have lying
172 all over the code in Samba3. I'm referring to the ones that generally
173 have a "static int initialised" and then some static string or integer
174 that remembers the last return value of the function. Get rid of them!
175 If you are *REALLY* absolutely completely certain that your personal
176 favourite mini-cache is needed then you should do it properly by
177 putting it into the appropriate context rather than doing it the lazy
178 way by putting it inside the target function. I would suggest however
179 that the vast majority of those little caches are useless - don't
180 stick it in unless you have really firm benchmarking results that show
181 that it is needed and helps by a significant amount.
182
183 Note that Samba4 is not yet completely clean of static data like
184 this. I've gotten the smbd/ directory down to 24 bytes of static data,
185 and libcli/raw/ down to zero. I've also gotten the ntvfs layer and all
186 backends down to just 8 bytes in ntvfs_base.c. The rest still needs
187 some more work.
188
189 Also note that truly constant data is OK, and will not in fact show up
190 in the data and bss columns in "size" anyway (it will be included in
191 "text"). So you can have constant tables of protocol data.
192
193
194 How to use talloc
195 -----------------
196
197 Please see the separate document, source/lib/talloc/talloc_guide.txt
198 You _must_ read this if you want to program in Samba4.
199
200
201 Interface Structures
202 --------------------
203
204 One of the biggest changes in Samba4 is the universal use of interface
205 structures. Go take a look through include/smb_interfaces.h now to get
206 an idea of what I am talking about.
207
208 In Samba3 many of the core wire structures in the SMB protocol were
209 never explicitly defined in Samba. Instead, our parse and generation
210 functions just worked directly with wire buffers. The biggest problem
211 with this is that is tied our parse code with our "business logic"
212 much too closely, which meant the code got extremely confusing to
213 read.
214
215 In Samba4 we have explicitly defined interface structures for
216 everything in the protocol. When we receive a buffer we always parse
217 it completely into one of these structures, then we pass a pointer to
218 that structure to a backend handler. What we must *not* do is make any
219 decisions about the data inside the parse functions. That is critical
220 as different backends will need different portions of the data. This
221 leads to a golden rule for Samba4:
222
223   "don't design interfaces that lose information"
224
225 In Samba3 our backends often received "condensed" versions of the
226 information sent from clients, but this inevitably meant that some
227 backends could not get at the data they needed to do what they wanted,
228 so from now on we should expose the backends to all of the available
229 information and let them choose which bits they want.
230
231 Ok, so now some of you will be thinking "this sounds just like our
232 msrpc code from Samba3", and while to some extent this is true there
233 are extremely important differences in the approach that are worth
234 pointing out.
235
236 In the Samba3 msrpc code we used explicit parse structures for all
237 msrpc functions. The problem is that we didn't just put all of the
238 real variables in these structures, we also put in all the artifacts
239 as well. A good example is the security descriptor strucrure that
240 looks like this in Samba3::
241
242         typedef struct security_descriptor_info
243         {
244                 uint16 revision; 
245                 uint16 type;    
246
247                 uint32 off_owner_sid;
248                 uint32 off_grp_sid;
249                 uint32 off_sacl;
250                 uint32 off_dacl;
251
252                 SEC_ACL *dacl;
253                 SEC_ACL *sacl;
254                 DOM_SID *owner_sid; 
255                 DOM_SID *grp_sid;
256         } SEC_DESC;
257
258 The problem with this structure is all the off_* variables. Those are
259 not part of the interface, and do not appear in any real descriptions
260 of Microsoft security descriptors. They are parsing artifacts
261 generated by the IDL compiler that Microsoft use. That doesn't mean
262 they aren't needed on the wire - indeed they are as they tell the
263 parser where to find the following four variables, but they should
264 *NOT* be in the interface structure.
265
266 In Samba3 there were unwritten rules about which variables in a
267 structure a high level caller has to fill in and which ones are filled
268 in by the marshalling code. In Samba4 those rules are gone, because
269 the redundent artifact variables are gone. The high level caller just
270 sets up the real variables and the marshalling code worries about
271 generating the right offsets.
272
273 The same rule applies to strings. In many places in the SMB and MSRPC
274 protocols complex strings are used on the wire, with complex rules
275 about padding, format, alighment, termination etc. None of that
276 information is useful to a high level calling routine or to a backend
277 - its all just so much wire fluff. So, in Samba4 these strings are
278 just "char *" and are always in our internal multi-byte format (which
279 is usually UTF8). It is up to the parse functions to worry about
280 translating the format and getting the padding right.
281
282 The one exception to this is the use of the WIRE_STRING type, but that
283 has a very good justification in terms of regression testing. Go and
284 read the comment in smb_interfaces.h about that now.
285
286 So, here is another rule to code by. When writing an interface
287 structure think carefully about what variables in the structure can be
288 left out as they are redundent. If some length is effectively defined
289 twice on the wire then only put it once in the packet. If a length can
290 be inferred from a null termination then do that and leave the length
291 out of the structure completely. Don't put redundent stuff in
292 structures!
293
294
295 Async Design
296 ------------
297
298 Samba4 has an asynchronous design. That affects *lots* of the code,
299 and the implications of the asynchronous design needs to be considered
300 just about everywhere.
301
302 The first aspect of the async design to look at is the SMB client
303 library. Lets take a look at the following three functions in
304 libcli/raw/rawfile.c::
305
306         struct cli_request *smb_raw_seek_send(struct cli_tree *tree, struct smb_seek *parms);
307         NTSTATUS smb_raw_seek_recv(struct cli_request *req, struct smb_seek *parms);
308         NTSTATUS smb_raw_seek(struct cli_tree *tree, struct smb_seek *parms);
309
310 Go and read them now then come back.
311
312 Ok, first notice there there are 3 separate functions, whereas the
313 equivalent code in Samba3 had just one. Also note that the 3rd
314 function is extremely simple - its just a wrapper around calling the
315 first two in order.
316
317 The three separate functions are needed because we need to be able to
318 generate SMB calls asynchronously. The first call, which for smb calls
319 is always called smb_raw_XXXX_send(), constructs and sends a SMB
320 request and returns a "struct cli_request" which acts as a handle for
321 the request. The caller is then free to do lots of other calls if it
322 wants to, then when it is ready it can call the smb_raw_XXX_recv()
323 function to receive the reply. 
324
325 If all you want is a synchronous call then call the 3rd interface, the
326 one called smb_raw_XXXX(). That just calls the first two in order, and
327 blocks waiting for the reply. 
328
329 But what if you want to be called when the reply comes in? Yes, thats
330 possible. You can do things like this::
331
332     struct cli_request *req;
333
334     req = smb_raw_XXX_send(tree, params);
335
336     req->async.fn = my_callback;
337     req->async.private = my_private_data;
338
339 then in your callback function you can call the smb_raw_XXXX_recv()
340 function to receive the reply. Your callback will receive the "req"
341 pointer, which you can use to retrieve your private data from
342 req->async.private.
343
344 Then all you need to do is ensure that the main loop in the client
345 library gets called. You can either do that by polling the connection
346 using cli_transport_pending() and cli_request_receive_next() or you
347 can use transport->idle.func to setup an idle function handler to call
348 back to your main code. Either way, you can build a fully async
349 application.
350
351 In order to support all of this we have to make sure that when we
352 write a piece of library code (SMB, MSRPC etc) that we build the
353 separate _send() and _recv() functions. It really is worth the effort.
354
355 Now about async in smbd, a much more complex topic.
356
357 The SMB protocol is inherently async. Some functions (such as change
358 notify) often don't return for hours, while hundreds of other
359 functions pass through the socket. Take a look at the RAW-MUX test in
360 the Samba4 smbtorture to see some really extreme examples of the sort
361 of async operations that Windows supports. I particularly like the
362 open/open/close sequence where the 2nd open (which conflicts with the
363 first) succeeds because the subsequent close is answered out of order.
364
365 In Samba3 we handled this stuff very badly. We had awful "pending
366 request" queues that allocated full 128k packet buffers, and even with
367 all that crap we got the semantics wrong. In Samba4 I intend to make
368 sure we get this stuff right.
369
370 So, how do we do this? We now have an async interface between smbd and
371 the NTVFS backends. Whenever smbd calls into a backend the backend has
372 an option of answer the request in a synchronous fashion if it wants
373 to just like in Samba3, but it also has the option of answering the
374 request asynchronously. The only backend that currently does this is
375 the CIFS backend, but I hope the other backends will soon do this to.
376
377 To make this work you need to do things like this in the backend::
378
379   req->control_flags |= REQ_CONTROL_ASYNC;
380
381 that tells smbd that the backend has elected to reply later rather
382 than replying immediately. The backend must *only* do this if
383 req->async.send_fn is not NULL. If send_fn is NULL then it means that
384 the smbd front end cannot handle this function being replied to in an
385 async fashion.
386
387 If the backend does this then it is up to the backend to call
388 req->async.send_fn() when it is ready to reply. It the meantime smbd
389 puts the call on hold and goes back to answering other requests on the
390 socket.
391
392 Inside smbd you will find that there is code to support this. The most
393 obvious change is that smbd splits each SMB reply function into two
394 parts - just like the client library has a _send() and _recv()
395 function, so smbd has a _send() function and the parse function for
396 each SMB.
397
398 As an example go and have a look at reply_getatr_send() and
399 reply_getatr() in smb_server/reply.c. Read them? Good.
400
401 Notice that reply_getatr() sets up the req->async structure to contain
402 the send function. Thats how the backend gets to do an async reply, it
403 calls this function when it is ready. Also notice that reply_getatr()
404 only does the parsing of the request, and does not do the reply
405 generation. That is done by the _send() function. 
406
407 The only missing piece in the Samba4 right now that prevents it being
408 fully async is that it currently does the low level socket calls (read
409 and write on sockets) in a blocking fashion. It does use select() to
410 make it somewhat async, but if a client were to send a partial packet
411 then delay before sending the rest then smbd would be stuck waiting
412 for the second half of the packet. 
413
414 To fix this I plan on making the socket calls async as well, which
415 luckily will not involve any API changes in the core of smbd or the
416 library. It just involves a little bit of extra code in clitransport.c
417 and smbd/request.c. As a side effect I hope that this will also reduce
418 the average number of system calls required to answer a request, so we
419 may see a performance improvement.
420
421
422 NTVFS
423 -----
424
425 One of the most noticeable changes in Samba4 is the introduction of
426 the NTVFS layer. This provided the initial motivation for the design
427 of Samba4 and in many ways lies at the heart of the design.
428
429 In Samba3 the main file serving process (smbd) combined the handling
430 of the SMB protocol with the mapping to POSIX semantics in the same
431 code. If you look in smbd/reply.c in Samba3 you see numerous places
432 where POSIX assumptions are mixed tightly with SMB parsing code. We
433 did have a VFS layer in Samba3, but it was a POSIX-like VFS layer, so
434 no matter how you wrote a plugin you could not bypass the POSIX
435 mapping decisions that had already been made before the VFS layer was
436 called.
437
438 In Samba4 things are quite different. All SMB parsing is performed in
439 the smbd front end, then fully parsed requests are passed to the NTVFS
440 backend. That backend makes any semantic mapping decisions and fills
441 in the 'out' portion of the request. The front end is then responsible
442 for putting those results into wire format and sending them to the
443 client.
444
445 Lets have a look at one of those request structures. Go and read the
446 definition of "union smb_write" and "enum write_level" in
447 include/smb_interfaces.h. (no, don't just skip reading it, really go
448 and read it. Yes, that means you!).
449
450 Notice the union? That's how Samba4 allows a single NTVFS backend
451 interface to handle the several different ways of doing a write
452 operation in the SMB protocol. Now lets look at one section of that
453 union::
454
455         /* SMBwriteX interface */
456         struct {
457                 enum write_level level;
458
459                 struct {
460                         uint16 fnum;
461                         SMB_BIG_UINT offset;
462                         uint16 wmode;
463                         uint16 remaining;
464                         uint32 count;
465                         const char *data;
466                 } in;
467                 struct {
468                         uint32 nwritten;
469                         uint16 remaining;
470                 } out;
471         } writex;
472
473 see the "in" and "out" sections? The "in" section is for parameters
474 that the SMB client sends on the wire as part of the request. The smbd
475 front end parse code parses the wire request and fills in all those
476 parameters. It then calls the NTVFS interface which looks like this::
477
478   NTSTATUS (*write)(struct request_context *req, union smb_write *io);
479
480 and the NTVFS backend does the write request. The backend then fills
481 in the "out" section of the writex structure and gives the union back
482 to the front end (either by returning, or if done in an async fashion
483 then by calling the async send function. See the async discussion
484 elsewhere in this document).
485
486 The NTVFS backend knows which particular function is being requested
487 by looking at io->generic.level. Notice that this enum is also
488 repeated inside each of the sub-structures in the union, so the
489 backend could just as easily look at io->writex.level and would get
490 the same variable.
491
492 Notice also that some levels (such as splwrite) don't have an "out"
493 section. This happens because there is no return value apart from a
494 status code from those SMB calls. 
495
496 So what about status codes? The status code is returned directly by
497 the backend NTVFS interface when the call is performed
498 synchronously. When performed asynchronously then the status code is
499 put into req->async.status before the req->async.send_fn() callback is
500 called.
501
502 Currently the most complete NTVFS backend is the CIFS backend. I don't
503 expect this backend will be used much in production, but it does
504 provide the ideal test case for our NTVFS design. As it offers the
505 full capabilities that are possible with a CIFS server we can be sure
506 that we don't have any gaping holes in our APIs, and that the front
507 end code is flexible enough to handle any advances in the NT style
508 feature sets of Unix filesystems that make come along.
509
510
511 Process Models
512 --------------
513
514 In Samba3 we supported just one process model. It just so happens that
515 the process model that Samba3 supported is the "right" one for most
516 users, but there are situations where this model wasn't ideal.
517
518 In Samba4 you can choose the smbd process model on the smbd command
519 line. 
520
521
522 DCERPC binding strings
523 ----------------------
524
525 When connecting to a dcerpc service you need to specify a binding
526 string. 
527
528 The format is:
529
530   TRANSPORT:host[flags]
531
532 where TRANSPORT is either ncacn_np for SMB or ncacn_ip_tcp for RPC/TCP
533
534 "host" is an IP or hostname or netbios name. If the binding string 
535 identifies the server side of an endpoint, "host" may be an empty 
536 string.
537
538 "flags" can include a SMB pipe name if using the ncacn_np transport or
539 a TCP port number if using the ncacn_ip_tcp transport, otherwise they
540 will be auto-determined.
541
542 other recognised flags are:
543
544   sign      : enable ntlmssp signing
545   seal      : enable ntlmssp sealing
546   spnego    : use SPNEGO instead of NTLMSSP authentication
547   krb5      : use KRB5 instead of NTLMSSP authentication
548   connect   : enable rpc connect level auth (auth, but no sign or seal)
549   validate  : enable the NDR validator
550   print     : enable debugging of the packets
551   bigendian : use bigendian RPC
552   padcheck  : check reply data for non-zero pad bytes
553
554
555 Here are some examples:
556
557    ncacn_np:myserver
558    ncacn_np:myserver[samr]
559    ncacn_np:myserver[\pipe\samr]
560    ncacn_np:myserver[/pipe/samr]
561    ncacn_np:myserver[samr,sign,print]
562    ncacn_np:myserver[sign,spnego]
563    ncacn_np:myserver[\pipe\samr,sign,seal,bigendian]
564    ncacn_np:myserver[/pipe/samr,seal,validate]
565    ncacn_np:
566    ncacn_np:[/pipe/samr]
567    ncacn_ip_tcp:myserver
568    ncacn_ip_tcp:myserver[1024]
569    ncacn_ip_tcp:myserver[sign,seal]
570    ncacn_ip_tcp:myserver[spnego,seal]
571
572
573 IDEA: Maybe extend UNC names like this?
574
575  smbclient //server/share
576  smbclient //server/share[sign,seal,spnego]
577
578 DCERPC Handles
579 --------------
580 The various handles that are used in the RPC servers should be created and 
581 fetch using the dcesrv_handle_* functions.
582
583 Use dcesrv_handle_new(struct dcesrv_connection *, uint8 handle_type) to obtain 
584 a new handle of the specified type. Handle types are unique within each 
585 pipe.
586
587 The handle can later be fetched again using
588 struct dcesrv_handle *dcesrv_handle_fetch(struct dcesrv_connection *dce_conn, struct policy_handle *p, uint8 handle_type)
589 and destroyed by dcesrv_handle_destroy(struct dcesrv_handle *).
590
591 User data should be stored in the 'data' member of the dcesrv_handle struct.
592
593
594 MSRPC
595 -----
596
597
598
599  - ntvfs
600  - testing
601  - command line handling
602  - libcli structure
603  - posix reliance
604  - uid/gid handling
605  - process models
606  - static data
607  - msrpc
608
609
610 don't zero structures! avoid ZERO_STRUCT() and talloc_zero()
611
612
613 GMT vs TZ in printout of QFILEINFO timezones
614
615 put in full UNC path in tconx
616
617 test timezone handling by using a server in different zone from client
618
619 do {} while (0) system
620
621 NT_STATUS_IS_OK() is NOT the opposite of NT_STATUS_IS_ERR()
622
623 need to implement secondary parts of trans2 and nttrans in server and
624 client
625
626 document access_mask in openx reply
627
628 check all capabilities and flag1, flag2 fields (eg. EAs)
629
630 large files -> pass thru levels
631
632 setpathinfo is very fussy about null termination of the file name
633
634 the overwrite flag doesn't seem to work on setpathinfo RENAME_INFORMATION
635
636 END_OF_FILE_INFORMATION and ALLOCATION_INFORMATION don't seem to work
637 via setpathinfo
638
639 on w2k3 setpathinfo DISPOSITION_INFORMATION fails, but does have an
640 effect. It leaves the file with SHARING_VIOLATION.
641
642 on w2k3 trans2 setpathinfo with any invalid low numbered level causes
643 the file to get into a state where DELETE_PENDING is reported, and the
644 file cannot be deleted until you reboot
645
646 trans2 qpathinfo doesn't see the delete_pending flag correctly, but
647 qfileinfo does!
648
649 get rid of pstring, fstring, strtok
650
651 add programming documentation note about lp_set_cmdline()
652
653 need to add a wct checking function in all client parsing code,
654 similar to REQ_CHECK_WCT()
655
656 need to make sure that NTTIME is a round number of seconds when
657 converted from time_t
658
659 not using a zero next offset in SMB_FILE_STREAM_INFORMATION for last
660 entry causes explorer exception under win2000
661
662
663 if the server sets the session key the same for a second SMB socket as
664 an initial socket then the client will not re-authenticate, it will go
665 straight to a tconx, skipping session setup and will use all the
666 existing parameters! This allows two sockets with the same keys!?
667
668
669 removed blocking lock code, we now queue the whole request the same as
670 we queue any other pending request. This allows for things like a
671 close() while a pending blocking lock is being processed to operate
672 sanely.
673
674 disabled change notify code
675
676 disabled oplock code
677
678
679
680 MILESTONES
681 ==========
682
683
684 client library and test code
685 ----------------------------
686
687   convert client library to new structure
688   get smbtorture working
689   get smbclient working
690   expand client library for all requests
691   write per-request test suite
692   gentest randomised test suite
693   separate client code as a library for non-Samba use
694
695 server code
696 -----------
697   add remaining core SMB requests
698   add IPC layer
699   add nttrans layer
700   add rpc layer
701   fix auth models (share, server, rpc)
702   get net command working
703   connect CIFS backend to server level auth
704   get nmbd working
705   get winbindd working
706   reconnect printing code
707   restore removed smbd options
708   add smb.conf macro substitution code
709   add async backend notification 
710   add generic timer event mechanism
711
712 clustering code
713 ---------------
714
715   write CIFS backend
716   new server models (break 1-1)
717   test clustered models
718   add fulcrum statistics gathering
719
720 docs
721 ----
722
723   conference paper
724   developer docs
725
726 svn instructions
727
728 Ideas
729 -----
730
731  - store all config in config.ldb
732
733  - load from smb.conf if modtime changes
734
735  - dump full system config with ldbsearch
736
737  - will need the ability to form a ldif difference file
738
739  - advanced web admin via a web ldb editor
740
741  - normal web admin via web forms -> ldif
742
743  - config.ldb will replace smb.conf, secrets.tdb, shares.tdb etc
744
745  - subsystems in smbd will load config parameters for a share
746    using ldbsearch at tconx time
747
748  - need a loadparm equivalent module that provides parameter defaults
749
750  - start smbd like this:  "smbd -C tdb://etc/samba/config.ldb" or
751    "smbd -C ldapi://var/run/ldapi"
752
753  - write a tool that generates a template ldap schema from an existing
754    ldb+tdb file
755
756  - no need to HUP smbd to reload config
757
758  - how to handle configuration comments? same problem as SWAT
759
760
761 BUGS:
762   add a test case for last_entry_offset in trans2 find interfaces
763   conn refused
764   connect -> errno
765   no 137 resolution not possible
766   should not fallback to anon when pass supplied
767   should check pass-thu cap bit, and skip lots of tests
768   possibly allow the test suite to say "allow oversized replies" for
769      trans2 and other calls
770   handle servers that don't have the setattre call in torture
771   add max file coponent length test and max path len test
772   check for alloc failure in all core reply.c and trans2.c code where
773     allocation size depends on client parameter
774
775 case-insenstive idea:
776   all filenames on disk lowercase
777   real case in extended attribute
778   keep cache of what dirs are all lowercase
779   when searching for name, don't search if dir is definately all lowercase
780   when creating file, use dnotify to tell if someone else creates at
781   same time
782
783 solve del *.* idea:
784   make mangle cache dynamic size
785   fill during a dir scan
786   setup a timer
787   destroy cache after 30 sec
788   destroy if a 2nd dir scan happens on same dir
789