tidied up: code shuffling and documentation.

created namedb*.c nameservresp.c nameservreply.c and namepacket.c
added modules to Makefile, downloading dan's current version first :-)
shuffled docs to match source
created more docs

fixed bug in announce_backup() discovered when going nameannounce.doc:
backup list requests to the master browser should be used when samba is
not a master browser; backup list requests to the primary domain
controller should be used when samba is not a primary domain controller.

fixed bug in sync_server: it would never send MasterAnnounce packets.

removed the code that ignored special browser names: these should only
be ignored (except 0x1b names) when broadcasted name queries are sent,
not when directed registration or directed queries are sent samba as a
WINS server. (note: exactly what's going on is still uncertain).

renamed NAME_QUERY_MST_SRV_CHK  to NAME_QUERY_PDC_SRV_CHK  (more accurate).
renamed NAME_STATUS_MST_SRV_CHK to NAME_STATUS_PDC_SRV_CHK (more accurate).

added secured WINS name registration: a new 'state' NAME_REGISTER_CHALLENGE;
functions send_name_response(), response_name_query_register(); added
sending of WAIT ACKNOWLEDGEMENT packet; added a reply_to_ip field to
the response record structure so that after the name query challenge,
you know who to inform of the outcome of that challenge.

note: these are all currently untested modifications (yikes!)

lkcl
(This used to be commit b50ff657ddc29b81b4aa02a597e5affab197e4f2)

1 files changed, 155 insertions, 0 deletions

diff --git a/source3/namedbname.doc b/source3/namedbname.doc
new file mode 100644
index 0000000000..3419fe1818
--- /dev/null
+++ b/source3/namedbname.doc
@@ -0,0 +1,155 @@
+this module deals with the NetBIOS name database for samba. it deals
+directly with adding, removing, finding, loading and saving of names.
+
+/*************************************************************************
+  search_for_name()
+  *************************************************************************/
+
+this function is responsible for finding a name in the appropriate part
+of samba's NetBIOS name database. if the name cannot be found, then it
+should look the name up using DNS. later modifications will be to
+forward the request on to another WINS server, should samba not be able
+to find out about the requested name (this will be implemented through
+issuing a new type of samba 'state').
+
+the name is first searched for in the NetBIOS cache. if it cannot be
+found, then it if the name looks like it's a server-type name (0x20
+0x0 or 0x1b) then DNS is used to look for the name.
+
+if DNS fails, then a record of this failure is kept. if it succeeds, then
+a new NetBIOS entry is added.
+
+the successfully found name is returned. on failure, NULL is returned.
+
+
+/*************************************************************************
+  expire_names()
+  *************************************************************************/
+
+this function is responsible for removing old NetBIOS names from its
+database. no further action is required.
+
+for over-zealous WINS systems, the use of query_refresh_names() is
+recommended. this function initiates polling of hosts that have
+registered with samba in its capacity as a WINS server. an alternative
+means to achieve the same end as query_refresh_names() is to
+reduce the time to live when the name is registered with samba,
+except that in this instance the responsibility for refreshing the
+name is with the owner of the name, not the server with which the name
+is registered. 
+
+
+/*************************************************************************
+  add_netbios_entry()
+  *************************************************************************/
+
+this function is responsible for adding or updating a NetBIOS name
+in the database. into the local interface records, the only names
+that will be added are those of primary domain controllers and
+samba's own names. into the WINS records, all names are added.
+
+the name to be added / updated will be looked up in the records.
+if it is found, then we will not overwrite the entry if the flag
+'newonly' is True, or if the name is being added as a non-SELF
+(non-samba) name and the records indicate that samba owns the
+name.
+
+otherwise, the name is added or updated with the new details.
+
+
+/*************************************************************************
+  remove_netbios_entry()
+  *************************************************************************/
+
+this function is responsible for removing a NetBIOS entry from
+the database. the name is searched for in the records using
+find_name_search(). if the ip is zero, then the ip is ignored.
+
+the name is removed if the expected source (e.g SELF, REGISTER)
+matches that in the database.
+
+
+/*************************************************************************
+  load_netbios_names()
+  *************************************************************************/
+
+this function is responsible for loading any NetBIOS names that samba,
+in its WINS capacity, has written out to disk. all the relevant details
+are recorded in this file, including the time-to-live. should the 
+time left to live be small, the name is not added back in to samba's
+WINS database.
+
+ 
+/*************************************************************************
+  dump_names()
+  *************************************************************************/
+
+this function is responsible for outputting NetBIOS names in two formats.
+firstly, as debugging information, and secondly, all names that have been
+registered with samba in its capacity as a WINS server are written to
+disk.
+
+writing all WINS names allows two things. firstly, if samba's NetBIOS
+daemon dies or is terminated, on restarting the daemon most if not all
+of the registered WINS names will be preserved (which is a good reason
+why query_netbios_names() should be used).
+ 
+
+/*************************************************************************
+  find_name_search()
+  *************************************************************************/
+
+this function is a wrapper around find_name(). find_name_search() can
+be told whether to search for the name in a local subnet structure or
+in the WINS database. on top of this, it can be told to search only
+for samba's SELF names.
+
+if it finds the name in the WINS database, it will set the subnet_record
+and also return the name it finds.
+ 
+
+/*************************************************************************
+  find_name()
+  *************************************************************************/
+
+this function is a low-level search function that searches a single
+interface's NetBIOS records for a name. if the ip to be found is
+zero then the ip address is ignored. this is to enable a name to
+be found without knowing its ip address, and also to find the exact
+name if a large number of group names are added with different ip
+addresses.
+
+
+/*************************************************************************
+  remove_name()
+  *************************************************************************/
+
+this function is responsible for removing a specific NetBIOS entry
+from a subnet list's records. only if the pointer to the entry is
+in the list will the name be removed.
+
+
+/*************************************************************************
+  add_name()
+  *************************************************************************/
+
+this function is responsible for adding a NetBIOS entry into a
+subnet list's records.
+
+
+/*************************************************************************
+  ms_browser_name()
+  *************************************************************************/
+
+this function returns True if the NetBIOS name passed to it is
+^1^2__MSBROWSE__^2^1
+
+
+/*************************************************************************
+  name_equal()
+  *************************************************************************/
+
+this function returns True if the two NetBIOS names passed to it
+match in name, type and scope: the NetBIOS names are equal.
+
+