Microsoft Windows CE 3.0 Web Server
Summary: This document is intended for Web page developers who use the Microsoft® Visual Basic®, Scripting Edition (VBScript) programming language or Microsoft® JScript® development software with Active Server Pages (ASP) to implement dynamic, interactive Web server applications. The Web server applications run on a Windows CE–based computer, and the server application sends Hypertext Markup Language (HTML) pages to a requesting browser. (30 printed pages)
Requirements for the Computer that Runs the Web Server
Web Server Details
Base Registry Keys
Starting and Stopping the Web Server
Virtual Path Settings
HTTP Authentication and Permissions
Debugging ISAPI Extensions and Filters
Tips for Converting Existing CGI Scripts to ISAPI Extensions
Web Server Components and Dependencies
Active Server Pages for Windows CE
Differences Between Header Files
Windows CE ASP Components and Dependencies
For More Information
Microsoft® Windows® CE version 3.0 is targeted to be the embedded operating system (OS) for all sorts of devices and systems—Handheld PCs, Palm-size PCs, telephones, vending machines, factory automation, home-security systems, and so on. A Hypertext Transfer Protocol (HTTP) server (or Web server) that is installed on any of these devices can be monitored, configured, and controlled remotely. The Web server provides a highly useful service on network printers, scanners, and other shared equipment. A Web server on these systems can facilitate the use of the Internet for communication with these devices. Users must have an Internet connection and a browser only.
Note The Windows CE Web server does not provide proxy services.
This document is intended for Web page developers who use the Microsoft® Visual Basic®, Scripting Edition (VBScript) programming language or Microsoft® JScript® development software with Active Server Pages (ASP) to implement dynamic, interactive Web server applications. The Web server applications run on a Windows CE–based computer, and the server application sends Hypertext Markup Language (HTML) pages to a requesting browser.
The following list describes the requirements for the computer that runs the Web server and its associated ASP-page interpreter:
- The computer can be any device that can run the Mincomm configuration of the Microsoft Windows CE OS, version 3.0.
- For communications purposes, the computer requires a TCP/IP network interface.
- The computer requires approximately 40 kilobytes (KB) of RAM for the Web server.
- The computer requires approximately 45 KB of RAM for the ASP-page interpreter.
The Web server, which is also referred to as Httpd, provides a convenient way of retrieving files and offers extensive scripting options for creating dynamic Web content for a device that runs Windows CE.
The Web server implements a subset of the HTTP/1.0 protocol and allows connections to be maintained by checking an idle network to verify that the network is active. All configurations provide file downloads, multiple virtual paths, and multiple simultaneous connections.
Figure 1. The client/server relationship
The Web server can include additional components that add support for authentication, Internet Server Application Program Interface (ISAPI) extensions, ISAPI filters, or ASP.
Figure 2. The client/server relationship with added components
The Httpd.dll dynamic-link library (DLL) contains the Web server. At startup, the Device.exe file loads the Web server.
The protected registry contains named values for Httpd configuration. The registry key name is HKEY_LOCAL_MACHINE\COMM\HTTPD. If you change any value, you must stop the Web server and then restart it to enable the new settings.
Note HKEY_LOCAL_MACHINE\COMM\HTTPD is a protected (access-restricted) registry key on some devices that run Windows CE 3.0. Refer to the Microsoft Windows CE Platform Builder version 3.0 documentation for more information about the protected registry.
The following table shows the named values for the protected registry Httpd-configuration parameters.
|AdminUsers||List of user names, separated by semicolons. A user who has gained user access must be listed in this value to gain Administrator access. For more information, see "HTTP Authentication and Permissions."|
|Basic||If this value is set to nonzero, Web server uses basic authentication for client connections. For more information, see "HTTP Authentication and Permissions."|
|DefaultPage||List of DLL names, separated by commas, that specify the filters to use. For more information, see "ISAPI Filters."|
|DefaultPage||List of page names, separated by semicolons, that specify file names that are interpreted by the Web server to be used as default pages. When the Web server browses a directory, the Web server traverses this list in search of a file of the same name in the directory. If the file is present, this file is sent to the client. If no matching file exists, the Web server either sends a directory listing or returns an error. See also DirBrowse in this table. If more than one file name is matched, the Web server uses the first matching file name. For more information, see "ISAPI Filters."|
|DirBrowse||If this value is set to nonzero, directory browsing is allowed.|
|Filter DLLs||List of DLL names, separated by commas, that specify the filters to be used. If no value is present, Default.htm and Index.htm are used as the default pages. For more information, see "ISAPI Filters."|
|IsEnabled||If this value is set to nonzero, the Web server is enabled; otherwise, this value is set to zero. For more information, see "Starting and Stopping the Web Server."|
|LogFileDirectory||Name of the directory in which to put logging files. If the name is not set, logging files are placed in the \Windows\www directory. If the directory that is specified is inaccessible, no logging is performed.|
|MaxConnections||Maximum number of HTTP requests that the Web server will handle simultaneously. If this value is not set, the default is 10. After the maximum number of connections are established, additional client requests will be sent a "503—Server Too Busy" message.|
|MaxLogSize||Maximum size that a log file can become before it is rolled over. If this value is not set, or if it is set to zero, no logging is performed.|
|NTLM||If this value is set to nonzero, the Web server uses NTLM authentication for client browser connections. Also, if this value is enabled, failure of Basic authentication forces NTLM authentication. For more information, see "HTTP Authentication and Permissions."|
|Port||Port that is used to receive HTTP connections. The default port setting is 80. Do not change the port setting.|
|PostReadSize||Maximum number of bytes that the Web server reads when the server receives POST data. To read more data, you either must use a raw data filter or call the ReadClient function in an ISAPI extension. The default value is 48 KB.|
If you make changes to the Web server registry settings, it is necessary to stop the Web server and restart it to make the changes take effect.
To stop, start, or refresh the Web server programmatically, use the CreateProcess function with "httpdsvc" as the lpApplicationName parameter and either "-stop", "-start", or "-refresh", respectively, as the lpCommandLine parameter.
Note For compatibility with future releases of the Windows CE, we recommend against starting or stopping the Web server directly through its exported functions.
The IsEnabled registry value is checked only when the Web server is starting. If the registry value is set to zero, the Web server does not start. Note that changing this value to zero while the Web server is running has no effect. You also must stop the Web server to make it stop accepting connections.
When logging is enabled, the Web server appends relevant data to the Current-httpd.log file after each request. The Current-httpd.log file is located in the directory that was specified by the LogFileDirectory setting. Each log entry contains the date and time of the request, the IP address of the client, the method that was used, the Uniform Resource Locator (URL) that was requested, the response code that was sent back, and, optionally, data that was appended by ISAPI extensions, ISAPI filters, or the ASP page.
When the size of the Current-httpd.log file approaches the size that is specified in the MaxLogSize registry value, the logging process renames the file to Previous-httpd.log and creates a new file that is named Current-httpd.log. If a file that is named Previous-httpd.log existed before this rollover occurred, that file is overwritten.
Note that if you set the logging to an invalid directory, but do not set the MaxLogSize registry value to zero, it can take 15 additional seconds for the Web server to begin accepting connections. If the Web server cannot create the log file, it does not abandon logging immediately, but attempts to reopen the log file once every second for 15 seconds. This functionality has been added because it is possible that the log file is being set up on a flash device that was not initialized by the time that the Web server starts up during the startup sequence.
Therefore, if you do not want to perform logging, it is recommended that you set the MaxLogSize registry value to zero to avoid this delay.
Virtual paths specify a mapping between the virtual path in a URL and the physical path on the device. For example, you can allow a client browser to connect to the URL http://www.computername.com/www/sample.htm while retrieving the file that is named Sample.htm from the \Windows\www\data directory. To accomplish this, specify a mapping between the /www virtual path and the \Windows\www\data physical path.
At least one virtual path must be created before the Web server starts. If no valid virtual path mappings have been specified, the Web server cannot perform any mappings, and it sends the "404—Object not found" status code for all requests.
If a Web client browser requests a directory, the Web server searches for default pages in the corresponding physical directory, following the order in which they are listed in the registry. If no pages are found and the DirBrowse registry value is nonzero, the Web server sends a list of links to all of the files and directories in the requested directory. If no default pages are found and the DirBrowse registry value is zero, the Web server sends the "403—Forbidden" status code.
HKEY_LOCAL_MACHINE\Comm\HTTPD\VROOTS is the protected registry key of the virtual path. This registry key contains one or more subkeys, one for each virtual path. Each subkey is named for the virtual path that it specifies. In the previous example, the registry should contain a registry key that is named HKEY_LOCAL_MACHINE\Comm\HTTPD\VROOTS\www.
Each subkey contains values that specify the physical path, as well as the permission levels, authorization level, and user list that are required for that virtual path. The following table shows the values for the registry key of each virtual path.
|(Default)||Specifies the physical directory that is mapped to the virtual directory.|
|A||Specifies the authentication level that a user must have to access this directory. If no value is set, is used as the default value. For more information, see HTTP Authentication and Permissions.|
|P||Specifies the access permissions that are associated with the directory. If no value is set, the default value that is used is either HSE_FLAGS_URL_READ, HSE_FLAGS_URL_EXECUTE, or HSE_FLAGS_URL_SCRIPT. For more information, see "HTTP Authentication and Permissions."|
|UserList||Allows authenticated users, groups, or both to be set on a per-virtual-root basis.|
The following code example shows a subkey that:
- Sets the \Windows\www directory as the default directory.
- Sets the authentication level to 1, which requires a valid user ID and password.
- Grants read, write, and execute permissions to valid users, by default, without the P option.
- Identifies a list of users, groups, or both who are allowed or not allowed to access the virtual directory.
[HKEY_LOCAL_MACHINE\Comm\HTTPD\VROOTS\www] "(default)"="\windows\www" "A"=1 "UserList" = "GladysL; -AnnD; @Group1"
Authentication, permissions, and user lists are described in the following sections.
To provide security, each virtual directory that is mapped by the Web server has associated authentication values and permission values that correspond, respectively, to the A and P values that are identified in the registry key for that virtual directory.
The authentication and permissions checks that are performed by the Web server should not be confused with a secure connection. The Web server does not support any form of encrypted transmission, such as Secure Sockets Layer (SSL). Therefore, all data (with the exception of Microsoft Windows NT® Challenge/Response (NTLM) passwords) that is sent between the client browser and the server is in plain text. Note that basic authentication is vulnerable to packet sniffing, so care should be taken when sending sensitive information to and from the server across a public or insecure network such as the Internet.
The authentication level for a virtual directory can be set to 0, 1, or 2. The following table describes each value.
|A=0||Anonymous users can access the virtual directory, and may have permission to read or execute scripts, depending on the P value for the virtual directory. By using A=0, anyone who can access the Web server can access files in that virtual directory.|
|A=1||A valid user ID and password are required to access a virtual directory with authentication that is set to A=1.|
|A=2||Virtual directories with authentication that is set to A=2 require the browser user to have Administrator privileges. A valid user ID and password are required to gain access to this virtual directory.|
The first attempt by a user to access a virtual directory that has an authentication value of 1 or 2 results in a "401—Unauthorized" status code that is sent back to the browser. The forms of acceptable authentication are sent to the browser in the Httpd header fields of the message. The authentication types that are sent depend on the values that are set for BASIC and NTLM under the HKEY_LOCAL_MACHINE\COMM\HTTPD protected registry key. By setting both BASIC and NTLM values to 1, the Web server sends both authentication types in response to the same request, allowing the client browser to select the authentication method. A script also can include an authentication scheme by setting the "WWW-Authenticate" field and the desired value in the Httpd header fields.
If Basic authentication is used, the client browser sends the user ID and password over the network in plain text (not encrypted). The Web server then checks the password against the network password of the client browser on that local computer. (The password can be set in Control Panel). If this fails, the Web server attempts to authenticate the user with NTLM, by using the same user name and password, as well as the domain controller, if one exists. This authentication process is transparent to the client browser.
If NTLM authentication is used, the Web server and the client browser negotiate a means through which the client browser can send the password across the network in an encrypted format. The Web server acts as the intermediary in this case, sending the requests between the authenticating domain controller and the client browser. The Web server determines the domain controller to use for pass-through authentication, based on the HKEY_LOCAL_MACHINE\COMM\Redir\DefaultDomain protected registry key. The Web server never has access to the plain-text password of the client when it communicates with the client browser by using NTLM.
Note The Web server supports only Basic authentication and NTLM authentication; SSL authentication is not supported.
If the user ID and password are not valid, the Web server sends another "401—Unauthorized" status code to the browser.
The following steps are required to gain access to a Web page that requires authentication (A>0):
- The user must be authenticated for the given virtual path by using NTLM authentication or BASIC authentication, as described above. If this step fails, the user is denied access to the page.
- If NTLM authentication is used, the Web server requests information regarding the groups in which the user has membership. If this step fails, the user is assumed not to have membership in any group.
- If 0<a<3 and the name of the authenticated user (or a group that contains the user) is listed in the HKEY_LOCAL_MACHINE\Comm\HTTPD\AdminUsers registry key, the user is granted access to the page as an Administrator.
- If A="1" and the name of the authenticated user (or a group that contains the user) is listed in the HKEY_LOCAL_MACHINECOMPUTER\Comm\HTTPD\Vroots\[vroot name]\UserList registry key, the user is granted access to the Web page.
Note At this point, if the authentication level is set to 2, but no users are listed in the administrator list, the user is granted access as an Administrator. This is done for ease of initial setup. However, be aware that the AdminUsers list on the Web server computer should be configured appropriately and as soon as possible, or else the first user to access the site, and who also passes the first step, will be given Administrator privileges. As a result, users could use the administration page to lock themselves in as the Administrator.
- If the above conditions fail, the user is denied access to the Web page.
The Administrative group check is performed only when the client browser uses NTLM authentication. The user-name check is performed for both types of authentication.
The authentication registry keys support individual users and groups, as well as the ability to exclude specific users and groups. For more information, see "User Lists."
The permissions registry value (P) in each virtual path specifies the permissions that the client browser has to the files that are under the virtual path, assuming that the client is authorized at the required level for the particular virtual path. P is a DWORD that is set to a bitwise-OR combination of the HSE_FLAGS_URL flags, which are defined in the Httpext.h file. The Web server only uses the HSE_FLAGS_URL_READ, HSE_FLAGS_URL_EXECUTE, and HSE_FLAGS_URL_SCRIPT flags. By default, read, execute, and script-execution permissions are granted; the Web server ignores HSE_FLAGS_URL_WRITE flags.
Within the Httpext.h file, the HSE_FLAGS_URL flags are defined in the following way:
#define HSE_URL_FLAGS_READ 0x00000001 // Allow for Read #define HSE_URL_FLAGS_EXECUTE 0x00000004 // Allow for Execute #define HSE_URL_FLAGS_SCRIPT 0x00000200 // Allow for Script execution
To create a virtual root that allows only read permission, set P=1 (no ASP or ISAPI DLLs will run from that virtual root).
To set a virtual root that has execute and script permissions, but no read permission, set P=516 (bitwise or 0x00000004 with 0x00000200 = 0x204 = 516).
The virtual path must have either the HSE_FLAGS_URL_EXECUTE flag or the HSE_FLAGS_URL_SCRIPT flag set for ASP pages in the directory to be interpreted; otherwise, the Web server returns the "403—Forbidden" status code to the client browser.
The Web server supports ISAPI extensions. To be run by the Web server, the ISAPI extension must be in a directory that has the HSE_FLAGS_URL_EXECUTE flag set. If an ISAPI DLL is in a directory that has HSE_FLAGS_URL_READ permissions, but does not have the HSE_FLAGS_URL_EXECUTE flag set, the DLL itself is downloaded to the client browser, and not executed on the server.
It is possible to set access permissions on a per-virtual-root basis. In this way, specific users can be granted access to certain directories without everyone being granted access or having to add the users to the Administrative groups.
To set access permissions in this way, set the UserList value for the appropriate virtual root to the list of users and groups who either have access to it or are denied access to it. For more information, see "Access Rights."
UserList="GladysL;AnnD;-KimYos;@SomeGroup;-@villains" allows 'GladysL', 'AnnD', and the 'SomeGroup' group, but restricts the 'KimYos' user and the 'villains' group. "*" or "@*" allows all users, and "-*" or "-@*" denies all users. The string is interpreted sequentially; in other words, if 'GladysL' is a member of the 'Finance' group, the following strings will allow GladysL:
The following strings will restrict GladysL:
Note '*' is a group and must be marked as such in the list. It is possible that parsers understand both '@*' and '*' syntax, but they always use '@*' syntax.
Note that Administrators always have access to virtual roots with A set to 1, even if they are not on the UserList for that root, and even if they are denied access explicitly in the UserList value.
The Web server (Httpd) supports a subset of the HTTP/1.0 protocol, which includes limited functionality, a status-code subset, and fewer header-field definitions.
The Web server provides a limited set of HTTP/1.0 functionality. The Head and Get functions are supported directly. ISAPI filters, ISAPI extensions, and ASP pages all have access to data that can be read from the POST header and body. However, the Web server does not use data from the POST header and body directly. All other methods are ignored.
The following list shows the only HTTP status codes that the Windows CE Web server can return:
404—"Object Not Found"
500—"Internal Server Error"
Note You can set custom response strings by using ASP, ISAPI extensions, and ISAPI filters.
The Web server can use the following header fields:
All other headers are parsed, but they are ignored.
ISAPI extensions provide a means of scripting for the Web server; they are implemented as DLLs that are loaded into the same process as the Web server.
If the Web server receives a request that maps to an ISAPI extension, such as http://www.mysite.com/MyISAPI.dll, it searches for the DLL in a cache of recently used extensions. If the DLL is not in the cache, the Web server loads it. After the DLL is loaded, the entire request is handled by the extension, with the Web server acting as an intermediary and helper.
The basic use and operation of ISAPI extensions on the Windows CE Web server are very similar to their use and operation on Microsoft Internet Information Services (IIS).
If a file that is requested has the .dll extension, the Web server attempts to load it as an ISAPI extension if it is in a directory that has the HSE_FLAGS_URL_EXECUTE flag set. If the load attempt fails, the Web server returns the "500—Internal Server Error" status code.
Windows CE allows virtual paths to specify an ISAPI extension or ASP page, instead of a directory. For instance, the http://www.computername.com/inventory URL could map to the \Windows\scripts\inventory.dll file. To set up this specification, name the physical path "\Windows\scripts\inventory.dll" under the inventory subkey in the registry. No characters should trail the file name in this registry value.
By calling the GetServerVariable function with the lpszVariableName parameter set to PATH_INFO, the trailing part of the URL (that is, the part of the URL that comes after the ISAPI DLL name or that mapped to the ISAPI DLL path in the Vroot mapping, but that comes before the query string, if any) is placed in the lpvBuffer parameter.
Using the previous example, the http://www.computername.com/inventory/a/b URL still would match the Inventory.dll file, and a call to the GetServerVariable function with the lpszVariableName parameter set to PATH_INFO would set the lpvBuffer parameter to /a/b.
The PATH_TRANSLATED variable specifies the same value as the PATH_INFO variable, but any virtual path contained in PATH_INFO is expanded into a directory specification in PATH_TRANSLATED.
ISAPI extension names may be embedded in a URL. Once again, the PATH_INFO portion of the URL comes after the ISAPI DLL name, but before the query string, if any. For the http://www.yourcomputer.com/scripts/inventory.dll/a/b request, the Web server would look for the Inventory.dll file in the directory that is specified by the virtual directory "scripts". The value of the PATH_INFO variable would be /a/b.
ISAPI Extension Functions
The following table lists the differences between the IIS version and the Windows CE version of ISAPI extension functions.
|ISAPI extension function||Windows CE implementation|
|GetServerVariable||See "GetServerVariable Implementation"|
|ServerSupportFunction||See "ISAPI Extension ServerSupportFunction Implementation"|
|WriteClient||Not supported for the HSE_IO_ASYNC flag|
ISAPI Extension ReadClient Implementation
The lpbData member of the EXTENSION_CONTROL_BUFFER structure points to a buffer that contains the data that the client sent, and the size of the client read buffer is specified by the cbAvailable value. The total number of bytes that the client is going to send is specified by the cbTotalBytes value.
If the cbTotalBytes value is equal to the cbAvailable value, all of the data from the client has been read and there is no need to call the ReadClient function. If the cbTotalBytes value is greater than the cbAvailable value, you will need to call ReadClient to make the Web server read more data from the client browser.
The advantage of using multiple calls to the ReadClient function is related to Windows CE memory constraints. You might want to use the Web server to upload a 10-megabyte (MB) file to a flash card. You might have only 2 MB of RAM available, but sufficient storage space is available on the card. If the entire buffer from the client was read at once, the device would run out of physical memory. However, if you use a 4-KB buffer while you call ReadClient and then call the WriteFile function immediately after each call, you can minimize the amount of RAM that is required.
If you use the ISAPI extension function ReadClient, you must use caution when you write ISAPI filters that receive notifications for read raw data events.
ISAPI Extension ServerSupportFunction Implementation
The following options for the dwHSERequest parameter are not supported on Windows CE. If the ServerSupportFunction function receives them, it returns FALSE and sets ERROR_INVALID_PARAMETER as the last error.
The following information applies to the GetServerVariable function for ISAPI extensions and ISAPI filters, and to the ASP-page Request.ServerVariables object.
The following options for the lpszVariableName parameter are not supported on Windows CE. If the ServerSupportFunction function receives them, it returns FALSE and sets ERROR_INVALID_INDEX as the last error.
Note The Web server ignores the members of the structure that the script can modify in the GetFilterVersion function.
ISAPI filters are DLLs that are loaded into the process of the Web server when it is started, and they stay in memory until the Web server shuts down. After they are loaded, ISAPI filters can be configured to receive a number of special filter-event notifications that occur with each HTTP request that the Web server receives, and with each response that the Web server generates in return.
When an ISAPI filter is loaded, the filter passes a structure to the Web server that contains, in addition to other information, a bit field that specifies the types of filter-event notifications for which the filter should be notified. Each time that the event occurs, an event notification is started, and every ISAPI filter that is set to monitor that event is notified.
ISAPI Filter Functions
The following table lists the differences between the IIS version and the Windows CE version of ISAPI filter functions.
|ISAPI filter function||Windows CE implementation|
|AddHeader||See "ISAPI Filters and HTTP Headers."|
|GetHeader||See "ISAPI Filters and HTTP Headers."|
|GetServerVariable||See "GetServerVariable Implementation."|
|ServerSupportFunction||See ISAPI Filters ServerSupportFunction Implementation.|
|SetHeader||See "ISAPI Filters and HTTP Headers."|
|WriteClient||Data-chunking capability not implemented.|
Note The Web server ignores the members of the structure that the script can modify in the GetFilterVersion function.
Because the Web server has no support for secure connections, the SF_NOTIFY_SECURE_PORT and SF_NOTIFY_NONSECURE_PORT flags that are set by the GetFilterVersion function in pVer->dwFlags are ignored. Events that are set to be notified are always in the pVer->dwFlags and always receive notifications, even if they did not set the SF_NOTIFY_NONSECURE_PORT flag.
IIS automatically breaks data that is larger than 16 KB into 16-KB chunks on requests from the WriteClient function. There is no support for this functionality on Windows CE.
ISAPI Filters ServerSupportFunction Implementation
The following options for the sfReq parameter are not supported on Windows CE. If the ServerSupportFunction function receives them, it returns FALSE and sets ERROR_INVALID_PARAMETER as the last error.
ISAPI Filters and HTTP Headers
The Windows CE Web server supports only a subset of the functionality that is offered by IIS for HTTP header management.
On an SF_NOTIFY_PREPROC_HEADERS flag event, both the AddHeader and SetHeader functions only modify the method, URI, and HTTP version values in the simple request line.
On an SF_NOTIFY_SEND_RESPONSE flag event, the AddHeader and SetHeader functions operate differently on the Windows CE Web server. On IIS, filters can delete the lpszName value if it has been set to "\0" by lpszValue on a call to the SetHeader or AddHeader function. IIS also allows existing response headers to be overwritten with a call to the SetHeader function, with the new value in lpszValue. The Windows CE Web server does not support either of these options; after a new header name and value pair has been added by using the SetHeader or AddHeader function, the pair cannot be deleted or overwritten.
When converting headers that are added with the AddHeader or SetHeader function into raw HTTP headers, the Web server adds a space between the lpszName and lpszValue values, and adds a trailing "\r\n" to the end of each header pair. However, it does not add a colon to the end of the lpszName value.
Note The Web server ISAPI filter implementation cannot change the read size of data on POST requests; the read size is fixed at 48 KB. Any block of incoming data that is larger than the read size is read into a buffer.
Because the Windows CE Web server is loaded upon startup, typically you would have to use a kernel-mode debugger to debug ISAPI extensions and filters. To make it easier to debug ISAPI applications, an executable version of the Web server, Httpdexe, is provided with Windows CE 3.0. Httpdexe is identical to the Web server, except that it runs as an executable application. To use this debugger on your ISAPI extensions and filters, you should follow these steps:
- Stop the Windows CE Web server, as described in "Starting and Stopping the Web Server."
- Copy the Httpdexe.exe file to the root directory of your device. The Httpdexe.exe file is included with your binary distribution of the Windows CE Web server, but it is not downloaded to the Windows CE device during startup.
- Build a debug version of your ISAPI application, and call the DebugBreak function where you want to begin debugging.
- Start Microsoft® Visual Studio®. From the File menu, choose Open, and then open the Httpdexe.exe file from the root directory.
- Open a Microsoft® ActiveSync® connection from the device to the desktop machine that is running Visual Studio, if you have not done so already.
- Press the F5 key to start Httpdexe.exe through Visual Studio. Note that the first time you debug your device, Httpdexe.exe might require a few minutes to initialize. After the first debug session, Visual Studio should only require approximately 30 seconds to initialize Httpdexe.exe.
- You might need to press the F5 key a few more times to start Httpdexe.exe. To determine if the Web server has successfully started, look for a startup message that is appended to the log file that is named current-httpd.log.
- Take the required steps to make the code that you are debugging run. The DebugBreak function halts operation of the extension or filter at the location of the failure.
Because Httpdexe is not running as a DLL, the Web server administration tools have no effect. To turn the Httpdexe server off, you must restart your device.
Running the Web server as an executable application offers increased isolation from faulty extensions and filters. When the Web server is run as a Device.exe file, it is possible for a faulty ISAPI extension or ISAPI filter to destabilize the system. If the Web server is run as an executable application, ISAPI extensions and filters are in a different address space from system threads, which reduces the possibility of system corruption. If you want additional stability and do not plan to administer the Web server remotely, you should run the Web server as an executable application.
This section explains the basic requirements for converting existing Common Gateway Interface (CGI) script-executable files to ISAPI extension DLLs. As with other DLLs, Web server applications should be thread-safe. More than one client browser might be executing the same function at the same time, so the code should follow safety procedures when it modifies a global or a static variable.
You can keep your ISAPI extension thread-safe by using appropriate synchronization techniques, such as creating critical sections and semaphores. For additional information on writing thread-safe DLLs, see the documentation that is in the Platform Builder 3.0 SDK and in the Microsoft Development Library compact disc.
There are several structural differences between an ISAPI extension and a CGI executable file. An ISAPI extension:
- Receives most of its data through the lpbData member of the Extension Control Block (ECB), as opposed to reading the data from the StdIn property. For additional data, the extension uses the ReadClient callback function.
- Accesses common CGI variables through the ECB. For other variables, an ISAPI extension calls the GetServerVariable function. In a CGI executable file, CGI variables are retrieved from the environment table by using the GetEnv function.
- Sends data back to the client browser by using the WriteClient callback function, instead of writing to the StdOut property.
- Specifies the completion status either by sending the header directly by using the WriteClient callback function, or calling the ServerSupportFunction function by using the HSE_REQ_SEND_RESPONSE_HEADER flag, instead of sending a "Status: NNN xxxxx..." status code to the StdOut property.
Note The status code is set to 200 before the server calls an extension, and the server ignores any changes that the extension makes to it. The ISAPI developer must set the response code that is sent back to the client in the ServerSupportFunction function.
- Redirects requests with a "Location:" or "URL:" header, instead of writing the header to the StdOut property. Use the HSE_REQ_SEND_URL flag if the URL is local; however, if the URL is remote or unknown, use the HSE_REQ_SEND_URL_REDIRECT_RESP flag in the ServerSupportFunction callback function.
Note The following section applies only to the Web server release in Windows CE Platform Builder, where the individual libraries that make up the Web server can be linked together in customizable ways.
The Web server contains seven components. The following table lists the descriptions of these components, as well as the dependencies that exist between the components. Size approximations are based on a retail build of Windows CE that was compiled for the Intel x86-based computer. With the exception of Httpasp, all of the components should be available in Maxall and Mincomm configurations.
|Component name||Description||Approximate size|
|Httpasp||Required for support of ASP; this component depends on Httpisapi and Httpextn. The size approximation represents only the overhead that is added to the Web server when the separate components of ASP are installed.||1 KB|
|Httpauth||Required for authentication.||2 KB|
|Httpcore||Required in all configurations.||—|
|Httpd||Required in all configurations.||20 KB|
|Httpextn||Required for ISAPI extensions; this component depends on Httpisapi.||4 KB|
|Httpfilt||Required for ISAPI filters; this component depends on Httpisapi and Httpextn.||10 KB|
|Httpisapi||Common component for scripting options; this component is the base for ISAPI extensions, ISAPI filters, and ASP pages, and performs no stand-alone operations.||3 KB|
|Httpparse||Required in all configurations.||—|
Note The Netregd component must be included to allow the Web server to be accessed by its Domain Name System (DNS) name. Without this component, you must use the IP address of the Web server to access it. See the Windows CE Platform Builder documentation for more information about the netregd component.
If a file that is requested by the client browser has a .dll extension and is in a virtual directory that has HSE_FLAGS_URL_EXECUTE permissions, and if the Httpextn component is not part of the Web server, the "501—Not Implemented" status code is returned to the client browser.
If a file that is requested has an .asp extension and the Httpasp component is not part of the Web server, or if the main ASP-page library has not been set up properly, the "501—Not Implemented" status code is returned to the client browser.
ASP provides a server-side scripting environment that can be used to create and run dynamic, interactive Web server applications. ASP combines HTML pages, script commands, and Component Object Model (COM) components to create interactive Web pages or powerful Web-based applications. ASP-page applications are easy to develop and modify.
A server-side script begins to run when a browser requests an .asp file from the Web server. The Web server then calls ASP, which processes the requested file from top to bottom, executes any script commands, and sends a Web page to the browser. Because scripts run on the server, instead of on the client browser, the Web server does all of the work that is involved in generating the HTML pages that are sent to browsers.
Windows CE supports a subset of the ASP-page functionality that IIS supports. The following section describes the limitations of ASP on Windows CE.
The Windows CE ASP-page interpreter processes a file with an .asp extension when it is requested by the client browser, assuming that the following conditions are met:
- The virtual root where the ASP page is located must have the permissions set to either HSE_FLAGS_URL_EXECUTE or HSE_FLAGS_URL_SCRIPT. If this is not the case, the Web server returns the "403— Forbidden" status code, along with an "Access Denied" message.
- The Httpisapi, Httpextn, and Httpasp components must be included when building the Web server. If they are not, the Web server returns the "501—Not Implemented" status code and an error message that informs the user of the problem.
- The Asp.dll file should not be missing or corrupt. If this is not the case, the Web server returns the "500—Internal Server Error" status code to the client browser.
- The JScript.dll or VBScript.dll file must be set up properly on the device. If the requested script language is not present on the device or has not been initialized, the Web server returns an error that states, "Error in initializing scripting engine."
You can map a virtual path to a specific ASP page, instead of to a directory. For example, a client browser could request the http://www.computername.com/directory URL and be mapped to a specific ASP page, such as Finance.asp. Using the functionality is identical to mapping virtual paths to ISAPI extensions. For more information, see "ISAPI Extensions."
Like ISAPI DLLs, the Web server keeps Asp.dll and any libraries that ASP loads—including JScript.dll, VBScript.dll, and any DLLs that contain COM objects that were created on the page—in a cache. The DLLs that are in this cache are unloaded automatically by the Web server if they have not been used for 20 minutes.
The Windows CE implementation of ASP uses the same syntax that IIS uses for the most basic ASP-page operations.
Script commands are differentiated from text by the "<%" and "%>"delimiters.
These script commands are processed by using the specified scripting language. Any command that is used within script delimiters must be valid for the scripting language.
ASP-page delimiters may be included in any statement, expression, procedure, or operator that is valid for the scripting language. A statement is a syntactically complete unit that expresses one kind of action, declaration, or definition. The following code example is a valid operation on Windows CE ASP, and sends the "Good Morning!" or "Hello!" greeting to the client browser, based on the time of day.
<% Dim dtmHour, strGreeting dtmHour = Hour(Now()) If dtmHour < Then strGreeting = "Good Morning!" Else strGreeting = "Hello!" End If Response.Write(strGreeting) %>
Just as in IIS, it is possible to include HTML text between the sections of a statement. For example, the following script, which mixes HTML within an If...Then...Else statement, produces the same result as the script in the previous example.
<% Dim dtmHour dtmHour = Hour(Now()) %> <% If dtmHour < 12 Then %> Good Morning! <% Else %> Hello! <% End If %>
The <%= %> directives inform ASP to print the value of the variable in the Web page.
For example, in the first script, the line
<%= strGreeting %>
sends the "Good Morning!" or "Hello!" string, just as the call to the Response.Write method did.
If a requested file has an .asp extension, but does not use any ASP-page functionality, it is sent to the client browser without undergoing any script processing. This practice is not recommended. There still is more overhead that is associated with a file that has an .asp extension than there is with other files. For performance reasons, files that do not contain ASP-page functionality should not have the .asp extension.
Features Not Supported
The Windows CE implementation of ASP supports a subset of the features that are supported by the IIS implementation of ASP. This section lists the features that are not supported by Windows CE ASP.
No State Maintained Between Requests
This feature is the greatest difference between the IIS and Windows CE implementations of ASP. Windows CE does not provide support for the Session or Application objects and does not send the Session-ID cookie that is used on IIS. Therefore, there is no automatic technique for maintaining state between requests or sessions.
The script writer must maintain information between requests and sessions. A script writer can do this by sending cookies to the client browser by using the Response.Cookies method, and retrieving them by using the Request.Cookies method. This scheme assumes that the client browser has cookie support enabled.
No <OBJECT> Tag support
Windows CE ASP treats the <OBJECT> tag and properties as plain text. Interpretation of the <OBJECT> tag by the client browser is browser-specific. For more information, see "Server Object Implementation."
No Transaction Support
None of the methods or properties that are associated with transactions is supported on Windows CE ASP. Tags and commands that are used by ASP on IIS to support transactions are ignored by Windows CE ASP and treated as plain text. How the client browser interprets these values is browser-specific.
No Server-side Scriptlets
There is no support for server-side scriptlets in Windows CE ASP. The <SCRIPTLET> and related tags are ignored by Windows CE ASP and treated as plain text. How the client browser interprets the <SCRIPTLET> tag is browser-specific.
No Additional Server-side Scripting Options
On IIS, it is possible to specify options such as <script LANGUAGE="JSCRIPT" RUNAT="SERVER">, in which case the code between the <SCRIPT> and </SCRIPT> tags is executed on the server in the specified language, instead of on the client computer.
Windows CE ignores the RUNAT option of <SCRIPT> tags, and sends the script to the client browser. How the client browser interprets the RUNAT option is browser-specific.
No Global.asa File
Windows CE ASP does not search automatically for a file that is named Global.asa to obtain global settings. You can include initial settings or commonly used routines by using header files.
No Automatic Initialization or Termination Functions
Script procedures can be named Application_OnStart, Application_OnEnd, Session_OnStart, or Session_OnEnd, although Windows CE ASP does not treat them differently from any other user-created procedures. Windows CE ASP does not call script procedures automatically upon application or session initialization or termination, as is the case on IIS ASP.
No Metabase Support
The Windows CE Web server does not provide metabase support. If a script contains a property that can be set in the IIS metabase, but the property is not explicitly listed as being supported in this Windows CE Web server document, it is not supported for use with the Windows CE Web server. For example, scripts that contain ScriptMap statements might operate correctly with IIS, but these scripts will fail with the Windows CE Web server.
The Windows CE implementation of ASP only supports three built-in server objects:
Each of these objects is a subset of the corresponding IIS implementation of each of them, as described below.
Request Object Implementation
The Request object retrieves the values that the client browser passed to the server during an HTTP request. The following table lists the level of support for Request.
|Request method||Windows CE implementation|
|BinaryRead||Fully supported (see Note).|
|Cookies||See "Collection Objects."|
|Form||See "Collection Objects."|
|QueryString||See "Collection Objects."|
|ServerVariables||See "Collection Objects."|
Note The Request.BinaryRead method returns the data exactly as it is read from the browser, which can have unexpected results. Both the JScript and VBScript languages use only UNICODE strings internally. Windows CE ASP automatically converts ASP pages from ANSI to UNICODE, but it does not perform the same conversion on data from Request.BinaryRead. If the browser sends an ANSI string as form data and an ASP page calls Request.BinaryRead, no conversion to UNICODE is made and the data is unintelligible to the scripting language.
The Request.BinaryRead method can be called multiple times. On the first call to Request.BinaryRead, ASP reads count bytes from the beginning of the form data. On the next call to Request.BinaryRead, ASP reads from where the first call to Request.BinaryRead ended, and not from the beginning of the Form buffer. Similarly, subsequent calls to Request.BinaryRead begin where the last read ended, and not at the beginning.
Response Object Implementation
The Response object returns the values that the server processed to the client browser in response to an HTTP request. The following table lists the level of support for Response.
|Response method or property||Windows CE implementation|
|Buffer||(Property) Fully supported (see Note)|
|CacheControl||Not supported; use AddHeader with name = "Cache-Control"|
|Clear||Fully supported (see Note)|
|Cookies||See "Collection Objects"|
|End||Fully supported (see Note)|
|Flush||Fully supported (see Note)|
|PICbS||Not supported; use AddHeader with name = "PICS"|
|Redirect||Fully supported (see Note)|
Note The Buffer property indicates whether to buffer page output. When page output is buffered, the server does not send a response to the client browser until all of the server scripts on the current page have been processed, or until the Flush or End method has been called.
If the current .asp file has buffering set to TRUE and does not call the Flush method, the server honors Keep-Alive requests that are made by the client browser. Avoiding the call to the Flush method saves time, because the server does not have to create a new connection for each client browser request.
If buffering is turned off, calls to the Clear, End, Flush, or Redirect method fail, just as on IIS. When buffering is off, response headers must be added at the very top of the ASP page, before any text is sent to the client browser.
Windows CE does not support some of the advanced header-management functions that are available on IIS, such as the CacheControl method. To set one of these values, call the Response.AddHeader method and specify the name and value as parameters. For example,
<% Response.CacheControl = "private" %>
can be implemented on Windows CE by using the following call:
<% Response.AddHeader("Cache-control","private") %>
If an advanced header-management function such as Response.CacheControl is called repeatedly on IIS, only the value that was set in the last call to the method is sent to the client browser. On Windows CE ASP, calls to the Response.AddHeader method append data to the end of the headers and do not overwrite any of the existing headers of the same name.
Server Object Implementation
The Server object provides access to methods and properties on the server. Most of these methods and properties serve as utility functions.
|Server method||Windows CE implementation|
To create a COM object on Windows CE ASP, use the scripting language support for creating COM objects, instead of the Server.CreateObject method, as on IIS.
In JScript, the following code would create the object of type class.name.
<% var newObject = new ActiveXObject("class.name") %>
To perform the same operation by using VBScript, use the following code:
<% dim newObject set newObject = CreateObject("class.name") %>
Unlike with JScript or VBScript, there is no explicit need to delete COM objects that are created on ASP pages. Windows CE ASP automatically deletes all COM objects that are created on ASP pages. See "Initial Settings" for more information on ASP and the caching of DLLs.
Collection objects are data structures that are similar to arrays and that store strings, numbers, objects, and other values. The collections that Windows CE supports provide a convenient way to read query string, form, and cookie data that is sent from the client browser, and to create cookies on responses. Windows CE implements the Response.Form, Response.QueryString, Request.Cookies, and Response.Cookies methods as collections.
Windows CE ASP uses the same syntax that is used on IIS for most of the collection objects.
Request.ServerVariables is implemented as a method, and not as a collection, on Windows CE ASP; attempts to treat it as a collection object fail. For example, the following line of code is not valid on Windows CE ASP.
<% Request.ServerVariables("URL").Count %>
IIS allows the Response object to be accessed as a collection object. The Response object searches for the value that is specified in the QueryString, Form, Cookies, ClientCertificate, and ServerVariables methods, and returns the value if it finds a match in this case. Windows CE has no support for this functionality. For example, the following action is valid on IIS, but not on Windows CE.
<% Request("URL") %>
None of the collection objects supports iteration. For example, the VBScript operation
<% for each Item in Request.Cookies Response.Write Item Next %>
returns an error message that states that the method is not implemented on Windows CE ASP.
Cookies cannot be subindexed on Windows CE. Only one value may be set per each named cookie. For example, calling
<% Response.Cookies("Index")("Sub-index") = "Value" %>
fails on Windows CE. Similarly, the Request.Cookies method does not parse out indexed arrays.
<% Response.Cookies("Index") = "Value" %>
The Response.Cookies method supports the Path, Domain, and Expires attributes, which can be set individually for each cookie value. The Secure attribute is not supported.
On IIS, it is possible to assign attributes to a response cookie before setting the value of the cookie or without setting the value at all. For instance, the following code sequence is valid.
<% Response.Cookies("Index").Path = "/" Response.Cookies("Index") = "Value" ` set the Path attribute before the cookie value %>
Windows CE requires that the value of the cookie be set before you set any of its attributes. Attempting to run the preceding code on Windows CE ASP would return the error "The collection object specified is read-only."
Accessing Client Data without the ASPCOLCT Component
You can access the raw input from the client browser even without having collection objects included as a component, although parsing is nontrivial. In particular, Web browsers use escape sequences to send certain characters, such as spaces, across the network. Handles within ASP automatically decode data that is sent from the browser when collection objects are used. However, if the data is accessed in its raw form, it becomes the responsibility of the script to handle this conversion. If you intend to write ASP pages that receive input from the client browser, it is recommended that you include the ASPCOLCT component and use the built-in objects.
The query string can be accessed easily in raw form without collection objects through a call to the Request.ServerVariables("QueryString") method.
To access cookies that are sent by the browser, call the Request.ServerVariables("ALL_RAW") method and remove the "Cookie:" value from the header.
To access POST data, call the Request.BinaryRead method. See the notes on Request.BinaryRead for more information on this function.
To send cookies to the client, call the Response.AddHeader method with the name parameter set to "Set-cookie" and the value parameter set to the cookie name and value pairs.
Windows CE ASP supports three ASP processing directives only: Codepage, Language, and LCID. Attempts to use other identifiers result in an error.
If the ASPPARSE component is included, the <%@ … %> ASP processing line behaves in the same manner as on IIS. The Web server allows these values to be set on a per-page basis.
Unlike IIS, Windows CE ASP does not check to ensure that the Preproc directive line is the first line of the ASP page. It also does not check to see if there is only one Preproc directive line per file. If multiple ASP processing statements are included in one file, ASP uses the values that are in the first directive line and treats the remaining ASP processing directives as commands in the primary scripting language. Multiple ASP processing statements in a single file cause a parse error, but it might not be immediately obvious that the problem was caused by the additional Preproc directive lines.
It is possible to set site-wide default settings for the ASP processing directives in the registry. These values override the default ASP settings. The registry settings and ASP default settings are overridden on a requested ASP page if there is an ASP processing line on the page.
HKEY_LOCAL_MACHINE\Comm\HTTPD\ASP is the protected registry key for the default ASP settings. The following table shows the named values for the protected registry ASP configuration parameters.
|Codepage||A DWORD that is equal to the code page to use. If this value is not set and not specified as a processing directive, ASP assumes it is working with ANSI strings.|
|Language||A string that is equal to either "JScript" or "VBScript", depending on which language is to be used. If this value does not exist, the default is VBScript.|
|LCID||The locale identifier (LCID) to use. If this value is not set and not specified as a processing directive, ASP uses the local default.|
Windows CE ASP evaluates ASP processing directives only if the ASPPARSE component has been included. However, the registry settings are read in, regardless of whether or not the ASPPARSE component has been included. In this way, it is possible to change the values (such as the scripting language) without including the ASPPARSE component. The disadvantage of not including the ASPPARSE component is that the values must be set site-wide and cannot be set on a page-by-page basis.
Windows CE ASP supports a subset of the support for header files that IIS supports. The basic syntax for including header files on Windows CE is identical to the syntax for IIS. Both virtual and file keywords are supported.
Windows CE allows a maximum of 16 files to be included on one page. Attempts to include more than 16 files results in an error being returned to the client browser, and no script processing taking place.
Windows CE ASP provides no support for nested header files. For example, if an ASP page includes the File1.inc file, and File1.inc includes the File2.inc file, File2.inc is not read into the script. Instead, the #include line that contained File2.inc is sent to the client as regular HTML text.
There can be only one #include statement per line. #include statements must not be on the same line with processing directives, output directives, or script directives, or with other #include statements. Attempts to do so result in an error message that informs the script writer of this condition; also, no script text is executed.
The ASP interpreter requires the Windows CE Web server to be active. The interpreter also requires availability of JScript, VBScript, or both.
The ASP interpreter is provided in three components, which the following table describes.
|Component name||Description||Approximate size|
|All components||45 KB|
|Aspcolct||Collection objects; needed to support accessing of Form, QueryString, and Cookie.||5 KB|
|Aspparse||Supports header files and ASP Preproc directives.||5 KB|
All size approximations are based on a retail version of this product that is compiled for the CEPC (Windows CE PC-based hardware development platform).
The Web server must have the Httpisapi, Httpextn, and Httpasp components included in order for ASP support to be enabled. The smallest Web server that can be built that still supports ASP functionality has a size of approximately 28 KB. The Windows CE Web server with all of the components included has a size of approximately 40 KB.
For more information on Web site design and development, see the MSDN Library.
For more information on the Windows programming environment, see the Platform SDK documentation, as well as Programming Windows, by Charles Petzold (Microsoft Press, 1999).