source4/build/pidl/NOTES.txt

   1 midl types
   2 ----------
   3
   4 pidl uses slightly different types to midl by default. The following
   5 defines in your MS IDL may make things easier to use the same IDL on
   6 both platforms.
   7
   8 #define unistr [string] wchar_t *
   9 #define uint8 char
  10 #define uint16 short
  11 #define uint32 long
  12 #define HYPER_T hyper
  13
  14
  15 Let's look at the mutliple ways you can encode an array.
  16
  17 CONFORMANT ARRAYS
  18 -----------------
  19
  20 A conformant array is one with that ends in [*] or []. The strange
  21 things about conformant arrays are:
  22
  23  * they can only appear as the last element of a structure
  24
  25  * the array size appears before the structure itself on the wire.
  26
  27 So, in this example:
  28
  29         typedef struct {
  30                 long abc;
  31                 long count;
  32                 long foo;
  33                 [size_is(count)] long s[*];
  34         } Struct1;
  35
  36 it appears like this:
  37
  38 [size_is] [abc] [count] [foo] [s...]
  39
  40 the first [size_is] field is the allocation size of the array, and
  41 occurs before the array elements and even before the structure
  42 alignment.
  43
  44 Note that size_is() can refer to a constant, but that doesn't change
  45 the wire representation. It does not make the array a fixed array.
  46
  47 midl.exe would write the above array as the following C header:
  48
  49        typedef struct {
  50                 long abc;
  51                 long count;
  52                 long foo;
  53                 long s[1];
  54         } Struct1;
  55
  56 pidl takes a different approach, and writes it like this:
  57
  58        typedef struct {
  59                 long abc;
  60                 long count;
  61                 long foo;
  62                 long *s;
  63         } Struct1;
  64
  65
  66
  67 VARYING ARRAYS
  68 --------------
  69
  70 A varying array looks like this:
  71
  72         typedef struct {
  73                 long abc;
  74                 long count;
  75                 long foo;
  76                 [size_is(count)] long *s;
  77         } Struct1;
  78
  79 This will look like this on the wire:
  80
  81 [abc] [count] [foo] [PTR_s]    [count] [s...]
  82
  83
  84 FIXED ARRAYS
  85 ------------
  86
  87 A fixed array looks like this:
  88
  89     typedef struct {
  90             long s[10];
  91     } Struct1;
  92
  93 The NDR representation looks just like 10 separate long
  94 declarations. The array size is not encoded on the wire.
  95
  96 pidl also supports "inline" arrays, which are not part of the IDL/NDR
  97 standard. These are declared like this:
  98
  99     typedef struct {
 100             uint32 foo;
 101             uint32 count;
 102             uint32 bar;
 103             long s[count];
 104     } Struct1;
 105
 106 This appears like this:
 107
 108 [foo] [count] [bar] [s...]
 109
 110 Fixed arrays are an extension added to support some of the strange
 111 embedded structures in security descriptors and spoolss.
 112
 113 Supported MIDL-compatible properties (attributes is the MIDL term)
 114 ------------------------------------
 115 in
 116 out
 117 ref
 118 public
 119 length_is
 120 switch_is
 121 size_is
 122 uuid
 123 case
 124 default
 125 string
 126 unique
 127
 128 PIDL Specific properties
 129 ---------------
 130 noprint
 131 value
 132 relative
 133 subcontext
 134 flag
 135
 136 Unsupported MIDL properties
 137 ---------------------------
 138 aggregatable
 139 appobject
 140 async_uuid
 141 bindable
 142 call_as
 143 coclass
 144 control
 145 cpp_quote
 146 defaultbind
 147 defaultcollelem
 148 defaultvalue
 149 defaultvtable
 150 dispinterface
 151 displaybind
 152 dual
 153 entry
 154 first_is
 155 helpcontext
 156 helpfile
 157 helpstringcontext
 158 helpstringdll
 159 helpstring
 160 hidden
 161 idl_module
 162 idl_quote
 163 id
 164 iid_is
 165 immediatebind
 166 importlib
 167 import
 168 include
 169 includelib
 170 last_is
 171 lcid
 172 licensed
 173 local
 174 max_is
 175 module
 176 ms_union
 177 no_injected_text
 178 nonbrowsable
 179 noncreatable
 180 nonextensible
 181 object
 182 odl
 183 oleautomation
 184 optional
 185 pointer_default
 186 pragma
 187 progid
 188 propget
 189 propputref
 190 propput
 191 ptr
 192 range
 193 readonly
 194 requestedit
 195 restricted
 196 retval
 197 source
 198 switch_type
 199 transmit_as
 200 uidefault
 201 usesgetlasterror
 202 v1_enum
 203 vararg
 204 vi_progid
 205 wire_marshal
 206
 207 [public] property
 208 -----------------
 209
 210 The [public] property on a structure or union is a pidl extension that
 211 forces the generated pull/push functions to be non-static. This allows
 212 you to declare types that can be used between modules. If you don't
 213 specify [public] then pull/push functions for other than top-level
 214 functions are declared static.
 215
 216 [relative] property
 217 -------------------
 218
 219 The [relative] property can be supplied on a pointer. When it is used
 220 it declares the pointer as a spoolss style "relative" pointer, which
 221 means it appears on the wire as an offset within the current
 222 encapsulating structure. This is not part of normal IDL/NDR, but it is
 223 a very useful extension as it avoids the manual encoding of many
 224 complex structures.
 225
 226
 227 [noprint] property
 228 ------------------
 229
 230 The [noprint] property is a pidl extension that allows you to specify
 231 that pidl should not generate a ndr_print_*() function for that
 232 structure or union. This is used when you wish to define your own
 233 print function that prints a structure in a nicer manner. A good
 234 example is the use of [noprint] on dom_sid, which allows the
 235 pretty-printing of SIDs.
 236
 237 [value] property
 238 ----------------
 239
 240 The [value(expression)] property is a pidl extension that allows you
 241 to specify the value of a field when it is put on the wire. This
 242 allows fields that always have a well-known value to be automatically
 243 filled in, thus making the API more programmer friendly. The
 244 expression can be any C expression, although if you refer to variables
 245 in the current structure you will need to dereference them with
 246 r->. See samr_Name as a good example.
 247
 248
 249 [nodiscriminant] property
 250 -------------------------
 251
 252 The [nodiscriminant] property on a union means that the usual uint16
 253 discriminent field at the start of the union on the wire is
 254 omitted. This is not normally allowed in IDL/NDR, but is used for some
 255 spoolss structures.
 256
 257
 258 VALIDATOR
 259 ---------
 260
 261 We need to write an IDL validator, so we know that we are writing
 262 valid IDL. Right now the compiler sails on regardless in many cases
 263 even if the IDL is invalid (for example, I don't check that conformant
 264 arrays are always the last element in any structure). There are dozens
 265 of rules that should be checked.