/*
* Copyright (c) 2009 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:
* 
* Description: 
*
*/



#ifndef __P2PIF_H__
#define __P2PIF_H__

#include <e32cmn.h>     // For RBusLogicalChannel
#include <p2pdefs.h>    // For TP2PProtocol

/**
* An interface for transceiving point-to-point (P2P) data between
* two end points according to used P2P protocol.
* Interface is used from user side.
*/
class RP2PIf : public RBusLogicalChannel
    {

    public:

        /*
        * C++ default constructor.
        */
        IMPORT_C RP2PIf();

        /*
        * Destructor
        */
        IMPORT_C ~RP2PIf();

        /*
        * Closes the interface and cancels any outstanding requests with KErrCancel.
        * If interface is not opened with RP2PIf::Open does nothing.
        * Automatically called in destructor.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   User::Panic
        * SMP safe:     Yes
        * @post Calling thread not blocked
        */
        IMPORT_C void Close();

        /*
        * Notifies when connection to other point is lost.
        * Automatically cancelled in RP2PIf::Close.
        * All data received after connection is lost shall be discarded.
        * NOTE! If interface is not open panicked with User::Panic.
        * NOTE! After connection lost RP2PIf::Close shall be called.
        * Execution:    Asynchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   User::Panic
        * SMP safe:     Yes
        * @param aStatus, updated when connection is lost
        *                 KErrNotReady when connection is lost
        *                 KErrCancel when request is cancelled
        * @post Calling thread not blocked
        */
        IMPORT_C void ConnectionLost( TRequestStatus& aStatus );

        /*
        * Cancels the pending connection lost request with KErrCancel.
        * Automatically cancelled in RP2PIf::Close.
        * NOTE! If interface is not open panicked with User::Panic.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   User::Panic
        * SMP safe:     Yes
        * @post Calling thread not blocked
        */
        IMPORT_C void ConnectionLostCancel();

        /**
        * Asynchronously opens a P2P protocol communication path from this point to another.
        * Open is not complited before the communication path is open.
        * When request is set to pending blocked calling thread is released.
        * Automatically cancelled in RP2PIf::Close.
        * Execution:    Asynchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   User::Panic
        * SMP safe:     Yes
        * @param aP2PProtocolId, unique identifier of the used point-to-point protocol
        * @param aStatus, KErrNone if ok
        *                 KErrNotSupported if protocol is not supported
        *                 KErrInUse if someone uses the same protocol id
        *                 KErrAlreadyExists same interface object is opened with other protocol id
        *                 KErrCancel if outstanding request is cancelled
        *                 KErrPermissionDenied if not enough capabilities
        * @param aHandleType, specifies whether the handle is owned by process or by thread.
        * @post Calling thread not blocked
        */
        IMPORT_C void Open( const TP2PProtocol aP2PProtocolId,
                            TRequestStatus& aStatus,
                            TOwnerType aHandleType = EOwnerThread );

        /**
        * Cancel asynchronous channel opening with KErrCancel.
        * Does nothing if request is not pending.
        * Automatically called in RP2PIf::Close.
        * NOTE! If interface is not open panicked with User::Panic.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   User::Panic
        * SMP safe:     Yes
        * @post Calling thread not blocked
        */
        IMPORT_C void OpenCancel();

        /**
        * Receive data from other point.
        * Either receives data immediately or set the receive request pending.
        * When request is set to pending blocked calling thread is released.
        * Automatically cancelled in RP2PIf::Close.
        * NOTE! If interface is not open panicked with User::Panic.
        * NOTE! If interface is not opened when other point is sending data to it data shall
        * be deallocated.
        * Execution:    Asynchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   User::Panic
        * SMP safe:     Yes
        * @param aStatus, KErrNone if ok.
        *                 KErrBadDescriptor if receive buffer is invalid or too small.
        * @param aReceiveBuffer, buffer where to receive data from kernel
        */
        IMPORT_C void Receive( TRequestStatus& aStatus, TDes8& aReceiveBuffer );

        /**
        * Cancel asynchronous receive request with KErrCancel.
        * Does nothing if request is not pending.
        * Automatically called in RP2PIf::Close.
        * NOTE! If interface is not open panicked with User::Panic.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   User::Panic
        * SMP safe:     Yes
        * @post Calling thread not blocked
        */
        IMPORT_C void ReceiveCancel();

        /**
        * Sends data to other point.
        * NOTE! If interface is not open panicked with User::Panic.
        * NOTE! Absolutely maximum send buffer size is 16-bit value.
        * Execution:    Synchronous
        * Re-entrant:   No
        * Blocking:     Yes
        * Panic mode:   User::Panic
        * SMP safe:     Yes
        * @param aSendBuffer, data to be send
        * @return KErrNone, is succesfull
        *                   KErrNoMemory buffer size is over the maximum size
        *                   KErrNotReady connection to other point lost, data lost
        *                   KErrBadDescriptor if send buffer is invalid
        * @post Calling thread not blocked
        */
        IMPORT_C TInt Send( const TDesC8& aSendBuffer );

    };

#endif      // __P2PIF_H__

// End of File