/*

* Copyright (c) 2003 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:  Core class for all Smart Card aware applications to use when 

*                communicating with the card.

*

*/

#ifndef CSCARDCOMM_H

#define CSCARDCOMM_H

//  INCLUDES

#include "ScardConnectionRequirement.h"

// FORWARD DECLARATIONS

class RScard;

// CLASS DECLARATION

/**

*  Core class for card communication.

*  This is the core class for all SC aware applications to use when 

*  communicating with the card. All objects of this class are 

*  connected to a reader, and the reader's name must be supplied as a 

*  parameter when constructing objects of this class

*

*  @lib Scard.lib

*  @since Series60 2.1

*/

class CScardComm : public CBase

    {

    public:  // Constructors and destructor

        /**

        * Two-phased constructor.

        * @param aScard The connection to server. 

        *        The RScard object must not have any other CScardComm objects

        *        attached to it.

        * @param aRequirement Parameters to the connection

        * @param aReaderName This is set to contain the name of the 

        *        reader that was contacted when a connection is established

        * @param aStatus This status is signaled when connection has been made

        * @param aTimeOut The timeout in microseconds

        * @return Pointer to CScardComm object

        */

        IMPORT_C static CScardComm* NewL(

            RScard* aScard, 

            TScardConnectionRequirement& aRequirement,

            TScardReaderName& aReaderName,

            TRequestStatus& aStatus, 

            const TInt32 aTimeOut = 0 );

        /**

        * Destructor.

        */

        IMPORT_C virtual ~CScardComm();

    public: // New functions

        /**

        * Returns the RScard object contained within this object.

        * @return Pointer to RScard object

        */

        IMPORT_C RScard* Scard() const;

        /**

        * This function fetches the answer-to-reset bytes of the SC 

        * currently in the card reader. If an error occurs during the 

        * operation, the  length of the atr bytes is set to zero. Currently

        * leaves with KErrNotSupported

        * @param aATR ATR-bytes

        * @return void

        */

        IMPORT_C void GetATRL( TScardATR& aATR ) const;

        /**

        * Get proprietary parameters from the reader handler.

        * @param aTag parameter wanted (see scardbase.h)

        * @param aValue value of desired parameter

        * @param aTimeOut timeout in microseconds

        * @return void

        */

        IMPORT_C void GetCapabilitiesL( const TInt32 aTag,

                                        TDes8& aValue, 

                                        const TInt32 aTimeOut = 0 ) const;

        /**

        * This function is the basic transmission function. It takes a

        * 8-bit command data of unspecified length and transmits it to 

        * the reader handler. The reader handler will pass it on to the 

        * card, and place the response in the supplied response buffer 

        * (also of undefined length). The buffer must be sufficiently 

        * big to accomodate the response, otherwise the calling thread 

        * will be panicked.

        * @param aCommand This descriptor holds the command sent to the 

        *        card. The length of the descriptor must match the data length

        *        of the command.

        * @param aResponse The response from the SC is copied here.

        * @param aStatus Signaled when the operation is finished.

        * @param aTimeOut Timeout in microseconds.

        * @param aChannel The logical channel this command will be executed in.

        * @return void

        */

        IMPORT_C void TransmitToCard( const TDesC8& aCommand, 

                                      TDes8& aResponse,

                                      TRequestStatus& aStatus,

                                      const TInt32 aTimeOut = 0, 

                                      const TInt8 aChannel = 0) const;

        /**

        * This function will cancel any transmissions and other 

        * operations this object has currently pending within the 

        * server. If the object has an active transaction reservation, 

        * this will also be cancelled. All operations sent before this 

        * command will terminate with error code KScErrCancelled.

        * @return void

        */

        IMPORT_C void CancelTransmit() const;

        /**

        * Channel management function.

        * @param aCommand Channel operation.

        * @param aArgument

        * @param aResponseBuffer Buffer for response.

        * @param aStatus Signaled when the operation is finished.

        * @param aTimeOut Timeout in microseconds.

        * @return void

        */

        IMPORT_C void ManageChannel( const TScChannelManagement aCommand, 

                                     const TInt8 aArgument,

                                     TDes8& aResponseBuffer,

                                     TRequestStatus& aStatus,

                                     const TInt32 aTimeOut ) const;

    private:

        /**

        * C++ default constructor.

        * @param aScard Pointer to RScard object

        */

        CScardComm( RScard* aScard );

        /**

        * By default Symbian OS constructor is private.

        */

        void ConstructL( TScardConnectionRequirement& aRequirement,

                         TScardReaderName& aReaderName, 

                         TRequestStatus& aStatus, 

                         const TInt32 aTimeOut );

        /**

        * Disconnect from reader

        * @return void

        */

        void DisconnectFromReader() const;

    private:    // Data

        // Pointer to Scard object. Not owned. 

        RScard* iScard;

    };

#endif      // CSCARDCOMM_H   

// End of File