source3/namedbresp.doc

   1 /*
   2    Unix SMB/Netbios documentation.
   3    Version 0.1
   4    Copyright (C) Luke Leighton  Andrew Tridgell  1996
   5
   6    This program is free software; you can redistribute it and/or modify
   7    it under the terms of the GNU General Public License as published by
   8    the Free Software Foundation; either version 2 of the License, or
   9    (at your option) any later version.
  10
  11    This program is distributed in the hope that it will be useful,
  12    but WITHOUT ANY WARRANTY; without even the implied warranty of
  13    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  14    GNU General Public License for more details.
  15
  16    You should have received a copy of the GNU General Public License
  17    along with this program; if not, write to the Free Software
  18    Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.
  19
  20    Document name: namedbresp.doc
  21
  22    Revision History:
  23
  24    0.0 - 02jul96 : lkcl@pires.co.uk
  25    created
  26
  27    0.1 - 22jul96 Andrew.Tridgell@anu.edu.au
  28    tridge's comments on first revision
  29 */
  30
  31 module namedbresp deals with the maintenance of the list of expected
  32 responses - creating, finding and removal.
  33
  34 module nameresp deals with the initial transmission, re-transmission
  35 and time-out of netbios response records.
  36
  37
  38 /*************************************************************************
  39   find_response_record()
  40   *************************************************************************/
  41
  42 this function is responsible for matching the unique response transaction
  43 id with an expected response record. as a side-effect of this search,
  44 it will find the subnet (or the WINS pseudo-subnet) that samba expected
  45 the response to come from.
  46
  47
  48 /*************************************************************************
  49   make_response_queue_record()
  50   *************************************************************************/
  51
  52 this function is responsible for creating a response record, which will
  53 be queued awaiting a response.
  54
  55 the number of retries is set to 3, and the retry period set to 1 second.
  56 if no response is received, then the packet is re-transmitted, which is
  57 why so much information is stored in the response record.
  58
  59 the number of expected responses queued is kept, so listen_for_packets()
  60 knows it must time-out after 1 second if one or more responses are
  61 expected.
  62
  63
  64 /*************************************************************************
  65   remove_response_record()
  66   *************************************************************************/
  67
  68 this function is responsible for removing a response record from the
  69 expected response queue. the number of expected responses is decreased.
  70
  71
  72 /*************************************************************************
  73   add_response_record()
  74   *************************************************************************/
  75
  76 this function is responsible for adding the response record created by
  77 make_response_queue_record() into the appropriate response record queue.
  78
  79
  80 -----------------
  81 NOTE FROM TRIDGE:
  82
  83 namedbresp.c is interesting because it implements a novel way of
  84 getting most of the advantages of a multi-threaded nmbd daemon without
  85 the portability problems.
  86
  87 The NBT specs (rfc1001/1002) talk about the 16 bit IDs in the packets
  88 as being used to ensure that packets are unique, and to stop packets
  89 from being confused. It suggests incrementing the ID by 1 each time.
  90
  91 Instead Luke uses these IDs to identify individual threads of control
  92 in nmbd. So when nmbd sends out a NBT packet as part of some complex
  93 processing, it adds to a linked list the information required to
  94 continue the processing when the reply comes in (or it times
  95 out). When a reply arrives this list can be searched to find the
  96 matching query and the next step in the processing can be carried out.
  97
  98 This is really good stuff, and allows for much more complex behaviour
  99 than was possible with the old nmbd.
 100 ----------------