159a50738c50a1d4e99dfb9642f459890287d657
[kai/samba.git] / source3 / namepacket.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: namepacket.doc
21
22    Revision History:
23
24    0.0 - 02jul96 : lkcl@pires.co.uk
25    created
26 */
27
28 this module deals with packets: sending, receiving, queueing
29 and some basic interpretation (e.g it excludes datagram
30 error packets at the moment).
31
32 the packet queueing mechanism was originally introduced when
33 samba dealt with responses by sending a packet, receiving
34 packets and queueing all packets that didn't match up with
35 the response expected. this is fine in a single-thread
36 environment, but samba now deals with response packets by
37 queueing the responses. to some extent, therefore, this
38 queue_packet mechanism is redundant.
39
40
41 /*************************************************************************
42   send_mailslot_reply()
43   *************************************************************************/
44
45 this function is responsible for sending a MAILSLOT packet.
46
47 it will _not_ send packets to the pseudo WINS subnet's address of 
48 255.255.255.255: this would be disastrous.
49
50 each packet sent out has a unique transaction identifier. this is done
51 so that responses can be matched later with the original purpose for
52 the packet being sent out in the first place.
53
54
55 /*************************************************************************
56   listen_for_packets()
57   *************************************************************************/
58
59 this function is responsible for reading NMB and DGRAM packets, and then
60 queueing them. it will normally time-out for NMBD_SELECT_LOOP seconds, but
61 if there is an election currently running or we are expecting a response
62 then this time is reduced to 1 second.
63
64 note: the time-out period needs refining to the millisecond level.
65
66
67 /*************************************************************************
68   queue_packet()
69   *************************************************************************/
70
71 this function is responsible for queueing any NMB and DGRAM packets passed
72 to it. these packets will be removed from the queue in run_packet_queue().
73
74
75 /*************************************************************************
76   run_packet_queue()
77   *************************************************************************/
78
79 this function is responsible for taking a packet off the queue, 
80 identifying whether it is an NMB or a DGRAM packet, processing
81 it accordingly and deleting it. this process continues until
82 there are no more packets on the queue.
83
84
85 /*************************************************************************
86   process_nmb()
87   *************************************************************************/
88
89 this function receives a packet identified as a netbios packet.
90 it further identifies whether it is a response or a query packet.
91 by identifying the type of packet (name registration, query etc)
92 process_nmb() will call the appropriate function to deal with the
93 type of packet received.
94
95
96 /*************************************************************************
97   process_dgram()
98   *************************************************************************/
99
100 this function is responsible for identifying whether the datagram
101 packet received is a browser packet or a domain logon packet. it
102 also does some filtering of certain types of packets (e.g it
103 filters out error packets).
104
105
106 /*************************************************************************
107   reply_netbios_packet()
108   *************************************************************************/
109
110 this function is responsible for sending a reply to another NetBIOS
111 packet from another host. it can be used to send a reply to a name
112 registration, name release, name query or name status request.
113
114 the reply can be either a positive or a negative one.
115
116
117 /*************************************************************************
118   initiate_netbios_packet()
119   *************************************************************************/
120
121 this function is responsible for construction a netbios packet and sending
122 it. if the packet has not had a unique transaction id allocated to it,
123 then initiate_netbios_packet() will give it one.
124
125
126 /*************************************************************************
127   update_name_trn_id()
128   *************************************************************************/
129
130 this function is responsible for allocating unique transaction identifiers
131 for each new packet sent on the network.
132
133