/*

* Copyright (c) 2010 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

*/

#ifndef USBNCM_H

#define USBNCM_H

//INCLUDES

#include <e32std.h>

/** Defines the exported P&S key and data structure of the value. */

namespace UsbNcm

    {

    /** The property's category UID.

     *  This property is to notify the NCM connection state.

     */

    static const TUid  KCatNcmSvrUid = {0x101F7989};

    /** The property's sub-key.*/

    static const TUint KKeyNcmConnectionEvent = 0x2002C33F;

    /** NCM connection state.*/

    enum TNcmConnectionState

      {

      ENcmStateDisconnected = 0,

      ENcmStateConnected,

      ENcmStateMax

      };

    /**

     * Defines the NCM connection event, which contains the IapId, NCM connection state and corresponding error code.

     * The NCM connection is a special one which can not only be used by RConnection, but also needed to monitor the P&S to fetch its state changing.

     * Once the P&S published the ENcmStateConnected, the iIapId is also available for starting this connection.

     * Otherwise, if the P&S published the ENcmStateDisconnected, the iErrCode should be checked to notify the failure reason:

     *            KErrNone, normally disconnected probably because of USB cable unpluged.

     *            KErrInUse, means the other component(currently, BtPan or RNDIS) hold the other P&S key so that the DHCP Provision can't be done by NCM.

     *            system-wide error code, please check Developer Library.

     *            It is also possible that this P&S key is deleted when fetching its value because of the NCM connection closed by its driver.

     *

     * @see below sample code.

     */

    struct TNcmConnectionEvent

      {

      TUint32                iIapId;

      TNcmConnectionState    iState;

      TInt                   iErrCode;

      TUint8                 reserved[20];

      };

    } // namespace UsbNcm

/**

 Example Usage:

 @code

 //header file.

 #include <usb/usbncm.h>

 using namespace UsbNcm;

 CMySampleClass: public CActive

     {

     private:

        RProperty                      iProperty;

        RConnection                    iConnection;

        TPckgBuf<TNcmConnectionEvent>  iNcmEvent;

        RSocket                        iSocket;

     }

 @endcode

 @code

 #include "mysampleclass.h"

 void CMySampleClass::ContructL()

    {

    User::LeaveIfError(iProperty.Attach(KCatNcmSvrUid, KKeyNcmConnectionEvent, EOwnerThread));

    iProperty.Get(iNcmEvent);

    if (ENcmStateConnected == iNcmEvent.iState)

        {

        TRequestStatus* pStatus = &iStatus;

        iStatus = KRequestPending;

        User::RequestComplete(pStatus, KErrNone);

        }

    else

        {

        iProperty.Subscribe(iStatus);

        SetActive();

        }

    }

 void CMySampleClass::RunL()

    {

    if (KErrNone == iStatus.Int())

        {

        iProperty.Get(iNcmEvent);

        switch(iNcmEvent.iState)

            {

            case ENcmStateConnected:

                StartConnection();

                break;

            case ENcmStateDisconnected:

                if (KErrInUse == iNcmEvent.u.iErrCode)

                    {

                    //Show error UI with msg like "BtPan or Rndis is active, pls deactive it then re-try....", etc.

                    }

                else

                    {

                    //Show error UI with other msg as you like.

                    //StopConnection();

                    }

                break;

            }

        }

    }

 //Sample code, not all string in this panic show on.

 LIT(KNotFoundNcm, "NotFoundPanic - The NCM connection was not found!");

 TInt CMySampleClass::StartConnection()

    {

    //the number of connections.

    TInt cnt = 0;

    iConnection.EnumerateConnections(cnt);

    TInt index = 1;

    for (index = 1; index <= cnt; index++)

        {

        TPckgBuf<TConnectionInfo> info;

        iConnection.GetConnectionInfo(index, info);

        if (info().iIapId == iNcmEvent.iIapId)

            {

            iConnection.Attach(info, RConnection::EAttachTypeNormal);

            break;

            }

        }

    __ASSERT_ALWAYS(index <= cnt, User::Panic(KErrNotFound, KNotFoundNcm));

    TInt ret = iSocket.Open(...., iConnection);

    //.....

    return ret;

    }

 @endcode

*/

#endif // USBNCM_H