/* Copyright (c) 2010 Daniel Doubrovkine, All Rights Reserved
*
* The contents of this file is dual-licensed under 2
* alternative Open Source/Free licenses: LGPL 2.1 or later and
* Apache License 2.0. (starting with JNA version 4.0.0).
*
* You can freely decide which license you want to apply to
* the project.
*
* You may obtain a copy of the LGPL License at:
*
* http://www.gnu.org/licenses/licenses.html
*
* A copy is also included in the downloadable source code package
* containing JNA, in file "LGPL2.1".
*
* You may obtain a copy of the Apache License at:
*
* http://www.apache.org/licenses/
*
* A copy is also included in the downloadable source code package
* containing JNA, in file "AL2.0".
*/
package com.sun.jna.platform.win32;
import com.sun.jna.Native;
import com.sun.jna.Pointer;
import com.sun.jna.WString;
import com.sun.jna.platform.win32.Guid.CLSID;
import com.sun.jna.platform.win32.Guid.GUID;
import com.sun.jna.platform.win32.WinDef.DWORD;
import com.sun.jna.platform.win32.WinDef.LPVOID;
import com.sun.jna.platform.win32.WinNT.HRESULT;
import com.sun.jna.ptr.PointerByReference;
import com.sun.jna.win32.StdCallLibrary;
import com.sun.jna.win32.W32APIOptions;
/**
* Ole32.dll Interface.
*
* @author dblock[at]dblock.org
* @author Tobias Wolf, wolf.tobias@gmx.net
*/
public interface Ole32 extends StdCallLibrary {
/** The instance. */
Ole32 INSTANCE = Native.loadLibrary("Ole32", Ole32.class, W32APIOptions.DEFAULT_OPTIONS);
/**
* Creates a GUID, a unique 128-bit integer used for CLSIDs and interface
* identifiers.
*
* @param pguid
* A pointer to the requested GUID.
* @return S_OK if the GUID was successfully created.
*/
HRESULT CoCreateGuid(GUID pguid);
/**
* @deprecated use {@link #CoCreateGuid(Guid.GUID)}.
* @param pguid GUID reference
* @return result
*/
HRESULT CoCreateGuid(GUID.ByReference pguid);
/**
* Converts a globally unique identifier (GUID) into a string of printable
* characters.
*
* @param rguid
* The GUID to be converted.
* @param lpsz
* A pointer to a caller-allocated string variable to receive the
* resulting string.
* @param cchMax
* The number of characters available in the lpsz buffer.
* @return 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.
*/
int StringFromGUID2(GUID rguid, char[] lpsz, int cchMax);
/**
* Converts a string generated by the StringFromIID function back into the
* original interface identifier (IID).
*
* @param lpsz
* A pointer to the string representation of the IID.
* @param lpiid
* A pointer to the requested IID on return.
* @return This function can return the standard return values E_INVALIDARG,
* E_OUTOFMEMORY, and S_OK.
*/
HRESULT IIDFromString(String lpsz, GUID lpiid);
/**
* 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.
*
* @param pvReserved
* the pv reserved
* @return 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.
*/
HRESULT CoInitialize(LPVOID pvReserved);
int COINIT_APARTMENTTHREADED = 0x2;
int COINIT_MULTITHREADED = 0x0;
int COINIT_DISABLE_OLE1DDE = 0x4;
int COINIT_SPEED_OVER_MEMORY = 0x8;
/**
* 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.
*
* @param reserved
* This parameter is reserved and must be NULL.
* @param 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 {@link #COINIT_APARTMENTTHREADED} and
* {@link #COINIT_MULTITHREADED} flags cannot both be set. The
* default (and only sane choice) is
* {@link #COINIT_MULTITHREADED}.
* @return 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
*/
HRESULT CoInitializeEx(Pointer reserved, int dwCoInit);
/**
* 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.
*
*/
void CoUninitialize();
/**
* Creates a single uninitialized object of the class associated with a
* specified CLSID.
*
* @param rclsid
* The CLSID associated with the data and code that will be used
* to create the object.
* @param 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).
* @param 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.
* @param riid
* A reference to the identifier of the interface to be used to
* communicate with the object.
* @param 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.
* @return an HRESULT
*/
HRESULT CoCreateInstance(GUID rclsid, Pointer pUnkOuter, int dwClsContext,
GUID riid, PointerByReference ppv);
/**
* Looks up a CLSID in the registry, given a ProgID.
*
* @param lpszProgID
* [in] A pointer to the ProgID whose CLSID is requested.
* @param lpclsid
* [out] Receives a pointer to the retrieved CLSID on return.
*
* @return 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.
*/
HRESULT CLSIDFromProgID(String lpszProgID, CLSID.ByReference lpclsid);
/**
* Converts a string generated by the StringFromCLSID function back into the
* original CLSID.
*
* @param lpsz
* [in] The string representation of the CLSID.
*
* @param pclsid
* [out] A pointer to the CLSID.
*
* @return 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.
*/
HRESULT CLSIDFromString(String lpsz, CLSID.ByReference pclsid);
/** @deprecated use the String version */
HRESULT CLSIDFromString(WString lpsz, CLSID.ByReference pclsid);
/**
* 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.
* <p>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.
* </p>
* 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.
* @param cb The size of the memory block to be allocated, in bytes.
* @return If the function succeeds, it returns the allocated memory block. Otherwise, it returns NULL.
*/
Pointer CoTaskMemAlloc(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.
* <p>
* 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.
* </p><p>
* 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.
* </p>
* 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.
* @param pv A pointer to the memory block to be reallocated. This parameter can be NULL.
* @param cb The size of the memory block to be reallocated, in bytes. This parameter can be 0.
* @return If the function succeeds, it returns the reallocated memory block. Otherwise, it returns NULL.
*/
Pointer CoTaskMemRealloc(Pointer pv, long cb);
/**
* Frees a block of task memory previously allocated through a call to the {@link #CoTaskMemAlloc} or
* {@link #CoTaskMemRealloc} 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.
* @param pv A pointer to the memory block to be freed. If this parameter is NULL, the function has no effect.
*/
void CoTaskMemFree(Pointer pv);
/**
* Retrieves a pointer to the default OLE task memory allocator.
*
* {@code
* HRESULT CoGetMalloc(
* [In] DWORD dwMemContext,
* [Out] LPMALLOC *ppMalloc
* );}
*
* @param dwMemContext context
* @param ppMalloc returned pointer
* @return status
* @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms693395%28v=vs.85%29.aspx">MSDN</a>
*
*/
HRESULT CoGetMalloc(DWORD dwMemContext, PointerByReference ppMalloc);
/**
* Returns a pointer to the IRunningObjectTable interface on the local running object table (ROT).
*
* {@code
* HRESULT GetRunningObjectTable(
* [In] DWORD reserved,
* [Out] LPRUNNINGOBJECTTABLE *pprot
* );
* }
*
*
* @param reserved unused
* @param pprot returned pointer
* @return status
* @see <a href="msdn.com">MSDN</a>
*/
HRESULT GetRunningObjectTable(DWORD reserved, PointerByReference pprot);
/**
* Returns a pointer to an implementation of IBindCtx (a bind context object).
*
* {@code
* HRESULT CreateBindCtx(
* [In] DWORD reserved,
* [Out] LPBC *ppbc
* );
* }
*
*
* @param reserved unused
* @param ppbc returned pointer
* @return status
* @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms678542%28v=vs.85%29.aspx">MSDN</a>
*/
HRESULT CreateBindCtx(DWORD reserved, PointerByReference ppbc);
/**
* Determines whether a remote object is connected to the corresponding in-process object.
*
* {@code
* BOOL CoIsHandlerConnected(
* [In] LPUNKNOWN pUnk
* );
* }
*
* @param pUnk object
* @return whether the object is connected
* @see <a href="http://msdn.microsoft.com/en-us/library/windows/desktop/ms694359%28v=vs.85%29.aspx">MSDN</a>
*
*/
boolean CoIsHandlerConnected(Pointer pUnk);
/**
* Initializes the COM library on the current apartment, identifies the
* concurrency model as single-thread apartment (STA), and enables
* additional functionality described in the Remarks section below.
* Applications must initialize the COM library before they can call COM
* library functions other than CoGetMalloc and memory allocation functions.
* @param pvReserved Reserved; must be null.
* @return {@link WinError#S_OK S_OK} if the COM library and additional functionality were
* initialized successfully on this apartment.<p>
* {@link WinError#S_FALSE S_FALSE} if the COM library is already initialized on this apartment.<p>
* {@link WinError#OLE_E_WRONGCOMPOBJ OLE_E_WRONGCOMPOBJ} if the versions of COMPOBJ.DLL and OLE2.DLL on
* your machine are incompatible with each other.<p>
* {@link WinError#RPC_E_CHANGED_MODE RPC_E_CHANGED_MODE} if a previous call to CoInitializeEx specified
* the concurrency model for this apartment as
* multithread apartment (MTA). If running
* Windows 2000, this could also mean that a
* change from neutral threaded apartment to
* single threaded apartment occurred.
*/
HRESULT OleInitialize(Pointer pvReserved);
/**
* Closes the COM library on the apartment, releases any class factories,
* other COM objects, or servers held by the apartment, disables RPC on the
* apartment, and frees any resources the apartment maintains.
*
* Remarks:
* Call OleUninitialize on application shutdown, as the last COM library
* call, if the apartment was initialized with a call to
* {@link #OleInitialize}. OleUninitialize calls the CoUninitialize function
* internally to shut down the OLE Component Object(COM) Library.
*
* If the COM library was initialized on the apartment with a call to
* CoInitialize or CoInitializeEx, it must be closed with a call to
* CoUninitialize.
*
* The {@link #OleInitialize} and OleUninitialize calls must be balanced —
* if there are multiple calls to the {@link #OleInitialize} function, there
* must be the same number of calls to OleUninitialize: Only the
* OleUninitialize call corresponding to the {@link #OleInitialize} call
* that actually initialized the library can close it.
*/
void OleUninitialize();
/**
* Carries out the clipboard shutdown sequence. It also releases the
* IDataObject pointer that was placed on the clipboard by the
* OleSetClipboard function.
* @return {@link WinError#S_OK S_OK} on success.<p>
* {@link WinError#CLIPBRD_E_CANT_OPEN CLIPBRD_E_CANT_OPEN} The Windows OpenClipboard function used
* within OleFlushClipboard failed.<p>
* {@link WinError#CLIPBRD_E_CANT_CLOSE CLIPBRD_E_CANT_CLOSE} The Windows CloseClipboard function used
* within OleFlushClipboard failed.<p>
* <b>Remarks</b><p>
* OleFlushClipboard renders the data from a data object onto the clipboard
* and releases the IDataObject pointer to the data object. While the
* application that put the data object on the clipboard is running, the
* clipboard holds only a pointer to the data object, thus saving memory.
* If you are writing an application that acts as the source of a clipboard
* operation, you can call the OleFlushClipboard function when your
* application is closed, such as when the user exits from your application.
* Calling OleFlushClipboard enables pasting and paste-linking of OLE
* objects after application shutdown.
* Before calling OleFlushClipboard, you can easily determine if your data
* is still on the clipboard with a call to the OleIsCurrentClipboard
* function.
*
* OleFlushClipboard leaves all formats offered by the data transfer object,
* including the OLE 1 compatibility formats, on the clipboard so they are
* available after application shutdown. In addition to OLE 1 compatibility
* formats, these include all formats offered on a global handle medium (all
* except for TYMED_FILE) and formatted with a null target device. For
* example, if a data-source application offers a particular clipboard
* format (say cfFOO) on an IStorage object, and calls the OleFlushClipboard
* function, the storage object is copied into memory and the hglobal memory
* handle is put on the clipboard.
*
* To retrieve the information on the clipboard, you can call the
* OleGetClipboard function from another application, which creates a
* default data object, and the hglobal from the clipboard again becomes a
* storage object. Furthermore, the FORMATETC enumerator and the
* IDataObject::QueryGetData method would all correctly indicate that the
* original clipboard format (cfFOO) is again available on a TYMED_ISTORAGE.
*
* To empty the clipboard, call the OleSetClipboard function specifying a
* null value for its parameter. The application should call this when it
* closes if there is no need to leave data on the clipboard after shutdown,
* or if data will be placed on the clipboard using the standard Windows
* clipboard functions.
*/
HRESULT OleFlushClipboard();
/**
* Puts an OLE compound document object into the running state.
* @param pUnknown [in] Pointer to the {@link IUnknown IUnknown} interface
* on the object, with which it will query for a pointer to
* the IRunnableObject interface, and then call its Run method.
* @return This function returns on success.
* Other possible values include the following.<p>
* {@link WinError#OLE_E_CLASSDIFF OLE_E_CLASSDIFF} The source of an
* OLE link has been converted to a different class.<p>
* <B>Remarks</B><p>
* The OleRun function puts an object in the running state. The
* implementation of OleRun was changed in OLE 2.01 to coincide with the
* publication of the IRunnableObject interface. You can use OleRun and
* IRunnableObject::Run interchangeably. OleRun queries the object for a
* pointer to IRunnableObject. If successful, the function returns the
* results of calling the IRunnableObject::Run method.<p><p>
* For more information on using this function, see IRunnableObject::Run.
*/
HRESULT OleRun(Pointer pUnknown);
}