//-----------------------------------------------------------------------------
//
//
//  File: intrnlqa.idl
//
//  Description:  Internal Queue Admin Interfaces.  IDL file containing the 
//      interface definitions for the internal queue admin interfaces.  These
//      interfaces are exlusively internal to AQueue and used to provide the
//      ability to admin different types of queues (i.e., local vs remote). 
//      
//      This works as follows... the AQSvrInst object returns a IQueueAdmin*
//      interface via HrLinkFromLinkID or HrQueueFromQueueID.  
//
//      The IQueueAdminMessageFilter interface is initialized from a 
//      MESSAGE_FILETER or MESSAGE_ENUM_FILTER.  
//
//      The IUknown message abstraction will typically also implement CMsgRef
//      (in the case of local and remote queues), but could also point to the
//      external message interface (IMailMsgProperties).  This is currently
//      not used, but can easily be done by creating a IQueueAdminMessageFilter
//      and IQueueAdminAction implementation that supports it.
//
//      IAdvQueueAdmin is the per-instance interface that is used by the 
//      RPC server to talk to aqueue.
//
//  Author: Mike Swafford (MikeSwa)
//
//  History:
//      2/20/99 - MikeSwa Created 
//		4/1/99 - MikeSwa Added context to IQueueAdminMessageFilter
//      6/7/99 - MikeSwa Moved IAdvQueueAdmin from aqueue.idl to intrnlqa.idl
//      7/1/99 - MikeSwa Added LinkDiagnostic HRESULT
//
//  Copyright (C) 1999 Microsoft Corporation
//
//-----------------------------------------------------------------------------

import "oaidl.idl";
import "ocidl.idl";
import "aqadmtyp.h";

interface IQueueAdminAction;

//---[ IQueueAdminMessageFilter ]----------------------------------------------
//
//
//  Description: 
//      Interface used to encapsulate message filtering/processing.  A queue
//      class will call HrProcessMsg for every message in the queue
//  
//-----------------------------------------------------------------------------
[
    object,
    local,
    uuid(34E2DCC4-C91A-11d2-A6B1-00C04FA3490A),
    helpstring("IQueueAdminMessageFilter Interface"),
    pointer_default(unique)
]
interface IQueueAdminMessageFilter : IUnknown
{
    //Called to process a message during enumeration.
    [helpstring("method HrProcessMessage")]
        HRESULT HrProcessMessage(
            IUnknown *pIUnknownMsg, 
            BOOL     *pfContinue,
            BOOL     *pfDelete);           

    [helpstring("method HrSetQueueAdminAction")]
        HRESULT HrSetQueueAdminAction(
            IQueueAdminAction *pIQueueAdminAction);

    //Allows the thread performing queue admin functions
    //to set a context that is passed to the 
    //pIQueueAdminAction implementation
    [helpstring("method HrSetCurrentUserContext")]
        HRESULT HrSetCurrentUserContext(
            PVOID	pvContext);

    [helpstring("method HrGetCurrentUserContext")]
        HRESULT HrGetCurrentUserContext(
            PVOID	*ppvContext);
};

//---[ IQueueAdminAction ]-----------------------------------------------------
//
//
//  Description: 
//      Internal interface that is the basis for all adminable queues.  It 
//      provides the abilitity to filter and apply actions to queues as well.
//
//      A class that implements this class should also implement one of 
//      the following:
//          IQueueAdminLink     - Admin a next hop link
//          IQueueAdminQueue    - Admin a final destination queue
//  
//-----------------------------------------------------------------------------
[
    object,
    local,
    uuid(486886B4-6542-4abe-8DE5-1A35E8A83A6C),
    helpstring("IQueueAdminAction Interface"),
    pointer_default(unique)
]
interface IQueueAdminAction : IUnknown
{
    //Applies a given Queue Admin function to all messages in this queue
    [helpstring("method HrApplyQueueAdminFunction")] 
        HRESULT HrApplyQueueAdminFunction(
                    IQueueAdminMessageFilter *pIQueueAdminMessageFilter);

    //Removes a message from this queue
    [helpstring("method HrApplyActionToMessage")] 
        HRESULT HrApplyActionToMessage(
                    IUnknown *pIUnknownMsg,
                    MESSAGE_ACTION ma,
                    PVOID  pvContext,
                    BOOL *pfShouldDelete);

    [helpstring("method fMatchesID")]
        BOOL    fMatchesID(QUEUELINK_ID *QueueLinkID);
    
    //Returns the supported actions on this interface
    [helpstring("method QuerySupportedActions")]
        HRESULT QuerySupportedActions(
                    DWORD               *pdwSupportedActions,
                    DWORD               *pdwSupportedFilterFlags);

};

//---[ IQueueAdminLink ]-------------------------------------------------------
//
//
//  Description: 
//      Queue Admin interface for a next hop link.
//  
//-----------------------------------------------------------------------------
[
    object,
    local,
    uuid(D81698CA-2FD1-11d3-BFD1-00C04FA3490A),
    helpstring("IQueueAdminLink Interface"),
    pointer_default(unique)
]
interface IQueueAdminLink : IUnknown
{
    [helpstring("method HrGetLinkInfo")] 
        HRESULT HrGetLinkInfo(
                    LINK_INFO *pliLinkInfo,
                    HRESULT   *phrLinkDiagnostic);

    [helpstring("method HrApplyActionToLink")] 
        HRESULT HrApplyActionToLink(
                    LINK_ACTION la);

    [helpstring("method HrGetLinkID")] 
        HRESULT HrGetLinkID(
                    QUEUELINK_ID *pLinkID);

    [helpstring("method HrGetNumQueues")]
        HRESULT HrGetNumQueues(DWORD *pcQueues);

    [helpstring("method HrGetQueueIDs")] 
        HRESULT HrGetQueueIDs(
                    DWORD *pcQueues,
                    QUEUELINK_ID *rgQueues);
    
};

//---[ IQueueAdminQueue ]------------------------------------------------------
//
//
//  Description: 
//      Queue Admin interface for a final destination queue
//  
//-----------------------------------------------------------------------------
[
    object,
    local,
    uuid(34E2DCC6-C91A-11d2-A6B1-00C04FA3490A),
    helpstring("IQueueAdminQueue Interface"),
    pointer_default(unique)
]
interface IQueueAdminQueue : IUnknown
{
    [helpstring("method HrGetQueueInfo")] 
        HRESULT HrGetQueueInfo(
                    QUEUE_INFO *pliQueueInfo);

    [helpstring("method HrGetQueueID")] 
        HRESULT HrGetQueueID(
                    QUEUELINK_ID *pQueueID);
};

//---[ IAdvQueueAdmin ]--------------------------------------------------------
//
//
//      Description: Public interface that exposes administrator APIs
//              for use by the SMTP Server's AQ RPCs.
//
//
//-----------------------------------------------------------------------------
[
    object,
    uuid(23700228-1D00-11d3-BFCB-00C04FA3490A),
    helpstring("IAdvQueueAdmin Interface"),
    pointer_default(unique)
]
interface IAdvQueueAdmin : IUnknown
{
    [helpstring("method ApplyActionToLinks")]
    HRESULT
    ApplyActionToLinks(
        [in]                        LINK_ACTION     laAction);

    [helpstring("method ApplyActionToMessages")]
    HRESULT
    ApplyActionToMessages(
        [in]                        QUEUELINK_ID    *pqlQueueLinkId,
        [in]                        MESSAGE_FILTER  *pmfMessageFilter,
        [in]                        MESSAGE_ACTION  maMessageAction,
        [out]                       DWORD           *pcMsgs);

    [helpstring("method GetQueueInfo")]
    HRESULT
    GetQueueInfo(
        [in]                        QUEUELINK_ID    *pqlQueueId,
        [out]                       QUEUE_INFO      *pqiQueueInfo);

    [helpstring("method GetLinkInfo")]
    HRESULT
    GetLinkInfo(
        [in]                        QUEUELINK_ID    *pqlLinkId,
        [out]                       LINK_INFO       *pliLinkInfo,
        [out]                       HRESULT         *phrLinkDiagnostic);

    [helpstring("method SetLinkState")]
    HRESULT
    SetLinkState(
        [in]                        QUEUELINK_ID    *pqlLinkId,
        [in]                        LINK_ACTION     la);

    [helpstring("method GetLinkIDs")]
    HRESULT
    GetLinkIDs(
        [in, out]                   DWORD           *pcLinks,
        [in, out]                   QUEUELINK_ID    *rgLinks);

    [helpstring("method GetQueueIDs")]
    HRESULT
    GetQueueIDs(
        [in]                        QUEUELINK_ID    *pqlLinkId,
        [in, out]                   DWORD           *pcQueues,
        [in, out]                   QUEUELINK_ID    *rgQueues);

    [helpstring("method GetMessageProperties")]
    HRESULT
    GetMessageProperties(
        [in]                        QUEUELINK_ID        *pqlQueueLinkId,
        [in]                        MESSAGE_ENUM_FILTER *pmfMessageEnumFilter,
        [in, out]                   DWORD               *pcMsgs,
        [in, out]                   MESSAGE_INFO        *rgMsgs);

    [helpstring("method QuerySupportedActions")]
    HRESULT
    QuerySupportedActions(
        [in]                        QUEUELINK_ID        *pqlQueueLinkId,
        [out]                       DWORD               *pdwSupportedActions,
        [out]                       DWORD               *pdwSupportedFilterFlags);
       
};