Package com.sun.jna.platform.win32.COM

Interface IEnumIDList

  • public interface IEnumIDList

    • 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.

      • 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.