Package com.sun.jna

Class Union

java.lang.Object
com.sun.jna.Structure
com.sun.jna.Union
Direct Known Subclasses:
Kstat2.Kstat2NV.UNION, LibKstat.KstatNamed.UNION, Ntifs.REPARSE_DATA_BUFFER.REPARSE_UNION, NTSecApi.LSA_FOREST_TRUST_RECORD.UNION, OaIdl.BINDPTR, OaIdl.CURRENCY, OaIdl.DECIMAL._DECIMAL1, OaIdl.DECIMAL._DECIMAL2, OaIdl.ELEMDESC._ELEMDESC, OaIdl.TYPEDESC._TYPEDESC, OaIdl.VARDESC._VARDESC, Perfstat.perfstat_protocol_t.AnonymousUnionPayload, ShTypes.STRRET.UNION, Variant.VARIANT, Variant.VARIANT._VARIANT.__VARIANT, WinBase.SYSTEM_INFO.UNION, Wincon.INPUT_RECORD.Event, WinCrypt.CERT_STRONG_SIGN_PARA.DUMMYUNION, Winevt.EVT_VARIANT.field1_union, Wininet.INTERNET_CACHE_ENTRY_INFO.UNION, WinNT.LARGE_INTEGER.UNION, WinNT.SYSTEM_LOGICAL_PROCESSOR_INFORMATION.AnonymousUnionPayload, WinRas.RASTUNNELENDPOINT.UNION, Winspool.NOTIFY_DATA, WinUser.INPUT.INPUT_UNION, X11.XClientMessageEvent.Data, X11.XEvent
public abstract class Union extends Structure
Represents a native union. When writing to native memory, the field corresponding to the type passed to setType(java.lang.Class<?>) will be written to native memory. Upon reading from native memory, Structure, String, or WString fields will not be initialized unless they are the current field as identified by a call to setType(java.lang.Class<?>). The current field is always unset by default to avoid accidentally attempting to read a field that is not valid. In the case of a String, for instance, an invalid pointer may result in a memory fault when attempting to initialize the String.

  • Constructor Details

    • Union

      protected Union()
      Create a Union whose size and alignment will be calculated automatically.

    • Union

      protected Union(Pointer p)
      Create a Union of the given size, using default alignment.

    • Union

      protected Union(Pointer p, int alignType)
      Create a Union of the given size and alignment type.

    • Union

      protected Union(TypeMapper mapper)
      Create a Union of the given size and alignment type.

    • Union

      protected Union(Pointer p, int alignType, TypeMapper mapper)
      Create a Union of the given size and alignment type.

  • Method Details

    • getFieldOrder

      protected List<String> getFieldOrder()
      Unions do not need a field order, so automatically provide a value to satisfy checking in the Structure superclass.
      Overrides:
      getFieldOrder in class Structure
      Returns:
      ordered list of field names

    • setType

      public void setType(Class<?> type)
      Indicates by type which field will be used to write to native memory. If there are multiple fields of the same type, use setType(String) instead with the field name.
      Parameters:
      type - desired active type for the union
      Throws:
      IllegalArgumentException - if the type does not correspond to any declared union field.

    • setType

      public void setType(String fieldName)
      Indicates which field will be used to write to native memory.
      Parameters:
      fieldName - desired field to use for the active union type
      Throws:
      IllegalArgumentException - if the name does not correspond to any declared union field.

    • readField

      public Object readField(String fieldName)
      Force a read of the given field from native memory.
      Overrides:
      readField in class Structure
      Parameters:
      fieldName - field to be read
      Returns:
      the new field value, after updating
      Throws:
      IllegalArgumentException - if no field exists with the given name

    • writeField

      public void writeField(String fieldName)
      Write the given field value to native memory. The given field will become the active one.
      Overrides:
      writeField in class Structure
      Parameters:
      fieldName - which field to synch
      Throws:
      IllegalArgumentException - if no field exists with the given name

    • writeField

      public void writeField(String fieldName, Object value)
      Write the given field value to the field and native memory. The given field will become the active one.
      Overrides:
      writeField in class Structure
      Parameters:
      fieldName - field to write
      value - value to write
      Throws:
      IllegalArgumentException - if no field exists with the given name

    • getTypedValue

      public Object getTypedValue(Class<?> type)
      Reads the Structure field of the given type from memory, sets it as the active type and returns it. Convenience method for 
      
 Union u;
 Class type;
 u.setType(type);
 u.read();
 value = u.field;
      Parameters:
      type - class type of the Structure field to read
      Returns:
      the Structure field with the given type

    • setTypedValue

      public Object setTypedValue(Object object)
      Set the active type and its value. Convenience method for 
      
 Union u;
 Class type;
 u.setType(type);
 u.field = value;
      Parameters:
      object - instance of a class which is part of the union
      Returns:
      this Union object

    • writeField

      protected void writeField(Structure.StructField field)
      Only the currently selected field will be written.
      Overrides:
      writeField in class Structure
      Parameters:
      field - internal field representation to synch to native memory

    • readField

      protected Object readField(Structure.StructField field)
      Avoid reading pointer-based fields and structures unless explicitly selected. Structures may contain pointer-based fields which can crash the VM if not properly initialized.
      Overrides:
      readField in class Structure
      Parameters:
      field - field to be read
      Returns:
      value of the requested field

    • getNativeAlignment

      protected int getNativeAlignment(Class<?> type, Object value, boolean isFirstElement)
      All fields are considered the "first" element.
      Overrides:
      getNativeAlignment in class Structure
      Parameters:
      type - field type
      value - field value, if available
      isFirstElement - is this field the first element in the struct?
      Returns:
      the native byte alignment