iunknown.java

java 调用windows的api

/*
 * IUnknown.java -
 *
 * This file is part of the Jawin Project: http://jawinproject.sourceforge.net/
 * 
 * Please consult the LICENSE file in the project root directory,
 * or at the project site before using this software.
 */

/* $Id: IUnknown.java,v 1.4 2004/07/02 18:43:22 arosii_moa Exp $ */

package org.jawin;

/**
 * A java interface mirroring the COM IUnknown-interface that all
 * COM objects MUST implement.
 *
 * @see org.jawin.UnknownPtr UnknownPtr for a concrete implementation of this interface.
 * 
 * @version     $Revision: 1.4 $
 * @author      Stuart Halloway, http://www.relevancellc.com/halloway/weblog/
 */
public interface IUnknown {
	
	/**
	 * return another interface on this object. The returned interface is NOT 
	 * threadsafe. To get a threadsafe interface, use {@link #queryGITInterface(Class)}.
	 * 
	 * @param newItf must be a subclass of {@link COMPtr}.
	 * @return the requested interface - the caller should cast it
	 * 			down to the requested type.
	 * @throws COMException if the requested interface is not supported
	 * 			on this object.
	 */
	IUnknown queryInterface(Class newItf) throws COMException;

	/**
	 * return a threadsafe interface on this object.
	 * <br><br>
	 * <b>Important: </b> note that invoking native methods on such a threadsafe
	 * object is a factor 5-20 times slower per call than using a non-threadsafe
	 * object.
	 * 
	 * @param newItf must be a subclass of {@link COMPtr}.
	 * @return the requested interface - the caller should cast it
	 * 			down to the requested type.
	 * @throws COMException if the requested interface is not supported
	 * 			on this object.
	 */
	IUnknown queryGITInterface(Class newItf) throws COMException;

	/**
	 * return a new interface object that can ONLY be used on this thread. 
	 * The interface is of the same type as the object this method is called on.
	 * 
	 * @return a new non-threadsafe object - the caller should cast it down to
	 * 			the requested type.
	 * @throws COMException if unable to create a non-threadsafe object.
	 * @see #queryInterface(Class)
	 */
	IUnknown createDirectRef() throws COMException;

	/**
	 * return a new threadsafe object, that is an interface on this object.
	 * The interface is of the same type as the object this method is called on.
	 * <br><br>
	 * <b>Important: </b> note that invoking native methods on such a threadsafe
	 * object is a factor 5-20 times slower per call than using a non-threadsafe
	 * object.
	 * 
	 * @return a new threadsafe object - the caller should cast it down
	 * 			to the requested type.
	 * @throws COMException if unable to create a threadsafe object
	 * 			for this interface.
	 * @see #queryGITInterface(Class)
	 */
	IUnknown createGITRef() throws COMException;

	/**
	 * should be called when finished using this IUnknown. Should
	 * decrease all reference counts for either the GIT-cookie or
	 * the vtable interface pointer, and for any other resources.
	 */
	void close() throws COMException;

	/**
	 * should return a registered token for the GUID for this interface
	 * (the socalled Interface Identifier (IID)).
	 */
	int getIIDToken();
	
	/**
	 * should return the GIT cookie if any for this IUnknown. If the returned
	 * value is 0, this IUnknown interface is not threadsafe. If the 
	 * unknown pointer is set, the GIT cookie is not used.
	 * 
	 * @see #getUnknown()
	 */
	int getPeer();

	/**
	 * should return the raw vtable pointer for this IUnknown. If this is set
	 * this IUnknown can not be used from different threads. If this
	 * is 0, the GIT cookie should be set.
	 * 
	 * @see #getPeer()
	 */
	int getUnknown();
}