[RAS] Ras Auto Dial

RAS AutoDial

RAS AutoDial enables a Windows CE device to automatically attempt a new dial-up connection when the current connection fails. For example, if a user is connected to a server on the corporate network with an 802.11 NIC and roams out of the 802.11 network, AutoDial senses the lost connection and dials the default host server to reconnect.

AutoDial is triggered when a connection is lost. It will not attempt a connection if there is any form of connectivity, either public or private. Nor will it attempt a connection if RAS is attempting to make a connection.

The AutoDial DLL, named Autoras.dll, provides the autodial functionality to dialer applications. An AutoDial-compatible dialer communicates with the AutoDial DLL through a message queue.

Windows CE includes a test application for RAS Autodial. This sample application is located in the %_WINCEROOT%\public\common\oak\drivers\netsamp\autoras\test directory and can be used either from the Platform Builder for Windows CE IDE, or from the command line.

The following topics explain how to write an AutoDial-compatible dialer and how enable a default AutoDial connectoid:

·                 AutoDial-Compatible Dialers

·                 Default AutoDial Connectoid Setup

AutoDial-Compatible Dialers

An AutoDial-compatible dialer is an application that communicates with the AutoDial DLL. AutoDial expects information about the dialer to be located at the following registry key:

HKEY_LOCAL_MACHINE\Comm\Autoras

    Dialer = Rnaapp.exe

    NoPromptOpt = -p

    RasEntryOpt = -e

As in this example, the Dialer entry contains the name of the executable file of the dialer. The NoPromptOpt entry defines the argument that AutoDial will use to inform the dialer at launch time not to prompt the user for anything. The RasEntryOpt defines the argument that AutoDial will use to inform the dialer at launch time which phone-book entry to dial.

AutoDial passes messages to the dialer through a message queue that the dialer must create using CreateMsgQueue. The dialer should pass AUTORAS_MSGQUEUE_NAME as the name of the message queue, set the options to write access, and set the MSGQUEUE_ALLOW_BROKEN flag.

At the current time, AutoDial recognizes only two messages: DIALER_START and DIALER_TERMINATE. More messages may be added in the future.

Sample code for a working dialer application is provided for you in this SDK. Go to the %_WINCEROOT%\Public\Common\Oak\Drivers\Netsamp\Rnaapp directory to view the code. The following examples were taken from the Rnaapp.c file.

Setting up the Message Queue

The following sample shows how to set up the message queue.

// RNAAPP as autodialer for AutoRas needs to send feedback

// to Autoas through message queue.

sOptions.dwSize         = sizeof(MSGQUEUEOPTIONS);

sOptions.dwFlags        = MSGQUEUE_ALLOW_BROKEN;

sOptions.dwMaxMessages  = 8;

sOptions.cbMaxMessage   = sizeof(DIALER_NOTIFICATION);

sOptions.bReadAccess    = FALSE;

g_hMsgQueue = CreateMsgQueue(AUTORAS_MSGQUEUE_NAME, &sOptions);

if (g_hMsgQueue == NULL)

{

   DEBUGMSG(ZONE_ERROR,

      (TEXT("RNAAPP:: Failed CreateMsgQueue..\r\n")));

}

else

{

   //

   // Autoras is at the other side, send DIALER_START to it.

   //

   g_DialerNotification.dwNotificationId = DIALER_START;

   WriteMsgQueue(

      g_hMsgQueue,

      &g_DialerNotification,

      sizeof(DIALER_NOTIFICATION),

      0x00,

      0x00);

}

Terminating the Dialer

The following sample shows how to terminate the dialer.

if (g_hMsgQueue)

   {

      g_DialerNotification.dwNotificationId = DIALER_TERMINATE;

      WriteMsgQueue(

         g_hMsgQueue,

         &g_DialerNotification,

         sizeof(DIALER_NOTIFICATION),

         0x00,

         0x00);

      CloseMsgQueue(g_hMsgQueue);

   }

Default AutoDial Connectoid Setup

The AutoDial DLL looks in the following registry entry for the phone-book entry that defines the default connectoid: HKEY_LOCAL_MACHINE\Comm\Autoras\RasEntry.

Your application should set the value of this registry entry to a valid connectoid and reset the value when the connectoid is no longer valid. An invalid registry entry will trigger a user-viewable error message.

A NetUI sample application, ConnMC.exe, sets and resets the default AutoDial connectoid. You can view the code in the %_WINCEROOT%\Public\Common\Oak\Drivers\Netsamp\Connmc directory.