OleAuto (JNA API)

com.sun.jna.platform.win32

## Interface OleAuto

- All Superinterfaces:
    AltCallingConvention, Library, StdCall, StdCallLibrary

      public interface OleAuto
      extends StdCallLibrary

  Oleaut32.dll Interface.
  Author:
    scott.palmer

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `OleAuto.DISPPARAMS` The Class DISPPARAMS.

    - ### Nested classes/interfaces inherited from interface com.sun.jna.win32.StdCallLibrary

      `StdCallLibrary.StdCallCallback`

    - ### Nested classes/interfaces inherited from interface com.sun.jna.Library

      `Library.Handler`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static int` | `DISPATCH_METHOD` The Constant DISPATCH_METHOD.
    `static int` | `DISPATCH_PROPERTYGET` The Constant DISPATCH_PROPERTYGET.
    `static int` | `DISPATCH_PROPERTYPUT` The Constant DISPATCH_PROPERTYPUT.
    `static int` | `DISPATCH_PROPERTYPUTREF` The Constant DISPATCH_PROPERTYPUTREF.
    `static int` | `FADF_AUTO` An array that is allocated on the stac.
    `static int` | `FADF_BSTR` An array of BSTRs.
    `static int` | `FADF_DISPATCH` An array of IDispatch*.
    `static int` | `FADF_EMBEDDED` An array that is embedded in a structure.
    `static int` | `FADF_FIXEDSIZE` An array that is embedded in a structure.
    `static int` | `FADF_HAVEIID` An array that is embedded in a structure.
    `static int` | `FADF_HAVEVARTYPE` An array that has a variant type.
    `static int` | `FADF_RECORD` An array that is embedded in a structure.
    `static int` | `FADF_RESERVED` Bits reserved for future use.
    `static int` | `FADF_STATIC` An array that is statically allocated.
    `static int` | `FADF_UNKNOWN` An array of IUnknown*.
    `static int` | `FADF_VARIANT` An array of VARIANTs.
    `static OleAuto` | `INSTANCE` The instance.

    - ### Fields inherited from interface com.sun.jna.win32.StdCallLibrary

      `FUNCTION_MAPPER, STDCALL_CONVENTION`

    - ### Fields inherited from interface com.sun.jna.Library

      `OPTION_ALLOW_OBJECTS, OPTION_CALLING_CONVENTION, OPTION_CLASSLOADER, OPTION_FUNCTION_MAPPER, OPTION_INVOCATION_MAPPER, OPTION_OPEN_FLAGS, OPTION_STRING_ENCODING, OPTION_STRUCTURE_ALIGNMENT, OPTION_TYPE_MAPPER`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `WinNT.HRESULT` | `GetActiveObject(Guid.GUID rclsid, WinDef.PVOID pvReserved, PointerByReference ppunk)` Retrieves a pointer to a running object that has been registered with OLE.
    `WinNT.HRESULT` | `LoadRegTypeLib(Guid.GUID rguid, int wVerMajor, int wVerMinor, WinDef.LCID lcid, PointerByReference pptlib)` Uses registry information to load a type library.
    `WinNT.HRESULT` | `LoadTypeLib(WString szFile, PointerByReference pptlib)` Loads and registers a type library.
    `OaIdl.SAFEARRAY.ByReference` | `SafeArrayCreate(WTypes.VARTYPE vt, int cDims, OaIdl.SAFEARRAYBOUND[] rgsabound)` Creates a new array descriptor, allocates and initializes the data for the array, and returns a pointer to the new array descriptor.
    `WinNT.HRESULT` | `SafeArrayGetElement(OaIdl.SAFEARRAY psa, long[] rgIndices, Pointer pv)` Retrieves a single element of the array.
    `WinNT.HRESULT` | `SafeArrayLock(OaIdl.SAFEARRAY psa)` Increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor.
    `WinNT.HRESULT` | `SafeArrayPutElement(OaIdl.SAFEARRAY psa, long[] idx, Variant.VARIANT pv)` Stores the data element at the specified location in the array.
    `WinNT.HRESULT` | `SafeArrayUnLock(OaIdl.SAFEARRAY psa)` Decrements the lock count of an array so it can be freed or resized.
    `WTypes.BSTR` | `SysAllocString(java.lang.String sz)` This function allocates a new string and copies the passed string into it.
    `void` | `SysFreeString(WTypes.BSTR bstr)` This function frees a string allocated previously by SysAllocString, SysAllocStringByteLen, SysReAllocString, SysAllocStringLen, or SysReAllocStringLen.
    `int` | `SystemTimeToVariantTime(WinBase.SYSTEMTIME lpSystemTime, DoubleByReference pvtime)` Converts a system time to a variant representation.
    `WinNT.HRESULT` | `VariantClear(Pointer pvarg)` Use this function to clear variables of type VARIANTARG (or VARIANT) before the memory containing the VARIANTARG is freed (as when a local variable goes out of scope).
    `WinNT.HRESULT` | `VariantCopy(Pointer pvargDest, Variant.VARIANT pvargSrc)` First, free any memory that is owned by pvargDest, such as VariantClear (pvargDest must point to a valid initialized variant, and not simply to an uninitialized memory location).
    `void` | `VariantInit(Variant.VARIANT.ByReference pvarg)` The VariantInit function initializes the VARIANTARG by setting the vt field to VT_EMPTY.
    `void` | `VariantInit(Variant.VARIANT pvarg)` The VariantInit function initializes the VARIANTARG by setting the vt field to VT_EMPTY.

- - ### Field Detail

    - #### DISPATCH_METHOD

          static final int DISPATCH_METHOD

      The Constant DISPATCH_METHOD.
      See Also:
        Constant Field Values

    - #### DISPATCH_PROPERTYGET

          static final int DISPATCH_PROPERTYGET

      The Constant DISPATCH_PROPERTYGET.
      See Also:
        Constant Field Values

    - #### DISPATCH_PROPERTYPUT

          static final int DISPATCH_PROPERTYPUT

      The Constant DISPATCH_PROPERTYPUT.
      See Also:
        Constant Field Values

    - #### DISPATCH_PROPERTYPUTREF

          static final int DISPATCH_PROPERTYPUTREF

      The Constant DISPATCH_PROPERTYPUTREF.
      See Also:
        Constant Field Values

    - #### FADF_AUTO

          static final int FADF_AUTO

      An array that is allocated on the stac.
      See Also:
        Constant Field Values

    - #### FADF_STATIC

          static final int FADF_STATIC

      An array that is statically allocated.
      See Also:
        Constant Field Values

    - #### FADF_EMBEDDED

          static final int FADF_EMBEDDED

      An array that is embedded in a structure.
      See Also:
        Constant Field Values

    - #### FADF_FIXEDSIZE

          static final int FADF_FIXEDSIZE

      An array that is embedded in a structure.
      See Also:
        Constant Field Values

    - #### FADF_RECORD

          static final int FADF_RECORD

      An array that is embedded in a structure.
      See Also:
        Constant Field Values

    - #### FADF_HAVEIID

          static final int FADF_HAVEIID

      An array that is embedded in a structure.
      See Also:
        Constant Field Values

    - #### FADF_HAVEVARTYPE

          static final int FADF_HAVEVARTYPE

      An array that has a variant type. The variant type can be retrieved with SafeArrayGetVartype.
      See Also:
        Constant Field Values

    - #### FADF_BSTR

          static final int FADF_BSTR

      An array of BSTRs.
      See Also:
        Constant Field Values

    - #### FADF_UNKNOWN

          static final int FADF_UNKNOWN

      An array of IUnknown*.
      See Also:
        Constant Field Values

    - #### FADF_DISPATCH

          static final int FADF_DISPATCH

      An array of IDispatch*.
      See Also:
        Constant Field Values

    - #### FADF_VARIANT

          static final int FADF_VARIANT

      An array of VARIANTs.
      See Also:
        Constant Field Values

    - #### FADF_RESERVED

          static final int FADF_RESERVED

      Bits reserved for future use.
      See Also:
        Constant Field Values

    - #### INSTANCE

          static final OleAuto INSTANCE

      The instance.

  - ### Method Detail

    - #### SysAllocString

          WTypes.BSTR SysAllocString(java.lang.String sz)

      This function allocates a new string and copies the passed string into it.
      Parameters:
        `sz` - Null-terminated UNICODE string to copy.
      Returns:
        Null if there is insufficient memory or if a null pointer is passed in.

    - #### SysFreeString

          void SysFreeString(WTypes.BSTR bstr)

      This function frees a string allocated previously by SysAllocString, SysAllocStringByteLen, SysReAllocString, SysAllocStringLen, or SysReAllocStringLen.
      Parameters:
        `bstr` - Unicode string that was allocated previously, or NULL. Setting this parameter to NULL causes the function to simply return.

    - #### VariantInit

          void VariantInit(Variant.VARIANT.ByReference pvarg)

      The VariantInit function initializes the VARIANTARG by setting the vt field to VT_EMPTY. Unlike VariantClear, this function does not interpret the current contents of the VARIANTARG. Use VariantInit to initialize new local variables of type VARIANTARG (or VARIANT).
      Parameters:
        `pvarg` - The variant to initialize.

    - #### VariantInit

          void VariantInit(Variant.VARIANT pvarg)

      The VariantInit function initializes the VARIANTARG by setting the vt field to VT_EMPTY. Unlike VariantClear, this function does not interpret the current contents of the VARIANTARG. Use VariantInit to initialize new local variables of type VARIANTARG (or VARIANT).
      Parameters:
        `pvarg` - The variant to initialize.

    - #### VariantCopy

          WinNT.HRESULT VariantCopy(Pointer pvargDest,
                                  Variant.VARIANT pvargSrc)

      First, free any memory that is owned by pvargDest, such as VariantClear (pvargDest must point to a valid initialized variant, and not simply to an uninitialized memory location). Then pvargDest receives an exact copy of the contents of pvargSrc. If pvargSrc is a VT_BSTR, a copy of the string is made. If pvargSrcis a VT_ARRAY, the entire array is copied. If pvargSrc is a VT_DISPATCH or VT_UNKNOWN, AddRef is called to increment the object's reference count. If the variant to be copied is a COM object that is passed by reference, the vtfield of the pvargSrcparameter is VT_DISPATCH | VT_BYREF or VT_UNKNOWN | VT_BYREF. In this case, VariantCopy does not increment the reference count on the referenced object. Because the variant being copied is a pointer to a reference to an object, VariantCopy has no way to determine if it is necessary to increment the reference count of the object. It is therefore the responsibility of the caller to call IUnknown::AddRef on the object or not, as appropriate. Note The VariantCopy method is not threadsafe.
      Parameters:
        `pvargDest` - [out] The destination variant.
        `pvargSrc` - [in] The source variant.
      Returns:
        the hresult

    - #### VariantClear

          WinNT.HRESULT VariantClear(Pointer pvarg)

      Use this function to clear variables of type VARIANTARG (or VARIANT) before the memory containing the VARIANTARG is freed (as when a local variable goes out of scope). The function clears a VARIANTARG by setting the vt field to VT_EMPTY. The current contents of the VARIANTARG are released first. If the vtfield is VT_BSTR, the string is freed. If the vtfield is VT_DISPATCH, the object is released. If the vt field has the VT_ARRAY bit set, the array is freed. If the variant to be cleared is a COM object that is passed by reference, the vtfield of the pvargparameter is VT_DISPATCH | VT_BYREF or VT_UNKNOWN | VT_BYREF. In this case, VariantClear does not release the object. Because the variant being cleared is a pointer to a reference to an object, VariantClear has no way to determine if it is necessary to release the object. It is therefore the responsibility of the caller to release the object or not, as appropriate. In certain cases, it may be preferable to clear a variant in code without calling VariantClear. For example, you can change the type of a VT_I4 variant to another type without calling this function. Safearrays of BSTR will have SysFreeString called on each element not VariantClear. However, you must call VariantClear if a VT_type is received but cannot be handled. Safearrays of variant will also have VariantClear called on each member. Using VariantClear in these cases ensures that code will continue to work if Automation adds new variant types in the future. Do not use VariantClear on unitialized variants; use VariantInit to initialize a new VARIANTARG or VARIANT. Variants containing arrays with outstanding references cannot be cleared. Attempts to do so will return an HRESULT containing DISP_E_ARRAYISLOCKED.
      Parameters:
        `pvarg` - [in, out] The variant to clear.
      Returns:
        the hresult

    - #### SafeArrayCreate

          OaIdl.SAFEARRAY.ByReference SafeArrayCreate(WTypes.VARTYPE vt,
                                                    int cDims,
                                                    OaIdl.SAFEARRAYBOUND[] rgsabound)

      Creates a new array descriptor, allocates and initializes the data for the array, and returns a pointer to the new array descriptor.
      Parameters:
        `vt` - [in] The base type of the array (the VARTYPE of each element of the array). The VARTYPE is restricted to a subset of the variant types. Neither the VT_ARRAY nor the VT_BYREF flag can be set. VT_EMPTY and VT_NULL are not valid base types for the array. All other types are legal. cDims
        `cDims` - the c dims
        `rgsabound` - the rgsabound
      Returns:
        Return value A safe array descriptor, or null if the array could not be created.

    - #### SafeArrayPutElement

          WinNT.HRESULT SafeArrayPutElement(OaIdl.SAFEARRAY psa,
                                          long[] idx,
                                          Variant.VARIANT pv)

      Stores the data element at the specified location in the array.
      Parameters:
        `psa` - [in] An array descriptor created by SafeArrayCreate.
        `idx` - the idx
        `pv` - [in] The data to assign to the array. The variant types VT_DISPATCH, VT_UNKNOWN, and VT_BSTR are pointers, and do not require another level of indirection.
      Returns:
        Return value This function can return one of these values. S_OK Success. DISP_E_BADINDEX The specified index is not valid. E_INVALIDARG One of the arguments is not valid. E_OUTOFMEMORY Memory could not be allocated for the element.

    - #### SafeArrayGetElement

          WinNT.HRESULT SafeArrayGetElement(OaIdl.SAFEARRAY psa,
                                          long[] rgIndices,
                                          Pointer pv)

      Retrieves a single element of the array.
      Parameters:
        `psa` - [in] An array descriptor created by SafeArrayCreate.
        `rgIndices` - [in] A vector of indexes for each dimension of the array. The right-most (least significant) dimension is rgIndices[0]. The left-most dimension is stored at rgIndices[psa->cDims - 1].
        `pv` - [out] The element of the array.
      Returns:
        Return value This function can return one of these values. S_OK Success. DISP_E_BADINDEX The specified index is not valid. E_INVALIDARG One of the arguments is not valid. E_OUTOFMEMORY Memory could not be allocated for the element.

    - #### SafeArrayLock

          WinNT.HRESULT SafeArrayLock(OaIdl.SAFEARRAY psa)

      Increments the lock count of an array, and places a pointer to the array data in pvData of the array descriptor.
      Parameters:
        `psa` - [in] An array descriptor created by SafeArrayCreate.
      Returns:
        Return value This function can return one of these values. S_OK Success. E_INVALIDARG The argument psa is not valid. E_UNEXPECTED The array could not be locked.

    - #### SafeArrayUnLock

          WinNT.HRESULT SafeArrayUnLock(OaIdl.SAFEARRAY psa)

      Decrements the lock count of an array so it can be freed or resized.
      Parameters:
        `psa` - [in] An array descriptor created by SafeArrayCreate.
      Returns:
        Return value This function can return one of these values. S_OK Success. E_INVALIDARG The argument psa is not valid. E_UNEXPECTED The array could not be locked.

    - #### GetActiveObject

          WinNT.HRESULT GetActiveObject(Guid.GUID rclsid,
                                      WinDef.PVOID pvReserved,
                                      PointerByReference ppunk)

      Retrieves a pointer to a running object that has been registered with OLE.
      Parameters:
        `rclsid` - [in] The class identifier (CLSID) of the active object from the OLE registration database.
        `pvReserved` - Reserved for future use. Must be null.
        `ppunk` - [out] The requested active object.
      Returns:
        Return value If this function succeeds, it returns S_OK. Otherwise, it returns an HRESULT error code.

    - #### LoadRegTypeLib

          WinNT.HRESULT LoadRegTypeLib(Guid.GUID rguid,
                                     int wVerMajor,
                                     int wVerMinor,
                                     WinDef.LCID lcid,
                                     PointerByReference pptlib)

      Uses registry information to load a type library.
      Parameters:
        `rguid` - The GUID of the library.
        `wVerMajor` - The major version of the library.
        `wVerMinor` - The minor version of the library.
        `lcid` - The national language code of the library.
        `pptlib` - The loaded type library. This function can return one of these values: S_OK Success. E_INVALIDARG One or more of the arguments is not valid. E_OUTOFMEMORY Insufficient memory to complete the operation. TYPE_E_IOERROR The function could not write to the file. TYPE_E_INVALIDSTATE The type library could not be opened. TYPE_E_INVDATAREAD The function could not read from the file. TYPE_E_UNSUPFORMAT The type library has an older format. TYPE_E_UNKNOWNLCID The LCID could not be found in the OLE-supported DLLs. TYPE_E_CANTLOADLIBRARY The type library or DLL could not be loaded.
      Returns:
        status

    - #### LoadTypeLib

          WinNT.HRESULT LoadTypeLib(WString szFile,
                                  PointerByReference pptlib)

      Loads and registers a type library.
      Parameters:
        `szFile` - The name of the file from which the method should attempt to load a type library.
        `pptlib` - The loaded type library. Return value This function can return one of these values. S_OK Success. E_INVALIDARG One or more of the arguments is not valid. E_OUTOFMEMORY Insufficient memory to complete the operation. TYPE_E_IOERROR The function could not write to the file. TYPE_E_INVALIDSTATE The type library could not be opened. TYPE_E_INVDATAREAD The function could not read from the file. TYPE_E_UNSUPFORMAT The type library has an older format. TYPE_E_UNKNOWNLCID The LCID could not be found in the OLE-supported DLLs. TYPE_E_CANTLOADLIBRARY The type library or DLL could not be loaded.
      Returns:
        status

    - #### SystemTimeToVariantTime

          int SystemTimeToVariantTime(WinBase.SYSTEMTIME lpSystemTime,
                                    DoubleByReference pvtime)

      Converts a system time to a variant representation.
      Parameters:
        `lpSystemTime` - [in] The system time.
        `pvtime` - [out] The variant time.
      Returns:
        The function returns TRUE on success and FALSE otherwise.

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