← Back to branch summary

~zulcss/samba/server-dailies-3.0.37

« back to all changes in this revision

Viewing changes to docs-xml/Samba3-Developers-Guide/internals.xml

  • Committer: Chuck Short
  • Date: 2010-09-28 20:24:01 UTC
  • Revision ID: zulcss@ubuntu.com-20100928202401-tgh438aoatxv3zp3
Initial commit

Show diffs side-by-side

added added

removed removed

Lines of Context:
docs-xml/Samba3-Developers-Guide/internals.xml
 
1
<?xml version="1.0" encoding="iso-8859-1"?>
 
2
<!DOCTYPE chapter PUBLIC "-//Samba-Team//DTD DocBook V4.2-Based Variant V1.0//EN" "http://www.samba.org/samba/DTD/samba-doc">
 
3
<chapter id="internals">
 
4
<chapterinfo>
 
5
        <author>
 
6
                <firstname>David</firstname><surname>Chappell</surname>
 
7
                <affiliation>
 
8
                        <address><email>David.Chappell@mail.trincoll.edu</email></address>
 
9
                </affiliation>
 
10
        </author>
 
11
        <pubdate>8 May 1996</pubdate>
 
12
</chapterinfo>
 
13
 
 
14
<title>Samba Internals</title>
 
15
 
 
16
<sect1>
 
17
<title>Character Handling</title>
 
18
<para>
 
19
This section describes character set handling in Samba, as implemented in
 
20
Samba 3.0 and above
 
21
</para>
 
22
 
 
23
<para>
 
24
In the past Samba had very ad-hoc character set handling. Scattered
 
25
throughout the code were numerous calls which converted particular
 
26
strings to/from DOS codepages. The problem is that there was no way of
 
27
telling if a particular char* is in dos codepage or unix
 
28
codepage. This led to a nightmare of code that tried to cope with
 
29
particular cases without handlingt the general case.
 
30
</para>
 
31
</sect1>
 
32
 
 
33
<sect1>
 
34
<title>The new functions</title>
 
35
 
 
36
<para>
 
37
The new system works like this:
 
38
</para>
 
39
 
 
40
<orderedlist>
 
41
<listitem><para>
 
42
        all char* strings inside Samba are "unix" strings. These are
 
43
        multi-byte strings that are in the charset defined by the "unix
 
44
        charset" option in smb.conf. 
 
45
</para></listitem>
 
46
 
 
47
<listitem><para>
 
48
        there is no single fixed character set for unix strings, but any
 
49
        character set that is used does need the following properties:
 
50
        </para>
 
51
        <orderedlist>
 
52
        
 
53
        <listitem><para>
 
54
                must not contain NULLs except for termination
 
55
        </para></listitem>
 
56
 
 
57
        <listitem><para>
 
58
                must be 7-bit compatible with C strings, so that a constant
 
59
                string or character in C will be byte-for-byte identical to the
 
60
                equivalent string in the chosen character set. 
 
61
        </para></listitem>
 
62
        
 
63
        <listitem><para>
 
64
                when you uppercase or lowercase a string it does not become
 
65
                longer than the original string
 
66
        </para></listitem>
 
67
 
 
68
        <listitem><para>
 
69
                must be able to correctly hold all characters that your client
 
70
                will throw at it
 
71
        </para></listitem>
 
72
        </orderedlist>
 
73
        
 
74
        <para>
 
75
        For example, UTF-8 is fine, and most multi-byte asian character sets
 
76
        are fine, but UCS2 could not be used for unix strings as they
 
77
        contain nulls.
 
78
        </para>
 
79
</listitem>
 
80
 
 
81
<listitem><para>
 
82
        when you need to put a string into a buffer that will be sent on the
 
83
        wire, or you need a string in a character set format that is
 
84
        compatible with the clients character set then you need to use a
 
85
        pull_ or push_ function. The pull_ functions pull a string from a
 
86
        wire buffer into a (multi-byte) unix string. The push_ functions
 
87
        push a string out to a wire buffer. 
 
88
</para></listitem>
 
89
 
 
90
<listitem><para>
 
91
        the two main pull_ and push_ functions you need to understand are
 
92
        pull_string and push_string. These functions take a base pointer
 
93
        that should point at the start of the SMB packet that the string is
 
94
        in. The functions will check the flags field in this packet to
 
95
        automatically determine if the packet is marked as a unicode packet,
 
96
        and they will choose whether to use unicode for this string based on
 
97
        that flag. You may also force this decision using the STR_UNICODE or
 
98
        STR_ASCII flags. For use in smbd/ and libsmb/ there are wrapper
 
99
        functions clistr_ and srvstr_ that call the pull_/push_ functions
 
100
        with the appropriate first argument.
 
101
        </para>
 
102
        
 
103
        <para>
 
104
        You may also call the pull_ascii/pull_ucs2 or push_ascii/push_ucs2
 
105
        functions if you know that a particular string is ascii or
 
106
        unicode. There are also a number of other convenience functions in
 
107
        charcnv.c that call the pull_/push_ functions with particularly
 
108
        common arguments, such as pull_ascii_pstring()
 
109
        </para>
 
110
</listitem>
 
111
 
 
112
<listitem><para>
 
113
        The biggest thing to remember is that internal (unix) strings in Samba
 
114
        may now contain multi-byte characters. This means you cannot assume
 
115
        that characters are always 1 byte long. Often this means that you will
 
116
        have to convert strings to ucs2 and back again in order to do some
 
117
        (seemingly) simple task. For examples of how to do this see functions
 
118
        like strchr_m(). I know this is very slow, and we will eventually
 
119
        speed it up but right now we want this stuff correct not fast.
 
120
</para></listitem>
 
121
 
 
122
<listitem><para>
 
123
        all lp_ functions now return unix strings. The magic "DOS" flag on
 
124
        parameters is gone.
 
125
</para></listitem>
 
126
 
 
127
<listitem><para>
 
128
        all vfs functions take unix strings. Don't convert when passing to them
 
129
</para></listitem>
 
130
 
 
131
</orderedlist>
 
132
 
 
133
</sect1>
 
134
 
 
135
<sect1>
 
136
<title>Macros in byteorder.h</title>
 
137
 
 
138
<para>
 
139
This section describes the macros defined in byteorder.h.  These macros 
 
140
are used extensively in the Samba code.
 
141
</para>
 
142
 
 
143
<sect2>
 
144
<title>CVAL(buf,pos)</title>
 
145
 
 
146
<para>
 
147
returns the byte at offset pos within buffer buf as an unsigned character.
 
148
</para>
 
149
</sect2>
 
150
 
 
151
<sect2>
 
152
<title>PVAL(buf,pos)</title>
 
153
<para>returns the value of CVAL(buf,pos) cast to type unsigned integer.</para>
 
154
</sect2>
 
155
 
 
156
<sect2>
 
157
<title>SCVAL(buf,pos,val)</title>
 
158
<para>sets the byte at offset pos within buffer buf to value val.</para>
 
159
</sect2>
 
160
 
 
161
<sect2>
 
162
<title>SVAL(buf,pos)</title>
 
163
<para>
 
164
        returns the value of the unsigned short (16 bit) little-endian integer at 
 
165
        offset pos within buffer buf.  An integer of this type is sometimes
 
166
        refered to as "USHORT".
 
167
</para>
 
168
</sect2>
 
169
 
 
170
<sect2>
 
171
<title>IVAL(buf,pos)</title>
 
172
<para>returns the value of the unsigned 32 bit little-endian integer at offset 
 
173
pos within buffer buf.</para>
 
174
</sect2>
 
175
 
 
176
<sect2>
 
177
<title>SVALS(buf,pos)</title>
 
178
<para>returns the value of the signed short (16 bit) little-endian integer at 
 
179
offset pos within buffer buf.</para>
 
180
</sect2>
 
181
 
 
182
<sect2>
 
183
<title>IVALS(buf,pos)</title>
 
184
<para>returns the value of the signed 32 bit little-endian integer at offset pos
 
185
within buffer buf.</para>
 
186
</sect2>
 
187
 
 
188
<sect2>
 
189
<title>SSVAL(buf,pos,val)</title>
 
190
<para>sets the unsigned short (16 bit) little-endian integer at offset pos within 
 
191
buffer buf to value val.</para>
 
192
</sect2>
 
193
 
 
194
<sect2>
 
195
<title>SIVAL(buf,pos,val)</title>
 
196
<para>sets the unsigned 32 bit little-endian integer at offset pos within buffer 
 
197
buf to the value val.</para>
 
198
</sect2>
 
199
 
 
200
<sect2>
 
201
<title>SSVALS(buf,pos,val)</title>
 
202
<para>sets the short (16 bit) signed little-endian integer at offset pos within 
 
203
buffer buf to the value val.</para>
 
204
</sect2>
 
205
 
 
206
<sect2>
 
207
<title>SIVALS(buf,pos,val)</title>
 
208
<para>sets the signed 32 bit little-endian integer at offset pos withing buffer
 
209
buf to the value val.</para>
 
210
</sect2>
 
211
 
 
212
<sect2>
 
213
<title>RSVAL(buf,pos)</title>
 
214
<para>returns the value of the unsigned short (16 bit) big-endian integer at 
 
215
offset pos within buffer buf.</para>
 
216
</sect2>
 
217
 
 
218
<sect2>
 
219
<title>RIVAL(buf,pos)</title>
 
220
<para>returns the value of the unsigned 32 bit big-endian integer at offset 
 
221
pos within buffer buf.</para>
 
222
</sect2>
 
223
 
 
224
<sect2>
 
225
<title>RSSVAL(buf,pos,val)</title>
 
226
<para>sets the value of the unsigned short (16 bit) big-endian integer at 
 
227
offset pos within buffer buf to value val.
 
228
refered to as "USHORT".</para>
 
229
</sect2>
 
230
 
 
231
<sect2>
 
232
<title>RSIVAL(buf,pos,val)</title>
 
233
<para>sets the value of the unsigned 32 bit big-endian integer at offset 
 
234
pos within buffer buf to value val.</para>
 
235
</sect2>
 
236
 
 
237
</sect1>
 
238
 
 
239
 
 
240
<sect1>
 
241
<title>LAN Manager Samba API</title>
 
242
 
 
243
<para>
 
244
This section describes the functions need to make a LAN Manager RPC call.
 
245
This information had been obtained by examining the Samba code and the LAN
 
246
Manager 2.0 API documentation.  It should not be considered entirely
 
247
reliable.
 
248
</para>
 
249
 
 
250
<para>
 
251
<programlisting>
 
252
call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt, 
 
253
        char *param, char *data, char **rparam, char **rdata);
 
254
</programlisting>
 
255
</para>
 
256
 
 
257
<para>
 
258
This function is defined in client.c.  It uses an SMB transaction to call a
 
259
remote api.
 
260
</para>
 
261
 
 
262
<sect2>
 
263
<title>Parameters</title>
 
264
 
 
265
<para>The parameters are as follows:</para>
 
266
 
 
267
<orderedlist>
 
268
<listitem><para>
 
269
        prcnt: the number of bytes of parameters begin sent.
 
270
</para></listitem>
 
271
<listitem><para>
 
272
        drcnt:   the number of bytes of data begin sent.
 
273
</para></listitem>
 
274
<listitem><para>
 
275
        mprcnt:  the maximum number of bytes of parameters which should be returned
 
276
</para></listitem>
 
277
<listitem><para>
 
278
        mdrcnt:  the maximum number of bytes of data which should be returned
 
279
</para></listitem>
 
280
<listitem><para>
 
281
        param:   a pointer to the parameters to be sent.
 
282
</para></listitem>
 
283
<listitem><para>
 
284
        data:    a pointer to the data to be sent.
 
285
</para></listitem>
 
286
<listitem><para>
 
287
        rparam:  a pointer to a pointer which will be set to point to the returned
 
288
        parameters.  The caller of call_api() must deallocate this memory.
 
289
</para></listitem>
 
290
<listitem><para>
 
291
        rdata:   a pointer to a pointer which will be set to point to the returned 
 
292
        data.  The caller of call_api() must deallocate this memory.
 
293
</para></listitem>
 
294
</orderedlist>
 
295
 
 
296
<para>
 
297
These are the parameters which you ought to send, in the order of their
 
298
appearance in the parameter block:
 
299
</para>
 
300
 
 
301
<orderedlist>
 
302
 
 
303
<listitem><para>
 
304
An unsigned 16 bit integer API number.  You should set this value with
 
305
SSVAL().  I do not know where these numbers are described.
 
306
</para></listitem>
 
307
 
 
308
<listitem><para>
 
309
An ASCIIZ string describing the parameters to the API function as defined
 
310
in the LAN Manager documentation.  The first parameter, which is the server
 
311
name, is ommited.  This string is based uppon the API function as described
 
312
in the manual, not the data which is actually passed.
 
313
</para></listitem>
 
314
 
 
315
<listitem><para>
 
316
An ASCIIZ string describing the data structure which ought to be returned.
 
317
</para></listitem>
 
318
 
 
319
<listitem><para>
 
320
Any parameters which appear in the function call, as defined in the LAN
 
321
Manager API documentation, after the "Server" and up to and including the
 
322
"uLevel" parameters.
 
323
</para></listitem>
 
324
 
 
325
<listitem><para>
 
326
An unsigned 16 bit integer which gives the size in bytes of the buffer we
 
327
will use to receive the returned array of data structures.  Presumably this
 
328
should be the same as mdrcnt.  This value should be set with SSVAL().
 
329
</para></listitem>
 
330
 
 
331
<listitem><para>
 
332
An ASCIIZ string describing substructures which should be returned.  If no 
 
333
substructures apply, this string is of zero length.
 
334
</para></listitem>
 
335
 
 
336
</orderedlist>
 
337
 
 
338
<para>
 
339
The code in client.c always calls call_api() with no data.  It is unclear
 
340
when a non-zero length data buffer would be sent.
 
341
</para>
 
342
 
 
343
</sect2>
 
344
 
 
345
<sect2>
 
346
<title>Return value</title>
 
347
 
 
348
<para>
 
349
The returned parameters (pointed to by rparam), in their order of appearance
 
350
are:</para>
 
351
 
 
352
<orderedlist>
 
353
 
 
354
<listitem><para>
 
355
An unsigned 16 bit integer which contains the API function's return code. 
 
356
This value should be read with SVAL().
 
357
</para></listitem>
 
358
 
 
359
<listitem><para>
 
360
An adjustment which tells the amount by which pointers in the returned
 
361
data should be adjusted.  This value should be read with SVAL().  Basically, 
 
362
the address of the start of the returned data buffer should have the returned
 
363
pointer value added to it and then have this value subtracted from it in
 
364
order to obtain the currect offset into the returned data buffer.
 
365
</para></listitem>
 
366
 
 
367
<listitem><para>
 
368
A count of the number of elements in the array of structures returned. 
 
369
It is also possible that this may sometimes be the number of bytes returned.
 
370
</para></listitem>
 
371
</orderedlist>
 
372
 
 
373
<para>
 
374
When call_api() returns, rparam points to the returned parameters.  The
 
375
first if these is the result code.  It will be zero if the API call
 
376
suceeded.  This value by be read with "SVAL(rparam,0)".
 
377
</para>
 
378
 
 
379
<para>
 
380
The second parameter may be read as "SVAL(rparam,2)".  It is a 16 bit offset
 
381
which indicates what the base address of the returned data buffer was when
 
382
it was built on the server.  It should be used to correct pointer before
 
383
use.
 
384
</para>
 
385
 
 
386
<para>
 
387
The returned data buffer contains the array of returned data structures. 
 
388
Note that all pointers must be adjusted before use.  The function
 
389
fix_char_ptr() in client.c can be used for this purpose.
 
390
</para>
 
391
 
 
392
<para>
 
393
The third parameter (which may be read as "SVAL(rparam,4)") has something to
 
394
do with indicating the amount of data returned or possibly the amount of
 
395
data which can be returned if enough buffer space is allowed.
 
396
</para>
 
397
 
 
398
</sect2>
 
399
</sect1>
 
400
 
 
401
<sect1>
 
402
<title>Code character table</title>
 
403
<para>
 
404
Certain data structures are described by means of ASCIIz strings containing
 
405
code characters.  These are the code characters:
 
406
</para>
 
407
 
 
408
<orderedlist>
 
409
<listitem><para>
 
410
W       a type byte little-endian unsigned integer
 
411
</para></listitem>
 
412
<listitem><para>
 
413
N       a count of substructures which follow
 
414
</para></listitem>
 
415
<listitem><para>
 
416
D       a four byte little-endian unsigned integer
 
417
</para></listitem>
 
418
<listitem><para>
 
419
B       a byte (with optional count expressed as trailing ASCII digits)
 
420
</para></listitem>
 
421
<listitem><para>
 
422
z       a four byte offset to a NULL terminated string
 
423
</para></listitem>
 
424
<listitem><para>
 
425
l       a four byte offset to non-string user data
 
426
</para></listitem>
 
427
<listitem><para>
 
428
b       an offset to data (with count expressed as trailing ASCII digits)
 
429
</para></listitem>
 
430
<listitem><para>
 
431
r       pointer to returned data buffer???
 
432
</para></listitem>
 
433
<listitem><para>
 
434
L       length in bytes of returned data buffer???
 
435
</para></listitem>
 
436
<listitem><para>
 
437
h       number of bytes of information available???
 
438
</para></listitem>
 
439
</orderedlist>
 
440
 
 
441
</sect1>
 
442
</chapter>