/*
* Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).
* All rights reserved.
* This component and the accompanying materials are made available
* under the terms of "Eclipse Public License v1.0"
* which accompanies this distribution, and is available
* at the URL "http://www.eclipse.org/legal/epl-v10.html".
*
* Initial Contributors:
* Nokia Corporation - initial contribution.
*
* Contributors:
*
* Description:
* Name        : sipresolvedclient2.h
* Part of     : SIP Client Resolver API
* Version     : 1.0
*
*/



#ifndef CSIPRESOLVEDCLIENT2_H
#define CSIPRESOLVEDCLIENT2_H

// INCLUDES
#include <sipacceptcontactheader.h>
#include <sipeventheader.h>
#include <stringpool.h>
#include <uri8.h>
#include <sipheaderbase.h>
#include <sipcontenttypeheader.h>
#include <e32base.h>

// FORWARD DECLARATIONS
class CSdpMediaField;

// CONSTANTS
/** Interface UID of this ECOM interface*/
const TUid KSIPResolvedClient2IFUid = { 0x10282EE5 };

// CLASS DEFINITION
/**
* @publishedAll
* @released
*
* Interface that SIP stack's clients must realize 
* in order to be able to receive incoming SIP requests outside SIP dialogs.
* Note that channel UIDs must be unique accross all SIP clients 
* e.g. clients may use UIDs assigned for binaries.
* 
* SIP stack utilizes the plug-ins that implement 
* this interface in the following manner:
*
* 1) If the SIP request does not contain Accept-Contact-header(s), go to step 2.
*    SIP stack calls CSIPResolvedClient2::MatchAcceptContactsL 
*    for all the plug-ins and applies the following logic: 
*    a) None of the clients match -> go to step 2
*    b) One client matches -> the SIP request is routed to the matching client
*    c) Several clients match -> go to step 2
*
* 2) If the SIP request does not contain Event-header, go to step 3.
*    SIP stack calls CSIPResolvedClient2::MatchEventL 
*    for all the plug-ins and applies the following logic:
*    a) None of the clients match -> go to step 3
*    b) One client matches -> the SIP request is routed to the matching client
*    c) Several clients match -> go to step 3
*
* 3) SIP stack calls CSIPResolvedClient2::MatchRequestL for all the plug-ins.
*    a) None of the clients match -> SIP generates an error response
*    b) One client matches -> the SIP request is routed to the matching client
*    c) Several clients match -> 
*       SIP picks one of these clients randomly and routes the request to it. 
*       The ROM-based clients are preferred.
*/
class CSIPResolvedClient2 : public CBase
    {
    public:    // Destructor

        /**
        * Destructor
        */
        inline ~CSIPResolvedClient2();

    public: // Abstract methods

        /**
        * Matches the Accept-Contact-headers 
        * to the client(s) represented by this plug-in.
        * This function is called for an incoming SIP request 
        * if it contains Accept-Contact-header(s).
        * @param aMethod the method of the SIP request
        * @param aRequestUri the request-URI of the SIP request
        * @param aHeaders all the headers in the SIP request
        * @param aContent SIP request body; 
        *        zero-length descriptor if not present
        * @param aContentType the content-type of the SIP request. 
        *        Zero-pointer if body is not present.
        * @param aClientUid indicates client's UID for 
        *        SIP e.g. the one passed as a parameter to CSIP::NewL().
        * @return ETrue, if the Accept-Contact-headers match to the client
        *         represented by this plug-in, otherwise EFalse. 
        */
        virtual TBool MatchAcceptContactsL(
            RStringF aMethod,
            const CUri8& aRequestUri,
            const RPointerArray<CSIPHeaderBase>& aHeaders,
            const TDesC8& aContent,
            const CSIPContentTypeHeader* aContentType,
            TUid& aClientUid) = 0;

        /**
        * Matches the Event-header to the client(s) represented by this plug-in.
        * This function is called for an incoming SIP request, 
        * if it contains an Event-header and 
        * MatchAcceptContactsL returned EFalse.
        * @param aMethod the method of the SIP request
        * @param aRequestUri the request-URI of the SIP request
        * @param aHeaders all the headers in the SIP request
        * @param aContent SIP request body; 
        *        zero-length descriptor if not present
        * @param aContentType the content-type of the SIP request. 
        *        Zero-pointer if body is not present.
        * @param aClientUid indicates client's UID for 
        *        SIP e.g. the one passed as a parameter to CSIP::NewL().
        * @return ETrue, if the Event-header matches to the client
        *         represented by this plug-in, otherwise EFalse. 
        */
        virtual TBool MatchEventL(
            RStringF aMethod,
            const CUri8& aRequestUri,
            const RPointerArray<CSIPHeaderBase>& aHeaders,
            const TDesC8& aContent,
            const CSIPContentTypeHeader* aContentType,
            TUid& aClientUid) = 0;

        /**
        * Matches the whole SIP request to the client(s) 
        * represented by this plug-in.
        * This function is called if the SIP request does not contain 
        * Accept- or Event-headers or  
        * MatchAcceptContactsL and MatchEventL returned EFalse.
        * @param aMethod the method of the SIP request
        * @param aRequestUri the request-URI of the SIP request
        * @param aHeaders all the headers in the SIP request
        * @param aContent SIP request body; 
        *        zero-length descriptor if not present
        * @param aContentType the content-type of the SIP request. 
        *        Zero-pointer if body is not present.
        * @param aClientUid indicates client's UID for 
        *        SIP e.g. the one passed as a parameter to CSIP::NewL().
        * @return ETrue, if the request can be handled by the client
        *         represented by this plug-in, otherwise EFalse. 
        */
        virtual TBool MatchRequestL(
            RStringF aMethod,
            const CUri8& aRequestUri,
            const RPointerArray<CSIPHeaderBase>& aHeaders,
            const TDesC8& aContent,
            const CSIPContentTypeHeader* aContentType,
            TUid& aClientUid) = 0;

        /**
        * Indicates whether the plug-in implements CSIPResolvedClient2::ConnectL
        * and by calling CSIPResolvedClient2::ConnectL 
        * SIP stack is able to force the client to connect to SIP stack.
        * @return ETrue, if the plug-in supports 
        *         CSIPResolvedClient2::ConnectL, otherwise EFalse.
        */
        virtual TBool ConnectSupported() = 0;

        /**
        * Requests the client to connect to SIP with 
        * the resolved UID in case there's no client connection with the UID.
        * @param aClientUid previously resolved client UID
        */
        virtual void ConnectL(const TUid& aClientUid) = 0;
        
        /**
        * Cancels a ConnectL request for a client.
        * Is called when for example a CANCEL for an INVITE is received 
        * before the client connects to SIP stack.
        * @param aClientUid a UID for which ConnectL was previously called
        */
        virtual void CancelConnect(const TUid& aClientUid) = 0;

        /** 
        * Gets all the SIP message content types supported by the client.
        * @return 0..n SIP Content-Type-headers.
        *         The ownership of the headers is transferred. 
        */
        virtual RPointerArray<CSIPContentTypeHeader> 
            SupportedContentTypesL() = 0;

        /** 
        * Gets all the SDP media-fields supported by the client.
        * @return 0..n SDP media-fields describing the client's media support.
        *         The ownership of the media-fields is transferred. 
        */
        virtual RPointerArray<CSdpMediaField> 
            SupportedSdpMediasL() = 0;
            

        /**
        * Adds client specific SIP-headers for the 200 OK for OPTIONS.
        * Each plug-in must check that the header to be added
        * is not yet in the array. For example when adding header 
        * "Allow: INVITE" the client must check that 
        * the header is not already present in the array.
        * @param aHeaders headers to be added to 200 OK for OPTIONS. 
        *        The ownership of the added headers is transferred to the caller.
        */            
        virtual void AddClientSpecificHeadersForOptionsResponseL(
            RPointerArray<CSIPHeaderBase>& aHeaders) = 0;

    public: // Data

        /// Unique key for implementations of this interface.
        TUid iInstanceKey;
		
		TUid iImplementationUid;
		
    protected: // Constructors:

        inline CSIPResolvedClient2();
    };

#include "sipresolvedclient2.inl"

#endif // CSIPRESOLVEDCLIENT2_H