Mapping Network Resources

As previously mentioned, you cannot directly add or remove folders in the \Network folder by using traditional file system functions such as CreateFile(). This is because the \Network folder is really a virtual representation of mapped network resources that have been mounted on the device. In order to connect or disconnect a network resource to this folder, you must use the WNet network APIs.

Connecting to the Network

To map a network resource to your Pocket PC device, you can use the WNetAddConnection3() function, which is defined as follows:

 DWORD WNetAddConnection3(HWND hwndOwner, LPNETRESOURCE    lpNetResource, LPCWSTR lpPassword, LPCWSTR lpUserName,    DWORD dwFlags); 

The first time you call into this function, the system attempts to validate the device name on the network, so it might take a few seconds to return (in fact, it can take up to 15 seconds).

The first parameter that WNetAddConnection3() expects is a handle to a window that the redirector can use as the parent for any dialog boxes that it might need to display. It can be set to a NULL value if you don't need to have an owner window. The next parameter, lpNetResource, is a pointer to a NETRESOURCE structure that defines some information about the resource to which you are trying to connect. This is followed by two null-terminated strings: lpPassword and lpUserName, which are used for authentication on the resource. If these values are set to NULL, Pocket PC will try to use the default username and password that were configured in the network control panel. If no defaults have been defined, a dialog box requesting the authentication details will be displayed. Lastly, the dwFlags parameter can be set to either 0 or CONNECT_UPDATE_PROFILE. Using the CONNECT_UPDATE_PROFILE flag will mark the new connection as persistent, and the device will store the network mapping in the registry and automatically attempt to reconnect it if the connection is lost. Note that Pocket PC cannot make a connection persistent if the connection is invalid or does not have a name.

The NETRESOURCE structure you pass in to the lpNetResource parameters is used for both the enumeration and connection of a network resource, and is defined as follows:

 typedef struct _NETRESOURCE {    DWORD dwScope;    DWORD dwType;    DWORD dwDisplayType;    DWORD dwUsage;    LPWSTR lpLocalName;    LPWSTR lpRemoteName;    LPWSTR lpComment;    LPWSTR lpProvider; } NETRESOURCE, *LPNETRESOURCE; 

The first three fields (dwScope, dwType, and dwDisplayType) are used when enumerating network resources only. When you use the NETRESOURCE structure with the WNetAddConnection3() function, you can set them all to 0.

The first field, dwScope, defines the scope of the network resource, and can be one of the flags in Table 4.2.

Table 4.2. Network Resource Scope Flags

Flag	Description
RESOURCE_CONNECTED	Return the currently connected resources
RESOURCE_GLOBALNET	Return all resources on the network
RESOURCE_REMEMBERED	Return network connections that have been marked as persistent

The next field, dwType, can be one of the network resource types listed in Table 4.3.

Table 4.3. Network Resource Types

Flag	Description
RESOURCETYPE_ANY	Any network resource
RESOURCETYPE_DISK	Drive and disk resource
RESOURCETYPE_PRINT	Printer resources

The dwDisplayType field can be used to obtain more specific information about the resource. It can be one of the types in Table 4.4.

Table 4.4. Network Resource Display Types

Flag	Description
RESOURCEDISPLAYTYPE_DOMAIN	The resource is a domain controller.
RESOURCEDISPLAYTYPE_GENERIC	The resource type does not matter.
RESOURCEDISPLAYTYPE_SERVER	The resource is a server.
RESOURCEDISPLAYTYPE_SHARE	The resource is a drive share.

The next field, dwUsage, is used only if the dwScope member is set to RESOURCE_GLOBALNET; otherwise, this should be set to NULL. This field further defines the scope during enumeration (see Table 4.5).

Table 4.5. Network Resource Usage Types

Flag	Description
RESOURCEUSAGE_CONNECTABLE	The resource is connectable, such as a drive share or printer.
RESOURCEUSAGE_CONTAINER	The resource is a container, such as a server or domain.

The lpLocalName field is a pointer to a null-terminated string that represents the local name of the connection. If you set this to NULL, a connection will still be established, but there will be no local name in the \Network folder. This is followed by the lpRemoteName field, which points to a null-terminated string that is the UNC name of the remote resource with which you want to connect. Be aware that the local name is limited to 99 characters, and the remote name is limited to 64.

Next is the lpComment field, which is an optional null-terminated string that contains information provided by some servers. The last field, lpProvider, should be set to NULL, as it is currently unused.

After calling WNetAddConnection3(), you will be returned an ERROR_SUCCESS value if the connection was successfully established and mapped to the device. Otherwise, you can use the GetLastError() function or look at the return value to determine what the error message is.

For example, if you wanted to connect to a network share named Backups that was located on the server \\LONDO, you would do the following:

 NETRESOURCE netResource; memset(&netResource, 0, sizeof(NETRESOURCE)); netResource.lpLocalName = TEXT("NetBackup"); netResource.lpRemoteName = TEXT("\\\\LONDO\\Backups"); DWORD dwReturn = WNetAddConnection3(NULL, &netResource,    NULL, NULL, CONNECT_UPDATE_PROFILE); 

Figure 4.3 shows the files contained in the new network mapping, which has been added to the \Network folder on the device.

Figure 4.3. The \Network folder

Disconnecting a Network Connection

Once you have established a network mapping and are finished using it, you can remove it as follows:

 DWORD WNetCancelConnection2(LPCWSTR lpName, DWORD dwFlags,   BOOL fForce); 

The first parameter points to a null-terminated string that contains either the local or the remote resource name from which you want to disconnect. This is followed by dwFlags, which can be set to either 0 or CONNECT_UPDATE_PROFILE. If you use the CONNECT_UPDATE_PROFILE flag, the device will no longer consider it a persistent connection. The last parameter, fForce, should be set to TRUE if you want the connection disconnect to occur even if there are open files or jobs on the connection. If it is set to FALSE, it will fail if a resource is in use.

If the WNetCancelConnection2() function returns successfully, you will receive an ERROR_SUCCESS result. Otherwise, you can use the GetLastError() function to find out what went wrong.

To disconnect from the share created in the last example, you could disconnect with a function that looks like the following:

 DWORD dwReturn = WNetCancelConnection2(TEXT("NetBackup"),    CONNECT_UPDATE_PROFILE, TRUE); 

Using the Network Connections Dialog Box

Another way to add and remove network connections is to use the built-in network connection dialogs. Users are presented with a dialog box that asks them for the remote resource location as well as the local name. To add a connection, you can call the WNetConnectionDialog1() function, which is defined as follows:

 DWORD WNetConnectionDialog1(LPCONNECTDLGSTRUCT   lpConnDlgStruct); 

The function takes a single parameter, which is a pointer to a CONNECTDLGSTRUCT structure. This structure is prototyped as shown here:

 typedef struct _CONNECTDLGSTRUCT{    DWORD cbStructure;    HWND hwndOwner;    LPNETRESOURCE lpConnRes;    DWORD dwFlags;    DWORD dwDevNum; } CONNECTDLGSTRUCT, FAR *LPCONNECTDLGSTRUCT; 

The first field, cbStructure, should be set to the size, in bytes, of the structure. Next, hwndOwner should be set to the handle of the window that owns the dialog. The lpConnRes field should point to a NETRESOURCE structure that contains information about the remote resource with which you want to connect. If you want to have the dialog automatically insert a remote name, you can fill in the lpRemoteName field of the NETRESOURCE structure; otherwise, set it to NULL. The rest of the NETRESOURCE structure can be set to 0.

If you have set the lpRemoteName field of the NETRESOURCE structure to a remote name, and you want this value to be read only in the dialog, you can set the dwFlags parameter to CONNDLG_RO_PATH; otherwise, set it to 0.

The last field, dwDevNum, is not used and should be set to 0.

When the dialog box closes, it will return an ERROR_SUCCESS value if the connection was established. If the user cancelled the dialog, you will be returned a value of 0xFFFFFFFF; otherwise, you can use the GetLastError() function to find out what went wrong.

Figure 4.4 shows the dialog box that is displayed with the following example:

Figure 4.4. The WNetConnectionDialog1 dialog box

 CONNECTDLGSTRUCT connectDlg; NETRESOURCE netResource; memset(&connectDlg, 0, sizeof(CONNECTDLGSTRUCT)); memset(&netResource, 0, sizeof(NETRESOURCE)); connectDlg.cbStructure = sizeof(CONNECTDLGSTRUCT); connectDlg.lpConnRes = &netResource; DWORD dwReturn = WNetConnectionDialog1(&connectDlg); 

Two different dialog boxes can be used to disconnect a network mapped resource. The first function, WNetDisconnectDialog(), displays a dialog box that lists all the currently connected and persistent connections, and allows the user to select which one to remove. The function looks like the following:

 DWORD WNetDisconnectDialog(HWND hwnd, DWORD dwType); 

The first parameter, hwnd, is the handle to the window that owns the dialog. The dwType parameter is not used and should be set to 0.

The other function to disconnect a mapped network resource is WNetDisconnectDialog1(). This function will attempt to disconnect the resources specified by the structure you pass in. If there is any current activity, such as an open file, on the network, the user is prompted for confirmation. The function looks like the following:

 DWORD WNetDisconnectDialog1(LPDISCDLGSTRUCT   lpConnDlgStruct); 

The only parameter that is passed in is a pointer to a DISCDLGSTRUCT structure, which is prototyped as follows:

 typedef struct _DISCDLGSTRUCTW{    DWORD cbStructure;    HWND hwndOwner;    LPWSTR lpLocalName;    LPWSTR lpRemoteName;    DWORD dwFlags; } DISCDLGSTRUCTW, FAR *LPDISCDLGSTRUCTW; 

The cbStructure field should contain the size of the structure, in bytes. This is followed by hwndOwner, which is the handle to the window that owns the dialog (if it pops up). The lpLocalName field points to a null-terminated string that specifies the local name to disconnect, and is followed by lpRemoteName. If the lpLocalName field contains a value, you can then set lpRemoteName to NULL; otherwise, it should point to a string that specifies the remote resource name. The last field, dwFlags, can be set to 0, or you can use the DISC_NO_FORCE flag if you do not want the dialog to appear.

To disconnect a network mapping using the WNetDisconnectDialog1() function, you can do the following:

 DISCDLGSTRUCT disconnectDlg; memset(&disconnectDlg, 0, sizeof(DISCDLGSTRUCT)); disconnectDlg.cbStructure = sizeof(DISCDLGSTRUCT); disconnectDlg.lpLocalName = TEXT("NetBackup"); DWORD dwReturn = WNetDisconnectDialog1(&disconnectDlg);