source3/internals.doc

   1 internals.txt, 8 May 1996
   2 Written by David Chappell <David.Chappell@mail.trincoll.edu>.
   3
   4 This document describes some of the internal functions which must be
   5 understood by anyone wishing to add features to Samba.
   6
   7
   8
   9
  10
  11 =============================================================================
  12 This section describes the macros defined in byteorder.h.  These macros
  13 are used extensively in the Samba code.
  14
  15 -----------------------------------------------------------------------------
  16 CVAL(buf,pos)
  17
  18 returns the byte at offset pos within buffer buf as an unsigned character.
  19
  20 -----------------------------------------------------------------------------
  21 PVAL(buf,pos)
  22
  23 returns the value of CVAL(buf,pos) cast to type unsigned integer.
  24
  25 -----------------------------------------------------------------------------
  26 SCVAL(buf,pos,val)
  27
  28 sets the byte at offset pos within buffer buf to value val.
  29
  30 -----------------------------------------------------------------------------
  31 SVAL(buf,pos)
  32
  33 returns the value of the unsigned short (16 bit) little-endian integer at
  34 offset pos within buffer buf.  An integer of this type is sometimes
  35 refered to as "USHORT".
  36
  37 -----------------------------------------------------------------------------
  38 IVAL(buf,pos)
  39
  40 returns the value of the unsigned 32 bit little-endian integer at offset
  41 pos within buffer buf.
  42
  43 -----------------------------------------------------------------------------
  44 SVALS(buf,pos)
  45
  46 returns the value of the signed short (16 bit) little-endian integer at
  47 offset pos within buffer buf.
  48
  49 -----------------------------------------------------------------------------
  50 IVALS(buf,pos)
  51
  52 returns the value of the signed 32 bit little-endian integer at offset pos
  53 within buffer buf.
  54
  55 -----------------------------------------------------------------------------
  56 SSVAL(buf,pos,val)
  57
  58 sets the unsigned short (16 bit) little-endian integer at offset pos within
  59 buffer buf to value val.
  60
  61 -----------------------------------------------------------------------------
  62 SIVAL(buf,pos,val)
  63
  64 sets the unsigned 32 bit little-endian integer at offset pos within buffer
  65 buf to the value val.
  66
  67 -----------------------------------------------------------------------------
  68 SSVALS(buf,pos,val)
  69
  70 sets the short (16 bit) signed little-endian integer at offset pos within
  71 buffer buf to the value val.
  72
  73 -----------------------------------------------------------------------------
  74 SIVALS(buf,pos,val)
  75
  76 sets the signed 32 bit little-endian integer at offset pos withing buffer
  77 buf to the value val.
  78
  79 -----------------------------------------------------------------------------
  80 RSVAL(buf,pos)
  81
  82 returns the value of the unsigned short (16 bit) big-endian integer at
  83 offset pos within buffer buf.
  84
  85 -----------------------------------------------------------------------------
  86 RIVAL(buf,pos)
  87
  88 returns the value of the unsigned 32 bit big-endian integer at offset
  89 pos within buffer buf.
  90
  91 -----------------------------------------------------------------------------
  92 RSSVAL(buf,pos,val)
  93
  94 sets the value of the unsigned short (16 bit) big-endian integer at
  95 offset pos within buffer buf to value val.
  96 refered to as "USHORT".
  97
  98 -----------------------------------------------------------------------------
  99 RSIVAL(buf,pos,val)
 100
 101 sets the value of the unsigned 32 bit big-endian integer at offset
 102 pos within buffer buf to value val.
 103
 104
 105
 106
 107
 108 =============================================================================
 109 This section describes the functions need to make a LAN Manager RPC call.
 110 This information had been obtained by examining the Samba code and the LAN
 111 Manager 2.0 API documentation.  It should not be considered entirely
 112 reliable.
 113
 114 -----------------------------------------------------------------------------
 115 call_api(int prcnt, int drcnt, int mprcnt, int mdrcnt,
 116         char *param, char *data, char **rparam, char **rdata);
 117
 118 This function is defined in client.c.  It uses an SMB transaction to call a
 119 remote api.
 120
 121 The parameters are as follows:
 122
 123 prcnt:   the number of bytes of parameters begin sent.
 124 drcnt:   the number of bytes of data begin sent.
 125 mprcnt:  the maximum number of bytes of parameters which should be returned
 126 mdrcnt:  the maximum number of bytes of data which should be returned
 127 param:   a pointer to the parameters to be sent.
 128 data:    a pointer to the data to be sent.
 129 rparam:  a pointer to a pointer which will be set to point to the returned
 130          paramters.  The caller of call_api() must deallocate this memory.
 131 rdata:   a pointer to a pointer which will be set to point to the returned
 132          data.  The caller of call_api() must deallocate this memory.
 133
 134 -----------------------------------------------------------------------------
 135 These are the parameters which you ought to send, in the order of their
 136 appearance in the parameter block:
 137
 138 * An unsigned 16 bit integer API number.  You should set this value with
 139 SSVAL().  I do not know where these numbers are described.
 140
 141 * An ASCIIZ string describing the parameters to the API function as defined
 142 in the LAN Manager documentation.  The first parameter, which is the server
 143 name, is ommited.  This string is based uppon the API function as described
 144 in the manual, not the data which is actually passed.
 145
 146 * An ASCIIZ string describing the data structure which ought to be returned.
 147
 148 * Any parameters which appear in the function call, as defined in the LAN
 149 Manager API documentation, after the "Server" and up to and including the
 150 "uLevel" parameters.
 151
 152 * An unsigned 16 bit integer which gives the size in bytes of the buffer we
 153 will use to receive the returned array of data structures.  Presumably this
 154 should be the same as mdrcnt.  This value should be set with SSVAL().
 155
 156 * An ASCIIZ string describing substructures which should be returned.  If no
 157 substructures apply, this string is of zero length.
 158
 159 -----------------------------------------------------------------------------
 160 The code in client.c always calls call_api() with no data.  It is unclear
 161 when a non-zero length data buffer would be sent.
 162
 163 -----------------------------------------------------------------------------
 164 The returned parameters (pointed to by rparam), in their order of appearance
 165 are:
 166
 167 * An unsigned 16 bit integer which contains the API function's return code.
 168 This value should be read with SVAL().
 169
 170 * An adjustment which tells the amount by which pointers in the returned
 171 data should be adjusted.  This value should be read with SVAL().  Basically,
 172 the address of the start of the returned data buffer should have the returned
 173 pointer value added to it and then have this value subtracted from it in
 174 order to obtain the currect offset into the returned data buffer.
 175
 176 * A count of the number of elements in the array of structures returned.
 177 It is also possible that this may sometimes be the number of bytes returned.
 178
 179 -----------------------------------------------------------------------------
 180 When call_api() returns, rparam points to the returned parameters.  The
 181 first if these is the result code.  It will be zero if the API call
 182 suceeded.  This value by be read with "SVAL(rparam,0)".
 183
 184 The second parameter may be read as "SVAL(rparam,2)".  It is a 16 bit offset
 185 which indicates what the base address of the returned data buffer was when
 186 it was built on the server.  It should be used to correct pointer before
 187 use.
 188
 189 The returned data buffer contains the array of returned data structures.
 190 Note that all pointers must be adjusted before use.  The function
 191 fix_char_ptr() in client.c can be used for this purpose.
 192
 193 The third parameter (which may be read as "SVAL(rparam,4)") has something to
 194 do with indicating the amount of data returned or possibly the amount of
 195 data which can be returned if enough buffer space is allowed.
 196
 197 -----------------------------------------------------------------------------
 198 Certain data structures are described by means of ASCIIz strings containing
 199 code characters.  These are the code characters:
 200
 201 W       a type byte little-endian unsigned integer
 202 N       a count of substructures which follow
 203 D       a four byte little-endian unsigned integer
 204 B       a byte (with optional count expressed as trailing ASCII digits)
 205 z       a four byte offset to a NULL terminated string
 206 l       a four byte offset to non-string user data
 207 b       an offset to data (with count expressed as trailing ASCII digits)
 208 r       pointer to returned data buffer???
 209 L       length in bytes of returned data buffer???
 210 h       number of bytes of information available???
 211
 212 ----------------------------------------------------------------------------