struct*. When used as a field within another Structure, it corresponds to struct. The tagging interfaces {@link ByReference} and {@link ByValue} may be usedto alter the default behavior. Structures may have variable size, but only by providing an array field (e.g. byte[]). See the overview for supported type mappings for struct fields.
Structure alignment and type mappings are derived by default from the enclosing interface definition (if any) by using {@link Native#getStructureAlignment} and {@link Native#getTypeMapper}. Alternatively you can explicitly provide alignment, field order, or type mapping by calling the respective Structure functions in your subclass's constructor.
Structure fields corresponding to native struct fields must be public. If your structure is to have no fields of its own, it must be declared abstract. You must define {@link #getFieldOrder} to return a List offield names (Strings) indicating the proper order of the fields. When dealing with multiple levels of subclasses of Structure, you must add to the list provided by the superclass {@link #getFieldOrder}the fields defined in the current class. In the past, most VMs would return them in a predictable order, but the JVM spec does not require it, so {@link #getFieldOrder} is now required toensure JNA knows the proper order). Structure fields may additionally have the following modifiers:volatile JNA will not write the field unless specifically instructed to do so via {@link #writeField(String)}. This allows you to prevent inadvertently overwriting memory that may be updated in real time on another (possibly native) thread. final JNA will overwrite the field via {@link #read()}, but otherwise the field is not modifiable from Java. Take care when using this option, since the compiler will usually assume all accesses to the field (for a given Structure instance) have the same value. This modifier is invalid to use on J2ME. char * is generally more common than wchar_t *. You may provide a type mapper ( {@link com.sun.jna.win32.W32APITypeMapper example here)} if you prefer to use String in place of {@link WString} ifyour native code predominantly uses wchar_t *. NOTE: In general, instances of this class are not synchronized.
@author Todd Fast, todd.fast@sun.com
@author twall@users.sf.net
A Structure is a collection of key/value pairs. The keys are expressed as GQuarks and the values can be of any GType.
In addition to the key/value pairs, a Structure also has a name. The name starts with a letter and can be followed by letters, numbers and any of "/-_.:".
Structure is used by various GStreamer subsystems to store information in a flexible and extensible way.
A Structure can be created with new {@link #Structure(String)} or {@link #Structure(String,String,Object)}, which both take a name and an optional set of key/value pairs along with the types of the values.
Field values can be changed with set{Integer,String}() etc functions.
Field values can be retrieved with get{Integer,String}() etc functions.
Fields can be removed with {@link #removeField} or {@link #removeFields} @see Caps @see Event
A call to structure.read() will read all of the data in a Structure, including nested structures, and returns an Array of StructureData, with all of the data in memory. If there is a nested sequence, the sequence data may be read into memory all at once, ot it may be read in increments as the iteration proceeds.
Generally, the programmer can assume that the data in one Structure are stored together, so that it is efficient to read an entire Structure, and then access the Variable data through the Arrays in the StructureData. @author caron
| |
| |
| |
| |
| |
| |