nexmon – Blame information for rev 1

Subversion Repositories:
Rev:
Rev Author Line No. Line
1 office 1 README.wslua
2  
3 This is a HOWTO for adding support for new Lua hooks/functions/abilities in
4 Wireshark. If you see any errors or have any improvements, submit patches -
5 free software is a community effort....
6  
7 This is NOT a guide for how to write Lua plugins - that's documented already
8 on the Wireshark webpages.
9  
10 Contributors to this README:
11 Hadriel Kaplan <hadrielk[AT]yahoo.com>
12  
13 ==============================================================================
14  
15 Overview:
16  
17 The way Wireshark exposes functions for Lua is generally based on a
18 callback/event model, letting Lua plugins register their custom Lua functions
19 into event callbacks. C-based "objects" are exposed as Lua tables with
20 typical Lua USERDATA pointer dispatching, plain C-functions are registered as
21 such in Lua, and C-based enums/variables are registered into Lua as table
22 key=value (usually... though rarely they're registered as array indexed
23 values). All of that is very typical for applications that expose things
24 into a Lua scripting environment.
25  
26 The details that make it a little different are (1) the process by which the
27 code is bound/registered into Lua, and (2) the API documentation generator.
28 Wireshark uses C-macros liberally, both for the usual reasons as well as for
29 the binding generator and documentation generator scripts. The macros are
30 described within this document.
31  
32 The API documentation is auto-generated from a Perl script called 'make-
33 wsluarm.pl', which searches C-files for the known macros and generates
34 appropriate HTML documentation from them. This includes using the C-comments
35 after the macros for the API document info.
36  
37 Likewise, another Perl script called 'make-reg.pl' generates the C-files
38 'register_wslua.c' and 'declare_wslua.h', based on the C-macros it searches
39 for in existing source files. The code this Perl script auto-generates is
40 what actually registers some classes/functions into Lua - you don't have to
41 write your own registration functions to get your new functions/classes into
42 Lua tables. (you can do so, but it's not advisable)
43  
44 Both of the perl scripts above are given the C-source files to search through
45 by the make process, generated from the lists in epan/wslua/CMakeLists.txt.
46 Naturally if you add new source files, you need to add them to the list in
47 epan/wslua/CMakeLists.txt and epan/wslua/Makefile.am. You also have to add
48 the module name into docbook/user-guide.xml and docbook/wsluarm.xml, and the
49 source files into docbook/CMakeLists.txt and docbook/Makefile.am, to get
50 it to be generated in the user guide.
51  
52 Another Perl script is used as well, called 'make-init-lua.pl', which
53 generates the init.lua script. A large part of it deals with exposing #define
54 values into the Lua global table, or sub-tables. Unfortunately not all of
55 them are put in sub-tables, which means the global Lua table is quite polluted
56 now. If you add new ones in here, please think of putting them in a subtable,
57 as they are for wtap, ftypes, and base. For example, there are several put in
58 as 'PI_' prefixed names, such as 'PI_SEVERITY_MASK = 15728640'. The fact they
59 all have a common 'PI_' prefix should be an indicator they can be put in a
60 table named PI, or PacketInfo. Just because C-code doesn't have namespaces,
61 doesn't mean Lua can't. This has now been fixed, and the PI_* names are now in
62 two separate subtables of a table named 'expert', as 'expert.group' and
63 'expert.severity' subtables. Follow that model in 'make-init-lua.pl'.
64  
65  
66 Due to those documentation and registration scripts, you MUST follow some very
67 specific conventions in the functions you write to expose C-side code to Lua,
68 as described in this document.
69  
70 Naming conventions/rules:
71  
72 Class/object names must be UpperCamelCase, no numbers/underscores.
73 Function and method names must be lower_underscore_case, no numbers.
74 Constants/enums must be ALLCAPS, and can have numbers.
75  
76 The above rules are more than merely conventions - the Perl scripts which
77 auto-generate stuff use regex patterns that require the naming syntax to be
78 followed.
79  
80 ==============================================================================
81  
82 Documenting things for the API docs:
83  
84 As explained previously, the API documentation is auto-generated from a
85 Perl script called 'make-wsluarm.pl', which searches C-files for the known
86 macros and generates appropriate HTML documentation from them. This includes
87 using the C-comments after the macros for the API document info. The comments
88 are extremely important, because the API documentation is what most Lua script
89 authors will see - do *not* expect them to go looking through the C-source code
90 to figure things out.
91  
92 Please make sure to at least use the '@since' version notification markup
93 in your comments, to let users know when the new class/function/etc. you
94 created became available.
95  
96 Because documentation is so important, the make-wsluarm.pl script supports
97 specific markup syntax in comments, and converts them to XML and ultimately
98 into the various documentation formats. The markup syntax is documented in
99 the top comments in make-wsluarm.pl, but are repeated here as well:
100 - two (or more) line breaks in comments result in separate paragraphs
101 - all '&' are converted into their entity names, except inside urls
102 - all '<', and '>' are converted into their entity names everywhere
103 - any word(s) wrapped in one star, e.g., *foo bar*, become italics
104 - any word(s) wrapped in two stars, e.g., **foo bar**, become bold
105 - any word(s) wrapped in backticks, e.g., `foo bar`, become bold (for now)
106 - any word(s) wrapped in two backticks, e.g., ``foo bar``, become one backtick
107 - any "[[url]]" becomes an XML ulink with the url as both the url and text
108 - any "[[url|text]]" becomes an XML ulink with the url as the url and text as text
109 - any indent with a single leading star '*' followed by space is a bulleted list item
110 reducing indent or having an extra linebreak stops the list
111 - any indent with a leading digits-dot followed by space, i.e. "1. ", is a numbered list item
112 reducing indent or having an extra linebreak stops the list
113 - supports meta-tagged info inside comment descriptions as follows:
114 * a line starting with "@note" or "Note:" becomes an XML note line
115 * a line starting with "@warning" or "Warning:" becomes an XML warning line
116 * a line starting with "@version" or "@since" becomes a "Since:" line
117 * a line starting with "@code" and ending with "@endcode" becomes an
118 XML programlisting block, with no indenting/parsing within the block
119 The above '@' commands are based on Doxygen commands
120  
121  
122 ==============================================================================
123  
124 Some implementation details:
125  
126 Creating new C-classes for Lua:
127  
128 Explaining the Lua class/object model and how it's bound to C-code functions
129 and data types is beyond the scope of this document; if you don't already know
130 how that works, I suggest you start reading lua-users.org's wiki, and
131 lua.org's free reference manual.
132  
133 Wireshark generally uses a model close to the typical binding
134 model: 'registering' class methods and metamethods, pushing objects into Lua
135 by applying the class' metatable to the USERDATA, etc. This latter part is
136 mostly handled for you by the C-macro's created by WSLUA_CLASS_DEFINE, such as
137 push/check, described later in this document.
138  
139 The actual way methods are dispatched is a little different from normal Lua
140 bindings, because attributes are supported as well (see next section). The
141 details won't be covered in this document - they're documented in the code
142 itself in: wslua_internals.c above the wslua_reg_attributes function.
143  
144 Registering a class requires you to write some code: a WSLUA_METHODS table,
145 a WSLUA_META table, and a registration function. The WSLUA_METHODS table is an
146 array of luaL_Reg structs, which map a string name that will be the function's
147 name in Lua, to a C-function pointer which is the C-function to be invoked by
148 Lua when the user calls the name. Instead of defining this array of structs
149 explicitly using strings and function names, you should use the WSLUA_METHODS
150 macro name for the array, and use WSLUA_CLASS_FNREG macro for each entry.
151 The WSLUA_META table follows the same behavior, with the WSLUA_CLASS_MTREG
152 macro for each entry. Make sure your C-function names use two underscores
153 instead of one.
154  
155 Once you've created the appropriate array tables, define a registration
156 function named 'ClassName_register', where 'ClassName'is your class name, the
157 same one used in WSLUA_CLASS_DEFINE. The make-reg.pl Perl script will search
158 your file for WSLUA_CLASS_DEFINE, and it generates a register_wslua.c which
159 will call your ClassName_register function during Wireshark initialization.
160 Inside your ClassName_register function, use either the WSLUA_REGISTER_CLASS
161 or the WSLUA_REGISTER_META macros with the class name as the argument. That
162 will automatically register the methods/meta tables into Lua. Use
163 WSLUA_REGISTER_CLASS if your class has methods and optionally metamethods, or
164 use WSLUA_REGISTER_META if it only has metamethods - do *not* use both. Note
165 that your class does not need to have a WSLUA_METHODS nor WSLUA_META table.
166 Also, you should read the 'Memory management model' section later in this
167 document.
168  
169 Class member variable attributes (getters/setters):
170  
171 The current implementation does not follow a single/common class-variable
172 attribute accessor model for the Lua API: some class member values are
173 populated/retrieved when a table field attribute is used that triggers the
174 __index or __newindex metamethods, and others are accessed through explicit
175 getter/setter method functions. In other words from a Lua code perspective
176 some class object variables are retrieves as 'foo = myObj.var', while others
177 are done as 'foo = myObj.getVar()'.
178  
179 From the C-side code perspective, some classes register no real method
180 functions but just have attributes (and use the WSLUA_ATTRIBUTE documentation
181 model for them). For example the FieldInfo class in wslua_field.c does this.
182 Other classes provide access to member variable through getter/setter method
183 functions (and thus use the WSLUA_METHOD documentation model). For example
184 the TvbRange class in wslua_tvb.c does this. Using the latter model of having
185 a getter/setter method function allows one to pass multiple arguments, whereas
186 the former __index/__newindex metamethod model does not. Both models are
187 fairly common in Lua APIs, although having a mixture of both in the same API
188 probably isn't. There is even a third model in use: pre-loading the member
189 fields of the class table with the values, instead of waiting for the Lua
190 script to access a particular one to retrieve it; for example the Listener tap
191 extractors table is pre-populated (see files 'wslua_listener.c' and 'taps'
192 which through the make-taps.pl perl script creates 'taps_wslua.c'). The
193 downside of that approach is the performance impact, filling fields the Lua
194 script may never access. Lastly, the Field, FieldInfo, and Tvb's ByteArray
195 type each provide a __call metamethod as an accessor - I strongly suggest you
196 do NOT do that, as it's not a common model and will confuse people since it
197 doesn't follow the model of the other classes in Wireshark.
198  
199 The way attribute accessing is handled is a bit too complicated to discuss
200 here, but is documented in wslua_internals.c above the wslua_reg_attributes
201 function definition. All you need to know is how to write the C-code to
202 register attributes, and the code to provide getter/setters for them. To
203 create them, you create an array table similar to the WSLUA_METHODS and
204 WSLUA_META tables, except using the macro name WSLUA_ATTRIBUTES. Inside this
205 array, each entry should use one of the following macros: WSLUA_ATTRIBUTE_ROREG,
206 WSLUA_ATTRIBUTE_WOREG, or WSLUA_ATTRIBUTE_RWREG. Those provide the hooks for
207 a getter-only, setter-only, or both getter and setter function. The functions
208 themselves need to follow a naming scheme of ClassName_get_attributename(),
209 or ClassName_set_attributename(), for the respective getter vs. setter function.
210 Trivial getters/setters have macros provided to make this automatic, for things
211 such as getting numbers, strings, etc. The macros are in wslua.h. For example,
212 the WSLUA_ATTRIBUTE_NAMED_BOOLEAN_GETTER(Foo,bar,choo) macro creates a getter
213 function to get the boolean value of the Class Foo's choo member variable, as
214 the Lua attribute named 'bar'.
215  
216 To register the attributes, your Class registration function must call the
217 WSLUA_REGISTER_ATTRIBUTES(ClassName) macro, after it calls either the
218 WSLUA_REGISTER_META(ClassName) macro or the WSLUA_REGISTER_CLASS(ClassName)
219 one.
220  
221 Callback function registration:
222  
223 For some callbacks, there are register_* Lua global functions, which take a
224 user-defined Lua function name as the argument - the one to be hooked into
225 that event. Unlike in most Lua APIs, there's a unique register_foo() function
226 for each event type, instead of a single register() with the event as an
227 argument. For example there's a register_postdissector() function. In some
228 cases the Lua functions are invoked based on a pre-defined function-name model
229 instead of explicit register_foo(), whereby a C-object looks for a defined
230 member variable in the Registry that represents a Lua function created by the
231 plugin. This would be the case if the Lua plugin had defined a pre-defined
232 member key of its object's table in Lua, for that purpose. For example if the
233 Lua plugin sets the 'reset' member of the Listener object table to a function,
234 then Wireshark creates a Registry entry for that Lua function, and executes
235 that Lua function when the Listener resets. (see the example Listener Lua
236 script in the online docs) That model is only useful if the object can only be
237 owned by one plugin so only one function is ever hooked, obviously, and thus
238 only if it's created by the Lua plugin (e.g., Listener.new()).
239  
240 Creating new Listener tap types:
241  
242 The Listener object is one of the more complicated ones. When the Lua script
243 creates a Listener (using Listener.new()), the code creates and returns a tap
244 object. The type of tap is based on the passed-in argument to Listener.new(),
245 and it creates a Lua table of the tap member variables. That happens in
246 taps_wslua.c, which is an auto-generated file from make-taps.pl. That Perl
247 script reads from a file called 'taps', which identifies every struct name
248 (and associated enum name) that should be exposed as a tap type. The Perl
249 script then generates the taps_wslua.c to push those whenever the Listener
250 calls for a tap; and it also generates a taps.tx file documenting them all.
251 So to add a new type, add the info to the taps file (or uncomment an existing
252 one), and make sure every member of the tap struct you're exposing is of a
253 type that make-taps.pl has in its Perl %types and %comments associative
254 arrays.
255  
256 Note on Lua versions:
257  
258 Wireshark supports both Lua 5.1 and 5.2, which are defined as LUA_VERSION_NUM
259 values 501 and 502 respectively. When exposing things into Lua, make sure to
260 use ifdef wrappers for things which changed between the versions of Lua. See
261 this for details: http://www.lua.org/manual/5.2/manual.html#8.3
262  
263 ==============================================================================
264  
265 Defined Macros for Lua-API C-files:
266  
267 WSLUA_MODULE - this isn't actually used in real C-code, but rather only
268 appears in C-comments at the top of .c files. That's because it's purely used
269 for documentation, and it makes a new section in the API documentation.
270  
271 For example, this appears near the top of the wslua_gui.c file:
272  
273 /* WSLUA_MODULE Gui GUI support */
274  
275 That makes the API documentation have a section titled 'GUI support' (it's
276 currently section 11.7 in the API docs). It does NOT mean there's any Lua
277 table named 'Gui' (in fact there isn't). It's just for documentation.
278 If you look at the documentation, you'll see there is 'ProgDlg', 'TextWindow',
279 etc. in that 'GUI support' section. That's because both ProgDlg and
280 TextWindow are defined in that same wslua_gui.c file using the
281 'WSLUA_CLASS_DEFINE' macro. (see description of that later) make-wsluarm.pl
282 created those in the same documentation section because they're in the same c
283 file as that WSLUA_MODULE comment. You'll also note the documentation
284 includes a sub-section for 'Non Method Functions', which it auto-generated
285 from anything with a 'WSLUA_FUNCTION' macro (as opposed to class member
286 functions, which use the 'WSLUA_METHOD' and 'WSLUA_CONSTRUCTOR' macros). Also,
287 to make new wslua files generate documentation, it is not sufficient to just
288 add this macro to a new file and add the file to the CMakeLists.txt; you also
289 have to add the module name into docbook/user-guide.xml, and docbook/wsluarm.xml.
290  
291  
292 WSLUA_CONTINUE_MODULE - like WSLUA_MODULE, except used at the top of a .c file
293 to continue defining classes/functions/etc. within a previously declared module
294 in a previous file (i.e., one that used WSLUA_MODULE). The module name must match
295 the original one, and the .c file must be listed after the original one in the
296 CMakeLists.txt/Makefile.am lists in the docbook directory.
297  
298  
299 WSLUA_ATTRIBUTE - this is another documentation-only "macro", only used within
300 comments. It makes the API docs generate documentation for a member variable
301 of a class, i.e. a key of a Lua table that is not called as a function in Lua,
302 but rather just retrieved or set. The 'WSLUA_ATTRIBUTE' token is followed by
303 a 'RO', 'WO', or 'RW' token, for Read-Only, Write-Only, or Read-Write. (ie,
304 whether the variable can be retrieved, written to, or both) This read/write
305 mode indication gets put into the API documentation. After that comes the name
306 of the attribute, which must be the class name followed by the specific
307 attribute name.
308  
309 Example:
310  
311 /* WSLUA_ATTRIBUTE Pinfo_rel_ts RO Number of seconds passed since beginning of capture */
312  
313  
314  
315 WSLUA_FUNCTION - this is used for any global Lua function (functions put into
316 the global table) you want to expose, but not for object-style methods (that's
317 the 'WSLUA_METHOD' macro), nor static functions within an object (that's
318 WSLUA_CONSTRUCTOR). Unlike many of the macros here, the function name must
319 begin with 'wslua_'. Everything after that prefix will be the name of the
320 function in Lua. You can ONLY use lower-case letters and the underscore
321 character in this function name. For example 'WSLUA_FUNCTION
322 wslua_get_foo(lua_State* L)' will become a Lua function named 'get_foo'.
323 Documentation for it will also be automatically generated, as it is for the
324 other macros. Although from a Lua perspective it is a global function (not in
325 any class' table), the documentation will append it to the documentation page
326 of the module/file its source code is in, in a "Non Method Functions" section.
327 Descriptive text about the function must be located after the '{' and optional
328 whitespace, within a '\*' '*\' comment block on one line.
329  
330 Example:
331  
332 WSLUA_FUNCTION wslua_gui_enabled(lua_State* L) { /* Checks whether the GUI facility is enabled. */
333 lua_pushboolean(L,GPOINTER_TO_INT(ops && ops->add_button));
334 WSLUA_RETURN(1); /* A boolean: true if it is enabled, false if it isn't. */
335 }
336  
337  
338 WSLUA_CLASS_DEFINE - this is used to define/create a new Lua class type (i.e.,
339 table with methods). A Class name must begin with an uppercase letter,
340 followed by any upper or lower case letters but not underscores; in other
341 words, UpperCamelCase without numbers. The macro is expanded to create a
342 bunch of helper functions - see wslua.h. Documentation for it will also be
343 automatically generated, as it is for the other macros.
344  
345 Example:
346  
347 WSLUA_CLASS_DEFINE(ProgDlg,NOP,NOP); /* Manages a progress bar dialog. */
348  
349  
350 WSLUA_CONSTRUCTOR - this is used to define a function of a class that is a
351 static function rather than a per-object method; i.e., from a Lua perspective
352 the function is called as 'myObj.func()' instead of 'myObj:func()'. From a
353 C-code perspective the code generated by make-reg.pl does not treat this
354 differently than a WSLUA_METHOD, the only real difference being that the code
355 you write within the function won't be checking the object instance as the
356 first passed-in argument on the Lua-API stack. But from a documentation
357 perspective this macro correctly documents the usage using a '.' period rather
358 than ':' colon. This can also be used within comments, but then it's
359 '_WSLUA_CONSTRUCTOR_'. The name of the function must use the Class name
360 first, followed by underscore, and then the specific lower_underscore name
361 that will end up being the name of the function in Lua.
362  
363 Example:
364  
365 WSLUA_CONSTRUCTOR Dissector_get (lua_State *L) {
366 /* Obtains a dissector reference by name */
367 #define WSLUA_ARG_Dissector_get_NAME 1 /* The name of the dissector */
368 const gchar* name = luaL_checkstring(L,WSLUA_ARG_Dissector_get_NAME);
369 Dissector d;
370  
371 if (!name)
372 WSLUA_ARG_ERROR(Dissector_get,NAME,"must be a string");
373  
374 if ((d = find_dissector(name))) {
375 pushDissector(L, d);
376 WSLUA_RETURN(1); /* The Dissector reference */
377 } else
378 WSLUA_ARG_ERROR(Dissector_get,NAME,"No such dissector");
379 }
380  
381  
382 WSLUA_METHOD - this is used for object-style class method definitions. The
383 documentation will use the colon syntax, and it will be called as
384 'myObj:func()' in Lua, so your function needs to check the first argument of
385 the stack for the object pointer. Two helper functions are automatically made
386 for this purpose, from the macro expansion of WSLUA_CLASS_DEFINE, of the
387 signatures 'MyObj toMyObj(lua_State* L, int idx)' and 'MyObj
388 checkMyObj(lua_State* L, int idx)'. They do the same thing, but the former
389 generates a Lua Error on failure, while the latter does not.
390  
391 Example:
392  
393 WSLUA_METHOD Listener_remove(lua_State* L) {
394 /* Removes a tap listener */
395 Listener tap = checkListener(L,1);
396 if (!tap) return 0;
397 remove_tap_listener(tap);
398 return 0;
399 }
400  
401  
402 WSLUA_METAMETHOD - this is used for defining object metamethods (ie, Lua
403 metatable functions). The documentation will describe these as well, although
404 currently it doesn't specify they're metamethods but rather makes them appear
405 as regular object methods. The name of it must be the class name followed by
406 *two* underscores, or else it will not appear in the documentation.
407  
408 Example:
409  
410 WSLUA_METAMETHOD NSTime__eq(lua_State* L) { /* Compares two NSTimes */
411 NSTime time1 = checkNSTime(L,1);
412 NSTime time2 = checkNSTime(L,2);
413 gboolean result = FALSE;
414  
415 if (!time1 || !time2)
416 WSLUA_ERROR(FieldInfo__eq,"Data source must be the same for both fields");
417  
418 if (nstime_cmp(time1, time2) == 0)
419 result = TRUE;
420  
421 lua_pushboolean(L,result);
422  
423 return 1;
424 }
425  
426  
427 WSLUA_ARG_ - the prefix used in a #define statement, for a required
428 function/method argument (ie, one without a default value). It is defined to
429 an integer representing the index slot number of the Lua stack it will be at,
430 when calling the appropriate lua_check/lua_opt routine to get it from the
431 stack. The make_wsluarm.pl Perl script will generate API documentation with
432 this argument name for the function/method, removing the 'WSLUA_ARG_' prefix.
433 The name following the 'WSLUA_ARG_' prefix must be the same name as the
434 function it's an argument for, followed by an underscore and then an ALLCAPS
435 argument name (including numbers is ok). Although this last part is in
436 ALLCAPS, it is documented in lowercase. The argument name itself is
437 meaningless since it does not exist in Lua or C code.
438  
439 Example: see the example in WSLUA_CONSTRUCTOR above, where
440 WSLUA_ARG_Dissector_get_NAME is used.
441  
442  
443 WSLUA_OPTARG_ - the prefix used in a #define statement, for an optional
444 function/method argument (ie, one with a default value). It is defined to an
445 integer representing the index slot number of the Lua stack it will be at,
446 when calling the appropriate lua_check/lua_opt routine to get it from the
447 stack. The make_wsluarm.pl Perl script will generate API documentation with
448 this argument name for the function/method, removing the 'WSLUA_OPTARG_'
449 prefix. The rules for the name of the argument after the prefix are the same
450 as for 'WSLUA_ARG_' above.
451  
452 Example:
453  
454 #define WSLUA_OPTARG_Dumper_new_FILETYPE 2 /* The type of the file to be created */
455  
456  
457 WSLUA_MOREARGS - a documentation-only macro used to document that more
458 arguments are expected/supported. This is useful when the number of
459 arguments is not fixed, i.e., a vararg model. The macro is followed by the
460 name of the function it's an argument for (without the 'wslua_' prefix if the
461 function is a WSLUA_FUNCTION type), and then followed by descriptive text.
462  
463 Example:
464  
465 WSLUA_FUNCTION wslua_critical( lua_State* L ) { /* Will add a log entry with critical severity*/
466 /* WSLUA_MOREARGS critical objects to be printed */
467 wslua_log(L,G_LOG_LEVEL_CRITICAL);
468 return 0;
469 }
470  
471  
472 WSLUA_RETURN - a macro with parentheses containing the number of return
473 values, meaning the number of items pushed back to Lua. Lua supports multiple
474 return values, although Wireshark usually just returns 0 or 1 value. The
475 argument can be an integer or a variable of the integer, and is not actually
476 documented. The API documentation will use the comments after this macro for
477 the return description. This macro can also be within comments, but is then
478 '_WSLUA_RETURNS_'.
479  
480 Example:
481  
482 WSLUA_RETURN(1); /* The ethernet pseudoheader */
483  
484  
485 WSLUA_ERROR - this C macro takes arguments, and expands to call luaL_error()
486 using them, and returns 0. The arguments it takes is the full function name
487 and a string describing the error. For documentation, it uses the string
488 argument and displays it with the function it's associated to.
489  
490 Example:
491 if (!wtap_dump_can_write_encap(filetype, encap))
492 WSLUA_ERROR(Dumper_new,"Not every filetype handles every encap");
493  
494  
495 WSLUA_ARG_ERROR - this is a pure C macro and does not generate any
496 documentation. It is used for errors in type/value of function/method
497 arguments.
498  
499 Example: see the example in thr WSLUA_CONSTRUCTOR above.
500  
501  
502 ==============================================================================
503  
504 Memory management model:
505  
506 Lua uses a garbage collection model, which for all intents and purposes can
507 collect garbage at any time once an item is no longer referenced by something
508 in Lua. When C-malloc'ed values are pushed into Lua, the Lua library has to
509 let you decide whether to try to free them or not. This is done through the
510 '__gc' metamethod, so every Wireshark class created by WSLUA_CLASS_DEFINE must
511 implement a metamethod function to handle this. The name of the function must
512 be 'ClassName__gc', where 'ClassName' is the same name as the class. Even if
513 you decide to do nothing, you still have to define the function or it will
514 fail to compile - as of this writing, which changed it to do so, in order to
515 make the programmer think about it and not forget.
516  
517 The thing to think about is the lifetime of the object/value. If C-code
518 controls/manages the object after pushing it into Lua, then C-code MUST NOT
519 free it until it knows Lua has garbage collected it, which is only known by
520 the __gc metamethod being invoked. Otherwise you run the risk of the Lua
521 script trying to use it later, which will dereference a pointer to something
522 that has been free'd, and crash. There are known ways to avoid this, but
523 those ways are not currently used in Wireshark's Lua API implementation;
524 except Tvb and TvbRange do implement a simple model of reference counting to
525 protect against this.
526  
527 If possible/reasonable, the best model is to malloc the object when you push
528 it into Lua, usually in a class function (not method) named 'new', and then
529 free it in the __gc metamethod. But if that's not reasonable, then the next
530 best model is to have a boolean member of the class called something like
531 'expired', which is set to true if the C-code decides it is dead/no-longer-
532 useful, and then have every Lua-to-C accessor method for that class type check
533 that boolean before trying to use it, and have the __gc metamethod set
534 expired=true or free it if it's already expired by C-side code; and vice-versa
535 for the C-side code.
536  
537 In some cases the class is exposed with a specific method to free/remove it,
538 typically called 'remove'; the Listener class does this, for example. When
539 the Lua script calls myListener:remove(), the C-code for that class method
540 free's the Listener that was malloc'ed previously in Listener.new(). The
541 Listener__gc() metamethod does not do anything, since it's hopefully already
542 been free'd. The downside with this approach is if the script never calls
543 remove(), then it leaks memory; and if the script ever tries to use the
544 Listener userdata object after it called remove(), then Wireshark crashes. Of
545 course either case would be a Lua script programming error, and easily
546 fixable, so it's not a huge deal.
547  
548 ==============================================================================
549