// Copyright (c) 2008-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:
//

/**
 @file
 @publishedPartner
 @released
*/

#ifndef SYMBIAN_NODEMESSAGES_MOBILITY_H
#define SYMBIAN_NODEMESSAGES_MOBILITY_H

namespace ESock
{

/**
The interface for a mobility provider, i.e.: a node that can swap access points and needs
to be instructed (by TCFMobilityControlClients via this interface) when to do so. 
TCFMobilityControlClient are the reverse facing role (nodes that want to instruct
TCFMobilityProviders to swap the access points).

Typical TCFMobilityProviders are: 
-CPRs (towards the application represented by ESock::AMobilityProtocolReq extension API) 
-MCPRs towards CPRs. 

@publishedPartner
@released
@see TCFMobilityControlClient
*/
class TCFMobilityProvider
	{
  private:
  enum
    {
    ECFStartMobility      = 1,
    ECFMobilityStarted    = 2,
    ECFMigrationRequested = 3,
    ECFMigrationComplete  = 4,
    ECFMigrationAccepted  = 5,
    ECFMigrationRejected  = 6
    };
protected:

public:
    enum { ERealmId = 0x10285F4A }; //UID allocated on 4/6/08 from KUidNodeMessageRealms

    /*==========================================================================
    [Name]:      TStartMobility
    [Semantics]: The client (TCFMobilityControlClient) requests the provider ('this' node)
                 to start mobility, i.e.: to prepare resources and start sending notifications 
                 (TCFMobilityControlClient::TMigrationNotification) about possible migrations
                 so that the client can decide upon them.
                 Following TStartMobility the client can perform a number of migrations, each
                 migration mandating a strict handshake to mark the beginning and end of that
                 migration. The handshake goes as follows:
                 TCFMobilityControlClient                                  TCFMobilityProvider
                                             <-TMigrationNotification
                                               TMigrationRequested->
                                             <-TMigrationComplete
                                               TMigrationAccepted->
                                               
                 At any time outside the handshakes, the client may instruct the provider
                 to stop mobility, i.e.: dealocate the resources and stop sending notifications.
                 The client can do that canceling (TEBase::TCancel) TStartMobility.
                 
    [Type]:      Request for TMobilityStarted
    [Fallible]:  Yes

    [Structure]:
    param        iValue - client id, used only when the request is originated by an application
                 when there is no iSender and it takes the value of TSubSessionUniqueId
    ===========================================================================*/
    typedef Messages::TMessageSigAnyNumberDefault<ECFStartMobility, TCFMobilityProvider::ERealmId> TStartMobility;
    typedef Messages::TMessageSigVoid<ECFMobilityStarted, TCFMobilityProvider::ERealmId> TMobilityStarted;

    /*==========================================================================
    [Name]:      TMigrationRequested
    [Semantics]: Request to perform the migration advertised by the most recent
                 TCFMobilityControlClient::TMigrationNotification. The provider
                 marks the completion of the migration by sending TMigrationComplete,
                 at which point the client gets to verify the new access point
                 and finally accept it (TMigrationAccepted) or reject it (TMigrationRejected)
                 closing the handshake.

    [Type]:      Request for TMigrationComplete
    [Fallible]:  Yes

    [Structure]:
    ===========================================================================*/
    typedef Messages::TMessageSigVoid<ECFMigrationRequested, TCFMobilityProvider::ERealmId> TMigrationRequested;
    typedef Messages::TMessageSigVoid<ECFMigrationComplete, TCFMobilityProvider::ERealmId> TMigrationComplete;

    /*==========================================================================
    [Name]:      TMigrationAccepted
    [Semantics]: Mobility handshake closure. The client accepts the new access point.

    [Type]:      Notification
    [Fallible]:  No

    [Structure]:
    ===========================================================================*/
    typedef Messages::TMessageSigVoid<ECFMigrationAccepted, TCFMobilityProvider::ERealmId> TMigrationAccepted;

    /*==========================================================================
    [Name]:      TMigrationRejected
    [Semantics]: TMigrationRejected will have a different meaning depending on the provider's state:
                 (1) Directly following TCFMobilityControlClient::TMigrationNotification, in which case the client
                     ignores the new access point advertised with TCFMobilityControlClient::TMigrationNotification.
                     The provider stays with the current access point. TMigrationRejected terminates the handshake.  
                 (2) Directly following TCFMobilityProvider::TMigrationComplete, in which case the client rejects
                     the access point the provider migrated to. The provider may at this point
                     offer another access point (TCFMobilityControlClient::TMigrationNotification),
                     which could be one of the previous active access points the client decided
                     to try to upgrade from. If the provider has no alternative the client should
                     observe the connection going down. TMigrationRejected terminates the handshake. 
                 (3) Outside of the mobility handshake. The client decides that, for whatever reasons
                     (e.g.: no desired routability), it is not happy with the current access point and wants to
                     force mobility. If the provider has an alternative access point to offer, the access point should
                     be offered with TCFMobilityControlClient::TMigrationNotification.

    [Type]:      Notification
    [Fallible]:  No

    [Structure]:
    ===========================================================================*/
    typedef Messages::TMessageSigNumber<ECFMigrationRejected, TCFMobilityProvider::ERealmId> TMigrationRejected;
	};



/**
Callback/reverse-facing interface for TCFMobilityProvider. Anybody invoking TCFMobilityProvider
must implement TCFMobilityControlClient.

@publishedPartner
@released
@see TCFMobilityProvider
*/
class TCFMobilityControlClient
    {
  private:
  enum
    {
    ECFMigrationNotification = 1
    };
protected:

public:
    enum { ERealmId = 0x10285F49 }; //UID allocated on 4/6/08 from KUidNodeMessageRealms
    /*==========================================================================
    [Name]:      TMigrationNotification
    [Semantics]: Notification about possible mobility migration sent by the TCFMobilityProvider.
                 The recipient _must_ respond to this notifaction by commencing the migration
                 handshake. The recipient must therefore respond with either:
                 TCFMobilityProvider::TMigrationRequested to pursue the migration
                 TCFMobilityProvider::TMigrationRejected to ignore the offer.

    [Type]:      Notification
    [Fallible]:  No

    [Structure]:
    param        iValue1 - old access point
                 iValue2 - new access point
                 iValue3 - is upgrade
    ===========================================================================*/
    typedef Messages::TMessageSigNumberNumberNumberNumber<ECFMigrationNotification, TCFMobilityControlClient::ERealmId> TMigrationNotification;
    };

} //namespace ESock

#endif //SYMBIAN_NODEMESSAGES_MOBILITY_H