<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"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: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-E9AF73E8-DF31-5C5E-889E-96CCD4C4A46B" xml:lang="en"><title>Example

IETF Profile Agent Plug-in</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>The IETF Profile Agent plug-in is an ECOM plug-in that uses the SIP Profile

Agent plug-in API. The IETF Profile Agent plug-in enters the IETF registration

details in the request headers. </p>

<p>The main functions of the ECom plug-in are: </p>

<ul>

<li id="GUID-7F8A4189-D118-57CD-9F1B-E444F83B1BE0"><p>to register, update,

and deregister IETF SIP profiles that use the SIP Client API </p> </li>

<li id="GUID-BDD4FA8B-7981-5849-B91F-5A4E7E237CAA"><p>to handle many SIP connections

when several SIP profiles are enabled at the same time but, do not use the

same Internet Access Point (IAP) </p> </li>

<li id="GUID-3F0718FF-A10C-5FE4-99EE-6B9FA6669084"><p>to provide HTTP Digest

settings from SIP Profiles to the SIP Client API </p> </li>

</ul>

<p>The plug-in uses the SIP Profile Finite State Machine (FSM) API which implements

a state machine for SIP Profiles. The FSM API responds to registration events

and notifies the client about changes in the profile registration status.

It also provides common error handling and handling of connection state changes. </p>

<p>The following sections provide information about the uses of the plug-in

and the source code for the plug-in: </p>

<ul>

<li id="GUID-ECA6D5CE-6D2D-50B2-8A76-3AA28E75DE8C"><p> <xref href="GUID-E9AF73E8-DF31-5C5E-889E-96CCD4C4A46B.dita#GUID-E9AF73E8-DF31-5C5E-889E-96CCD4C4A46B/GUID-CFB776D6-399E-55E1-ACAA-06B29DC695B6">Typical uses of the IETF Profile Agent plug-in</xref>  </p> </li>

<li id="GUID-B91486BC-DEFE-5085-B5E9-E16FCF01D5BF"><p> <xref href="GUID-E9AF73E8-DF31-5C5E-889E-96CCD4C4A46B.dita#GUID-E9AF73E8-DF31-5C5E-889E-96CCD4C4A46B/GUID-46D9399E-F3F4-5A7F-955B-4D2D08726029">Source code</xref>  </p> </li>

</ul>

<section id="GUID-CFB776D6-399E-55E1-ACAA-06B29DC695B6"><title>Typical uses

of the IETF Profile Agent plug-in</title> <p><b>Registering an IETF profile </b> </p> <p>Load

the IETF Profile Agent plug-in and register an IETF profile. The following

steps describe the IETF profile registration process: </p> <ol id="GUID-F23557DF-26C4-51CC-9D05-7E9E50F76B72">

<li id="GUID-450741AA-7FC0-561E-AD25-FD1394E3897F"><p>The SIP Profile Server

sends a profile registration request to the IETF plug-in. </p> </li>

<li id="GUID-C594C73F-900E-541C-A3AF-83AF7338267B"><p>The plug-in finds a

context for the profile that use the connection context and passes the registration

request to the profile context class. </p> </li>

<li id="GUID-CC13A752-DCB0-5B8E-B72C-15120CC2C360"><p>The profile context

class passes the request to the SIP Profile FSM class, which sets the profile

state to <b>RegistrationInProgressState</b> and passes the request to the

SIP Stack. </p> </li>

<li id="GUID-DE0DD98D-BC3C-5A62-B6E3-55F5CACA9D50"><p>The SIP Stack responds

to the profile context after the registration process is complete. </p> </li>

<li id="GUID-34184F96-0E54-5C2C-951A-E991A885ACB6"><p>The profile state is

changed to <b>RegisteredState</b> and the SIP Profile Server is notified. </p> </li>

</ol> <p>The following sequence diagram shows the call flow of IETF profile

registration process. </p> <fig id="GUID-0C9B80F8-0061-5597-A216-ABF1C545FD52">

<title>                 IETF profile registration sequence diagram       

       </title>

<image href="GUID-8D72AE33-AF61-5AD7-A40D-A2918474DD0D_d0e564036_href.png" placement="inline"/>

</fig> <p><b>Updating an IETF profile</b> </p> <p>To update an IETF profile,

the IETF Profile Agent plug-in is loaded and the profile is in the <b>RegisteredState</b> state.

The following steps describe how to update the IETF profile: </p> <ol id="GUID-898A25C5-45AA-5066-BAC1-89509F26873D">

<li id="GUID-EF327FC8-CA28-5865-8BA4-2F432B194F91"><p>The SIP Profile Server

sends a request to the IETF plug-in to update the IETF profile. </p> </li>

<li id="GUID-AB222C74-55F3-5BBD-97CF-629C3FFAFC45"><p>The plug-in finds a

context for the profile that use the connection context and passes the profile

update request to the profile context class. </p> </li>

<li id="GUID-76F711A8-FB17-594D-8D3C-FEB4CA877D40"><p>The profile context

class initiates a request to deregister the old profile, sets the profile

state to <b>DeregistrationInProgressState</b> and passes the request to the

SIP Stack. </p> </li>

<li id="GUID-51B96824-EB8F-5E25-A0A0-FD14264D7E81"><p>The SIP Stack responds

to the profile context after the deregistration process is complete and the

profile state is set to <b>DeregisteredState</b>. </p> </li>

<li id="GUID-C4963BDD-F871-5C18-8C5B-F99027D0B406"><p>The updated profile

is registered and the SIP Profile Server is notified. </p> </li>

</ol> <p>The following sequence diagram shows the call flow of updating the

IETF profile: </p> <fig id="GUID-0DF3456B-F0B8-550C-B3B0-CA45C8B30E5C">

<title>                 IETF profile update sequence diagram             

 </title>

<image href="GUID-7E8DA853-BE41-5C8D-B286-9F5F7992FD2C_d0e564092_href.png" placement="inline"/>

</fig> <p><b>Deregistering an IETF profile</b> </p> <p>To deregister an IETF

profile, the IETF Profile Agent plug-in is loaded and the profile is in the <b>RegisteredState</b>.

The following steps describe the IETF profile deregistration process: </p> <ol id="GUID-7274958A-CF11-57DB-A0E0-B4A965F2C719">

<li id="GUID-4303B836-2167-5020-9CED-81444F876DDA"><p>The SIP Profile Server

sends a profile deregistration request to the IETF plug-in. </p> </li>

<li id="GUID-9F6A96E6-7199-5C83-947A-4A3625F12F6D"><p>The plug-in finds a

context for the profile that use the connection context and passes the deregistration

request to the profile context class. </p> </li>

<li id="GUID-E00A6519-AEC9-526A-A4F7-88DB5317C324"><p>The profile context

class passes the request to the SIP Profile FSM class, which sets the profile

state as <b/><b>DeregistrationInProgressState</b> and passes the request

to the SIP Stack. </p> </li>

<li id="GUID-EAF13DE8-29B1-5962-975B-07EA6B1C106D"><p>The SIP Stack responds

to the profile context after the deregistration process is complete. </p> </li>

<li id="GUID-4F19F07B-6D1F-54C2-B92E-4508B259A50D"><p>The profile state is

changed to <b>DeregisteredState</b> and the SIP Profile Server is notified. </p> </li>

</ol> <p>The following sequence diagram shows the call flow of IETF profile

deregistration process: </p> <fig id="GUID-DE79B542-C6C1-504D-B8C6-493C78208287">

<title>                 IETF profile deregistration sequence diagram     

         </title>

<image href="GUID-DDD07E37-E5BE-5187-9C62-A3F4F9343C2A_d0e564149_href.png" placement="inline"/>

</fig> </section>

<section id="GUID-46D9399E-F3F4-5A7F-955B-4D2D08726029"><title>Source code</title> <p>Here

is the source for the IETF Profile Agent plug-in: </p> <p><b>sipietfprofileagent.h</b> </p> <codeblock id="GUID-F2C978BC-AC9D-53FB-9621-34509BC773BF" xml:space="preserve">// sipietfprofileagent.h

#ifndef CSIPIETFPROFILEAGENT_H

#define CSIPIETFPROFILEAGENT_H

//  INCLUDES

#include <e32base.h>

#include "sipprofileagent.h"

#include "sipprofileagentobserver.h"

#include "sipprofilefsmuser.h"

#include "sipobserver.h"

#include "siphttpdigestchallengeobserver2.h"

//FORWARD DECLARATIONS

class CSIP;

class CSIPHttpDigest;

class TSIPProfileTypeInfo;

class CSIPIetfConnectionContext;

class CSIPPrflInitState;

class CSIPPrflResolvingProxiesState;

class CSIPPrflRegisterRequestedState;

class CSIPPrflRegistrationInProgressState;

class CSIPPrflRegisteredState;

class CSIPPrflDeregisterRequestedState;

class CSIPPrflDeregistrationInProgressState;

class CSIPPrflRegisterDelayRequestedState;

class CSIPIetfProfileContext;

class CSIPProfileQueueHandling;

// CLASS DECLARATION

/**

*  Registers profiles and maintains

*  profile registrations as per RFC3261.

*  

*  @lib n/a

*/

class CSIPIetfProfileAgent: 

    public CSIPProfileAgent, 

    public MSIPProfileAgentObserver,

    public MSIPProfileFSMUser,

    public MSIPObserver,

    public MSIPHttpDigestChallengeObserver2

    {

    public: // Constructors and destructor

        /**

        * Two-phased constructor.

        * @param aInitParams parameters passed in the construction

        */

        static CSIPIetfProfileAgent* NewL(TAny* aInitParams);

        /**

        * Destructor.

        */

        virtual ~CSIPIetfProfileAgent();

    public: // From CSIPProfileAgent

        const TSIPProfileTypeInfo& Type() const;

        CSIPConcreteProfile* CreateL();

        void RegisterL(

            CSIPConcreteProfile& aSIPConcreteProfile);

        void UpdateL(

            CSIPConcreteProfile& aNewProfile, 

            CSIPConcreteProfile& aOldProfile);

        void DeregisterL(

            CSIPConcreteProfile& aSIPConcreteProfile);

        TInt GetProfileState(

            CSIPConcreteProfile::TStatus& aState, 

            CSIPConcreteProfile& aProfile) const;

        TBool IsIdle();

        TBool RegisterPending(CSIPConcreteProfile& aSIPProfile) const;

        TInt TerminateHandling(CSIPConcreteProfile& aProfile);

        TInt Extension(TInt aOperationCode, TAny* aParams); 

    public: // From MSIPProfileAgentObserver

        void SIPProfileStatusEvent(

            CSIPConcreteProfile& aProfile,

            TUint32 aContextId);

        void SIPProfileErrorEvent(

            CSIPConcreteProfile& aProfile,

            TInt aError);

        TBool ProceedRegistration(CSIPConcreteProfile& aProfile);

        void GetFailedProfilesL( 

            const TSIPProfileTypeInfo& aType,

            RPointerArray<CSIPConcreteProfile>& aFailedProfiles) const;    

    public: // From MSIPProfileFSMUser

        void RegisterProfileL(

            CSIPConcreteProfile& aSIPConcreteProfile);

        void DeregisterProfileL(

            CSIPConcreteProfile& aSIPConcreteProfile);

        void RetryProfileRegistrationL( 

            CSIPConcreteProfile& aSIPProfile );

        TBool AddProfileIntoQueue( 

            CSIPConcreteProfile& aSIPConcreteProfile ) const;

        void RegisterProfileAfterQueueL( 

            CSIPConcreteProfile& aSIPConcreteProfile );

        void DeregisterProfileAfterQueueL( 

            CSIPConcreteProfile& aSIPConcreteProfile );

        void RetryProfileRegistrationAfterQueueL( 

            CSIPConcreteProfile& aSIPConcreteProfile );

        TBool IsInQueue( 

            CSIPConcreteProfile& aSIPProfile ) const;

        void SetInterimProfile( CSIPConcreteProfile* 

                                            aSIPConcreteProfile );

    public: // From MSIPObserver

        void IncomingRequest(

            TUint32 aIapId,

            CSIPServerTransaction* aTransaction);

        void TimedOut(CSIPServerTransaction& aTransaction);

    public: // From MSIPHttpDigestChallengeObserver2

        void ChallengeReceived(const CSIPClientTransaction& aTransaction);

        void ChallengeReceived(const CSIPRefresh& aRefresh);

    private: // Constructors

        /**

        * C++ default constructor.

        */

        CSIPIetfProfileAgent(TSIPProfileAgentInitParams* aInitParams);

        /**

        * By default Symbian 2nd phase constructor is private.

        */

        void ConstructL();

    private: // New functions        

        /**

        * Provides profile context

        * @param aProfile a profile

        * @return a profile context

        */

        CSIPIetfProfileContext& ProvideProfileContextL(CSIPConcreteProfile& aProfile);

        /**

        * Finds profile context

        * @param aSIPConcreteProfile a profile

        * @return profile context, the ownership is not transferred

        */

        CSIPIetfProfileContext* FindProfileContext(CSIPConcreteProfile& aSIPConcreteProfile) const;

        /**

        * Finds profile context

        * @param aProfileId identifier of the profile

        * @return profile context, the ownership is not transferred

        */

        CSIPIetfProfileContext* FindProfileContext(TUint32 aProfileId) const;

        /**

        * Finds connection context

        * @param aPriofile a profile

        * @return a connection context

        */

        CSIPIetfConnectionContext* FindConnectionContext(CSIPConcreteProfile& aProfile) const;

        /**

        * Destroys idle connection contexts

        */

        void CleanIdleConnectionContexts();

        TBool DeregisterToWaitingQueueL( CSIPIetfProfileContext* aContext );

        void HandleRegisterQueue( CSIPIetfProfileContext* aContext, TBool aReportError );

        void RegisterQueue( CSIPConcreteProfile& aProfile, TBool aReportError );

        TBool AllowedTakeFromQueue( CSIPConcreteProfile& aSIPConcreteProfile );

    private: //  Data

        CSIP*                                    iSIP;

        CSIPHttpDigest*                         iHttpDigest;

        MSIPProfileAgentObserver&                iSIPProfileAgentObserver;

        CDeltaTimer&                            iDeltaTimer;

        TSIPProfileTypeInfo                        iType;

        CSIPPrflInitState*                        iInit;

        CSIPPrflResolvingProxiesState*            iResolvingProxies;

        CSIPPrflRegisterRequestedState*            iRegRequested;

        CSIPPrflRegistrationInProgressState*    iRegInProgress;

        CSIPPrflRegisteredState*                iRegistered;

        CSIPPrflDeregisterRequestedState*        iDeregRequested;

        CSIPPrflDeregistrationInProgressState*    iDeregInProgress;

        CSIPPrflRegisterDelayRequestedState*    iRegDelayRequested;

        RPointerArray<CSIPIetfConnectionContext> iConnectionCtxArray;

        CSIPProfileQueueHandling*                 iProfileQueueHandling;

#ifdef CPPUNIT_TEST    

        friend class CSIPIetfProfileAgentTest;

#endif

    };

#endif CSIPIETFPROFILEAGENT_H

</codeblock> <p><b>sipietfprofilecontext.h</b> </p> <codeblock id="GUID-D4157C14-60BB-5A1F-A45A-7AA80A95A552" xml:space="preserve">// sipietfprofilecontext.h

#ifndef SIPIETFPRROFILECONTEXT_H

#define SIPIETFPRROFILECONTEXT_H

//INCLUDES 

#include "sipprofilecontextbase.h"

#include "sipietfconnectioncontext.h"

// FORWARD DECLARATIONS

class CSIPConcreteProfile;

// CLASS DECLARATION

/**

*  Class for maintaining the information related

*  to a particular IETF type profile. Class stores

*  related registration, sip connection and transactions.

*

*  @lib n/a.

*/

class CSIPIetfProfileContext : public CSIPProfileContextBase

    {

    public:

        /**

        * Two-phased constructor.

        * @param aSIP a handle to SIP server

        * @param aConnection a SIP connection

        * @param aInitState a init state

        * @param aProfile a profile

        */

        static CSIPIetfProfileContext* NewL(

            CSIP& aSIP,

            CSIPIetfConnectionContext& aConnection,

            MSIPProfileAgentObserver& aObserver,

            CSIPPrflStateBase& aInitState,

            CSIPConcreteProfile& aProfile,

            CDeltaTimer& aDeltaTimer);

        /**

        * Two-phased constructor.

        * @param aSIP a handle to SIP server

        * @param aConnection a SIP connection

        * @param aInitState a init state

        * @param aProfile a profile

        */

        static CSIPIetfProfileContext* NewLC(

            CSIP& aSIP,

            CSIPIetfConnectionContext& aConnection,

            MSIPProfileAgentObserver& aObserver,

            CSIPPrflStateBase& aInitState,

            CSIPConcreteProfile& aProfile,

            CDeltaTimer& aDeltaTimer);

        /**

        * Destructor.

        */

        ~CSIPIetfProfileContext();

    public: // From MSIPProfileContext

        void DestroyRegistration();

        void CreateRegistrationL();

        CSIPMessageElements* CreateMsgElementsLC();

        CSIPMessageElements* CreateDeRegisterElementsL();

        void UpdateContactHeaderParamsL(CSIPConcreteProfile& aNewProfile);

        void SetRegisteredAORsL();    

        void ResolveProxyL();

        void CancelProxyResolving();    

    public: // New functions

        /**

        * Deregisters SIP profile according to the profile type.

        * @param aSIPConcreteProfile sip profile to deregister

        */

        void DeregisterL();

         /**

        * Updates SIP profile. This can lead to profile de-registration

        * and registration. Function leaves with KErrArgument if profiles 

        * are the same.

        * @param aNewProfile sip profile to update

        */

        void UpdateL(CSIPConcreteProfile& aNewProfile);

        /**

        * A SIP response creating a registration binding or an error response 

        * that is related to an refreshed registration binding  

        * has been received from the network.

        * @param aTransaction contains response elements.

        * The ownership is transferred.

        * @param aRegistration associated registration

        * @param aHandled, returned ETrue if response handled

        */

        void IncomingResponse(CSIPClientTransaction& aTransaction,

                              CSIPRegistrationBinding& aRegistration,

                              TBool& aHandled);

        TBool RetryTimerInUse();                      

        TUint DelayTime();

        TBool RetryAfterTimer();

    private: // Constructor

        CSIPIetfProfileContext(

            CSIP& aSIP,

            CSIPIetfConnectionContext& iConnection,

            MSIPProfileAgentObserver& aObserver,

            CSIPPrflStateBase& aInitState,

            CSIPConcreteProfile& aProfile,

            CDeltaTimer& aDeltaTimer);

        void ConstructL();

    private: // From CSIPProfileContextBase

        void ConnectionStateChangedImpl(CSIPConnection::TState aState);

        TBool RetryRegister(CSIPClientTransaction* aTransaction, 

                            TInt aError);

        TBool ShouldRetryRegistration(TInt aError);                     

        void InitializeRetryTimerValue();

    private: // New functions

        CSIPMessageElements* CreateMsgElementsForUpdateLC(

            CSIPConcreteProfile& aProfile);

        TUint RandomPercent();

        TBool IsAddressSIPSURIL(const TDesC8& aValue) const;

        HBufC8* SetAddressToSIPSURIL(const TDesC8& aValue);

        TBool SetTlsToSecurityClientL();

        TBool IsDynamicNumericIPAddress( const TDesC8& aValue );

        TBool IsConfiguredOutboundProxySIPURIL( const TDesC8& aValue );

        RStringF TransportProtocol(const CUri8& aUri) const;

    private: // Data

        CSIPIetfConnectionContext&    iConnectionContext;

        RStringF iStrNATTraversalRequired;

        TInt64                         iRandomSeed;

        TUint                          iRetryTime;

        TUint                        iRetryCounter;

        TUint                        iRetryCounterSum;

        TBool                        iRetryTimerUse;

    private: // For testing purposes

        friend class CSIPIetfProfileContextTest;

        friend class CSIPIetfConnectionContextTest;

        friend class CSIPIetfProfileAgentTest;