/*

* Copyright (c) 2006 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:  Bluetooth Engine ECom plug-in base class declaration.

*

*/

#ifndef BTENGINEPLUGIN_H

#define BTENGINEPLUGIN_H

#include <ecom/ecom.h>

#include <bt_sock.h>

#include <btengconstants.h>

/**

 * Class MBTEngConnObserver

 *

 * Callback class for receiving CBTEngPlugin events

 * for connect/disconnect complete events.

 *

 *  @lib btengdevman.dll

 *  @since S60 V3.0

 */

class MBTEngPluginObserver

    {

public:

    /**

     * Indicates to the caller that a service-level connection has completed.

     * This function is called for both incoming and outgoing connections. 

     * This function is also called when an outgoing connection request fails, 

     * e.g. with error code KErrCouldNotConnect.

     * Profiles are identified by the SDP Service Class UUID (short form), 

     * as assigned by the Bluetooth SIG.

     *

     * The caller of this function must be ready to receive new commands on the 

     * CBTEngPlugin interface during execution of this function i.e. it should 

     * have released all resources relating to execution of such commands. 

     *

     * @since  S60 v3.2

     * @param  aAddr The address of the remote device.

     * @param  aProfile Identifier for the service-level connection.

     * @param  aErr Status information, if there is an error.

     * @param  aConflicts If there already is a connection for the selected 

     *                    profile(s) of an outgoing connection request, then 

     *                    this array contains the bluetooth device addresses 

     *                    of the remote devices for those connections.

     */

    virtual void ConnectComplete( const TBTDevAddr& aAddr, 

                                   TBTProfile aProfile, TInt aErr, 

                                   RBTDevAddrArray* aConflicts = NULL ) = 0;

    /**

     * Indicates to the caller that a service-level connection has disconnected.

     *

     * The caller of this function must be ready to receive new commands on the 

     * CBTEngPlugin interface during execution of this function i.e. it should 

     * have released all resources relating to execution of such commands. 

     *

     * @since  S60 v3.2

     * @param  aAddr The address of the remote device.

     * @param  aProfile Identifier for the service-level connection.

     * @param  aErr Status information, if there is an error.

     */

    virtual void DisconnectComplete( const TBTDevAddr& aAddr, 

                                      TBTProfile aProfile, TInt aErr ) = 0;

    };

/**

 *  BTEng plug-in base class.

 *

 *  This is the base class from which a BT Engine ECom plug-in inherit. 

 *  BT Engine plug-ins implement Bluetooth profiles. This interface is 

 *  used to issue commands relating to service-level connection management 

 *  (i.e. relating to profile connections). Each plugin implementation 

 *  identifies itself through the SDP Service Class UUIDs defined by 

 *  the Bluetooth SIG for profiles it supports.

 *

 *  @lib bteng.lib

 *  @since S60 v3.2

 */

class CBTEngPlugin : public CBase

    {

public:

    /**  Array of BT profiles. */

    typedef RArray<TBTProfile> RProfileArray;

    /**

     * Constructor; loads the plug-in through the ECom framework.

     *

     * @since S60 v3.2

     * @param aImplementationUid The UID of the interface implementation 

     *                           to be loaded.

     * @return Pointer to the constructed CBTEngPlugin object.

     */

    inline static CBTEngPlugin* NewL( const TUid aImplementationUid );

    /**

     * Destructor; destroys the plug-in through the ECom framework.

     */

    inline virtual ~CBTEngPlugin();

    /**

     * Sets the observer for receiving connection events through the 

     * MBTEngPluginObserver interface. This method MUST be called 

     * before any command is given to the plug-in

     *

     * @since S60 v3.2

     * @param aObserver The observer of connection events.

     */

    virtual void SetObserver( MBTEngPluginObserver* aObserver ) = 0;

    /**

     * Gets the list of profiles implemented by this plug-in.

     * Profiles are identified by the SDP Service Class UUID (short form), 

     * as assigned by the Bluetooth SIG.

     *

     * @since S60 v3.2

     * @param aProfiles Array of integers identifying the BT profiles 

     *                  implemented by this plug-in.

     */

    virtual void GetSupportedProfiles( RProfileArray& aProfiles ) = 0;

    /**

     * Indicates if this plug-in implements the specified profiles.

     * Profiles are identified by the SDP Service Class UUID (short form), 

     * as assigned by the Bluetooth SIG.

     *

     * @since S60 v3.2

     * @param aProfile Integer identifying the BT profile.

     * @return ETrue if the plug-in implements the requested profile, 

     *               otherwise EFalse.

     */

    virtual TBool IsProfileSupported( const TBTProfile aProfile ) const = 0;

    /**

     * Instructs the plug-in to create a service-level connection 

     * with the specified Bluetooth address.

     *

     * This is an asynchronous operation; on completion, the plug-in informs 

     * the observer by calling MBTEngPluginObserver::ConnectComplete with 

     * the appropriate error code.

     *

     * @since S60 v3.2

     * @param aAddr The BT device address identifying a remote device.

     * @return KErrNone on success, otherwise an appropriate error code.

     */

    virtual TInt Connect( const TBTDevAddr& aAddr ) = 0;

    /**

     * Instructs the plug-in to cancel the creation a service-level 

     * connection with the specified Bluetooth address.

     *

     * In addition, as this is part of an asynchronous operation, the plug-in 

     * completes the outstanding asyncronous request status with KErrCancel.

     *

     * @since S60 v3.2

     * @param aAddr The BT device address identifying a remote device.

     */

    virtual void CancelConnect( const TBTDevAddr& aAddr ) = 0;

    /**

     * Instructs the plug-in to create a service-level connection 

     * with the specified Bluetooth address.

     *

     * This is an asynchronous operation; on completion, the plug-in informs 

     * the observer by calling MBTEngPluginObserver::DisconnectComplete with 

     * the appropriate error code.

     *

     *

     * @since S60 v3.2

     * @param aAddr The BT device address identifying a remote device.

     *              In case the address is the NULL address, the plug-in is

     *              expected to disconnect all its connections.

     * @param aDiscType The type of disconnection; 

     *                  EGraceful for graceful (normal) disconnection, 

     *                  EImmediate for immediate (forced) disconnection.

     * @return KErrNone on success, otherwise an appropriate error code.

     */

    virtual TInt Disconnect( const TBTDevAddr& aAddr, 

                              TBTDisconnectType aDiscType ) = 0;

    /**

     * Gets the addresses of the connected devices for the specified profile.

     *

     * @since S60 v3.2

     * @param aAddrArray On return, holds the Bluetooth device addresses 

     *                   of the connected Bluetooth devices for the 

     *                   requested profile.

     * @param aConnectedProfile The profile for which the existing 

     *                          connections are requested.

     * @return KErrNone if sucessful, otherwise the error code 

     *                  indicating the error situation.

     */

    virtual void GetConnections( RBTDevAddrArray& aAddrArray, 

                                  TBTProfile aConnectedProfile ) = 0;

    /**

     * Indicates if this plug-in has a service-level connection 

     * with the specified Bluetooth address.

     *

     * @since S60 v3.2

     * @param aAddr The BT device address identifying a remote device.

     * @return The status of the connection according to the TConnectionStatus

     *         enumeration. EConnecting is interpreted that at least one 

     *         incoming connection request has been completed, but that not 

     *         all service-level connections have been fully established.

     */

    virtual TBTEngConnectionStatus IsConnected( const TBTDevAddr& aAddr ) = 0;

private: // data

    /**

     * UID set by ECOM when the instance is created.

     * Used when the instance is destroyed.

     */

    TUid iInstanceUid;

    };

// -----------------------------------------------------------------------------

// Create the requested implementation.

// -----------------------------------------------------------------------------

//

inline CBTEngPlugin* CBTEngPlugin::NewL( const TUid aImplementationUid )

    {

    TInt32 keyOffset = _FOFF( CBTEngPlugin, iInstanceUid );

    TAny* plugin = REComSession::CreateImplementationL( aImplementationUid, 

                                                         keyOffset );

    return reinterpret_cast<CBTEngPlugin*>( plugin );

    }

// -----------------------------------------------------------------------------

// The implementation has been deleted.

// -----------------------------------------------------------------------------

//

inline CBTEngPlugin::~CBTEngPlugin()

    {

    REComSession::DestroyedImplementation( iInstanceUid );

    }

#endif // BTENGINEPLUGIN_H