summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorJelmer Vernooij <jelmer@samba.org>2002-10-28 19:43:04 +0000
committerJelmer Vernooij <jelmer@samba.org>2002-10-28 19:43:04 +0000
commitdedc2c87757509f63e5979845664daaf62417c9a (patch)
tree5e7f7cba65e3653c9d59fb9a16db1ccc48de7720
parent26b9d7d12e6eff09473153a14822761e8a1300c2 (diff)
downloadsamba-dedc2c87757509f63e5979845664daaf62417c9a.tar.gz
samba-dedc2c87757509f63e5979845664daaf62417c9a.tar.bz2
samba-dedc2c87757509f63e5979845664daaf62417c9a.zip
Sync with hEAD
(This used to be commit d3c29d2902420f434b2505568c82dd6e1508a00f)
-rw-r--r--source3/internals.doc281
1 files changed, 0 insertions, 281 deletions
diff --git a/source3/internals.doc b/source3/internals.doc
deleted file mode 100644
index c8cc6dd136..0000000000
--- a/source3/internals.doc
+++ /dev/null
@@ -1,281 +0,0 @@
-internals.txt, 8 May 1996
-Written by David Chappell <David.Chappell@mail.trincoll.edu>.
-
-This document describes some of the internal functions which must be
-understood by anyone wishing to add features to Samba.
-
-
-
-=============================================================================
-This section describes character set handling in Samba, as implemented in
-Samba 3.0 and above
-
-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.
-
-The new system works like this:
-
-- 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.
-
-- there is no single fixed character set for unix strings, but any
- character set that is used does need the following properties:
- * must not contain NULLs except for termination
- * 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.
- * when you uppercase or lowercase a string it does not become
- longer than the original string
- * must be able to correctly hold all characters that your client
- will throw at it
- 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.
-
-- 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.
-
-- 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.
-
- 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()
-
-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.
-
-Other rules:
-
- - all lp_ functions now return unix strings. The magic "DOS" flag on
- parameters is gone.
- - all vfs functions take unix strings. Don't convert when passing to
- them
-
-
-=============================================================================
-This section describes the macros defined in byteorder.h. These macros
-are used extensively in the Samba code.
-
------------------------------------------------------------------------------
-CVAL(buf,pos)
-
-returns the byte at offset pos within buffer buf as an unsigned character.
-
------------------------------------------------------------------------------
-PVAL(buf,pos)
-
-returns the value of CVAL(buf,pos) cast to type unsigned integer.
-
------------------------------------------------------------------------------
-SCVAL(buf,pos,val)
-
-sets the byte at offset pos within buffer buf to value val.
-
------------------------------------------------------------------------------
-SVAL(buf,pos)
-
-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".
-
------------------------------------------------------------------------------
-IVAL(buf,pos)
-
-returns the value of the unsigned 32 bit little-endian integer at offset
-pos within buffer buf.
-
------------------------------------------------------------------------------
-SVALS(buf,pos)
-
-returns the value of the signed short (16 bit) little-endian integer at
-offset pos within buffer buf.
-
------------------------------------------------------------------------------
-IVALS(buf,pos)
-
-returns the value of the signed 32 bit little-endian integer at offset pos
-within buffer buf.
-
------------------------------------------------------------------------------
-SSVAL(buf,pos,val)
-
-sets the unsigned short (16 bit) little-endian integer at offset pos within
-buffer buf to value val.
-
------------------------------------------------------------------------------
-SIVAL(buf,pos,val)
-
-sets the unsigned 32 bit little-endian integer at offset pos within buffer
-buf to the value val.
-
------------------------------------------------------------------------------
-SSVALS(buf,pos,val)
-
-sets the short (16 bit) signed little-endian integer at offset pos within
-buffer buf to the value val.
-
------------------------------------------------------------------------------
-SIVALS(buf,pos,val)
-
-sets the signed 32 bit little-endian integer at offset pos withing buffer
-buf to the value val.
-
------------------------------------------------------------------------------
-RSVAL(buf,pos)
-
-returns the value of the unsigned short (16 bit) big-endian integer at
-offset pos within buffer buf.
-
------------------------------------------------------------------------------
-RIVAL(buf,pos)
-
-returns the value of the unsigned 32 bit big-endian integer at offset
-pos within buffer buf.
-
------------------------------------------------------------------------------
-RSSVAL(buf,pos,val)
-
-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".
-
------------------------------------------------------------------------------
-RSIVAL(buf,pos,val)
-
-sets the value of the unsigned 32 bit big-endian integer at offset
-pos within buffer buf to value val.
-
-
-
-
-
-=============================================================================
-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.
-
------------------------------------------------------------------------------
-call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt,
- char *param, char *data, char **rparam, char **rdata);
-
-This function is defined in client.c. It uses an SMB transaction to call a
-remote api.
-
-The parameters are as follows:
-
-prcnt: the number of bytes of parameters begin sent.
-drcnt: the number of bytes of data begin sent.
-mprcnt: the maximum number of bytes of parameters which should be returned
-mdrcnt: the maximum number of bytes of data which should be returned
-param: a pointer to the parameters to be sent.
-data: a pointer to the data to be sent.
-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.
-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.
-
------------------------------------------------------------------------------
-These are the parameters which you ought to send, in the order of their
-appearance in the parameter block:
-
-* An unsigned 16 bit integer API number. You should set this value with
-SSVAL(). I do not know where these numbers are described.
-
-* 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.
-
-* An ASCIIZ string describing the data structure which ought to be returned.
-
-* 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.
-
-* 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().
-
-* An ASCIIZ string describing substructures which should be returned. If no
-substructures apply, this string is of zero length.
-
------------------------------------------------------------------------------
-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.
-
------------------------------------------------------------------------------
-The returned parameters (pointed to by rparam), in their order of appearance
-are:
-
-* An unsigned 16 bit integer which contains the API function's return code.
-This value should be read with SVAL().
-
-* 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.
-
-* 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.
-
------------------------------------------------------------------------------
-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)".
-
-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.
-
-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.
-
-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.
-
------------------------------------------------------------------------------
-Certain data structures are described by means of ASCIIz strings containing
-code characters. These are the code characters:
-
-W a type byte little-endian unsigned integer
-N a count of substructures which follow
-D a four byte little-endian unsigned integer
-B a byte (with optional count expressed as trailing ASCII digits)
-z a four byte offset to a NULL terminated string
-l a four byte offset to non-string user data
-b an offset to data (with count expressed as trailing ASCII digits)
-r pointer to returned data buffer???
-L length in bytes of returned data buffer???
-h number of bytes of information available???
-
-----------------------------------------------------------------------------