1 /*

     2 * Copyright (c) 2007-2009 Nokia Corporation and/or its subsidiary(-ies).

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of the License "Symbian Foundation License v1.0" to Symbian Foundation members and "Symbian Foundation End User License Agreement v1.0" to non-members

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.symbianfoundation.org/legal/licencesv10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:

    15 * Name        : sipresolvedclient2.h

    16 * Part of     : SIP Client Resolver API

    17 * Version     : 1.0

    18 *

    19 */

    20 

    21 

    22 

    23 #ifndef CSIPRESOLVEDCLIENT2_H

    24 #define CSIPRESOLVEDCLIENT2_H

    25 

    26 // INCLUDES

    27 #include <sipacceptcontactheader.h>

    28 #include <sipeventheader.h>

    29 #include <stringpool.h>

    30 #include <uri8.h>

    31 #include <sipheaderbase.h>

    32 #include <sipcontenttypeheader.h>

    33 #include <e32base.h>

    34 

    35 // FORWARD DECLARATIONS

    36 class CSdpMediaField;

    37 

    38 // CONSTANTS

    39 /** Interface UID of this ECOM interface*/

    40 const TUid KSIPResolvedClient2IFUid = { 0x10282EE5 };

    41 

    42 // CLASS DEFINITION

    43 /**

    44 * @publishedAll

    45 * @released

    46 *

    47 * Interface that SIP stack's clients must realize 

    48 * in order to be able to receive incoming SIP requests outside SIP dialogs.

    49 * Note that channel UIDs must be unique accross all SIP clients 

    50 * e.g. clients may use UIDs assigned for binaries.

    51 * 

    52 * SIP stack utilizes the plug-ins that implement 

    53 * this interface in the following manner:

    54 *

    55 * 1) If the SIP request does not contain Accept-Contact-header(s), go to step 2.

    56 *    SIP stack calls CSIPResolvedClient2::MatchAcceptContactsL 

    57 *    for all the plug-ins and applies the following logic: 

    58 *    a) None of the clients match -> go to step 2

    59 *    b) One client matches -> the SIP request is routed to the matching client

    60 *    c) Several clients match -> go to step 2

    61 *

    62 * 2) If the SIP request does not contain Event-header, go to step 3.

    63 *    SIP stack calls CSIPResolvedClient2::MatchEventL 

    64 *    for all the plug-ins and applies the following logic:

    65 *    a) None of the clients match -> go to step 3

    66 *    b) One client matches -> the SIP request is routed to the matching client

    67 *    c) Several clients match -> go to step 3

    68 *

    69 * 3) SIP stack calls CSIPResolvedClient2::MatchRequestL for all the plug-ins.

    70 *    a) None of the clients match -> SIP generates an error response

    71 *    b) One client matches -> the SIP request is routed to the matching client

    72 *    c) Several clients match -> 

    73 *       SIP picks one of these clients randomly and routes the request to it. 

    74 *       The ROM-based clients are preferred.

    75 */

    76 class CSIPResolvedClient2 : public CBase

    77     {

    78     public:    // Destructor

    79 

    80         /**

    81         * Destructor

    82         */

    83         inline ~CSIPResolvedClient2();

    84 

    85     public: // Abstract methods

    86 

    87         /**

    88         * Matches the Accept-Contact-headers 

    89         * to the client(s) represented by this plug-in.

    90         * This function is called for an incoming SIP request 

    91         * if it contains Accept-Contact-header(s).

    92         * @param aMethod the method of the SIP request

    93         * @param aRequestUri the request-URI of the SIP request

    94         * @param aHeaders all the headers in the SIP request

    95         * @param aContent SIP request body; 

    96         *        zero-length descriptor if not present

    97         * @param aContentType the content-type of the SIP request. 

    98         *        Zero-pointer if body is not present.

    99         * @param aClientUid indicates client's UID for 

   100         *        SIP e.g. the one passed as a parameter to CSIP::NewL().

   101         * @return ETrue, if the Accept-Contact-headers match to the client

   102         *         represented by this plug-in, otherwise EFalse. 

   103         */

   104         virtual TBool MatchAcceptContactsL(

   105             RStringF aMethod,

   106             const CUri8& aRequestUri,

   107             const RPointerArray<CSIPHeaderBase>& aHeaders,

   108             const TDesC8& aContent,

   109             const CSIPContentTypeHeader* aContentType,

   110             TUid& aClientUid) = 0;

   111 

   112         /**

   113         * Matches the Event-header to the client(s) represented by this plug-in.

   114         * This function is called for an incoming SIP request, 

   115         * if it contains an Event-header and 

   116         * MatchAcceptContactsL returned EFalse.

   117         * @param aMethod the method of the SIP request

   118         * @param aRequestUri the request-URI of the SIP request

   119         * @param aHeaders all the headers in the SIP request

   120         * @param aContent SIP request body; 

   121         *        zero-length descriptor if not present

   122         * @param aContentType the content-type of the SIP request. 

   123         *        Zero-pointer if body is not present.

   124         * @param aClientUid indicates client's UID for 

   125         *        SIP e.g. the one passed as a parameter to CSIP::NewL().

   126         * @return ETrue, if the Event-header matches to the client

   127         *         represented by this plug-in, otherwise EFalse. 

   128         */

   129         virtual TBool MatchEventL(

   130             RStringF aMethod,

   131             const CUri8& aRequestUri,

   132             const RPointerArray<CSIPHeaderBase>& aHeaders,

   133             const TDesC8& aContent,

   134             const CSIPContentTypeHeader* aContentType,

   135             TUid& aClientUid) = 0;

   136 

   137         /**

   138         * Matches the whole SIP request to the client(s) 

   139         * represented by this plug-in.

   140         * This function is called if the SIP request does not contain 

   141         * Accept- or Event-headers or  

   142         * MatchAcceptContactsL and MatchEventL returned EFalse.

   143         * @param aMethod the method of the SIP request

   144         * @param aRequestUri the request-URI of the SIP request

   145         * @param aHeaders all the headers in the SIP request

   146         * @param aContent SIP request body; 

   147         *        zero-length descriptor if not present

   148         * @param aContentType the content-type of the SIP request. 

   149         *        Zero-pointer if body is not present.

   150         * @param aClientUid indicates client's UID for 

   151         *        SIP e.g. the one passed as a parameter to CSIP::NewL().

   152         * @return ETrue, if the request can be handled by the client

   153         *         represented by this plug-in, otherwise EFalse. 

   154         */

   155         virtual TBool MatchRequestL(

   156             RStringF aMethod,

   157             const CUri8& aRequestUri,

   158             const RPointerArray<CSIPHeaderBase>& aHeaders,

   159             const TDesC8& aContent,

   160             const CSIPContentTypeHeader* aContentType,

   161             TUid& aClientUid) = 0;

   162 

   163         /**

   164         * Indicates whether the plug-in implements CSIPResolvedClient2::ConnectL

   165         * and by calling CSIPResolvedClient2::ConnectL 

   166         * SIP stack is able to force the client to connect to SIP stack.

   167         * @return ETrue, if the plug-in supports 

   168         *         CSIPResolvedClient2::ConnectL, otherwise EFalse.

   169         */

   170         virtual TBool ConnectSupported() = 0;

   171 

   172         /**

   173         * Requests the client to connect to SIP with 

   174         * the resolved UID in case there's no client connection with the UID.

   175         * @param aClientUid previously resolved client UID

   176         */

   177         virtual void ConnectL(const TUid& aClientUid) = 0;

   178         

   179         /**

   180         * Cancels a ConnectL request for a client.

   181         * Is called when for example a CANCEL for an INVITE is received 

   182         * before the client connects to SIP stack.

   183         * @param aClientUid a UID for which ConnectL was previously called

   184         */

   185         virtual void CancelConnect(const TUid& aClientUid) = 0;

   186 

   187         /** 

   188         * Gets all the SIP message content types supported by the client.

   189         * @return 0..n SIP Content-Type-headers.

   190         *         The ownership of the headers is transferred. 

   191         */

   192         virtual RPointerArray<CSIPContentTypeHeader> 

   193             SupportedContentTypesL() = 0;

   194 

   195         /** 

   196         * Gets all the SDP media-fields supported by the client.

   197         * @return 0..n SDP media-fields describing the client's media support.

   198         *         The ownership of the media-fields is transferred. 

   199         */

   200         virtual RPointerArray<CSdpMediaField> 

   201             SupportedSdpMediasL() = 0;

   202             

   203 

   204         /**

   205         * Adds client specific SIP-headers for the 200 OK for OPTIONS.

   206         * Each plug-in must check that the header to be added

   207         * is not yet in the array. For example when adding header 

   208         * "Allow: INVITE" the client must check that 

   209         * the header is not already present in the array.

   210         * @param aHeaders headers to be added to 200 OK for OPTIONS. 

   211         *        The ownership of the added headers is transferred to the caller.

   212         */            

   213         virtual void AddClientSpecificHeadersForOptionsResponseL(

   214             RPointerArray<CSIPHeaderBase>& aHeaders) = 0;

   215 

   216     public: // Data

   217 

   218         /// Unique key for implementations of this interface.

   219         TUid iInstanceKey;

   220 		

   221 		TUid iImplementationUid;

   222 		

   223     protected: // Constructors:

   224 

   225         inline CSIPResolvedClient2();

   226     };

   227 

   228 #include "sipresolvedclient2.inl"

   229 

   230 #endif // CSIPRESOLVEDCLIENT2_H