Pocket PC and Windows Networking

Using the Pocket PC network redirector, you can enable your device to browse, add, cancel, and enumerate network connections anywhere on a Windows network. Accessing an actual network resource can be done in two different ways on the Pocket PC. The first is by mapping the network resource to a name that is placed in the \Network folder, which will appear to the file system as a local folder. The other method is by directly calling the resource by using its Universal Naming Convention (UNC) name.

Network Names

To successfully use a Windows Network resource, you first must make sure that your device has a unique name on the network. This is typically done by configuring it in the network control panel applet, or by setting the registry value HKEY_LOCAL_MACHINE\Ident\Name to a unique device name. If you attempt to access a network resource without a valid name, the network redirector will fail and return an error. Be aware that when a network connection is accessed for the first time, Pocket PC will attempt to register the name on the network. This means that the first operation on a network can take up to 15 seconds longer while it completes the initial registration.

Device network names can be up to 15 characters long, and may contain any characters from A to Z, 0 through 9, or a hyphen. Invalid characters, such as the # or * will not register correctly on the network.

Pocket PC also uses the network login information that you have entered in the control panel for authentication when accessing a network resource. If you connected to the network via a RAS connection instead of a network card, whatever username and password you used for the dial-up connection will be sent when accessing a resource on that network. If an error occurs, a dialog box will prompt you for information.

Universal Naming Convention

One method for accessing network resources is to call any function that requires a filename and path, such as CreateFile() or CopyFile(). Instead of passing in a file path that is located in the Pocket PC object store, you can instead use a UNC path.

A UNC path is a standard, case-insensitive naming convention that contains the server name, the share name, and a filename (much like a URL does for an HTTP resource). Here is an example of a UNC path:

 \\MyServer\MyShare\SomeDirectory\SomeFile.txt 

A UNC path always begins with double backslashes and is followed by the server name. In this example, the server name for the resource is MyServer, and is followed by the network share name MyShare. In this example, we are explicitly looking at the file SomeFile.txt located in a directory named SomeDirectory.

The \Network Folder

The other method for using a network resource is to directly map it to a local path that will be placed underneath the \Network folder. Because Pocket PC does not support drive letters like the desktop, you can only make a network resource appear as a directory in the local object store.

For example, suppose you have a server named \\Copper that has a directory that is shared with the name StacyH. If you mapped the share to the device with a local name BrettH, you could then access all the files and directories in the \\Copper\StacyH share by accessing the local path \Network\BrettH.

TIP:

By default, Pocket PC does not expose network drive mappings in the \Network folder to the common system dialogs (such as GetSaveFileName()) or the local folder browsers. To expose your network mappings to the local system, just set the DWORD value RegisterFSRoot, which is located under the HKEY_LOCAL_MACHINE\Comm\Redir key, to a nonzero value. When the device is reset, the \Network folder will be visible.


Once a resource has been mapped to the local device, you can then use any of the standard file system functions, such as CreateFile() and WriteFile(), to work with files and directories located in the share. However, be aware that the only operations you can perform at the root level of the \Network folder are adding connections using the WNetAddConnection3() function, removing connections with the WNetCancelConnection2() function, and enumerating share names using FindFirstFile() and FindNextFile(). Because \Network contains only virtual folders, it is not considered a real object in the file system, and standard operations other than enumeration will fail.

Handling Network Errors

If an error occurs when using any of the network redirector functions, use the standard GetLastError() function to get details about the failure. Because only one network is supported, the desktop-based WNetGetLastError() function is not implemented on Pocket PC devices.

For example, if you wanted to get further information about an error that occurred when querying for the local device name, you could use the following:

 if(dwReturn != ERROR_SUCCESS) {    // The function has failed, get standard error code    DWORD dwError = GetLastError();    // Let's get the full error text as well    LPVOID lpErrorText = NULL;    FormatMessage(FORMAT_MESSAGE_ALLOCATE_BUFFER|       FORMAT_MESSAGE_FROM_SYSTEM|FORMAT_MESSAGE_IGNORE_INSERTS,       NULL, dwError, 0, (LPTSTR) &lpErrorText, 0, NULL);    // Format and pop a message box with the error number and    // message    TCHAR tchErrorString[1024] = TEXT("\0");    wsprintf(tchErrorString, TEXT("Error Number: %d\r\nError       Message: %s"), dwError, lpErrorText);    MessageBox(NULL, tchErrorString, TEXT("Network Error"),       MB_OK|MB_ICONERROR);    return FALSE; } 

Typically, when calling GetLastError() for a WNet error, one of the values described in Table 4.1 will be returned.

Table 4.1. Network Errors Returned by GetLastError()

Error Code

Description

ERROR_ACCESS_DENIED

Access is denied to the network resource.

ERROR_ALREADY_ASSIGNED

The local name has already been connected.

ERROR_BAD_DEVICE

The local name is invalid.

ERROR_BAD_NET_NAME

The remote name is not valid or cannot be found.

ERROR_BUSY

The network was busy and could not connect to the resource.

ERROR_CANCELLED

The connection attempt was cancelled.

ERROR_DEVICE_ALREADY_REMEMBERED

The local name has already been defined for another resource.

ERROR_INVALID_PASSWORD

The network password is invalid.

ERROR_NO_NET_OR_BAD_PATH

The network could not be started.

ERROR_NO_NETWORK

There is no network installed or available.

Differences between Windows and Pocket PC Network APIs

Besides the fact that Pocket PC supports only a subset of the WNet APIs, note a few other minor differences compared to desktop implementations:

  • Pocket PC has no support for drive letters. Network resources should be mapped to local folders under the \Network directory, or can be accessed directly via UNC.

  • No NetBIOS function support. Although parts of NetBIOS are present in CIFS, there is no direct access to NetBIOS outside of the WNet APIs.

  • The only network supported is the Microsoft Windows Network.

  • Connections are not restored over a device warm reboot. The only way to reestablish a connection over a reboot is to mark the connection as persistent.

  • Pocket PC does not support network mail slots or named pipes.

  • The WNetGetLastError() function is not supported. Use the GetLastError() function to retrieve network error messages.

  • There is no concept of network context on Pocket PC.



Pocket PC Network Programming
Pocket PC Network Programming
ISBN: 0321133528
EAN: 2147483647
Year: 2005
Pages: 90

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net