Configuring and Running RNDIS

Introduction

RNDIS uses the Comms Framework to provide IP communications over USB. It is necessary to configure an Internet Access Point (IAP) for use by RNDIS. Comms Framework uses a layered architecture and so it is necessary to configure RNDIS for each layer as well as for LAN and PAN. The IAP ID for RNDIS must be placed in the Central Repository. IP forwarding must be configured to enable TCP/IP to transfer data between the two interfaces.

In addition it is necessary to define the RNDIS Personality for USB so RNDIS can be started and stopped when the USB cable is attached or detached.

• Configuring the IAP ID in the Central Repository

• Configuring the IAP Settings

• IP forwarding

• Specifying the RNDIS personality

• Starting the RNDIS service

Configuring the IAP ID in the Central Repository

The IAP ID to be used by the RNDIS service is saved in the Central Repository. Device creators need to configure the IAP ID in the Central Repository.

If more than one IAP is provided, the first record in the table has a higher priority than the later IAP. If the first IAP fails to start, the second IAP tries to start and so on.

The following code shows how to configure an IAP ID to the Central Repository. For simplicity, it does not show the transaction. It places the IAP in the first row, giving it a higher priority than any other IAP IDs.

Note: Processes that write to the Central Repository must have NetworkControl capability.

 
const TUid KRndisIapIdRepositoryUID = {0x10286a43};
TInt iapPrefId = 2;
TUint firstRow = 0x01010000; // The first row of IAP repository table
TInt err = KErrNone;

CRepository* repository = NULL;
repository = CRepository::NewLC(KRndisIapIdRepositoryUID);

err = repository->Create(firstRow, iapPrefId);
if (KErrAlreadyExists == err)
    {
    err = repository->Set(firstRow, iapPrefId);
    }
User::LeaveIfError(err);
User::PopAndDestroy(repository);

IP forwarding

To allow the TCP/IP stack to forward traffic between two interfaces, IP forwarding must be enabled. To do this the appropriate tcpip.ini file needs to be modified to include forward= 1 under the [ip] section, for example:

[ip]
maxholdtime= 90
ipv4linklocal= 2
forward= 1

Specifying the RNDIS personality

The RNDIS personality is defined in usbmanrndis.rss and usbmanmtprndis.rss. Device creators need to provide the fields that are indicated by comments below.

PERSONALITY
{
    bDeviceClass = 0x02;
    bDeviceSubClass = 0x00;
    protocol = 0x00;
    numConfigurations = 1;
    vendorId = per_vendoridx; // please specify
    productId = per_productidx; // please specify
    bcdDevice = per_bcddevicex; // please specify
    manufacturer = per_manufacturerx; // please specify, see note below
    product =  per_productx; // please specify, see note below
    id = x; // please specify                
    class_uids = "20013d2f";            
    description = per_descriptionx; // please specify, see note below
}

Note: The field manufacturer, product and description can be specified in a local language, for example, in French or in German. To do this, define them in the local language in usbman_01.rls, usbman_02.rls and so on.

Starting the RNDIS service

To start the RNDIS service, the USB Control Application needs to iterate through the USB Personalities and find the one that supports RNDIS.

Note: There is a USB Control Application in the source code that detects when a USB cable attaches or detaches. Device creators can use that for reference and add the starting and stopping of the RNDIS Control Application.

const TUid KUsbRndisClassControllerUID={0x20013d2f};

     RUsb usb;
     User::LeaveIfError( usb.Connect() ); 
     //Iterate through the USB Personalities and find the one that supports RNDIS.
      TInt personalityId = KErrNotFound;
      TBool supported    = EFalse;
      RArray<TInt> personalityIds; 
      if (KErrNone == usb.GetPersonalityIds(personalityIds))
            {
            const TInt size = personalityIds.Count();
            for (TInt index = 0; index < size; index++)
                {
                 TInt err = usb.ClassSupported(personalityIds[index], 
                                            KUsbRndisClassControllerUID, 
                                             supported);
                 if(supported && KErrNone == err)
                  {
                  personalityId = personalityIds[index];
                  break;
                  }
                }
            personalityIds.Close();
            }
       if (KErrNotFound != personalityId) 
          {
TRequestStatus status;
           usb.TryStart(personalityId, status);
           User::WaitForRequest(status);
           usb.Close();
           LEAVEIFERROR(status.Int());
        }