patch to fix NetServerEnum with multiple workgroup lists kindly supplied.
[samba.git] / source / nameresp.doc
1 the netbios expected response code is a key part of samba's NetBIOS
2 handling capabilities. it allows samba to carry on dealing with
3 other things while expecting a response from one or more hosts.
4 this allows samba to simultaneously deal with registering its names
5 with another WINS server, register its names on its local subnets,
6 query any hosts that have registered with samba in its capacity as
7 a WINS server, and at a later date it will be also be able handle
8 END-NODE CHALLENGES (see rfc1001.txt 15.2.2.2 and 15.2.2.3 - secured
9 NBNS functionality). all at once!
10
11 when a netbios packet is sent out by samba and it expects a response,
12 a record of all the relevant information is kept (most importantly,
13 the unique transaction id associated which will come back to us in
14 a response packet is recorded, and also recorded is the reason that
15 the original packet was sent out by samba in the first place!).
16
17 if a response is received, then the unique transaction identifier 
18 returned in the response packet is searched for in the expected
19 response records. the record indicates why the initial request was
20 made (and therefore the type of response can be verified) and
21 appropriate action can be taken.
22
23 when no responses, after a number of retries, are not received, then
24 samba may take appropriate action.
25
26 nameresp.c deals with the maintenance of the netbios response records:
27 their creation, retransmission, and eventual removal.
28
29
30 /*************************************************************************
31   dead_netbios_entry()
32   *************************************************************************/
33
34 this function is responsible for dealing with the case when a NetBIOS
35 response to a packet sent out by samba was not received. for certain
36 transactions, this may be normal. for others, under certain conditions
37 it may constitute either an error or a problem with or failure of one
38 or more hosts.
39
40 - NAME_QUERY_CONFIRM
41
42 when a samba 'command' of type NAME_QUERY_CONFIRM is sent, a response
43 may or may not be forthcoming. if no response is received to a unique
44 name, then the record is removed from samba's WINS database. non-unique
45 names are simply expected to die off on a time-to-live basis (see
46 rfc1001.txt 15.1.3.4)
47
48 query_refresh_names() issues this samba 'command'
49 response_name_query_sync() deals with responses to NAME_QUERY_CONFIRM.
50
51 - NAME_QUERY_MST_CHK
52
53 when a samba 'command' of type NAME_QUERY_MST_CHK is sent, and a response
54 is not received, this implies that a master browser will have failed.
55 remedial action may need to be taken, for example if samba is a member
56 of that workgroup and it is also a potential master browser it could
57 force an election.
58
59 check_master_browser() issues this samba 'command'.
60 response_process() does nothing if a response is received. this is normal.
61
62 - NAME_RELEASE
63
64 when a samba 'command' of type NAME_RELEASE is sent, and a response is
65 not received, it is assumed to be acceptable to release the name. if the
66 original response was sent to another WINS server, then that WINS server
67 may be inaccessible or may have failed. if so, then at a later date
68 samba should take this into account (see rfc1001.txt 10.3).
69
70 remove_name_entry() issues this samba 'command'
71 response_name_rel() deals with responses to NAME_RELEASE.
72
73 - NAME_REGISTER
74
75 when a samba 'command' of type NAME_REGISTER is sent, and a response is
76 not received, if the registration was done by broadcast, it is assumed
77 that there are no objections to the registration of this name, and samba
78 adds the name to the appropriate subnet record name database. if the
79 registration was point-to-point (i.e with another WINS server) then that
80 WINS server may be inaccessible or may have failed. if so, then at a later
81 date samba should take this into account (see rfc1001.txt 10.3).
82
83 add_my_name_entry() issues this samba 'command'
84 response_name_reg() deals with responses to NAME_REGISTER.
85
86 no action is taken for any other kinds of samba 'commands' if a response
87 is not received. this is not to say that action may not be appropriate,
88 just that it's not been looked at yet :-)