/*

* Copyright (c) 2005 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:   Connection manager

*

*/

#ifndef __MSGCONNMANAGERAPI__

#define __MSGCONNMANAGERAPI__

#include "msgbearerobscallback.h"

//Define the CommDb parameters which the Conn Manager must support

enum TSupportedCommDbRecords

    {

    EMsgProxyAddress = 0,

    EMsgProxyPort

    };

//FORWARD DECLARATIONS

class TInetAddr;

class RConnection;

class RSocketServ;

class MMsgBearerObsCallback;

class MMsgConnManager 

    {

    public:  // New functions

        /**

        * Start a connection. This asynchronous request completes

        * as soon as a connection has been successfully opened or

        * an error condition has been detected.

        *

        * Completes with:

        *

        *    - KErrNone if a connection has been succesfully opened

        *    - KErrNotReady if client has called StopConnection()

        *      and attempts to start a new connection before the previous

        *      one has been disconnected.

        *    - KErrAlreadyExists if a client attempts to open a connection

        *      while one is already being opened

        *    - KErrTimedOut if the specified timeout value expires

        *

        * @param aStatus Request status of the client.

        */  

        virtual void StartConnection( TRequestStatus& aStatus ) = 0;

        /**

        * Stop a connection, synchronous version

        */  

        virtual void StopConnection() = 0;

        /**

        * Stop a connection. This asynchronous request completes

        * as soon as a connection has been closed. Note that it 

        * takes a few seconds for the connection to really wear out.

        * Thus, when a client calls this function, it should really

        * mean what it is saying, because a new connection CANNOT BE 

        * OPENED before a previous one has been deactivated.

        *

        * The request may complete with

        *    - KErrNone if connection closing is successful

        *    - KErrAbort if call takes place while connection initiation

        *      is ongoing or if there is no active connection that would

        *      require closing. If a connection initiation is ongoing

        *      client should use CancelStartL() method instead.

        *

        * @param aStatus Request status of the client

        */  

        virtual void StopConnection( TRequestStatus& aStatus ) = 0;

        /**

        * Cancel StartConnection(). The method may leave with

        *   - KErrAbort if the TRequestStatus object the client

        *     supplied is not active, hence, there is no pending

        *     request that would require cancelling.

        * In normal cases - when RConnection::Start() or its 

        * progress notifications are pending - ConnMan completes

        * the client's request with the "error" KErrCancel.

        *

        * @return void

        */  

        virtual void CancelStartL() = 0;

        /**

        * Set the ID of the Access Point to connect to. Note that this

        * function is effective only when there is no active connection

        * the start of which has been initiated by the client. In other

        * words, the ID of the desired Access Point can be changed only

        * BEFORE calling StartConnection().

        * 

        * May leave with

        *    - KErrNotFound if the Access Point ID does not exist

        *

        * @param TInt aAccessPointID ID of the Accee Point to use

        */

        virtual void SetAccessPointIDL( const TInt aAccessPointID ) = 0;

        /**

        * Returns a reference to the active socket server.

        *

        * @return RSocketServ& An opened socket server

        */

        virtual RSocketServ& SocketSession() = 0;

        /**

        * Returns a reference to the currently open connection

        *

        * @return RConnection& An opened connection

        */

        virtual RConnection& Connection() = 0;

        /**

        * Returns the number of active connections currently open

        *

        * @return TInt Number of active connections on the device

        */

        virtual TInt NumberOfActiveConns() = 0;

        /**

        * Read data from the Comms Database

        *

        * @param TMsgSupportedCommDbRecords aParameter The type of the CommDb record

        * @return HBufC* Value of the requested record

        */

        virtual HBufC* ReadFromCommsDbLC( const TSupportedCommDbRecords aParameter ) = 0;

        /**

        * Add an object to the queue of listeners. The object to be added

        * must inplement the interface MMsgBearerObsCallback in order

        * to receive events from the system agent. It is important to note

        * that the call to the notification handler (HandleBearerEventL())

        * takes place inside the RunL() method of this Connection Manager,

        * so the listening object MUST return the control to the Manager

        * AS SOON AS POSSIBLE in order not to clog the scheduler.

        *

        * @param MMsgBearerObserverCallback* aClient A subscribing client

        * @return void

        */

        virtual void AddEventSubscriberL( MMsgBearerObsCallback* aClient ) = 0;

        /**

        * Remove an object from the queue of listeners. It is not necessary

        * to call this method at deletion time, as the destructor destroys

        * the subscriber queue altogether. If, however, a listener object is

        * destroyed (or is likely to be) before an instance of Connection Manager,

        * it is mandatory to remove the listener from the queue prior to deleting

        * the listener.

        *

        * @param MMsgBearerObsCallback* aClient The client to be removed

        * @return void

        */

        virtual void RemoveEventSubscriber( MMsgBearerObsCallback* aClient ) = 0;

        /**

        * Returns the state of this connection manager:

        *

        *    - ETrue, if a connection is available

        *    - EFalse otherwise; bearer suspended, StartConnection() failed etc.

        *

        * A component that wishes to send/receive data is encouraged

        * to call this function before opening a socket, or reading

        * from or writing to one. This way it can be assured that

        * no component prompts up that annoying IAP dialog.

        *

        * @return TBool Is the connection OK

        */

        virtual TBool Status() const = 0;

        /**

        * Destructor. Must be called when the services of the

        * manager are no longer needed. This is merely a

        * wrapper to the C++ destructor.

        *

        * It is highly advisable that a client of this API

        * ALWAYS Destroy()s the instance it owns only after

        * it has disposed of all other connection-related

        * components at its command. This is because the other

        * components may still be dependent on the RConnection

        * and RSocketServ instances provided by this object.

        *

        * @return void

        */

        virtual void Destroy() = 0;

    };

/**

* Creates a new Connection Manager

* @param aDefaultAccessPoint ID of the default Access Point

*/     

IMPORT_C MMsgConnManager* NewMsgConnManagerL( const TInt aDefaultAccessPoint );

#endif

// End of File