/*
        @doc AQADMIN EXTERNAL

    @module AQADMIN.IDL - IDL for Advanced Queue Admin Object. | This module 
    declares the various interfaces exported for access to the Advanced Queue
        administration object
*/

cpp_quote("/*++")
cpp_quote("")
cpp_quote("Copyright (c) 1998 Microsoft Corporation")
cpp_quote("")
cpp_quote("Module Name:")
cpp_quote("")
cpp_quote("     aqadmin.idl / aqadmin.h")
cpp_quote("")
cpp_quote("Abstract:")
cpp_quote("")
cpp_quote("     This module contains definitions for the COM interfaces for")
cpp_quote("     the Advanced Queue administration object.")
cpp_quote("")
cpp_quote("--*/")

import "oaidl.idl";
import "ocidl.idl";

//
// @doc AQADMIN EXTERNAL
//

interface IVSAQAdmin;
interface IEnumVSAQLinks;
interface IAQEnumMessages;
interface IEnumLinkQueues;
interface IAQMessage;
interface IVSAQLink;
interface ILinkQueue;

cpp_quote("#ifndef __AQADMTYP_H__")
cpp_quote("#define __AQADMTYP_H__")
#include "aqadmtyp.h"
cpp_quote("#endif")

/*
        @interface IAQAdmin | Primary interface to Advanced Queue admin objects
        @meth HRESULT | GetVirtualServerAdminITF | Get admin interface to a
        SMTP or MTA virtual server's queues
*/
[
        helpstring("Advanced Queue Administration Object"),
        object,
        pointer_default(unique),
        uuid(476D70A6-1A90-11d3-BFCB-00C04FA3490A)

]
interface IAQAdmin : IUnknown
{
        // @method HRESULT | IAQAdmin | GetVirtualServerAdminITF | Get admin 
        // interface to a SMTP or MTA virtual server's queues
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Out of resources
        // @rvalue E_ACCESSDENIED | Logged on principal not authorized to view 
        // queues on specified virtual server
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        //connect to specified virtual server
        HRESULT GetVirtualServerAdminITF(
				// @parm hostname of the computer 
				[in] 	LPCWSTR wszComputer,
				// @parm virtual server number
				[in] 	LPCWSTR wszVirtualServer,
				// @parm Interface to Virtual Server admin object is 
				// returned here
				[out] 	IVSAQAdmin **ppivsaqadmin 
                );
}

/*
        @interface IAQMessageAction | Interface used to apply actions
        to messages on this virtual server.  This interface is
        implemented at the server, link and queue level
        @meth HRESULT | ApplyActionToMessages | Apply specified action to 
		messages on this Virtual Server that match the specified message 
		filter criteria.
        @meth HRESULT | QuerySupportedActions | Describes
        which actions/filters of <t ApplyActionToMessages> is supported.
*/
[
        helpstring("Advanced Queue Message Action Interface"),
        object,
        pointer_default(unique),
        uuid(1EB44A71-1E95-11d3-BFCC-00C04FA3490A)
]
interface IAQMessageAction : IUnknown
{
        // @method HRESULT | IAQMessageAction | ApplyActionToMessages | Apply 
		// specified action to messages on this Virtual Server that match the 
		// specified message filter criteria.  The actions will only be applied
        // to messages that belong to the object implmenting this interface.  
        // For example, on messages that match the filter on a given queue will
        // be affected if this method is called on an ILinkQueue object.
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT ApplyActionToMessages(
				// @parm The <t MESSAGE_FILTER> to use to select messages
				[in] PMESSAGE_FILTER Filter,
				// @parm The <t MESSAGE_ACTION> to apply to matching messages
                [in] MESSAGE_ACTION Action,
                // @parm The number of messages affected by the action
                [out] DWORD *pcMsgs 	
                );

        // @method HRESULT | IAQMessageAction | QuerySupportedActions | Describes
        // which actions/filters of <t ApplyActionToMessages> is supported.
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT QuerySupportedActions(
                [out] DWORD *pdwSupportedActions,
                // @parm The <t MESSAGE_ACTION> flags supported by this interface.
                [out] DWORD *pdwSupportedFilterFlags);
                // @parm The <t MESSAGE_FILTER_FLAGS> supported by this interface.

}

/*
        @interface IVSAQAdmin | Interface to per-virtual-server AQ 
		Administration
        @meth HRESULT | GetLinkEnum | Get an enumerator over all links on 
		this VS
        @meth HRESULT | StopAllLinks | Stop all active outbound links
        @meth HRESULT | StartAllLinks | Start all eligible outbound links
*/
[
        helpstring("Advanced Queue Administration Object"),
        object,
        pointer_default(unique),
        uuid(E2ED3340-1E96-11d3-BFCC-00C04FA3490A)
]
interface IVSAQAdmin : IUnknown
{
        // @method HRESULT | IVSAQAdmin | GetLinkEnum | Get an enumerator over 
		// all links on this VS
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT GetLinkEnum(
				// @parm Interface to link enumerator is returned here.
                [out] IEnumVSAQLinks **ppenum 
                );

        // @method HRESULT | IVSAQAdmin | StopAllLinks | Stop all active 
		// outbound links
        // @rvalue S_OK | Success
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT StopAllLinks();

        // @method HRESULT | IVSAQAdmin | StartAllLinks | Start all active 
		// outbound links
        // @rvalue S_OK | Success
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT StartAllLinks();

        // @method HRESULT | IVSAQAdmin | GetGlobalLinkState | Checks the 
        // global state of the links as set by StopAllLinks/StartAllLinks.
        // @rvalue S_OK | Links are started
        // @rvalue S_FALSE | Link have been stopped (by a previous call
        // to StopAllLinks.
        // @rvalue E_NOTIMPL | This provider does not support getting or 
        // setting the global link state.
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT GetGlobalLinkState();
}

/*
        @interface IEnumVSAQLinks | Enumerator for a Virtual Server's AQ Links
        @meth HRESULT | Next | Returns the sequentially consequetive specified 
        number of IVSAQLink objects.
        @meth HRESULT | Skip | Advances current element cursor by specified 
		number of elements
        @meth HRESULT | Reset | Resets current element cursor to start of list
        @meth HRESULT | Clone | Creates a copy of this enumerator object
*/
[
        helpstring("Advanced Queue Administration Object"),
        object,
        pointer_default(unique),
        uuid(ba7af300-7373-11d2-94e4-00c04fa379f1)
]
interface IEnumVSAQLinks : IUnknown
{
        // @method HRESULT | IEnumVSAQLinks | Next | Returns the sequentially 
        // consequetive specified number of IVSAQLink objects.
        // @rvalue S_OK | Success
        // @rvalue S_FALSE | Fewer than requested number of object returned
        HRESULT Next(
				// @parm Number of elements requested	
                [in] ULONG cElt, 
				// @parm Array in which to return IVSAQLink objects. Must be 
				// atleast <p cElt> long.
                [out] IVSAQLink **rgelt, 
				// @parm Number of elements actually returned.
                [out] ULONG *pcFetched 
                );

        // @method HRESULT | IEnumVSAQLinks | Skip | Advances current element 
		// cursor by specified number of elements
        // @rvalue S_OK | Success
        // @rvalue S_FALSE | Too few elements in enumerator to successfully 
		// advance cursor. Cursor positioned to last element
        HRESULT Skip(
				// @parm Number of elements to advance cursor by.
                [in] ULONG cElt 
                );

        // @method HRESULT | IEnumVSAQLinks | Reset | Resets current element 
		// cursor to start of list
        // @rvalue S_OK | Success
        HRESULT Reset();

        // @method HRESULT | IEnumVSAQLinks | Clone | Creates a clone of the 
		// this enumerator object.
        // @rvalue S_OK | Success
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_OUTOFMEMORY | Out of memory creating clone.
        HRESULT Clone(
				// @parm Interface to cloned IEnumVSAQLinks	is returned here.
                [out] IEnumVSAQLinks **ppenum  
                );             

}

/*
        @interface IVSAQLink | Interface to a single virtual server AQ Link. A 
		link represents a connectable entity. Another way to think of a link 
		is that it represents the next-hop to which mail messages on this 
		link will be delivered to.
        @meth HRESULT | GetInfo | Returns information about the link
        @meth HRESULT | SetLinkState | Sets the links state.
        @meth HRESULT | GetQueueEnum | Returns an enumerator for msg queues 
		on this link
*/

[
        helpstring("Advanced Queue Administration Object"),
        object,
        pointer_default(unique),
        uuid(3F962F94-1ECD-11d3-BFCC-00C04FA3490A)
]
interface IVSAQLink : IUnknown
{
        // @method HRESULT | IVSAQLink | GetInfo | Returns information about 
		// the link
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT GetInfo(
				// @parm Pointer to <t LINK_INFO> structure to fill.	
                [in, out] PLINK_INFO pli 
                );

        // @method HRESULT | IVSAQLink | SetLinkState | Changes the state of the link
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT SetLinkState(
				// @parm <t LINK_ACTION> describing	new state of link. 
                [in] LINK_ACTION la 
                );                         
                                           
        // @method HRESULT | IVSAQLink | GetQueueEnum | Get an enumerator for
        // message queues on this link
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT GetQueueEnum(
				// @parm Interface to IEnumLinkQueues is returned here.
                [out] IEnumLinkQueues **ppenum 
                );                                           

}


/*
        @interface IAQEnumMessages | Enumerator for a AQ Link's messages
        @meth HRESULT | Next | Returns the sequentially consequetive specified 
        number of IAQMessage objects.
        @meth HRESULT | Skip | Advances current element cursor by specified 
		number of elements
        @meth HRESULT | Reset | Resets current element cursor to start of list
        @meth HRESULT | Clone | Creates a copy of this enumerator object
*/
[
        helpstring("Advanced Queue Administration Object"),
        object,
        pointer_default(unique),
        uuid(ba7af302-7373-11d2-94e4-00c04fa379f1)
]
interface IAQEnumMessages : IUnknown
{
        // @method HRESULT | IAQEnumMessages | Next | Returns the 
		// sequentially consequetive specified number of IAQMessage objects.
        // @rvalue S_OK | Success
        // @rvalue S_FALSE | Fewer than requested number of object returned
        HRESULT Next(
				// @parm Number of elements requested
                [in] ULONG cElt, 
				// @parm Array in which to return IAQMessage objects. Must be 
				// atleast <p cElt> long.
                [out] IAQMessage **rgelt, 
                // @parm Number of elements actually returned.
                [out] ULONG *pcFetched 
                );

        // @method HRESULT | IAQEnumMessages | Skip | Advances current 
		// element cursor by specified number of elements
        // @rvalue S_OK | Success
        // @rvalue S_FALSE | Too few elements in enumerator to successfully 
		// advance cursor. Cursor positioned to last element
        HRESULT Skip(
				// @parm Number of elements to advance cursor by.
                [in] ULONG cElt 
                );

        // @method HRESULT | IAQEnumMessages | Reset | Resets current element 
		// cursor to start of list
        // @rvalue S_OK | Success
        HRESULT Reset();

        // @method HRESULT | IAQEnumMessages | Clone | Creates a clone of the 
		// this enumerator object.
        // @rvalue S_OK | Success
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_OUTOFMEMORY | Out of memory creating clone.
        HRESULT Clone(
				// @parm Interface to cloned IAQEnumMessages is returned here.
                [out] IAQEnumMessages **ppenum  
                );                                               

}

/*
        @interface IEnumLinkQueues | Enumerator for a AQ Link's messages
        @meth HRESULT | Next | Returns the sequentially consequetive specified 
        number of ILinkQueue objects.
        @meth HRESULT | Skip | Advances current element cursor by specified 
		number of elements
        @meth HRESULT | Reset | Resets current element cursor to start of list
        @meth HRESULT | Clone | Creates a copy of this enumerator object
*/
[
        helpstring("Advanced Queue Administration Object"),
        object,
        pointer_default(unique),
        uuid(ba7af303-7373-11d2-94e4-00c04fa379f1)
]
interface IEnumLinkQueues : IUnknown
{
        // @method HRESULT | IEnumLinkQueues | Next | Returns the sequentially 
        // consequetive specified number of ILinkQueue objects.
        // @rvalue S_OK | Success
        // @rvalue S_FALSE | Fewer than requested number of object returned
        HRESULT Next(
				// @parm Number of elements requested
                [in] ULONG cElt, 
				// @parm Array in which to return ILinkQueue objects. Must 
				// be atleast <p cElt> long.
                [out] ILinkQueue **rgelt, 
				// @parm Number of elements actually returned.	
                [out] ULONG *pcFetched 
                );

        // @method HRESULT | IEnumLinkQueues | Skip | Advances current element 
		// cursor by specified number of elements
        // @rvalue S_OK | Success
        // @rvalue S_FALSE | Too few elements in enumerator to successfully 
		// advance cursor. Cursor positioned to last element
        HRESULT Skip(
				// @parm Number of elements to advance cursor by.
                [in] ULONG cElt 
                );

        // @method HRESULT | IEnumLinkQueues | Reset | Resets current element 
		// cursor to start of list
        // @rvalue S_OK | Success
        HRESULT Reset();

        // @method HRESULT | IEnumLinkQueues | Clone | Creates a clone of 
		// the this enumerator object.
        // @rvalue S_OK | Success
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_OUTOFMEMORY | Out of memory creating clone.
        HRESULT Clone(
				// @parm Interface to cloned IEnumLinkQueues is returned here.
                [out] IEnumLinkQueues **ppenum  
                );                                               

}

/*
        @interface ILinkQueue | Interface to a single queue of messages that 
		will be serviced by a link. A link may be servicing 0 to many queues. 
		For example, if the server GW1 has a SMTP connector for *.com, then 
		on server MB1, there may be a link for GW1 servicing the queues for 
		IBM.COM and MSFT.COM
        @meth HRESULT | GetInfo | Returns information about the Queue
        @meth HRESULT | GetMessageEnum | Returns an enumerator for messages 
		on this link
*/

[
        helpstring("Advanced Queue Administration Object"),
        object,
        pointer_default(unique),
        uuid(FF9A1BB6-1E96-11d3-BFCC-00C04FA3490A)
]
interface ILinkQueue : IUnknown
{
        // @method HRESULT | ILinkQueue | GetInfo | Returns information about 
		// the link
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT GetInfo(
				// @parm Pointer to <t QUEUE_INFO> structure to fill.
                [in, out] PQUEUE_INFO pqi 
                );

        // @method HRESULT | ILinkQueue | GetMessageEnum | Get an enumerator for
        // messages on this link
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT GetMessageEnum(
				// @parm Filter specifying messages to return
                [in] PMESSAGE_ENUM_FILTER pFilter, 
				// @parm Interface to IAQEnumMessages is returned here.
                [out] IAQEnumMessages **ppenum     
                );                                                 

}

/*
        @interface IAQMessage | Interface representing a single message
        @meth HRESULT | GetInfo | Returns information about the Queue
        @meth HRESULT | GetContentStream | Returns a stream for the message content
*/

[
        helpstring("Advanced Queue Administration Object"),
        object,
        pointer_default(unique),
        uuid(ba7af305-7373-11d2-94e4-00c04fa379f1)
]
interface IAQMessage : IUnknown
{
        // @method HRESULT | IAQMessage | GetInfo | Returns information about 
		// the message
        // @rvalue S_OK | Success
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT GetInfo(
				// @parm Pointer to <t MESSAGE_INFO> structure to fill        
                [in, out] PMESSAGE_INFO pmi 
                );

        // @method HRESULT | IAQMessage | GetContentStream | Returns 
		// a Stream of the message content
        // @rvalue S_OK | Success
        // @rvalue E_NOTIMPL | This queue provider does not support 
        // this functionality
        // @rvalue E_OUTOFMEMORY | Insufficient resources
        // @rvalue E_POINTER | Null pointer parameter
        // @rvalue E_INVALIDARG | Invalid parameter
        // @rvalue HRESULT_FROM_WIN32(RPC_S_SERVER_UNAVAILABLE) | Unable to 
        // connect to specified virtual server
        HRESULT GetContentStream(
                // @parm Pointer to IStream interface for message content
                [out] IStream **ppIStream,
                // @parm String describing the content type (if known) of the message
                [out] LPWSTR *pwszContentType);


}

/*
        @interface IUniqueId | Interface to get canonical name of queue/link
        @meth HRESULT | GetUniqueId | Return QUEUELINK_ID for queue/link
*/
[
        helpstring("Queue/Link Id Object"),
        object,
        pointer_default(unique),
        uuid(EA4DFDF2-9E87-4c57-B845-123872C5649F)

]
interface IUniqueId : IUnknown
{
        // @method HRESULT | IUniqueId | GetUniqueId | Returns 
        // a QUEUELINK_ID for this queue or link.  This is the canonical 
        // representation of the queue.  The QAPI guarantees that there is
        // no more than one queue or link with the same QUEUELINKID at a
        // given point in time.  The memory associated with the out parameter
        // is guaranteed good until the underlying QAPI object is released
        // @rvalue S_OK | Success
        // @rvalue E_NOTIMPL | This queue provider does not support 
        // this functionality
        HRESULT GetUniqueId(
                [out] QUEUELINK_ID **ppqlid);

}

[
	helpstring("Advanced Queueing Admin 1.0 Type Library"),
	uuid(83866cac-740d-11d2-94e4-00c04fa379f1),
	version(1.0)
]
library AQAdmin
{
	importlib("stdole2.tlb");

	interface IAQAdmin;

	[
		helpstring("Advanced Queueuing Administration Class"),
		uuid(83866cad-740d-11d2-94e4-00c04fa379f1)
	]
	coclass AQAdmin {
		[default]	interface	IAQAdmin;
	}
};