updating documentation to reflect code a little bit.

lkcl
(This used to be commit 2193c1ee4eff33c32367ff27c817a6b78af51409)

7 files changed, 68 insertions, 43 deletions

diff --git a/source3/nameannounce.doc b/source3/nameannounce.doc
index afc4850a1f..a1e33cb800 100644
--- a/source3/nameannounce.doc
+++ b/source3/nameannounce.doc
@@ -1,6 +1,6 @@
 /* 
    Unix SMB/Netbios documentation.
-   Version 0.1
+   Version 0.2
    Copyright (C) Luke Leighton  Andrew Tridgell  1996
    
    This program is free software; you can redistribute it and/or modify
@@ -26,6 +26,11 @@
 
    0.1 - 22jul96 : Andrew.Tridgell@anu.edu.au
    tridge's comments on first revision
+
+   0.2 - 05aug96 : lkcl@pires.co.uk
+   actioned tridge comments about pdc -> domain master
+   documented NAME_QUERY_ANNOUNCE_HOST
+
 */
 
 
@@ -39,22 +44,22 @@ or as a response to announcement requests.
   *************************************************************************/
 
 this function is responsible for announcing samba as a master browser
-to all known primary domain controllers.
+to all known domain masters.
 
 this announcement is sent out at CHECK_TIME_MST_ANNOUNCE minute
 intervals, only if samba is a master browser on one or more of
 its local interfaces.
 
 if no domain controller has been specified (lp_domain_controller())
-samba goes through its list of servers looking for primary domain
-controllers. when it finds one (other than itself) it will either
+samba goes through its list of servers looking for domain master
+browsers. when it finds one (other than itself) it will either
 initiate a NAME_QUERY_PDC_SRV_CHK by broadcast or with a WINS
 server. this will result in a NAME_STATUS_PDC_SRV_CHK, which
 will result in a sync browse list and an announcement
 ANN_MasterAnnounce being sent (see sync_server()).
 
 if a domain controller has been specified, samba will search for
-a primary domain controller for its workgroup (either by directed
+a domain master browser for its workgroup (either by directed
 packet or by broadcast if it cannot resolve the domain controller
 name using DNS), which results in the same action as listed above.
 
@@ -119,20 +124,42 @@ these packets are received by other servers, which will then
 update their records accordingly: what services we have, our
 name, our comment field and our time to live (to name a few).
 
+if samba is a non-master then we need to see if there is a
+domain master (on a remote subnet) that we need to announce to
+it.
+
+if samba is not the WINS server (and it is using another
+WINS server) then we need to do a name query to the WINS
+server to ask it what the domain controller is. this is done
+using a samba 'state' NAME_QUERY_ANNOUNCE_HOST, which passes
+sufficient information on to be able to carry out the
+host announcement using a unicasted do_announce_host() if and
+when a reply comes back. if there is no reply to the name query,
+this is not necessarily an error - there may genuinely be no
+domain master currently up and running for samba's workgroup.
+
+if samba is a WINS server, then samba will need to look up the
+domain controller for its workgroup in its WINS records. an
+over-cautious samba could carry out a name query on that
+domain controller to make sure that it is alive and that samba's
+WINS records are up-to-date. in any event, it will send a unicast
+do_announce_host() to inform the domain master browser, if one
+exists, of samba's server status.
+
 if we are a master browser, then using do_announce_host() we
-must send an announcement notifying members of that workgroup
-that we are their master browser, and another announcement
-indicating to all backup browsers and master browsers that
-we are a master browser.
+must send a broadcast announcement on the local interface
+notifying members of that workgroup that we are their master
+browser, and another announcement indicating to all backup
+browsers and master browsers that we are a master browser.
 
-(note: if another master browser receives this announcement
-and thinks that it is also the master browser for this
-workgroup, it stops being a master browser and forces an
-election).
+(note: if another master browser receives this broadcasted
+announcement and thinks that it is also the master browser
+for this workgroup, it stops being a master browser and forces
+an election).
 
-if we are not a master browser, then we send an announcement
-notifying the master browser that we are a member of its
-workgroup.
+if we are not a master browser, then we send a broacast 
+announcement notifying the master browser that we are a member
+of its workgroup, on the local interface.
 
 
 /*************************************************************************
@@ -165,7 +192,7 @@ this function is responsible for getting master browsers and domain
 controllers to send us lists of backup servers. this is done by
 sending an ANN_GetBackupListReq browse mailslot.
 
-the master browser, or primary domain controller, should respond 
+the local master browser, or domain master browser, should respond 
 with an ANN_GetBackupListResp browse mailslot containing the list
 of backup servers.
 
@@ -189,8 +216,8 @@ else for it.
 
 this function is responsible for initiating a sync browse list
 sequence and, if necessary, carrying out an ANN_MasterAnnouncement
-to the primary domain controller (that we are also sync'ing
-browse lists with).
+to the domain master browser (that we are also sync'ing browse lists
+with).
 
 see nameservresp.c:response_name_status_check().
 
diff --git a/source3/namebrowse.doc b/source3/namebrowse.doc
index cef41ee4d2..82713d8570 100644
--- a/source3/namebrowse.doc
+++ b/source3/namebrowse.doc
@@ -41,8 +41,7 @@ the entry is removed.
 
 samba can ask for a NetServerEnum call to be issued to grab a remote
 server's list of servers and workgroups either in its capacity as
-a primary domain controller (domain master browser), as a local
-master browser.
+a domain master browser, as a local master browser.
 
 samba does not deal with becoming a backup master browser properly
 at present.
diff --git a/source3/namedbname.doc b/source3/namedbname.doc
index df47cbf08e..34a791dbb8 100644
--- a/source3/namedbname.doc
+++ b/source3/namedbname.doc
@@ -72,7 +72,7 @@ is registered.
 
 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
+that will be added are those of domain master browsers 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.
diff --git a/source3/nameelect.doc b/source3/nameelect.doc
index ecc00c7234..df025e2069 100644
--- a/source3/nameelect.doc
+++ b/source3/nameelect.doc
@@ -43,9 +43,8 @@ unique special browser names (either on your local subnet or with
 the WINS server) then you must stop being a master browser.
 
 this is a double fail-safe mechanism to ensure that there is only
-one master browser per workgroup per subnet (and one primary domain
-controller - domain master browser - per domain (workgroup) per
-wide area network).
+one master browser per workgroup per subnet (and one domain master
+browser - per domain (workgroup) per wide area network).
 
 (a wide area network is created when one or more servers on a
 broadcast-isolated subnet point to the same WINS server).
@@ -137,7 +136,7 @@ becoming non-master is done on a per-subnet basis.
   *************************************************************************/
 
 this function is responsible for slowly turning samba into a
-master browser or a domain master (primary domain controller).
+local master browser or a domain master browser.
 
 
 this is done in stages. note that this could take a while, 
diff --git a/source3/nameservreply.doc b/source3/nameservreply.doc
index 26b8a0a1e7..a5acf8a9c2 100644
--- a/source3/nameservreply.doc
+++ b/source3/nameservreply.doc
@@ -74,7 +74,7 @@ if it is found, then we need to check whether it is appropriate for us
 to reply to such a query.
 
 we will only reply if the query is a directed query, the name belongs to
-samba on that subnet, or the name is a primary domain controller type,
+samba on that subnet, or the name is a domain master browser type,
 or we're doing replies on behalf of hosts on subnets not known to the
 host issuing the query. in the latter instance, it would be appropriate
 if samba is using a WINS server for it to forward the name query on to
diff --git a/source3/nameservresp.doc b/source3/nameservresp.doc
index 0d6a4ee8c1..635db45084 100644
--- a/source3/nameservresp.doc
+++ b/source3/nameservresp.doc
@@ -95,15 +95,15 @@ entry should be removed if we receive a negative response.
   response_name_status_check()
   *************************************************************************/
 
-this function receives responses to samba 'states' NAME_STATUS_CHECK
-and NAME_STATUS_MASTER_CHECK
+this function receives responses to samba 'states' NAME_STATUS_SRV_CHK
+and NAME_STATUS_DOM_SRV_CHK
 
-NAME_STATUS_MASTER_CHECK: name status a primary domain controller, 
+NAME_STATUS_DOM_SRV_CHK: name status a domain master browser
                           confirm its domain and then initiate syncing
                           its browse list.
 
-NAME_STATUS_CHECK: same as NAME_STATUS_MASTER_CHECK except the name status
-                   is issued to a master browser.
+NAME_STATUS_SRV_CHK: same as NAME_STATUS_DOM_SRV_CHK except the
+                     name status is issued to a master browser.
 
 if we don't know what workgroup a server is responsible for, but we
 know that there is a master browser at a certain ip, we can issue a
@@ -117,7 +117,7 @@ correct part of samba's workgroup - server database.
   response_server_check()
   *************************************************************************/
 
-this function receives responses to samba 'states' NAME_QUERY_MST_SRV_CHK,
+this function receives responses to samba 'states' NAME_QUERY_DOM_SRV_CHK,
 NAME_QUERY_SRV_CHK and NAME_QUERY_FIND_MST.
 
 NAME_QUERY_FIND_MST: issued as a broadcast when we wish to find out all
@@ -126,10 +126,10 @@ NAME_QUERY_FIND_MST: issued as a broadcast when we wish to find out all
                      issue a NAME_STATUS_MASTER_CHECK on any servers that
                      respond, which will initiate a sync browse lists.
 
-NAME_QUERY_MST_SRV_CHK: same as a NAME_QUERY_FIND_MST except this is sent
-                        to a primary domain controller.
+NAME_QUERY_DOM_SRV_CHK: same as a NAME_QUERY_FIND_MST except this is sent
+                        to a domain master browser.
 
-NAME_QUERY_SRV_CHK: same as a NAME_QUERY_MST_SRV_CHK except this is sent to
+NAME_QUERY_SRV_CHK: same as a NAME_QUERY_DOM_SRV_CHK except this is sent to
                     a master browser.
                         
 the purpose of each of these states is to do a broadcast name query, or
@@ -160,9 +160,9 @@ is added to samba's database.
 
 when a negative response is received, samba will remove the name
 from its database. if, however, the name is a browser type (0x1b is
-a primary domain controller type name; or 0x1d, which is a master
-browser type name) then it must also stop being a primary domain
-controller or master browser respectively, depending on what kind
+a domain master browser type name; or 0x1d, which is a local master
+browser type name) then it must also stop being a domain master
+browser or master browser respectively, depending on what kind
 of name was rejected.
 
 (when no response is received, then expire_netbios_response_entries()
diff --git a/source3/namework.doc b/source3/namework.doc
index 6bc872a5f2..958a86c866 100644
--- a/source3/namework.doc
+++ b/source3/namework.doc
@@ -201,8 +201,8 @@ this function is part of samba's domain master browser functionality.
 it is responsible for giving master browsers a list of other browsers
 that maintain backup lists of servers for that master browser's workgroup.
 
-it is also responsible for giving master browsers a list of primary domain
-controllers for that master browser's domain.
+it is also responsible for giving master browsers a list of domain master
+browsers for that local master browser's domain.
 
 a correct way to think of this function is that it is a 'request to
 send out a backup list for the requested workgroup or domain'.
@@ -217,8 +217,8 @@ matter of experimenting until it's right.
   *************************************************************************/
 
 this function is responsible for compiling a list of either master
-browsers and backup master browsers or primary domain controllers or
-backup domain controllers. samba constructs this list from its 
+browsers and backup master browsers or domain master browsers and
+backup domain master browsers. samba constructs this list from its 
 workgroup / server database.
 
 the list is then sent to the host that requested it by sending an