Ole32 (JNA API)

com.sun.jna.platform.win32

## Interface Ole32

- All Superinterfaces:
    AltCallingConvention, Library, StdCall, StdCallLibrary

      public interface Ole32
      extends StdCallLibrary

  Ole32.dll Interface.
  Author:
    dblock[at]dblock.org, Tobias Wolf, wolf.tobias@gmx.net

- - ### Nested Class Summary

    - ### 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` | `COINIT_APARTMENTTHREADED`
    `static int` | `COINIT_DISABLE_OLE1DDE`
    `static int` | `COINIT_MULTITHREADED`
    `static int` | `COINIT_SPEED_OVER_MEMORY`
    `static Ole32` | `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

    All Methods Instance Methods Abstract Methods Deprecated Methods
    Modifier and Type | Method and Description
    --- | ---
    `WinNT.HRESULT` | `CLSIDFromProgID(java.lang.String lpszProgID, Guid.CLSID.ByReference lpclsid)` Looks up a CLSID in the registry, given a ProgID.
    `WinNT.HRESULT` | `CLSIDFromString(java.lang.String lpsz, Guid.CLSID.ByReference pclsid)` Converts a string generated by the StringFromCLSID function back into the original CLSID.
    `WinNT.HRESULT` | `CLSIDFromString(WString lpsz, Guid.CLSID.ByReference pclsid)` Deprecated. use the String version
    `WinNT.HRESULT` | `CoCreateGuid(Guid.GUID.ByReference pguid)` Deprecated. use `CoCreateGuid(Guid.GUID)`.
    `WinNT.HRESULT` | `CoCreateGuid(Guid.GUID pguid)` Creates a GUID, a unique 128-bit integer used for CLSIDs and interface identifiers.
    `WinNT.HRESULT` | `CoCreateInstance(Guid.GUID rclsid, Pointer pUnkOuter, int dwClsContext, Guid.GUID riid, PointerByReference ppv)` Creates a single uninitialized object of the class associated with a specified CLSID.
    `WinNT.HRESULT` | `CoGetMalloc(WinDef.DWORD dwMemContext, PointerByReference ppMalloc)` Retrieves a pointer to the default OLE task memory allocator.
    `WinNT.HRESULT` | `CoInitialize(WinDef.LPVOID pvReserved)` Initializes the COM library on the current thread and identifies the concurrency model as single-thread apartment (STA).
    `WinNT.HRESULT` | `CoInitializeEx(Pointer reserved, int dwCoInit)` Initializes the COM library for use by the calling thread, sets the thread's concurrency model, and creates a new apartment for the thread if one is required.
    `boolean` | `CoIsHandlerConnected(Pointer pUnk)` Determines whether a remote object is connected to the corresponding in-process object.
    `Pointer` | `CoTaskMemAlloc(long cb)` Allocates a block of task memory in the same way that IMalloc::Alloc does.
    `void` | `CoTaskMemFree(Pointer pv)` Frees a block of task memory previously allocated through a call to the `CoTaskMemAlloc(long)` or `CoTaskMemRealloc(com.sun.jna.Pointer, long)` function.
    `Pointer` | `CoTaskMemRealloc(Pointer pv, long cb)` Changes the size of a previously allocated block of task memory.
    `void` | `CoUninitialize()` Closes the COM library on the current thread, unloads all DLLs loaded by the thread, frees any other resources that the thread maintains, and forces all RPC connections on the thread to close.
    `WinNT.HRESULT` | `CreateBindCtx(WinDef.DWORD reserved, PointerByReference ppbc)` Returns a pointer to an implementation of IBindCtx (a bind context object).
    `WinNT.HRESULT` | `GetRunningObjectTable(WinDef.DWORD reserved, PointerByReference pprot)` Returns a pointer to the IRunningObjectTable interface on the local running object table (ROT).
    `WinNT.HRESULT` | `IIDFromString(java.lang.String lpsz, Guid.GUID lpiid)` Converts a string generated by the StringFromIID function back into the original interface identifier (IID).
    `int` | `StringFromGUID2(Guid.GUID rguid, char[] lpsz, int cchMax)` Converts a globally unique identifier (GUID) into a string of printable characters.

- - ### Field Detail

    - #### INSTANCE

          static final Ole32 INSTANCE

      The instance.

    - #### COINIT_APARTMENTTHREADED

          static final int COINIT_APARTMENTTHREADED

      See Also:
        Constant Field Values

    - #### COINIT_MULTITHREADED

          static final int COINIT_MULTITHREADED

      See Also:
        Constant Field Values

    - #### COINIT_DISABLE_OLE1DDE

          static final int COINIT_DISABLE_OLE1DDE

      See Also:
        Constant Field Values

    - #### COINIT_SPEED_OVER_MEMORY

          static final int COINIT_SPEED_OVER_MEMORY

      See Also:
        Constant Field Values

  - ### Method Detail

    - #### CoCreateGuid

          WinNT.HRESULT CoCreateGuid(Guid.GUID pguid)

      Creates a GUID, a unique 128-bit integer used for CLSIDs and interface identifiers.
      Parameters:
        `pguid` - A pointer to the requested GUID.
      Returns:
        S_OK if the GUID was successfully created.

    - #### CoCreateGuid

          WinNT.HRESULT CoCreateGuid(Guid.GUID.ByReference pguid)

      Deprecated. use `CoCreateGuid(Guid.GUID)`.
      Parameters:
        `pguid` - GUID reference
      Returns:
        result

    - #### StringFromGUID2

          int StringFromGUID2(Guid.GUID rguid,
                              char[] lpsz,
                              int cchMax)

      Converts a globally unique identifier (GUID) into a string of printable characters.
      Parameters:
        `rguid` - The GUID to be converted.
        `lpsz` - A pointer to a caller-allocated string variable to receive the resulting string.
        `cchMax` - The number of characters available in the lpsz buffer.
      Returns:
        If the function succeeds, the return value is the number of characters in the returned string, including the null terminator. If the buffer is too small to contain the string, the return value is 0.

    - #### IIDFromString

          WinNT.HRESULT IIDFromString(java.lang.String lpsz,
                                      Guid.GUID lpiid)

      Converts a string generated by the StringFromIID function back into the original interface identifier (IID).
      Parameters:
        `lpsz` - A pointer to the string representation of the IID.
        `lpiid` - A pointer to the requested IID on return.
      Returns:
        This function can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, and S_OK.

    - #### CoInitialize

          WinNT.HRESULT CoInitialize(WinDef.LPVOID pvReserved)

      Initializes the COM library on the current thread and identifies the concurrency model as single-thread apartment (STA). New applications should call CoInitializeEx instead of CoInitialize. pvReserved [in, optional] This parameter is reserved and must be NULL.
      Parameters:
        `pvReserved` - the pv reserved
      Returns:
        S_OK The COM library was initialized successfully on this thread. S_FALSE The COM library is already initialized on this thread. RPC_E_CHANGED_MODE A previous call to CoInitializeEx specified the concurrency model for this thread as multithread apartment (MTA). This could also indicate that a change from neutral-threaded apartment to single-threaded apartment has occurred.

    - #### CoInitializeEx

          WinNT.HRESULT CoInitializeEx(Pointer reserved,
                                       int dwCoInit)

      Initializes the COM library for use by the calling thread, sets the thread's concurrency model, and creates a new apartment for the thread if one is required.
      Parameters:
        `reserved` - This parameter is reserved and must be NULL.
        `dwCoInit` - The concurrency model and initialization options for the thread. Values for this parameter are taken from the COINIT enumeration. Any combination of values from COINIT can be used, except that the `COINIT_APARTMENTTHREADED` and `COINIT_MULTITHREADED` flags cannot both be set. The default (and only sane choice) is `COINIT_MULTITHREADED`.
      Returns:
        This function can return the standard return values E_INVALIDARG, E_OUTOFMEMORY, and E_UNEXPECTED, as well as the following values. S_OK, S_FALSE, RPC_E_CHANGED_MODE

    - #### CoUninitialize

          void CoUninitialize()

      Closes the COM library on the current thread, unloads all DLLs loaded by the thread, frees any other resources that the thread maintains, and forces all RPC connections on the thread to close.

    - #### CoCreateInstance

          WinNT.HRESULT CoCreateInstance(Guid.GUID rclsid,
                                         Pointer pUnkOuter,
                                         int dwClsContext,
                                         Guid.GUID riid,
                                         PointerByReference ppv)

      Creates a single uninitialized object of the class associated with a specified CLSID.
      Parameters:
        `rclsid` - The CLSID associated with the data and code that will be used to create the object.
        `pUnkOuter` - If NULL, indicates that the object is not being created as part of an aggregate. If non-NULL, pointer to the aggregate object's IUnknown interface (the controlling IUnknown).
        `dwClsContext` - Context in which the code that manages the newly created object will run. The values are taken from the enumeration CLSCTX defined in WTypes.
        `riid` - A reference to the identifier of the interface to be used to communicate with the object.
        `ppv` - Address of pointer variable that receives the interface pointer requested in riid. Upon successful return, *ppv contains the requested interface pointer. Upon failure, *ppv contains NULL.
      Returns:
        an HRESULT

    - #### CLSIDFromProgID

          WinNT.HRESULT CLSIDFromProgID(java.lang.String lpszProgID,
                                        Guid.CLSID.ByReference lpclsid)

      Looks up a CLSID in the registry, given a ProgID.
      Parameters:
        `lpszProgID` - [in] A pointer to the ProgID whose CLSID is requested.
        `lpclsid` - [out] Receives a pointer to the retrieved CLSID on return.
      Returns:
        S_OK The CLSID was retrieved successfully. CO_E_CLASSSTRING The registered CLSID for the ProgID is invalid. REGDB_E_WRITEREGDB An error occurred writing the CLSID to the registry. See Remarks below. Remarks Given a ProgID, CLSIDFromProgID looks up its associated CLSID in the registry. If the ProgID cannot be found in the registry, CLSIDFromProgID creates an OLE 1 CLSID for the ProgID and a CLSID entry in the registry. Because of the restrictions placed on OLE 1 CLSID values, CLSIDFromProgID and CLSIDFromString are the only two functions that can be used to generate a CLSID for an OLE 1 object.

    - #### CLSIDFromString

          WinNT.HRESULT CLSIDFromString(java.lang.String lpsz,
                                        Guid.CLSID.ByReference pclsid)

      Converts a string generated by the StringFromCLSID function back into the original CLSID.
      Parameters:
        `lpsz` - [in] The string representation of the CLSID.
        `pclsid` - [out] A pointer to the CLSID.
      Returns:
        Return value This function can return the standard return value E_INVALIDARG, as well as the following values. NOERROR The CLSID was obtained successfully. CO_E_CLASSSTRING The class string was improperly formatted. REGDB_E_CLASSNOTREG The CLSID corresponding to the class string was not found in the registry. REGDB_E_READREGDB The registry could not be opened for reading.

    - #### CLSIDFromString

          WinNT.HRESULT CLSIDFromString(WString lpsz,
                                        Guid.CLSID.ByReference pclsid)

      Deprecated. use the String version

    - #### CoTaskMemAlloc

          Pointer CoTaskMemAlloc(long cb)

      Allocates a block of task memory in the same way that IMalloc::Alloc does. CoTaskMemAlloc uses the default allocator to allocate a memory block in the same way that IMalloc::Alloc does. It is not necessary to call the CoGetMalloc function before calling CoTaskMemAlloc.

      The initial contents of the returned memory block are undefined - there is no guarantee that the block has been initialized. The allocated block may be larger than cb bytes because of the space required for alignment and for maintenance information.

      If cb is 0, CoTaskMemAlloc allocates a zero-length item and returns a valid pointer to that item. If there is insufficient memory available, CoTaskMemAlloc returns NULL. Applications should always check the return value from this function, even when requesting small amounts of memory, because there is no guarantee that the memory will be allocated.
      Parameters:
        `cb` - The size of the memory block to be allocated, in bytes.
      Returns:
        If the function succeeds, it returns the allocated memory block. Otherwise, it returns NULL.

    - #### CoTaskMemRealloc

          Pointer CoTaskMemRealloc(Pointer pv,
                                   long cb)

      Changes the size of a previously allocated block of task memory. This function changes the size of a previously allocated memory block in the same way that IMalloc::Realloc does. It is not necessary to call the CoGetMalloc function to get a pointer to the OLE allocator before calling CoTaskMemRealloc.

      The pv parameter points to the beginning of the memory block. If pv is NULL, CoTaskMemRealloc allocates a new memory block in the same way as the CoTaskMemAlloc function. If pv is not NULL, it should be a pointer returned by a prior call to CoTaskMemAlloc.

      The cb parameter specifies the size of the new block. The contents of the block are unchanged up to the shorter of the new and old sizes, although the new block can be in a different location. Because the new block can be in a different memory location, the pointer returned by CoTaskMemRealloc is not guaranteed to be the pointer passed through the pv argument. If pv is not NULL and cb is 0, then the memory pointed to by pv is freed.

      CoTaskMemRealloc returns a void pointer to the reallocated (and possibly moved) memory block. The return value is NULL if the size is 0 and the buffer argument is not NULL, or if there is not enough memory available to expand the block to the specified size. In the first case, the original block is freed; in the second case, the original block is unchanged. The storage space pointed to by the return value is guaranteed to be suitably aligned for storage of any type of object. To get a pointer to a type other than void, use a type cast on the return value.
      Parameters:
        `pv` - A pointer to the memory block to be reallocated. This parameter can be NULL.
        `cb` - The size of the memory block to be reallocated, in bytes. This parameter can be 0.
      Returns:
        If the function succeeds, it returns the reallocated memory block. Otherwise, it returns NULL.

    - #### CoTaskMemFree

          void CoTaskMemFree(Pointer pv)

      Frees a block of task memory previously allocated through a call to the `CoTaskMemAlloc(long)` or `CoTaskMemRealloc(com.sun.jna.Pointer, long)` function. The function uses the default OLE allocator. The number of bytes freed equals the number of bytes that were originally allocated or reallocated. After the call, the memory block pointed to by pv is invalid and can no longer be used.
      Parameters:
        `pv` - A pointer to the memory block to be freed. If this parameter is NULL, the function has no effect.

    - #### CoGetMalloc

          WinNT.HRESULT CoGetMalloc(WinDef.DWORD dwMemContext,
                                    PointerByReference ppMalloc)

      Retrieves a pointer to the default OLE task memory allocator. `HRESULT CoGetMalloc( [In] DWORD dwMemContext, [Out] LPMALLOC *ppMalloc );`
      Parameters:
        `dwMemContext` - context
        `ppMalloc` - returned pointer
      Returns:
        status
      See Also:
        MSDN

    - #### GetRunningObjectTable

          WinNT.HRESULT GetRunningObjectTable(WinDef.DWORD reserved,
                                              PointerByReference pprot)

      Returns a pointer to the IRunningObjectTable interface on the local running object table (ROT). `HRESULT GetRunningObjectTable( [In] DWORD reserved, [Out] LPRUNNINGOBJECTTABLE *pprot );`
      Parameters:
        `reserved` - unused
        `pprot` - returned pointer
      Returns:
        status
      See Also:
        MSDN

    - #### CreateBindCtx

          WinNT.HRESULT CreateBindCtx(WinDef.DWORD reserved,
                                      PointerByReference ppbc)

      Returns a pointer to an implementation of IBindCtx (a bind context object). `HRESULT CreateBindCtx( [In] DWORD reserved, [Out] LPBC *ppbc );`
      Parameters:
        `reserved` - unused
        `ppbc` - returned pointer
      Returns:
        status
      See Also:
        MSDN

    - #### CoIsHandlerConnected

          boolean CoIsHandlerConnected(Pointer pUnk)

      Determines whether a remote object is connected to the corresponding in-process object. `BOOL CoIsHandlerConnected( [In] LPUNKNOWN pUnk );`
      Parameters:
        `pUnk` - object
      Returns:
        whether the object is connected
      See Also:
        MSDN

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