OaIdl.SAFEARRAY (JNA API)

com.sun.jna.platform.win32

## Class OaIdl.SAFEARRAY

- java.lang.Object
- - com.sun.jna.Structure
  - - com.sun.jna.platform.win32.OaIdl.SAFEARRAY

- All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
  Direct Known Subclasses:
    OaIdl.SAFEARRAY.ByReference
  Enclosing interface:
    OaIdl

      public static class OaIdl.SAFEARRAY
      extends Structure
      implements java.io.Closeable

  Implementation of SAFEARRAY. Implements Closable, which in this case delegates to destroy, to free native memory on close.

  VARTYPE for the SAFEARRAY can be:

  - VT_BOOL
  - VT_BSTR
  - VT_CY
  - VT_DATE
  - VT_DECIMAL
  - VT_DISPATCH
  - VT_ERROR
  - VT_I1
  - VT_I2
  - VT_I4
  - VT_INT
  - VT_R4
  - VT_R8
  - VT_RECORD
  - VT_UI1
  - VT_UI2
  - VT_UI4
  - VT_UINT
  - VT_UNKNOWN
  - VT_VARIANT

  General comment: All indices in the helper methods use java int.

  The native type for the indices is LONG, which is defined as:

  > A 32-bit signed integer. The range is �2147483648 through 2147483647 decimal.

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `OaIdl.SAFEARRAY.ByReference`

    - ### Nested classes/interfaces inherited from class com.sun.jna.Structure

      `Structure.ByValue, Structure.StructField`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `WinDef.ULONG` | `cbElements`
    `WinDef.USHORT` | `cDims`
    `WinDef.ULONG` | `cLocks`
    `WinDef.USHORT` | `fFeatures`
    `static java.util.List<java.lang.String>` | `FIELDS`
    `WinDef.PVOID` | `pvData`
    `OaIdl.SAFEARRAYBOUND[]` | `rgsabound` The rgsabound.

    - ### Fields inherited from class com.sun.jna.Structure

      `ALIGN_DEFAULT, ALIGN_GNUC, ALIGN_MSVC, ALIGN_NONE, CALCULATE_SIZE`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `SAFEARRAY()`
    `SAFEARRAY(Pointer pointer)`

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `Pointer` | `accessData()` Lock array and retrieve pointer to data
    `void` | `close()` Implemented to satisfy Closeable interface, delegates to destroy.
    `static OaIdl.SAFEARRAY` | `createSafeArray(int... size)` Create a SAFEARRAY with supplied VARIANT as element type.
    `static OaIdl.SAFEARRAY` | `createSafeArray(WTypes.VARTYPE vartype, int... size)` Create a SAFEARRAY with supplied element type.
    `void` | `destroy()` Destroy the underlying SAFEARRAY and free memory
    `int` | `getDimensionCount()` Return number of dimensions of the SAFEARRAY
    `java.lang.Object` | `getElement(int... indices)` Retrieve the value at the referenced index from the SAFEARRAY.
    `long` | `getElemsize()` Get size of one element in bytes
    `protected java.util.List<java.lang.String>` | `getFieldOrder()` Return this Structure's field names in their proper order.
    `int` | `getLBound(int dimension)` Retrieve lower bound for the selected dimension.
    `int` | `getUBound(int dimension)` Retrieve upper bound for the selected dimension.
    `WTypes.VARTYPE` | `getVarType()` Return VARTYPE of the SAFEARRAY
    `void` | `lock()` Increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor.
    `Pointer` | `ptrOfIndex(int... indices)` Retrieve pointer to data element from array.
    `void` | `putElement(java.lang.Object arg, int... indices)` Set value at `indices` in `array` to arg.
    `void` | `read()` Reads the fields of the struct from native memory
    `void` | `redim(int cElements, int lLbound)` Changes the right-most (least significant) bound of the specified safe array.
    `void` | `unaccessData()` Unlock array and invalidate the pointer retrieved via SafeArrayAccessData
    `void` | `unlock()` Decrements the lock count of an array so it can be freed or resized

    - ### Methods inherited from class com.sun.jna.Structure

      `allocateMemory, allocateMemory, autoAllocate, autoRead, autoRead, autoWrite, autoWrite, cacheTypeInfo, calculateSize, clear, createFieldsOrder, createFieldsOrder, createFieldsOrder, createFieldsOrder, dataEquals, dataEquals, ensureAllocated, equals, fieldOffset, getAutoRead, getAutoWrite, getFieldList, getFields, getNativeAlignment, getNativeSize, getNativeSize, getPointer, getStringEncoding, getStructAlignment, hashCode, newInstance, newInstance, readField, readField, setAlignType, setAutoRead, setAutoSynch, setAutoWrite, setFieldOrder, setStringEncoding, size, sortFields, toArray, toArray, toString, toString, useMemory, useMemory, write, writeField, writeField, writeField`

    - ### Methods inherited from class java.lang.Object

      `clone, finalize, getClass, notify, notifyAll, wait, wait, wait`

- - ### Field Detail

    - #### FIELDS

          public static final java.util.List<java.lang.String> FIELDS

    - #### cDims

          public WinDef.USHORT cDims

    - #### fFeatures

          public WinDef.USHORT fFeatures

    - #### cbElements

          public WinDef.ULONG cbElements

    - #### cLocks

          public WinDef.ULONG cLocks

    - #### pvData

          public WinDef.PVOID pvData

    - #### rgsabound

          public OaIdl.SAFEARRAYBOUND[] rgsabound

      The rgsabound.

  - ### Constructor Detail

    - #### SAFEARRAY

          public SAFEARRAY()

    - #### SAFEARRAY

          public SAFEARRAY(Pointer pointer)

  - ### Method Detail

    - #### read

          public void read()

      Description copied from class: `Structure`
      Reads the fields of the struct from native memory
      Overrides:
        `read` in class `Structure`

    - #### getFieldOrder

          protected java.util.List<java.lang.String> getFieldOrder()

      Description copied from class: `Structure`
      Return this Structure's field names in their proper order. For example,

           protected List getFieldOrder() {
               return Arrays.asList(new String[] { ... });
           }

      IMPORTANT When deriving from an existing Structure subclass, ensure that you augment the list provided by the superclass, e.g.

           protected List getFieldOrder() {
               List fields = new ArrayList(super.getFieldOrder());
               fields.addAll(Arrays.asList(new String[] { ... }));
               return fields;
           }

      Field order must be explicitly indicated, since the field order as returned by `Class.getFields()` is not guaranteed to be predictable.
      Specified by:
        `getFieldOrder` in class `Structure`
      Returns:
        ordered list of field names

    - #### createSafeArray

          public static OaIdl.SAFEARRAY createSafeArray(int... size)

      Create a SAFEARRAY with supplied VARIANT as element type.

      This helper creates a basic SAFEARRAY with a base type of VT_VARIANT. The array will have as many dimensions as parameters are passed in. The lowerbound for each dimension is set to zero, the count to the parameter value.

      Parameters:
        `size` - array of dimension size
      Returns:
        SAFEARRAYWrapper or `NULL` if creation fails.

    - #### createSafeArray

          public static OaIdl.SAFEARRAY createSafeArray(WTypes.VARTYPE vartype,
                                                        int... size)

      Create a SAFEARRAY with supplied element type.

      The array will have as many dimensions as parameters are passed in. The lowerbound for each dimension is set to zero, the count to the parameter value.

      Parameters:
        `vartype` - type of array contents (see Variant.VT_* constants)
        `size` - array of dimension size
      Returns:
        SAFEARRAYWrapper or `NULL` if creation fails.

    - #### putElement

          public void putElement(java.lang.Object arg,
                                 int... indices)

      Set value at `indices` in `array` to arg.

      The supplied argument is copied into the array. If the value is no longer needed, it needs to be freed if not handled automatically.

      Parameters:
        `indices` - the index, order follows java/C convention
        `arg` - the arg

    - #### getElement

          public java.lang.Object getElement(int... indices)

      Retrieve the value at the referenced index from the SAFEARRAY.

      The function creates a copy of the value. The values are allocated with native functions and need to be freed accordingly.

      Parameters:
        `indices` - the index, order follows java/C convention
      Returns:
        the variant

    - #### ptrOfIndex

          public Pointer ptrOfIndex(int... indices)

      Retrieve pointer to data element from array.

      Caller is responsible for (un)locking the array via `OleAuto.SafeArrayLock(com.sun.jna.platform.win32.OaIdl.SAFEARRAY)` and `OleAuto.SafeArrayUnlock(com.sun.jna.platform.win32.OaIdl.SAFEARRAY)` or the helper methods: `lock()` and `unlock()`.

      Parameters:
        `indices` - the index, order follows java/C convention
      Returns:
        the pointer to the data element

    - #### destroy

          public void destroy()

      Destroy the underlying SAFEARRAY and free memory

    - #### close

          public void close()

      Implemented to satisfy Closeable interface, delegates to destroy.
      Specified by:
        `close` in interface `java.io.Closeable`
      Specified by:
        `close` in interface `java.lang.AutoCloseable`

    - #### getLBound

          public int getLBound(int dimension)

      Retrieve lower bound for the selected dimension.

      As in the all the accessor functions, that index is converted to java conventions.

      Parameters:
        `dimension` - zerobased index
      Returns:
        lower bound for the selected dimension

    - #### getUBound

          public int getUBound(int dimension)

      Retrieve upper bound for the selected dimension.

      As in the all the accessor functions, that index is converted to java conventions.

      Parameters:
        `dimension` - zerobased index
      Returns:
        upper bound for the selected dimension

    - #### getDimensionCount

          public int getDimensionCount()

      Return number of dimensions of the SAFEARRAY
      Returns:
        number of dimensions of the SAFEARRAY

    - #### accessData

          public Pointer accessData()

      Lock array and retrieve pointer to data
      Returns:
        Pointer to arraydata

    - #### unaccessData

          public void unaccessData()

      Unlock array and invalidate the pointer retrieved via SafeArrayAccessData

    - #### lock

          public void lock()

      Increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor.

    - #### unlock

          public void unlock()

      Decrements the lock count of an array so it can be freed or resized

    - #### redim

          public void redim(int cElements,
                            int lLbound)

      Changes the right-most (least significant) bound of the specified safe array.
      Parameters:
        `cElements` -
        `lLbound` -

    - #### getVarType

          public WTypes.VARTYPE getVarType()

      Return VARTYPE of the SAFEARRAY
      Returns:
        VARTYPE of the SAFEARRAY

    - #### getElemsize

          public long getElemsize()

      Get size of one element in bytes
      Returns:
        element size in bytes

Copyright © 2007-2016 Timothy Wall. All Rights Reserved.