get_field_details
| Definition: |
include cffi.e
sequence res = get_field_details(integer id, atom_string field) where res is {integer offset, integer size, integer signed, string mtype} |
| Description: |
Get the low level details of a named field in a structure previously defined by define_struct().
id: a result from define_struct(). pStruct: a result from allocate_struct(). field: a string name or, caveat emptor, a numeric index. If field is "" then it returns a list of all field names. |
| pwa/p2js: | Not supported. |
| Comments: |
Normally field is a string, which is searched for in the private table of field names, or it can already be an integer to skip that step.
It is normally sufficient to use set_struct_field() and get_struct_field(), however this routine may be necessary to deal with arrays of structures, nested or hybrid structures, unions, etc. While it is reasonable to suggest that compiling even several hundred structs and functions, once at startup, is unlikely to cause a measurable performance issue, the same cannot in the general case be said for repeated named lookups on individual fields. Use of this routine prior to a tight inner loop might offer significant performance benefits - but unless you are going to be calling something more than a million times I would advise you not to bother. The offset would normally be added to a value from allocate_struct() or similar. The size and signed can be passed to peekNS(), and size to pokeN(). The mtype is for diagnostic assistance purposes only. Note that cffi.e itself only knows [the name/subscript, which is passed to this routine and] the offset and size in bytes, and whether it is signed, which of course this routine has already returned to you, and cannot provide any further assistance with obscure C types. While it might not be a bad idea to verify your app understands all types in use, especially should it be automatically extracting from the latest lib.h file, generally speaking anything along the lines of if mtype="long" or... should certainly
be considered a "bad code smell", unless as just implied you know there will be no sudden/quietly hidden surprises.
It is not particularly unusual for say int to evolve into lib_int, usually for reasons that have very
little impact on or relevance to Phix interfacing with precompiled dll/so files. In such cases it is usually pretty
straightforward to modify cffi.e to recognise the new "lib_int", with fingers crossed there’s no conflict with
anything prior, but of course that would have no impact on other code that may (still) be checking for "int".
|
| Example 1: |
include cffi.e
integer idMBP = define_struct(...)
atom pMBP = allocate_struct(idMBP)
..
atom pTitle = get_struct_field(idMBP,pMBP,"lpszText")
?peek_string(pTitle)
constant {title_offset,tsize,tsign} = get_field_details(idMBP,"lpszText")
?peek_string(peekNS(pMBP+title_offset,tsize,tsign))
|
| Example 2: |
?get_field_details(idRECT,"") -- {"left","top","right","bottom"}
Where idRECT is as per the example in define_struct().
|
| See Also: | define_struct, set_struct_field, get_struct_field, allocate_struct, peek, poke |