diff options
Diffstat (limited to 'docs/devel/internals.xml')
| -rw-r--r-- | docs/devel/internals.xml | 440 |
1 files changed, 440 insertions, 0 deletions
diff --git a/docs/devel/internals.xml b/docs/devel/internals.xml new file mode 100644 index 0000000000..982cfd2e10 --- /dev/null +++ b/docs/devel/internals.xml @@ -0,0 +1,440 @@ +<chapter id="internals"> +<chapterinfo> + <author> + <firstname>David</firstname><surname>Chappell</surname> + <affiliation> + <address><email>David.Chappell@mail.trincoll.edu</email></address> + </affiliation> + </author> + <pubdate>8 May 1996</pubdate> +</chapterinfo> + +<title>Samba Internals</title> + +<sect1> +<title>Character Handling</title> +<para> +This section describes character set handling in Samba, as implemented in +Samba 3.0 and above +</para> + +<para> +In the past Samba had very ad-hoc character set handling. Scattered +throughout the code were numerous calls which converted particular +strings to/from DOS codepages. The problem is that there was no way of +telling if a particular char* is in dos codepage or unix +codepage. This led to a nightmare of code that tried to cope with +particular cases without handlingt the general case. +</para> +</sect1> + +<sect1> +<title>The new functions</title> + +<para> +The new system works like this: +</para> + +<orderedlist> +<listitem><para> + all char* strings inside Samba are "unix" strings. These are + multi-byte strings that are in the charset defined by the "unix + charset" option in smb.conf. +</para></listitem> + +<listitem><para> + there is no single fixed character set for unix strings, but any + character set that is used does need the following properties: + </para> + <orderedlist> + + <listitem><para> + must not contain NULLs except for termination + </para></listitem> + + <listitem><para> + must be 7-bit compatible with C strings, so that a constant + string or character in C will be byte-for-byte identical to the + equivalent string in the chosen character set. + </para></listitem> + + <listitem><para> + when you uppercase or lowercase a string it does not become + longer than the original string + </para></listitem> + + <listitem><para> + must be able to correctly hold all characters that your client + will throw at it + </para></listitem> + </orderedlist> + + <para> + For example, UTF-8 is fine, and most multi-byte asian character sets + are fine, but UCS2 could not be used for unix strings as they + contain nulls. + </para> +</listitem> + +<listitem><para> + when you need to put a string into a buffer that will be sent on the + wire, or you need a string in a character set format that is + compatible with the clients character set then you need to use a + pull_ or push_ function. The pull_ functions pull a string from a + wire buffer into a (multi-byte) unix string. The push_ functions + push a string out to a wire buffer. +</para></listitem> + +<listitem><para> + the two main pull_ and push_ functions you need to understand are + pull_string and push_string. These functions take a base pointer + that should point at the start of the SMB packet that the string is + in. The functions will check the flags field in this packet to + automatically determine if the packet is marked as a unicode packet, + and they will choose whether to use unicode for this string based on + that flag. You may also force this decision using the STR_UNICODE or + STR_ASCII flags. For use in smbd/ and libsmb/ there are wrapper + functions clistr_ and srvstr_ that call the pull_/push_ functions + with the appropriate first argument. + </para> + + <para> + You may also call the pull_ascii/pull_ucs2 or push_ascii/push_ucs2 + functions if you know that a particular string is ascii or + unicode. There are also a number of other convenience functions in + charcnv.c that call the pull_/push_ functions with particularly + common arguments, such as pull_ascii_pstring() + </para> +</listitem> + +<listitem><para> + The biggest thing to remember is that internal (unix) strings in Samba + may now contain multi-byte characters. This means you cannot assume + that characters are always 1 byte long. Often this means that you will + have to convert strings to ucs2 and back again in order to do some + (seemingly) simple task. For examples of how to do this see functions + like strchr_m(). I know this is very slow, and we will eventually + speed it up but right now we want this stuff correct not fast. +</para></listitem> + +<listitem><para> + all lp_ functions now return unix strings. The magic "DOS" flag on + parameters is gone. +</para></listitem> + +<listitem><para> + all vfs functions take unix strings. Don't convert when passing to them +</para></listitem> + +</orderedlist> + +</sect1> + +<sect1> +<title>Macros in byteorder.h</title> + +<para> +This section describes the macros defined in byteorder.h. These macros +are used extensively in the Samba code. +</para> + +<sect2> +<title>CVAL(buf,pos)</title> + +<para> +returns the byte at offset pos within buffer buf as an unsigned character. +</para> +</sect2> + +<sect2> +<title>PVAL(buf,pos)</title> +<para>returns the value of CVAL(buf,pos) cast to type unsigned integer.</para> +</sect2> + +<sect2> +<title>SCVAL(buf,pos,val)</title> +<para>sets the byte at offset pos within buffer buf to value val.</para> +</sect2> + +<sect2> +<title>SVAL(buf,pos)</title> +<para> + returns the value of the unsigned short (16 bit) little-endian integer at + offset pos within buffer buf. An integer of this type is sometimes + refered to as "USHORT". +</para> +</sect2> + +<sect2> +<title>IVAL(buf,pos)</title> +<para>returns the value of the unsigned 32 bit little-endian integer at offset +pos within buffer buf.</para> +</sect2> + +<sect2> +<title>SVALS(buf,pos)</title> +<para>returns the value of the signed short (16 bit) little-endian integer at +offset pos within buffer buf.</para> +</sect2> + +<sect2> +<title>IVALS(buf,pos)</title> +<para>returns the value of the signed 32 bit little-endian integer at offset pos +within buffer buf.</para> +</sect2> + +<sect2> +<title>SSVAL(buf,pos,val)</title> +<para>sets the unsigned short (16 bit) little-endian integer at offset pos within +buffer buf to value val.</para> +</sect2> + +<sect2> +<title>SIVAL(buf,pos,val)</title> +<para>sets the unsigned 32 bit little-endian integer at offset pos within buffer +buf to the value val.</para> +</sect2> + +<sect2> +<title>SSVALS(buf,pos,val)</title> +<para>sets the short (16 bit) signed little-endian integer at offset pos within +buffer buf to the value val.</para> +</sect2> + +<sect2> +<title>SIVALS(buf,pos,val)</title> +<para>sets the signed 32 bit little-endian integer at offset pos withing buffer +buf to the value val.</para> +</sect2> + +<sect2> +<title>RSVAL(buf,pos)</title> +<para>returns the value of the unsigned short (16 bit) big-endian integer at +offset pos within buffer buf.</para> +</sect2> + +<sect2> +<title>RIVAL(buf,pos)</title> +<para>returns the value of the unsigned 32 bit big-endian integer at offset +pos within buffer buf.</para> +</sect2> + +<sect2> +<title>RSSVAL(buf,pos,val)</title> +<para>sets the value of the unsigned short (16 bit) big-endian integer at +offset pos within buffer buf to value val. +refered to as "USHORT".</para> +</sect2> + +<sect2> +<title>RSIVAL(buf,pos,val)</title> +<para>sets the value of the unsigned 32 bit big-endian integer at offset +pos within buffer buf to value val.</para> +</sect2> + +</sect1> + + +<sect1> +<title>LAN Manager Samba API</title> + +<para> +This section describes the functions need to make a LAN Manager RPC call. +This information had been obtained by examining the Samba code and the LAN +Manager 2.0 API documentation. It should not be considered entirely +reliable. +</para> + +<para> +<programlisting> +call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt, + char *param, char *data, char **rparam, char **rdata); +</programlisting> +</para> + +<para> +This function is defined in client.c. It uses an SMB transaction to call a +remote api. +</para> + +<sect2> +<title>Parameters</title> + +<para>The parameters are as follows:</para> + +<orderedlist> +<listitem><para> + prcnt: the number of bytes of parameters begin sent. +</para></listitem> +<listitem><para> + drcnt: the number of bytes of data begin sent. +</para></listitem> +<listitem><para> + mprcnt: the maximum number of bytes of parameters which should be returned +</para></listitem> +<listitem><para> + mdrcnt: the maximum number of bytes of data which should be returned +</para></listitem> +<listitem><para> + param: a pointer to the parameters to be sent. +</para></listitem> +<listitem><para> + data: a pointer to the data to be sent. +</para></listitem> +<listitem><para> + rparam: a pointer to a pointer which will be set to point to the returned + paramters. The caller of call_api() must deallocate this memory. +</para></listitem> +<listitem><para> + rdata: a pointer to a pointer which will be set to point to the returned + data. The caller of call_api() must deallocate this memory. +</para></listitem> +</orderedlist> + +<para> +These are the parameters which you ought to send, in the order of their +appearance in the parameter block: +</para> + +<orderedlist> + +<listitem><para> +An unsigned 16 bit integer API number. You should set this value with +SSVAL(). I do not know where these numbers are described. +</para></listitem> + +<listitem><para> +An ASCIIZ string describing the parameters to the API function as defined +in the LAN Manager documentation. The first parameter, which is the server +name, is ommited. This string is based uppon the API function as described +in the manual, not the data which is actually passed. +</para></listitem> + +<listitem><para> +An ASCIIZ string describing the data structure which ought to be returned. +</para></listitem> + +<listitem><para> +Any parameters which appear in the function call, as defined in the LAN +Manager API documentation, after the "Server" and up to and including the +"uLevel" parameters. +</para></listitem> + +<listitem><para> +An unsigned 16 bit integer which gives the size in bytes of the buffer we +will use to receive the returned array of data structures. Presumably this +should be the same as mdrcnt. This value should be set with SSVAL(). +</para></listitem> + +<listitem><para> +An ASCIIZ string describing substructures which should be returned. If no +substructures apply, this string is of zero length. +</para></listitem> + +</orderedlist> + +<para> +The code in client.c always calls call_api() with no data. It is unclear +when a non-zero length data buffer would be sent. +</para> + +</sect2> + +<sect2> +<title>Return value</title> + +<para> +The returned parameters (pointed to by rparam), in their order of appearance +are:</para> + +<orderedlist> + +<listitem><para> +An unsigned 16 bit integer which contains the API function's return code. +This value should be read with SVAL(). +</para></listitem> + +<listitem><para> +An adjustment which tells the amount by which pointers in the returned +data should be adjusted. This value should be read with SVAL(). Basically, +the address of the start of the returned data buffer should have the returned +pointer value added to it and then have this value subtracted from it in +order to obtain the currect offset into the returned data buffer. +</para></listitem> + +<listitem><para> +A count of the number of elements in the array of structures returned. +It is also possible that this may sometimes be the number of bytes returned. +</para></listitem> +</orderedlist> + +<para> +When call_api() returns, rparam points to the returned parameters. The +first if these is the result code. It will be zero if the API call +suceeded. This value by be read with "SVAL(rparam,0)". +</para> + +<para> +The second parameter may be read as "SVAL(rparam,2)". It is a 16 bit offset +which indicates what the base address of the returned data buffer was when +it was built on the server. It should be used to correct pointer before +use. +</para> + +<para> +The returned data buffer contains the array of returned data structures. +Note that all pointers must be adjusted before use. The function +fix_char_ptr() in client.c can be used for this purpose. +</para> + +<para> +The third parameter (which may be read as "SVAL(rparam,4)") has something to +do with indicating the amount of data returned or possibly the amount of +data which can be returned if enough buffer space is allowed. +</para> + +</sect2> +</sect1> + +<sect1> +<title>Code character table</title> +<para> +Certain data structures are described by means of ASCIIz strings containing +code characters. These are the code characters: +</para> + +<orderedlist> +<listitem><para> +W a type byte little-endian unsigned integer +</para></listitem> +<listitem><para> +N a count of substructures which follow +</para></listitem> +<listitem><para> +D a four byte little-endian unsigned integer +</para></listitem> +<listitem><para> +B a byte (with optional count expressed as trailing ASCII digits) +</para></listitem> +<listitem><para> +z a four byte offset to a NULL terminated string +</para></listitem> +<listitem><para> +l a four byte offset to non-string user data +</para></listitem> +<listitem><para> +b an offset to data (with count expressed as trailing ASCII digits) +</para></listitem> +<listitem><para> +r pointer to returned data buffer??? +</para></listitem> +<listitem><para> +L length in bytes of returned data buffer??? +</para></listitem> +<listitem><para> +h number of bytes of information available??? +</para></listitem> +</orderedlist> + +</sect1> +</chapter> |