• Home
  • History
  • Annotate
  • Line#
  • Navigate
  • Raw
  • Download
  • only in /netgear-R7000-V1.0.7.12_1.2.5/ap/gpl/samba-3.0.25b/docs/htmldocs/Samba3-Developers-Guide/
1<html><head><meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Chapter�5.�Samba Internals</title><link rel="stylesheet" href="samba.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.71.0"><link rel="start" href="index.html" title="SAMBA Developers Guide"><link rel="up" href="pt02.html" title="Part�II.�Samba Basics"><link rel="prev" href="debug.html" title="Chapter�4.�The samba DEBUG system"><link rel="next" href="CodingSuggestions.html" title="Chapter�6.�Coding Suggestions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Chapter�5.�Samba Internals</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="debug.html">Prev</a>�</td><th width="60%" align="center">Part�II.�Samba Basics</th><td width="20%" align="right">�<a accesskey="n" href="CodingSuggestions.html">Next</a></td></tr></table><hr></div><div class="chapter" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="internals"></a>Chapter�5.�Samba Internals</h2></div><div><div class="author"><h3 class="author"><span class="firstname">David</span> <span class="surname">Chappell</span></h3><div class="affiliation"><div class="address"><p><code class="email">&lt;<a href="mailto:David.Chappell@mail.trincoll.edu">David.Chappell@mail.trincoll.edu</a>&gt;</code></p></div></div></div></div><div><p class="pubdate">8 May 1996</p></div></div></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="sect1"><a href="internals.html#id323122">Character Handling</a></span></dt><dt><span class="sect1"><a href="internals.html#id323142">The new functions</a></span></dt><dt><span class="sect1"><a href="internals.html#id323249">Macros in byteorder.h</a></span></dt><dd><dl><dt><span class="sect2"><a href="internals.html#id323259">CVAL(buf,pos)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323269">PVAL(buf,pos)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323280">SCVAL(buf,pos,val)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323290">SVAL(buf,pos)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323302">IVAL(buf,pos)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323313">SVALS(buf,pos)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323323">IVALS(buf,pos)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323334">SSVAL(buf,pos,val)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323345">SIVAL(buf,pos,val)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323356">SSVALS(buf,pos,val)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323367">SIVALS(buf,pos,val)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323377">RSVAL(buf,pos)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323388">RIVAL(buf,pos)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323399">RSSVAL(buf,pos,val)</a></span></dt><dt><span class="sect2"><a href="internals.html#id323410">RSIVAL(buf,pos,val)</a></span></dt></dl></dd><dt><span class="sect1"><a href="internals.html#id323422">LAN Manager Samba API</a></span></dt><dd><dl><dt><span class="sect2"><a href="internals.html#id323447">Parameters</a></span></dt><dt><span class="sect2"><a href="internals.html#id323556">Return value</a></span></dt></dl></dd><dt><span class="sect1"><a href="internals.html#id323614">Code character table</a></span></dt></dl></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id323122"></a>Character Handling</h2></div></div></div><p>
2This section describes character set handling in Samba, as implemented in
3Samba 3.0 and above
4</p><p>
5In the past Samba had very ad-hoc character set handling. Scattered
6throughout the code were numerous calls which converted particular
7strings to/from DOS codepages. The problem is that there was no way of
8telling if a particular char* is in dos codepage or unix
9codepage. This led to a nightmare of code that tried to cope with
10particular cases without handlingt the general case.
11</p></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id323142"></a>The new functions</h2></div></div></div><p>
12The new system works like this:
13</p><div class="orderedlist"><ol type="1"><li><p>
14	all char* strings inside Samba are "unix" strings. These are
15	multi-byte strings that are in the charset defined by the "unix
16	charset" option in smb.conf. 
17</p></li><li><p>
18	there is no single fixed character set for unix strings, but any
19	character set that is used does need the following properties:
20	</p><div class="orderedlist"><ol type="a"><li><p>
21		must not contain NULLs except for termination
22	</p></li><li><p>
23		must be 7-bit compatible with C strings, so that a constant
24		string or character in C will be byte-for-byte identical to the
25		equivalent string in the chosen character set. 
26	</p></li><li><p>
27		when you uppercase or lowercase a string it does not become
28		longer than the original string
29	</p></li><li><p>
30		must be able to correctly hold all characters that your client
31		will throw at it
32	</p></li></ol></div><p>
33	For example, UTF-8 is fine, and most multi-byte asian character sets
34	are fine, but UCS2 could not be used for unix strings as they
35	contain nulls.
36	</p></li><li><p>
37	when you need to put a string into a buffer that will be sent on the
38	wire, or you need a string in a character set format that is
39	compatible with the clients character set then you need to use a
40	pull_ or push_ function. The pull_ functions pull a string from a
41	wire buffer into a (multi-byte) unix string. The push_ functions
42	push a string out to a wire buffer. 
43</p></li><li><p>
44	the two main pull_ and push_ functions you need to understand are
45	pull_string and push_string. These functions take a base pointer
46	that should point at the start of the SMB packet that the string is
47	in. The functions will check the flags field in this packet to
48	automatically determine if the packet is marked as a unicode packet,
49	and they will choose whether to use unicode for this string based on
50	that flag. You may also force this decision using the STR_UNICODE or
51	STR_ASCII flags. For use in smbd/ and libsmb/ there are wrapper
52	functions clistr_ and srvstr_ that call the pull_/push_ functions
53	with the appropriate first argument.
54	</p><p>
55	You may also call the pull_ascii/pull_ucs2 or push_ascii/push_ucs2
56	functions if you know that a particular string is ascii or
57	unicode. There are also a number of other convenience functions in
58	charcnv.c that call the pull_/push_ functions with particularly
59	common arguments, such as pull_ascii_pstring()
60	</p></li><li><p>
61	The biggest thing to remember is that internal (unix) strings in Samba
62	may now contain multi-byte characters. This means you cannot assume
63	that characters are always 1 byte long. Often this means that you will
64	have to convert strings to ucs2 and back again in order to do some
65	(seemingly) simple task. For examples of how to do this see functions
66	like strchr_m(). I know this is very slow, and we will eventually
67	speed it up but right now we want this stuff correct not fast.
68</p></li><li><p>
69	all lp_ functions now return unix strings. The magic "DOS" flag on
70	parameters is gone.
71</p></li><li><p>
72	all vfs functions take unix strings. Don't convert when passing to them
73</p></li></ol></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id323249"></a>Macros in byteorder.h</h2></div></div></div><p>
74This section describes the macros defined in byteorder.h.  These macros 
75are used extensively in the Samba code.
76</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323259"></a>CVAL(buf,pos)</h3></div></div></div><p>
77returns the byte at offset pos within buffer buf as an unsigned character.
78</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323269"></a>PVAL(buf,pos)</h3></div></div></div><p>returns the value of CVAL(buf,pos) cast to type unsigned integer.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323280"></a>SCVAL(buf,pos,val)</h3></div></div></div><p>sets the byte at offset pos within buffer buf to value val.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323290"></a>SVAL(buf,pos)</h3></div></div></div><p>
79	returns the value of the unsigned short (16 bit) little-endian integer at 
80	offset pos within buffer buf.  An integer of this type is sometimes
81	refered to as "USHORT".
82</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323302"></a>IVAL(buf,pos)</h3></div></div></div><p>returns the value of the unsigned 32 bit little-endian integer at offset 
83pos within buffer buf.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323313"></a>SVALS(buf,pos)</h3></div></div></div><p>returns the value of the signed short (16 bit) little-endian integer at 
84offset pos within buffer buf.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323323"></a>IVALS(buf,pos)</h3></div></div></div><p>returns the value of the signed 32 bit little-endian integer at offset pos
85within buffer buf.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323334"></a>SSVAL(buf,pos,val)</h3></div></div></div><p>sets the unsigned short (16 bit) little-endian integer at offset pos within 
86buffer buf to value val.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323345"></a>SIVAL(buf,pos,val)</h3></div></div></div><p>sets the unsigned 32 bit little-endian integer at offset pos within buffer 
87buf to the value val.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323356"></a>SSVALS(buf,pos,val)</h3></div></div></div><p>sets the short (16 bit) signed little-endian integer at offset pos within 
88buffer buf to the value val.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323367"></a>SIVALS(buf,pos,val)</h3></div></div></div><p>sets the signed 32 bit little-endian integer at offset pos withing buffer
89buf to the value val.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323377"></a>RSVAL(buf,pos)</h3></div></div></div><p>returns the value of the unsigned short (16 bit) big-endian integer at 
90offset pos within buffer buf.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323388"></a>RIVAL(buf,pos)</h3></div></div></div><p>returns the value of the unsigned 32 bit big-endian integer at offset 
91pos within buffer buf.</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323399"></a>RSSVAL(buf,pos,val)</h3></div></div></div><p>sets the value of the unsigned short (16 bit) big-endian integer at 
92offset pos within buffer buf to value val.
93refered to as "USHORT".</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323410"></a>RSIVAL(buf,pos,val)</h3></div></div></div><p>sets the value of the unsigned 32 bit big-endian integer at offset 
94pos within buffer buf to value val.</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id323422"></a>LAN Manager Samba API</h2></div></div></div><p>
95This section describes the functions need to make a LAN Manager RPC call.
96This information had been obtained by examining the Samba code and the LAN
97Manager 2.0 API documentation.  It should not be considered entirely
98reliable.
99</p><p>
100</p><pre class="programlisting">
101call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt, 
102	char *param, char *data, char **rparam, char **rdata);
103</pre><p>
104</p><p>
105This function is defined in client.c.  It uses an SMB transaction to call a
106remote api.
107</p><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323447"></a>Parameters</h3></div></div></div><p>The parameters are as follows:</p><div class="orderedlist"><ol type="1"><li><p>
108	prcnt: the number of bytes of parameters begin sent.
109</p></li><li><p>
110	drcnt:   the number of bytes of data begin sent.
111</p></li><li><p>
112	mprcnt:  the maximum number of bytes of parameters which should be returned
113</p></li><li><p>
114	mdrcnt:  the maximum number of bytes of data which should be returned
115</p></li><li><p>
116	param:   a pointer to the parameters to be sent.
117</p></li><li><p>
118	data:    a pointer to the data to be sent.
119</p></li><li><p>
120	rparam:  a pointer to a pointer which will be set to point to the returned
121	paramters.  The caller of call_api() must deallocate this memory.
122</p></li><li><p>
123	rdata:   a pointer to a pointer which will be set to point to the returned 
124	data.  The caller of call_api() must deallocate this memory.
125</p></li></ol></div><p>
126These are the parameters which you ought to send, in the order of their
127appearance in the parameter block:
128</p><div class="orderedlist"><ol type="1"><li><p>
129An unsigned 16 bit integer API number.  You should set this value with
130SSVAL().  I do not know where these numbers are described.
131</p></li><li><p>
132An ASCIIZ string describing the parameters to the API function as defined
133in the LAN Manager documentation.  The first parameter, which is the server
134name, is ommited.  This string is based uppon the API function as described
135in the manual, not the data which is actually passed.
136</p></li><li><p>
137An ASCIIZ string describing the data structure which ought to be returned.
138</p></li><li><p>
139Any parameters which appear in the function call, as defined in the LAN
140Manager API documentation, after the "Server" and up to and including the
141"uLevel" parameters.
142</p></li><li><p>
143An unsigned 16 bit integer which gives the size in bytes of the buffer we
144will use to receive the returned array of data structures.  Presumably this
145should be the same as mdrcnt.  This value should be set with SSVAL().
146</p></li><li><p>
147An ASCIIZ string describing substructures which should be returned.  If no 
148substructures apply, this string is of zero length.
149</p></li></ol></div><p>
150The code in client.c always calls call_api() with no data.  It is unclear
151when a non-zero length data buffer would be sent.
152</p></div><div class="sect2" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="id323556"></a>Return value</h3></div></div></div><p>
153The returned parameters (pointed to by rparam), in their order of appearance
154are:</p><div class="orderedlist"><ol type="1"><li><p>
155An unsigned 16 bit integer which contains the API function's return code. 
156This value should be read with SVAL().
157</p></li><li><p>
158An adjustment which tells the amount by which pointers in the returned
159data should be adjusted.  This value should be read with SVAL().  Basically, 
160the address of the start of the returned data buffer should have the returned
161pointer value added to it and then have this value subtracted from it in
162order to obtain the currect offset into the returned data buffer.
163</p></li><li><p>
164A count of the number of elements in the array of structures returned. 
165It is also possible that this may sometimes be the number of bytes returned.
166</p></li></ol></div><p>
167When call_api() returns, rparam points to the returned parameters.  The
168first if these is the result code.  It will be zero if the API call
169suceeded.  This value by be read with "SVAL(rparam,0)".
170</p><p>
171The second parameter may be read as "SVAL(rparam,2)".  It is a 16 bit offset
172which indicates what the base address of the returned data buffer was when
173it was built on the server.  It should be used to correct pointer before
174use.
175</p><p>
176The returned data buffer contains the array of returned data structures. 
177Note that all pointers must be adjusted before use.  The function
178fix_char_ptr() in client.c can be used for this purpose.
179</p><p>
180The third parameter (which may be read as "SVAL(rparam,4)") has something to
181do with indicating the amount of data returned or possibly the amount of
182data which can be returned if enough buffer space is allowed.
183</p></div></div><div class="sect1" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="id323614"></a>Code character table</h2></div></div></div><p>
184Certain data structures are described by means of ASCIIz strings containing
185code characters.  These are the code characters:
186</p><div class="orderedlist"><ol type="1"><li><p>
187W	a type byte little-endian unsigned integer
188</p></li><li><p>
189N	a count of substructures which follow
190</p></li><li><p>
191D	a four byte little-endian unsigned integer
192</p></li><li><p>
193B	a byte (with optional count expressed as trailing ASCII digits)
194</p></li><li><p>
195z	a four byte offset to a NULL terminated string
196</p></li><li><p>
197l	a four byte offset to non-string user data
198</p></li><li><p>
199b	an offset to data (with count expressed as trailing ASCII digits)
200</p></li><li><p>
201r	pointer to returned data buffer???
202</p></li><li><p>
203L	length in bytes of returned data buffer???
204</p></li><li><p>
205h	number of bytes of information available???
206</p></li></ol></div></div></div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="debug.html">Prev</a>�</td><td width="20%" align="center"><a accesskey="u" href="pt02.html">Up</a></td><td width="40%" align="right">�<a accesskey="n" href="CodingSuggestions.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">Chapter�4.�The samba DEBUG system�</td><td width="20%" align="center"><a accesskey="h" href="index.html">Home</a></td><td width="40%" align="right" valign="top">�Chapter�6.�Coding Suggestions</td></tr></table></div></body></html>
207