source3/namedbname.doc

   1 /*
   2    Unix SMB/Netbios documentation.
   3    Version 0.0
   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: namedbname.doc
  21
  22    Revision History:
  23
  24    0.0 - 02jul96 : lkcl@pires.co.uk
  25    created
  26 */
  27
  28 this module deals with the NetBIOS name database for samba. it deals
  29 directly with adding, removing, finding, loading and saving of names.
  30
  31 /*************************************************************************
  32   search_for_name()
  33   *************************************************************************/
  34
  35 this function is responsible for finding a name in the appropriate part
  36 of samba's NetBIOS name database. if the name cannot be found, then it
  37 should look the name up using DNS. later modifications will be to
  38 forward the request on to another WINS server, should samba not be able
  39 to find out about the requested name (this will be implemented through
  40 issuing a new type of samba 'state').
  41
  42 the name is first searched for in the NetBIOS cache. if it cannot be
  43 found, then it if the name looks like it's a server-type name (0x20
  44 0x0 or 0x1b) then DNS is used to look for the name.
  45
  46 if DNS fails, then a record of this failure is kept. if it succeeds, then
  47 a new NetBIOS entry is added.
  48
  49 the successfully found name is returned. on failure, NULL is returned.
  50
  51
  52 /*************************************************************************
  53   expire_names()
  54   *************************************************************************/
  55
  56 this function is responsible for removing old NetBIOS names from its
  57 database. no further action is required.
  58
  59 for over-zealous WINS systems, the use of query_refresh_names() is
  60 recommended. this function initiates polling of hosts that have
  61 registered with samba in its capacity as a WINS server. an alternative
  62 means to achieve the same end as query_refresh_names() is to
  63 reduce the time to live when the name is registered with samba,
  64 except that in this instance the responsibility for refreshing the
  65 name is with the owner of the name, not the server with which the name
  66 is registered.
  67
  68
  69 /*************************************************************************
  70   add_netbios_entry()
  71   *************************************************************************/
  72
  73 this function is responsible for adding or updating a NetBIOS name
  74 in the database. into the local interface records, the only names
  75 that will be added are those of domain master browsers and
  76 samba's own names. into the WINS records, all names are added.
  77
  78 the name to be added / updated will be looked up in the records.
  79 if it is found, then we will not overwrite the entry if the flag
  80 'newonly' is True, or if the name is being added as a non-SELF
  81 (non-samba) name and the records indicate that samba owns the
  82 name.
  83
  84 otherwise, the name is added or updated with the new details.
  85
  86
  87 /*************************************************************************
  88   remove_netbios_entry()
  89   *************************************************************************/
  90
  91 this function is responsible for removing a NetBIOS entry from
  92 the database. the name is searched for in the records using
  93 find_name_search(). if the ip is zero, then the ip is ignored.
  94
  95 the name is removed if the expected source (e.g SELF, REGISTER)
  96 matches that in the database.
  97
  98
  99 /*************************************************************************
 100   load_netbios_names()
 101   *************************************************************************/
 102
 103 this function is responsible for loading any NetBIOS names that samba,
 104 in its WINS capacity, has written out to disk. all the relevant details
 105 are recorded in this file, including the time-to-live. should the
 106 time left to live be small, the name is not added back in to samba's
 107 WINS database.
 108
 109
 110 /*************************************************************************
 111   dump_names()
 112   *************************************************************************/
 113
 114 this function is responsible for outputting NetBIOS names in two formats.
 115 firstly, as debugging information, and secondly, all names that have been
 116 registered with samba in its capacity as a WINS server are written to
 117 disk.
 118
 119 writing all WINS names allows two things. firstly, if samba's NetBIOS
 120 daemon dies or is terminated, on restarting the daemon most if not all
 121 of the registered WINS names will be preserved (which is a good reason
 122 why query_netbios_names() should be used).
 123
 124
 125 /*************************************************************************
 126   find_name_search()
 127   *************************************************************************/
 128
 129 this function is a wrapper around find_name(). find_name_search() can
 130 be told whether to search for the name in a local subnet structure or
 131 in the WINS database. on top of this, it can be told to search only
 132 for samba's SELF names.
 133
 134 if it finds the name in the WINS database, it will set the subnet_record
 135 and also return the name it finds.
 136
 137
 138 /*************************************************************************
 139   find_name()
 140   *************************************************************************/
 141
 142 this function is a low-level search function that searches a single
 143 interface's NetBIOS records for a name. if the ip to be found is
 144 zero then the ip address is ignored. this is to enable a name to
 145 be found without knowing its ip address, and also to find the exact
 146 name if a large number of group names are added with different ip
 147 addresses.
 148
 149
 150 /*************************************************************************
 151   remove_name()
 152   *************************************************************************/
 153
 154 this function is responsible for removing a specific NetBIOS entry
 155 from a subnet list's records. only if the pointer to the entry is
 156 in the list will the name be removed.
 157
 158
 159 /*************************************************************************
 160   add_name()
 161   *************************************************************************/
 162
 163 this function is responsible for adding a NetBIOS entry into a
 164 subnet list's records.
 165
 166
 167 /*************************************************************************
 168   ms_browser_name()
 169   *************************************************************************/
 170
 171 this function returns True if the NetBIOS name passed to it is
 172 ^1^2__MSBROWSE__^2^1
 173
 174
 175 /*************************************************************************
 176   name_equal()
 177   *************************************************************************/
 178
 179 this function returns True if the two NetBIOS names passed to it
 180 match in name, type and scope: the NetBIOS names are equal.
 181
 182