Configuring Client Information and Connections on a Thin Client (Windows Embedded CE 6.0)
1/5/2010
When it connects to a server, the shell uses registry settings to determine the list of registered clients. Therefore, you can configure each client in the registry.
Before it can establish a connection to a server, the Windows Thin Client Shell must have the following information for each client that it manages:
- The shell requires the Description value, or a display name to show when it creates a new connection.
- The shell requires the Type value, or an eight-character description to display in List View.
- The shell requires information about how to create the connection.
Information about how to configure the information in the previous three bullet points is provided in the rest of this topic.
Registered Client Registry Root Key
In the HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration registry root key, a registry key with a unique name must exist for each client. Each of these registry keys contains information about a specific client and about each connection that has been defined for it.
The shell uses information in the registry root key, HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration, to determine registered clients. The registry root key contains client information registry keys and an entry. The following table shows the named value in the registry root key.
| Value | Description |
|---|---|
DefaultClient: REG_SZ |
This value specifies the registered client key to designate as the default client when a user creates a new connection. For example, to set the default client to RDP, this value would be RDP. No default setting is provided. Do not confuse this key name with the Type entry of a registered client. |
The following are examples of client information registry keys in the registry key root.
[HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration\RDP]
[HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration\VT100]
[HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration\3270]
Client Information Registry Key
The HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration\<Your client name> registry key contains information about a specific client. If the entry for a specific client is incomplete or invalid, the shell ignores that client, and a user cannot create connections to a server that are based on that client. If the shell encounters a client that is configured incorrectly, no error message is displayed.
The following table shows the named values under a client information registry key.
| Value | Description |
|---|---|
Description: REG_SZ |
This value specifies the display name for the client. For example, the display name for Microsoft RDP may be "Microsoft Remote Desktop Client." When it creates connections, the shell presents a list of emulators and their descriptions. No default setting is provided. This value is required. |
Type: REG_SZ |
This value specifies the short eight-character description for the client. This information is displayed in the Type column of the Windows Thin Client Shell user interface (UI). This value does not have to match the name in the client information registry key. For example, two VT100 clients might have the client key names of VT100a and VT100b. However, the Type value can be No default setting is provided. This value is required. |
NewExe: REG_SZ |
This value specifies the helper application to call when a new connection is created. Each client must have a helper application for creating new connections. The helper application for creating new connections must be a wizard. No default setting is provided. This value is required. |
NewCmdLineArgs: REG_SZ |
This value specifies the command-line arguments to pass to the helper application that is specified by the NewExe value. The command-line arguments can specify the required function. This is useful if you want to provide a helper application to create, edit, and delete connections. No default setting is provided. This value is optional. |
The following code example shows the client information registry key that is required for RDP, and its entries.
[HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration\RDP]
"Description"="Microsoft Remote Desktop Client"
"Type"="RDP"
"NewExe"="Tsconwiz.exe"
"NewCmdLineArgs"=""
Connections Registry Key
The Windows Thin Client Shell also requires information about how to start, edit and delete each connection that it manages. Information about connections is specified in the HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration\Your client name\Connections registry key.
Each specific connection is represented as a HKEY_LOCAL_MACHINE\Software\Microsoft\WBT\Clients\Registration\Your client name\Connections\<Your connection name> subkey in the Connections registry key.
.gif "Ee480797.collapse(en-US,WinEmbedded.60).gif")
Create the Connections Registry Key
You must create a Connections registry key in each client information registry key. In the Connections key, each subkey represents a connection entry. The entries in each connection-entry subkey must store all values that are required by the shell.
During operation, each client must also maintain connection information in the Connection key. Be aware that if connection entries for a client are changed, you do not have to reset the system.
Shell and Connections Registry Keys
The shell enumerates through items in the Connections key to determine the list of connections that are defined for each client.
The shell also updates connection information for a client after an add operation, an edit operation, or a delete operation is performed by a user.
Named Values Entries
Information in the form of connection-entry named values must be added in the connection-entry subkey that is defined for each connection.
If the registry values for a connection entry are incomplete or not valid, the shell will ignore the connection and will not add the connection to the list. However, an error message does not display to the user if the shell encounters a connection configured incorrectly.
The following table shows the named values for each connection entry in the Connections key. These values are required.
| Value | Description |
|---|---|
Description: REG_SZ |
This value specifies the display name for the connection. The Windows Thin Client Shell displays connections by names that are obtained from this value. No default setting is provided. |
StartExe: REG_SZ |
This value specifies the executable file to start when a new connection is created. No default setting is provided. |
StartCmdLineArgs: REG_SZ |
This value specifies the command-line arguments to pass to the executable that is specified by the StartExe value. No default setting is provided. |
PropertiesExe: REG_SZ |
This value specifies the helper application to call when modifying the properties or editing an existing connection. No default setting is provided. |
PropertiesCmdLineArgs: REG_SZ |
This value specifies the command-line arguments to pass to the helper application that is specified by the PropertiesExe value. No default setting is provided. |
DeleteExe: REG_SZ |
This value specifies the helper application to call when it deletes a connection. No default setting is provided. |
DeleteCmdLineArgs: REG_SZ |
This value specifies the command-line arguments to pass to the helper application that is specified by the DeleteExe value. No default setting is provided. |
To configure client information in the registry
In Platform Builder, on the File menu, select Open, and then select File.
Set Files of Type to All Files.
Navigate to %_WINCEROOT%\PUBLIC\RDP\OAK\FILES.
Select rdp.reg file and click Open.
In rdp.reg, add a registry root key.
In the root key, add a Client Information registry key, and give it a unique name.
For the Client Information registry key, add the named values for Description, Type, NewExe, and optionally for NewCmdLineArgs.
In the Client Information registry key, add a Connections registry key.
For the Connections registry key, add the named values for Description, StartExe, StartCmdLineArgs, PropertiesExe, PropertiesCmdLineArgs, DeleteExe, and DeleteCmdLineArgs.
On the File menu, select Save rdp.reg.
During the build process, makeimg.exe processes all .reg files in the build directories to create a single file, Reginit.ini. Reginit.ini forms the basis for the system registry.