The Remote Network Access (RNA) Dialer

So far in this chapter, you have learned how to manipulate the RAS phonebook, dial and establish RAS connections, and query the RAS interface to get statistical information about currently active remote sessions. The last thing to cover is how Pocket PC takes advantage of the RAS service to dial, connect to, and maintain a connection with a RAS server. The dialer application that is built into Pocket PC is located in the \Windows folder and has the name rnaapp.exe. The rnaapp.exe dialer (see Figure 6.3) is nothing more than a wrapper around the RAS functions already discussed.

Figure 6.3. The rnaapp.exe Pocket PC dialer

Besides automating most of the RAS functions, it provides you with a graphical interface for the dialer, which calling RasDial() by itself would not provide. Unless you want to manually provide user feedback and an interface for dialing a RAS connection, you can launch rnaapp.exe to handle your connection.

Creating a RAS Connection with rnaapp.exe

Integrating your application with rnaapp.exe is fairly straightforward. To dial a remote server, you need to launch rnaapp.exe from your application by using the CreateProcess() function. Rnaapp.exe takes the command-line parameters described in Table 6.5.

For example, if you wanted to connect the "Work" RAS entry and use rnaapp.exe to dial it, you could do the following:

 PROCESS_INFORMATION pi; memset(&pi, 0, sizeof(PROCESS_INFORMATION)); CreateProcess(TEXT("\\Windows\\rnaapp.exe"), TEXT("-e\"My    Connection\" -c00FF"), NULL, NULL, NULL, 0, NULL, NULL, NULL,    &pi); 

Once a connection to the server has been established, rnaapp.exe will send a global broadcast message, WM_NETCONNECT, to all of the running applications on your device.

As with any window message, WM_NETCONNECT contains two informational parameters that are sent along with the message. The wParam parameter specifies the connection status of the session. If the value is TRUE, then the connection has been established; otherwise, it will be set to FALSE when the connection has been terminated.

The lParam parameter is a pointer to an RNAAPP_INFO structure. The structure contains information that rnaapp.exe has stored about the particular dial-up session. The RNAAPP_INFO structure is defined as follows:

 typedef struct tagRNAAppInfo {    DWORD dwSize;    DWORD hWndRNAApp;    DWORD Context;    DWORD ErrorCode;    TCHAR RasEntryName[RAS_MaxEntryName+1]; } RNAAPP_INFO, *PRNAAPP_INFO; 

Table 6.5. rnaapp.exe Command-Line Parameters

Option	Description
-n	Disable all message boxes.
-p	Do not display any user authentication prompts (username/password).
-m	Minimize the connection dialog box.
-cNUM	Set the connection context value in hex (e.g., -c00FF). This value will be used to uniquely identify a RAS connection when sending/receiving messages to the rnaapp.exe dialer.
-eRASPHONEBOOKENTRY	The name of the RAS phonebook entry to dial. If the name contains any spaces, it should be enclosed in quotes.

The RNAAPP_INFO structure contains the following information:

• The dwSize member contains the size of the structure.

• The hWndRNAApp member is the window handle of rnaapp.exe.

• The Context member contains the value that was specified to rnaapp.exe with the -c parameter when the application was run.

• The ErrorCode member specifies the error code of the RAS connection if the wParam value of the WM_NETCONNECT message is FALSE. See raserror.h for more information on RAS errors.

• The RasEntryName member contains a null-terminated string that specifies the RAS phonebook entry name of the connection.

For example, if you wanted to process a WM_NETCONNECT message in your application's main message loop, you would do the following:

 case WM_NETCONNECT: {    BOOL fConnected = (BOOL)wParam;    RNAAPP_INFO *prnaInfo = (RNAAPP_INFO *)lParam;    // Check to see if we've disconnected    if(fConnected == FALSE) {       TCHAR tchRNAError[128] = TEXT("\0");       wsprintf(tchRNAError, TEXT("RNAError: %d"),          prnaInfo->ErrorCode);       MessageBox(NULL, tchRNAError, TEXT("RNA Dial Error"),          MB_ICONERROR|MB_OK);       break;    }    // Looks like we have an active connection    MessageBox(NULL, prnaInfo->RasEntryName, TEXT("Connection       Established"), MB_ICONERROR|MB_OK); } break; 

Working with rnaapp.exe

If you have established a dial-up connection with rnaapp.exe (or want to work with a connection that was created with the Pocket PC Connection Manager), you can use the SendMessage() function to further communicate with the dialer application.

Before you can send a message to rnaapp.exe, however, you must first know the window handle of the connection dialog. This value can be obtained in two ways: by storing the hWndRNAApp handle that was sent as part of the RNAAPP_INFO structure you received when the initial connection was established, or by using the EnumWindow() function.

Because EnumWindow() will enumerate all of the active windows, you need to look at each one for a "magic" number that signifies the dialer. The magic number, RNAAPP_MAGIC_NUM, is defined as 0x006A6D6D, and can be found by calling the GetWindowLong() function on each window handle that is returned when you call EnumWindows().

While this sounds somewhat complicated, it is actually relatively straightforward to find the dialer window:

 #define RNAAPP_MAGIC_NUM 0x006A6D6D BOOL RNAEnumFunc(HWND hWnd, LPARAM lParam){    TCHAR tchClass[128] = TEXT("\0");    HWND *hRnaWnd = (HWND *)lParam;    DWORD dwMagicNumber = GetWindowLong(hWnd, DWL_USER);    if(dwMagicNumber == RNAAPP_MAGIC_NUM) {       *hRnaWnd = hWnd;       return FALSE;    }    return TRUE; } BOOL FindRemoteDialer() {    HWND hWndRNAWnd = NULL;    EnumWindows(RNAEnumFunc, (LPARAM)&hWndRNAWnd);    if(!hWndRNAWnd)       return FALSE;    // Send a message here to the dialer    return TRUE; } 

Now that you have the handle to the rnaapp.exe dialer, you can send it an RNA_RASCMD message:

 SendMessage(hWnd, RNA_RASCMD, wParam, lParam); 

Table 6.6 describes the three messages that you can send to the rnaapp.exe dialer window.

Table 6.6. Messages sent by rnaapp.exe

wParam	IParam	#define value	Description
RNA_ADDREF	0	1	Add a reference to the current active connection.
RNA_DELREF	0	2	Remove a reference to the active connection. When the reference count hits 0, rnaapp.exe will disconnect the connection.
RNA_GETINFO	Window handle	3	Send a WM_NETCONNECT message to the window handle that is specified in the lParam value.

In other words, if you need to disconnect from a RAS session using the rnaapp.exe dialer, you only need to send it an RNA_DELREF message.

This function is also useful when you want to obtain information about a different dial-up connection that another application has established. Using the RNA_GETINFO message, you could query the dialer for the connection information as follows:

 #define RNA_GETINFO 3 // Once you have found the RNAAPP.exe window handle, you // can send it a message SendMessage(hWndRNAWnd, RNA_RASCMD, (WPARAM)hWnd,   RNA_GETINFO);