com.sun.jna.platform.win32.COM

Interface IEnumIDList

public interface IEnumIDList

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	IEnumIDList.Converter

Field Summary

Fields

Modifier and Type	Field and Description
static Guid.IID	IID_IEnumIDList The interface IID for QueryInterface et al

Method Summary

Modifier and Type	Method and Description
int	AddRef() Increments the reference count for an interface on an object.
WinNT.HRESULT	Clone(PointerByReference ppenum) Creates a new item enumeration object with the same contents and state as the current one.
WinNT.HRESULT	Next(int celt, PointerByReference rgelt, IntByReference pceltFetched)
WinNT.HRESULT	QueryInterface(Guid.REFIID riid, PointerByReference ppvObject) Retrieves pointers to the supported interfaces on an object.
int	Release() Decrements the reference count for an interface on an object.
WinNT.HRESULT	Reset() Returns to the beginning of the enumeration sequence.
WinNT.HRESULT	Skip(int celt) Skips the specified number of elements in the enumeration sequence.

Field Detail

IID_IEnumIDList

static final Guid.IID IID_IEnumIDList

The interface IID for QueryInterface et al

Method Detail

QueryInterface

WinNT.HRESULT QueryInterface(Guid.REFIID riid,
                             PointerByReference ppvObject)

Retrieves pointers to the supported interfaces on an object. This method calls IUnknown::AddRef on the pointer it returns.

Parameters:

riid - The identifier of the interface being requested.

ppvObject - The address of a pointer variable that receives the interface pointer requested in the riid parameter. Upon successful return, *ppvObject contains the requested interface pointer to the object. If the object does not support the interface, *ppvObject is set to NULL.

Returns:

This method returns S_OK if the interface is supported, and E_NOINTERFACE otherwise. If ppvObject is NULL, this method returns E_POINTER. For any one object, a specific query for the IUnknown interface on any of the object's interfaces must always return the same pointer value. This enables a client to determine whether two pointers point to the same component by calling QueryInterfacewith IID_IUnknown and comparing the results. It is specifically not the case that queries for interfaces other than IUnknown (even the same interface through the same pointer) must return the same pointer value. There are four requirements for implementations of QueryInterface (In these cases, "must succeed" means "must succeed barring catastrophic failure."): The set of interfaces accessible on an object through QueryInterface must be static, not dynamic. This means that if a call toQueryInterface for a pointer to a specified interface succeeds the first time, it must succeed again, and if it fails the first time, it must fail on all subsequent queries.
 It must be reflexive: if a client holds a pointer to an interface on an object, and queries for that interface, the call must succeed.
 It must be symmetric: if a client holding a pointer to one interface queries successfully for another, a query through the obtained pointer for the first interface must succeed.
 It must be transitive: if a client holding a pointer to one interface queries successfully for a second, and through that pointer queries successfully for a third interface, a query for the first interface through the pointer for the third interface must succeed.
 Notes to Implementers Implementations of QueryInterface must never check ACLs. The main reason for this rule is that COM requires that an object supporting a particular interface always return success when queried for that interface. Another reason is that checking ACLs on QueryInterface does not provide any real security because any client who has access to a particular interface can hand it directly to another client without any calls back to the server. Also, because COM caches interface pointers, it does not callQueryInterface on the server every time a client does a query.

AddRef

int AddRef()

Increments the reference count for an interface on an object. This method should be called for every new copy of a pointer to an interface on an object.

Returns:

The method returns the new reference count. This value is intended to be used only for test purposes. Objects use a reference counting mechanism to ensure that the lifetime of the object includes the lifetime of references to it. You use AddRef to stabilize a copy of an interface pointer. It can also be called when the life of a cloned pointer must extend beyond the lifetime of the original pointer. The cloned pointer must be released by calling IUnknown::Release. The internal reference counter that AddRef maintains should be a 32-bit unsigned integer. Notes to Callers Call this method for every new copy of an interface pointer that you make. For example, if you are passing a copy of a pointer back from a method, you must call AddRef on that pointer. You must also call AddRef on a pointer before passing it as an in-out parameter to a method; the method will call IUnknown::Release before copying the out-value on top of it.

Release

int Release()

Decrements the reference count for an interface on an object.

Returns:

The method returns the new reference count. This value is intended to be used only for test purposes. When the reference count on an object reaches zero, Release must cause the interface pointer to free itself. When the released pointer is the only existing reference to an object (whether the object supports single or multiple interfaces), the implementation must free the object. Note that aggregation of objects restricts the ability to recover interface pointers. Notes to Callers Call this method when you no longer need to use an interface pointer. If you are writing a method that takes an in-out parameter, call Release on the pointer you are passing in before copying the out-value on top of it.

Next

WinNT.HRESULT Next(int celt,
                   PointerByReference rgelt,
                   IntByReference pceltFetched)

Skip

WinNT.HRESULT Skip(int celt)

Skips the specified number of elements in the enumeration sequence.

Parameters:

celt - The number of item identifiers to skip.

Returns:

HRESULT Returns S_OK if successful, or a COM-defined error value otherwise.

Reset

WinNT.HRESULT Reset()

Returns to the beginning of the enumeration sequence.

Returns:

HRESULT Returns S_OK if successful, or a COM-defined error value otherwise.

Clone

WinNT.HRESULT Clone(PointerByReference ppenum)

Creates a new item enumeration object with the same contents and state as the current one.

Parameters:

ppenum - The address of a pointer to the new enumeration object. The calling application must eventually free the new object by calling its Release member function.

Returns:

HRESULT Returns S_OK if successful, or a COM-defined error value otherwise.