Legal Information

Microsoft Internet Information Server Software Development Kit Documentation

Information in this document is subject to change without notice. The names of companies, products, people, characters, and/or data mentioned herein are fictitious and are in no way intended to represent any real individual, company, product, or event, unless otherwise noted. Complying with all applicable copyright laws is the responsibility of the user. No part of this document may be reproduced or transmitted in any form or by any means, electronic or mechanical, for any purpose, without the express written permission of Microsoft Corporation. If, however, your only means of access is electronic, permission to print one copy is hereby granted.

Microsoft may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering subject matter in this document. Except as expressly provided in any written license agreement from Microsoft, the furnishing of this document does not give you any license to these patents, trademarks, copyrights, or other intellectual property.

Copyright © 1997-1998 Microsoft Corporation. All rights reserved.

Microsoft, MS-DOS, MS, Windows, Windows NT, ActiveX, JScript, Microsoft Press, Visual Basic, Visual C++, Visual J++, Win32, and Win32s are either registered trademarks or trademarks of Microsoft Corporation in the United States and/or other countries.

Java is a trademark of Sun Microsystems, Inc.

Macintosh and QuickTime are registered trademarks of Apple Computer, Inc.

Other product and company names mentioned herein may be the trademarks of their respective owners.


Advanced Web Application Development

This guide provides an overview of Web application design, and introduces the more advanced topics of security, data access, and Web-based transactions.

Note The information contained in this section is excerpted from the forthcoming Internet Information Server Resource Kit, to be published by Microsoft Press.

This section contains:

  • Web Applications: An Overview: An introduction to the IIS programming model.
  • Security Ramifications for IIS Applications: Choosing the right access control to prevent unauthorized access to your site.
  • Accessing Data with Active Server Pages (ASP): An introduction to data access from a Web page with Microsoft® ActiveX™ Data Objects (ADO).
  • Debugging Your Application: Troubleshooting tips and tricks for ISAPI, and component developers.


Web Applications: An Overview

Open Internet standards, coupled with the explosive popularity of the Web, have changed the architecture of distributed computing forever. The basic language of the Web, HTML, has developed into an ideal language for representing the elements of the user interface. Cross-platform support for scripting languages and Java applets makes it possible to combine dynamic elements with static text for a more interactive user experience. Embedded ActiveX components provide another level of interactivity, and can be used as navigation controls or to add multimedia to Web applications. Web technologies aren't solely for use on the Internet, however. They have been adapted for use by businesses to:

  • Create an environment for component-based development.
  • Enable distribution of applications throughout an enterprise.
  • Customize and create new applications quickly.
  • Take part in intranet-enabled database processing.
  • Add transaction processing to Web applications.
  • Manage resources and enable remote system administration.

This section outlines the technological advances that brought dramatic change to programming paradigms, and how this change will shape the way you will build applications in the future.

  • Building on the Client/Server Architecture: A brief history of the client/server design model.
  • The New System Design: An introduction to n-tier and distributed systems design.


Building on the Client/Server Architecture

Building on Client/Server Architecture

Before delving into the details of building a Web-based application, it might be helpful to review the architectural model of the Web, and the roles of the browser and server in that model.

Typically, cooperating applications can be categorized as either a client or a server. The client application requests services and data from the server and the server application responds to client requests. Early two-tier (client/server) applications were developed to access large databases, and combined the rules used to manipulate the data with the user interface into the client application. The server's task was simply to process requests for data storage and retrieval, as many and as fast as possible.

Two-tier applications perform many of the functions of stand-alone systems; they present a user interface, gather and process user input, perform the requested processing, and report the status of the request. This sequence of commands may be repeated as many times as an application runs. Because servers only provide access to the data, the client uses its local resources to perform most of the processing. The client application must contain information about where the data resides and how it is laid out in the database. Once the data has been retrieved, the client is responsible for formatting and displaying it to the user.

One major advantage of the client/server model is that by allowing multiple users to simultaneously access the same application data, updates from one computer were instantly made available to all computers that had access to the server. However, as the number of clients increased, the server was quickly overwhelmed by client requests. Also, since much of the processing logic was tied to a monolithic suite of applications, changes in business rules lead to expensive and time-consuming alterations to source code. Although the ease and flexibility of two-tier products continue to drive many small-scale business applications, an increasingly competitive need for faster data access and more rapid developmental timelines has persuaded systems developers to seek out a new way of creating distributed applications.


The New System Design

Today's client/server applications resemble their ancestors so little, in fact, that they have been given a new name, the multi-tier application, also known as n-tier architecture. In this model, the division between client and server isn't as easily discernible, and often the server becomes a client itself. Not surprisingly, the new system model attempts to distribute computing tasks more evenly between the client and server. Viewed from a purely functional standpoint, most systems will perform the following three main tasks:

Presentation - Business Logic – Data Services
  • The presentation layer comprises the entire user experience. Not only does this layer allow the users to interact with the application, input data, and view the results of requests, it manages the manipulation and formatting of data once it arrives at the client. On the Web, the browser application performs the tasks of the presentation layer.

Data services are provided by a structured (SQL, Oracle database) or unstructured store (Microsoft® Exchange, Microsoft® Message Queue), which manages and provides access to the application data. A single application may enlist the services of one or more data stores.

Between these two layers lies the murky domain of the distributed application developer. Business logic, which are the rules that govern application processing, connect the user at one end with the data at the other. The functions that these rules govern closely mimic everyday business tasks, and can be a single task, or a series of tasks.

The three-tier architecture isolates each major piece of functionality. The presentation is independent of the processing rules and business logic, which in turn is separate from the data. This model requires much more analysis and design up front, but greatly reduces maintenance costs and increases functional flexibility in the long run.


Security Ramifications for IIS Applications

Securing Web sites is one of the most critical issues for Web developers. It is also one of the most potentially confusing. A secure system requires careful planning, and Web site administrators and programmers must have a clear understanding of their options for securing their site. In addition, they need to understand how all of the various security sub-systems interact. This section provides an overview of the technologies used by IIS to create a secure environment for application development.

This section includes:

  • ASP Session ID Encryption and Session Security: An overview of ASP Session security.
  • User Authentication Methods: The three types of client authentication.
  • Additional Security Considerations: Managing security and system resources.

Security and permission problems account for the majority of ASP issues. In order to avoid these problems, ASP developers must have a firm grasp of IIS authentication and controlling access to pages using NTFS file permissions. For more information about securing your ASP application, see Securing an ASP Application.


ASP Session ID Encryption and Session Security

Once an ASP session begins, a browser request is identified only by its session ID cookie. Any HTTP request with a matching cookie is assumed to have come from the same browser that originated the session. This simple session management approach could open a potential security problem. If a hacker were able to capture, or guess, the session ID cookie in-use by an active session, he or she could submit valid HTTP requests that included this cookie. In this manner, a hacker could hijack, or steal, a user's active session. For example, if a user had supplied valid credit card information, and an ASP script stored this information in the Session object, a hacker who managed to hijack the session could make purchases using the stolen session. If an application requires strong security, a number of solutions can be employed.

Secure Sockets Layer Encryption

Encrypting all communications between the browser and the server prevents hackers from capturing the session cookie. Using Secure Sockets Layer (SSL) encryption, all traffic—including the session cookies—are encrypted, so a hacker sniffing or monitoring the network will not be able to see the private cookies in use. When using SSL encryption, remember that all browser requests to the Web application directory will include the session ID cookie. Even requests for static HTML content in the same application root will include the session ID cookie. All requests to the virtual directory, not just for .asp files, must be encrypted.

Hard-to-Guess Cookie Values

Using encryption prevents hackers from capturing valid cookies. However, a hacker could conceivably guess an active Session ID. ASP Session ID values are selected from a huge range, and are then encrypted. This makes it hard to guess an active cookie. You can obtain higher security by implementing cookies longer than 16 characters and matching them with session variables. Also, keep in mind that if someone does manage to guess a valid cookie once, this will not help him or her guess another valid cookie.

The following precautions are taken when generating ASP session cookies:

  • Session ID values are 32-bit long integers.
  • Each time the Web server is restarted, a random Session ID starting value is selected.
  • For each ASP session that is created, this Session ID value is incremented.
  • The 32-bit Session ID is mixed with random data and encrypted to generate a 16-character cookie string. Later, when a cookie is received, the Session ID can be restored from the 16-character cookie string (ASPSESSIONID).
  • The encryption key used is randomly selected each time the Web server is restarted.

If the combination of SSL encryption and the complexity of the ASP cookie generation algorithm do not meet your security requirements, user authentication and client certificates can be used in conjunction with session management to provide secure Web applications with client authentication.

For more information about ASP session IDs, and how to design ASP session-aware Web farms, see Managing Sessions in the Active Server Pages documentation.


User Authentication Methods

Let's begin with a quick overview of the client authentication types. Internet Information Server (IIS) supports the following authentication schemes:

  • Anonymous
  • Basic (Clear Text)
  • Microsoft Windows NT Challenge/Response
  • Any combination of the above

Each of these authentication methods can be enabled or disabled on the Directory Security page of the Virtual Directory properties in the Microsoft Management Console. A typical IIS configuration has Anonymous enabled, as well as either, or both, of the other methods. Anonymous authentication is the least secure method, while Basic and Microsoft® Windows NT® Challenge/Response provide increasingly greater levels of security for your Web pages. Each of these authentication schemes has a different impact on the security context of an application launched by IIS. This includes ISAPI extension agents, CGI applications, IDC scripts, and future scripting capabilities.


Anonymous Authentication

Setting Anonymous Authentication in IIS Manager means that IIS will not use any HTTP authentication mechanism to control access to resources on the computer. By default, when IIS is installed, it creates a user account called IUSR_<servername>, where <servername> is the name of the server on which IIS is running. This user account is added to the Guests group on the computer, which indicates that its access to resources is limited. When an HTTP request is received by IIS with Anonymous authentication being used, IIS will first impersonate the IUSR_<servername> account before executing any code or accessing any files that are involved in the request. This allows a level of security by limiting the accessibility to such things as system files by an unauthenticated user. IIS is able to impersonate the IUSR_<servername> account because the user name and password credentials for this account are known by IIS.

You can change the account that is used for anonymous authentication in Internet Service Manager, either at the Web server service level, or for individual virtual directories. You can also change the security privileges for the IUSR_<servername> account in Windows NT User Manager. Any changes to the IUSR_<servername> account will affect every anonymous HTTP request that is serviced by IIS.

Note Because you can configure IIS to use an anonymous account that is different from the USR_<servername> account, wherever this article refers to the IUSR_<servername> account, you should think of it as a placeholder for the account name configured as the Anonymous Logon account in the Microsoft Management Console.

The anonymous account configured in Internet Manager must have the user right to log on locally. If the account does not have the Log On Locally permission (not given to guest accounts by default on domain controllers), IIS will not be able to service any anonymous requests. The IIS installation specifically grants the Log On Locally permission to the IUSR_<servername> account.

Most resources that allow Guest access do so by allowing access to the special group, Everyone. You can set permissions on files and other resources specifically to allow or disallow access by the IUSR_<servername> account, but most people end up managing access by controlling access to the groups Everyone or Guests.

Before IIS returns a requested page to a client, it first verifies that the client has permission to view the page. Although you can restrict permission to a page by turning off Read and Execute permissions on its virtual root in IIS, the preferred method of restricting access to individual pages is to use NTFS file permissions.

Before returning a page to the client, IIS checks the NTFS file permissions on the page to see if the current user is allowed access to the file. If the NTFS permissions on the file do not allow IUSR_<servername> access to the requested page, IIS returns an HTTP 401 Unauthorized status code to the browser.

At this point the browser attempts to authenticate the user using one of the other authentication methods. If Basic authentication is used, the user is prompted for his or her user name and password. If Windows NT Challenge/Response is used, the browser automatically returns the appropriate information to satisfy the authentication request. The user is not prompted for a user name and password unless the server does not recognize the user name provided by Windows NT Challenge/Response. IIS then checks the user's credentials against the access permissions on the requested page, and either returns the page to the browser or returns an Access Denied response.


Basic Authentication

Basic authentication prompts the client for a user name and password that are then Base64-encoded and passed to IIS. IIS receives the user name and password credentials and verifies them against the Microsoft® Windows NT®-user database on the computer or the applicable domain controllers in any trusted Windows NT domains. If the credentials are valid, IIS will impersonate the specified user when allowing access to resources by IIS or any applications that the request is launching. Thus, the application being executed, whether it is an ISAPI extension DLL, a CGI application, or a scripting mechanism, will be executed with the permissions of the corresponding user account passed by Basic authentication.

Because Basic authentication provides the user name and password credentials to IIS, access to items that require credential knowledge can be performed successfully when using Basic authentication. For example, if an ISAPI application mapped a drive letter across a network, it would require knowledge of the current user's credentials. Because IIS is given the user name and password credentials as part of Basic authentication, this task will succeed if the account specified has access to the network resource.

The advantage of Basic authentication is that it is part of the HTTP specification, and is thus supported by most browsers. The disadvantage of Basic authentication is that if someone is monitoring packets on your network, they could easily intercept and decipher your password using publicly available algorithms. This is not possible with Windows NT Challenge/Response authentication because the actual password is never sent over the network. Instead, the browser returns a custom token that satisfies the server's authentication request.


Windows NT Challenge/Response Authentication

Windows NT Challenge/Response authentication (often called NTLM authentication) is the most secure form of authentication because the user name and password are not sent across the network. Instead, the Windows Security Provider interface is used to provide an encrypted challenge/response handshake mechanism that is functionally unbreakable. The Windows security provider interface allows IIS to validate and impersonate the user. Unlike Basic authentication, NTLM authentication does not initially prompt users for their user name and password. The current Windows user account on the client computer is used for the NTLM authentication. Then, if this fails, it will prompt the user for the user name and password. If NTLM authentication succeeds, the requested application or resource is executed in the context of the specified user.

Because one-way encryption is used, NTLM authentication validates the user for IIS without providing knowledge of the user's password to IIS. Therefore, a full set of user name and password credentials is not available to IIS for doing such tasks as mapping a network drive. For instance, if an ISAPI application calls the WNetAddConnection2 function without specifying a user name and password, it will fail under NTLM authentication.

Although Windows NT Challenge/Response is very secure, it does have a couple of limitations. First, only Microsoft browsers support this proprietary scheme. Second, Windows NT Challenge/Response does not work over HTTP Proxy connections. Because of these limitations, Windows NT Challenge/Response may not always be the best choice for an Internet server, although it is often ideal for intranet use. As you can see, choosing an authentication method is a trade-off in security verses flexibility.


Multiple Authentication Schemes Selected

You can select any combination of Anonymous, Basic, and NTLM authentication. If Anonymous authentication is checked, the request will be handled without any actual authentication and IIS will execute the request in the context of the IUSR_<servername> account. If, for some reason, the IUSR_<servername> account does not have access to the resource, IIS will send back an access-denied error to the client indicating that the client needs to use one of the other authentication schemes. This scenario could occur if you limited access to the actual ISAPI DLL file to a specific user, such as User1. IIS would receive the initial anonymous request and attempt to launch the ISAPI DLL under the IUSR_<servername> user context, only to get an access-denied error from the NTFS file system. IIS would respond to the client with a message saying that access was denied and the client needs to submit the request using either the Basic or NTLM authentication schemes (depending on which one is enabled, possibly even both). The client can then resubmit the request with the Basic authentication credentials or with the initial NTLM challenge/response sequence. If either of these responses provides validation of the User1 account, then IIS will impersonate the User1 account and successfully launch the ISAPI DLL.

It is worth noting that if both NTLM and Basic authentication schemes are checked, IIS responds to requests indicating that both schemes are acceptable. It is up to the client to determine which authentication schemes it supports and to respond appropriately. Browsers, such as Internet Explorer, that support both Basic and NTLM Authentication will respond using the first supported authentication scheme indicated by IIS.


Additional Security Considerations

This section outlines additional security considerations.

Registry Issues

Many IIS applications require resources provided by other software components. For instance, an ISAPI extension DLL may call an Automation server from a third-party software company, or a CGI application may launch an applet built with Microsoft® Visual Basic®. These components may have persistent information stored in the registry that they require in order to execute properly. For standard desktop use of these components, the registry information is read from the profile of the user currently logged on a computer with Windows NT. These applications often have problems when launched by IIS because the profile made available to an IIS application is that of the default user. The default-user profile is filled with information generic to all users, but, unfortunately, is specific to no users. Therefore, a component may run as expected when User1 executes it interactively on his or her desktop because it is reading information from User1's profile in the registry. The same application may not run at all from IIS because it will not have access to User1's profile. This is true even if IIS is impersonating User1's account using Basic or NTLM authentication.

Desktop Issues

Windows NT uses the concept of having multiple desktops on the same computer. A desktop can be thought of as the screen that you view when you are logged on your computer. Your desktop receives all the mouse and keyboard messages that you create as the user in front of the computer, and it allows for applications to interact with one another to a certain extent. For instance, one application on a desktop can post messages to other applications on the desktop. Support for multiple desktops implies that there are other desktops running; you just can't see them and you have no way of sending keyboard or mouse messages to them. This may seem like a futile concept, but, in fact, many applications that run as Windows NT Services require the capabilities that a desktop provides but don't want to interact with the interactive user's desktop. Therefore, each service gets its own desktop that won't be interfered with by the currently logged-on user.

The implication of this to IIS applications is that the IIS service has its own desktop. If your IIS application interacts with a desktop in any way (for instance, if it displays a message box), then it will display that message box on a desktop that cannot be seen on the computer's monitor. Similarly, an IIS application will not be able to send or post messages to an application on the interactive desktop. If your IIS application needs to interact with the interactive desktop, then you should use another form of inter-process communication such as named pipes.

ISAPI Filter DLLs

ISAPI Filter DLLs, not to be confused with ISAPI Extension DLLs, run in the original context of the IIS service. All services run by default under the Local System account of the computer on which they are installed. The Local System account has access to almost all resources on the local computer not specifically denied to it, and no resources on any other computers on the network.

COM Permissions

Launching a COM object on a computer running Windows NT requires certain permissions. This is normally not an issue for most interactive users because the default permissions for launching and accessing COM objects on Windows NT allows access to anyone logged on the local computer interactively. An IIS application, whether it is running in the context of the IUSR_<servername> account or an impersonated user account from Basic or NTLM authentication, is not interactively logged on. Therefore, the default permissions for launching and accessing COM objects will not allow an ISAPI extension DLL, CGI application, or Internet script to launch these objects successfully by default.

The utility DCOMCNFG on Windows NT 4.0 allows you to set the default permissions for all COM objects on your computer. You can use this utility to provide COM access to the IUSR_<servername> account as well as all user accounts that might be impersonated by your IIS configuration. You can even grant permissions to the Everyone group.

However, providing global access to all COM objects may not be in your best interest. DCOMCNFG will also allow you to specify permissions for specific applications so you can provide access only to the applications you will need to access from your IIS application. COM applications also have the ability to determine which permissions are associated with launching and accessing themselves. To do this from inside your COM server, see the CoInitializeSecurity function new to Windows NT 4.0, as well as CoCreateInstanceEx (in particular, the COSERVERINFO and COAUTHINFO structures) for manipulating OLE access from the client side.

Distributed COM (DCOM), also referred to as Remote Automation, requires all of the COM permissions discussed above. In addition, it needs to access resources across the network. If a request is received using Anonymous authentication, the IUSR_<servername> account user name and password credentials will be used to connect to the remote DCOM server. Unless the computer running IIS is also a domain controller, the remote computer by default will not know who the IUSR_<servername> account is (it only exists on the local computer running IIS). Adding access and launch permissions to the group Everyone does not help in this case because DCOM will not map access by an unknown account to the guest account in the same way that the Server service does for file sharing. The computer running DCOM server must explicitly know the account that is being used.

When you have IIS applications accessing resources (including DCOM resources) on remote computers, you need to have all the computers involved participate in a domain relationship. Then, in Internet Manager, you can change your anonymous account to an account in the local or trusted domain. Now, all computers in the domain structure will recognize the account and can explicitly add/delete access to their network resources for that account or any group that the account is a member of.

Be aware that if Basic authentication is used for an IIS request, access to network resources (including DCOM servers) will be done in the context of the user whose credentials were passed with the request. If the user specified does not have permissions to launch or access the DCOM server, the request will fail.

If the IIS request is validated using NTLM authentication, the impersonation level does not imply knowledge of the user name and password credentials. Therefore, access to network resources, regardless of the permissions on the resource, will be denied (with the exception of NULL Session resources).

For more information, please see article Q172925: Security Issues with Objects in ASP and ISAPI Extensions in the Microsoft Knowledge Base.


Accessing Data With ASP

ASP with IIS offer the Web developer flexible, easy to use, scaleable methods to interact with ODBC compliant databases for Internet or intranet applications. Using ASP and the Microsoft Data Access Components (MDAC) as part of your development not only means that you can initially develop a solution using Microsoft Access and scale up to Microsoft SQL Server 6.5, but that you can access any other databases that are ODBC compliant. With the additional power of Microsoft Transaction Server (MTS), you can create highly scalable multi-tier applications that support Web-based transactions.

This section includes:

  • Introducing ADO: A brief overview of ActiveX™ Data Objects.
  • Remote Data Binding with RDS: An introduction to Remote Data Services and client-side data binding.
  • Processing Transactions: How and when to add transactions to your Web site.
  • Simplifying Development With Process Isolation: The benefits of out-of-process component development.


Introducing ADO

ActiveX™ Data Objects (ADO) implements a common programming model for any OLE-DB provider. ADO is built around a set of core functions that all data sources are expected to implement. In addition to this core set of features, ADO can also access the unique features of specific data sources through general OLE-DB service providers. ADO utilizes native OLE-DB data sources, including a specific OLE-DB provider that provides access to ODBC drivers. ADO was designed to replace the need for all other high-level data access methods. ADO can access relational databases, or ISAM, or text, or hierarchical, or any type of data source—as long as there is an ODBC-compliant data access provider for it.

ADO was first introduced in IIS, where it was used in conjunction with ASP. Its primary benefits are ease of use, high speed, low memory overhead, and minimal disk space requirements, which makes it ideal for server-side scripting. In fact, ADO is the recommended technology for data access for ASP applications. ADO can be called directly from server-side scripts.

In ADO, the object hierarchy is de-emphasized. Unlike earlier data access methods, you no longer need to navigate through a hierarchy to create objects; most ADO objects can be created independently. This allows you greater flexibility in re-using objects in different contexts. It also allows you to create only the objects you need, resulting in fewer ADO objects and a smaller working set. ADO also takes advantage of ODBC 3.0 connection pooling.

What ADO cannot do, however, is provide remote data to the client. In other words, once the data has been retrieved and sent to the browser, the user cannot easily manipulate it or make changes to it within the client application. Data operations—including filtering and record modifications—must take place on the server, where the actual data manipulation objects reside.

Enhancing Performance on SQL-only Systems

The ADO objects are, by default, assigned the Apartment threading model in the registry. This model guarantees that each object is allocated a single thread for the life of the object, and all calls to the object execute on the same thread. While this model provides significant improvements over the single- or free-threading models, it also has its performance drawbacks. For instance, if you store Microsoft Data Access Components, like the ADODB.Connection object, in the ASP Session object, it will cause the Web server to enforce a limit of one thread per user session.

If the only database you intend to use with ASP is Microsoft SQL Server (that is, you don't plan to use Microsoft Access .MDB files with ASP) and you create instances of Database Access Components that you store in the Session object, you can enhance performance by changing the threading model for some Database Access Components from Apartment to Both in the registry. To change from Apartment to Both, double-click Makefre15.bat in the ADO installation folder (C:\Program Files\Common Files\System\Ado, by default). To reverse the process, (that is, to change the threading model from Both to Apartment) double-click Makeapt15.bat in the ADO installation folder.

For more information on the recommended threading models to use with the ASP Session object, see Setting Object Scope in the Active Server Pages documentation.

For more information, see the ADO Overview.


Remote Data Binding with RDS

Remote Data Service (RDS) replaces the Advanced Data Connector (ADC), which is now considered obsolete. In particular, the ADC remoting functionality (the ability to manipulate and modify sets of records on the client) has been integrated into ADO as RDS. Client-side RDS components send queries to the Web server. The server-side RDS components process these requests and send them to the DBMS via a business object. The DBMS responds to the request, sending back the data. The RDS components on the Web server transform that data into an ADO Recordset object. The data is parsed for transport to the client and sent back across the network to the client computer where it may be displayed in data-aware controls, such as a text or combo box, which are bound to the data by the AdvancedDataControl object. One AdvancedDataControl can channel data to many data-aware controls.

For more information, see Getting Started with Remote Data Service.


Processing Transactions

The integration of IIS and Microsoft Transaction Server (MTS) has made it easy to manage transactions. For all transactions, the "unit of work" is the ASP page. Transactional pages begin with the new @-directive, <% transaction=required %>. For these pages, a new ASP built-in object, ObjectContext, is created that can be used to commit or abort the transaction. Unless the SetAbort method is called, the transaction will commit automatically when the page has completed processing. You may also define two additional event handlers on transactional pages, OnTransactionCommit and OnTransactionAbort. Only one of these subroutines will be called, depending on the outcome of the transaction.

For more information on MTS transactions, see Transactions in the Microsoft Transaction Server Programmer's Guide. To view samples of transactional scripting, see Creating Transactional Scripts in the Active Server Pages documentation.


Simplifying Development With Process Isolation

In earlier versions of IIS, all ISAPI applications (including ASP) shared the resources and memory of the server process. Although this increases performance, unstable components would often cause the server to crash--not an acceptable behavior for a mission-critical application like IIS. To make matters worse, in-process components couldn't be unloaded unless the server was restarted—which meant that modifying existing components would effect all sites that shared the same server, whether they were directly effected by the upgrade or not.

Thanks to close integration with Microsoft Transaction Server, IIS 4.0 applications can now be started in an isolated process. There are two reasons for doing this: component development and fault isolation.

Component Development

Rather than taking down the entire server to update a single component, process isolation allows you to stop and restart just a single application. To add an updated component to an application, or an entirely new application, you had to stop the Web server service, replace the old DLL with your new version in its shared location on the server, and restart the Web service again. Now with an isolated process, you can update a production Web site without shutting down your system.

Fault Isolation

Process isolation limits the effects of such a crash to the single application that caused it. In addition to protecting your server from the crash, the application can be configured to restart automatically as often as you like. In the case of an application fatal error, the application's process is automatically terminated. Since the application is running in the MTS system process, all transactions in progress are aborted. The system event log stores a record of the event, and MTS restarts the application. The only ones affected by the failure are clients with outstanding requests to that specific application.

An IIS application runs in the IIS process by default. If you decide to run your application as a separate process, you will need to mark your application to Run in separate memory space on the Virtual Root property page. You must first create an application for your virtual root, if you haven't already done so. Components that are to run in the new process must be installed into the appropriate MTS package. For more information, see Creating MTS Packages.

Out-of-process Components

Note that out-of-process applications are different from out-of-process components, executables that are launched from within another application. When Server.CreateObject is used to launch an EXE, the following error may occur:

Server object error 'ASP 0196'
Cannot launch out of process component
/myvroot/launch_exe.asp, line 16

This error is the result of a safety mechanism in ASP that prevents the unauthorized launching of executables from within ASP. Not all executables are safe to use on the server, and may pose security risks as well. Because in-process components are faster, more secure and can be hosted by MTS, they are much better suited for server-side use.

If you still want to enable the use of out-of-process components, you must first set the AspAllowOutOfProcComponents metabase property to TRUE. This metabase setting is accessible on both the IIsWebService and the IIsWebVirtualDir Admin objects.

  • Take note that if you set the AspAllowOutOfProcComponents property to TRUE on the IIsWebService object, all in-process applications will be able to launch executables from script. An in-process application is a directory that has been marked as an application starting point, but which does not have the Run in separate memory space option selected.
  • If you set the AspAllowOutOfProcComponents property to TRUE on the IIsWebVirtualDir object, and the application is marked to Run in separate memory space, only the affected application may launch executables from script. If the application is set to run in process, the setting will have no effect.

The following ASP code demonstrates the steps required for setting the AspAllowOutOfProcComponents parameter on the IIsWebService Admin object.

Note You must have adequate permission to modify the metabase. If you attempt to modify the metabase from an ASP script without sufficient privileges, you may encounter an Invalid Syntax or other error. In order to modify the metabase from script, you must first require authentication as a user with administrative rights.

<%
   ' Get the IIsWebService Admin object
   Set oWebService = GetObject("IIS://LocalHost/W3svc")

   ' Enable AspAllowOutOfProcComponents
   oWebService.Put "AspAllowOutOfProcComponents", True

   ' Save the changed value to the metabase
   oWebService.SetInfo
%>

Important You will need to restart the Web server service after making this change.

For more information about setting metabase properties using the Admin objects, see the section entitled IIS Adminstration in the Programmer's Reference.

Security Considerations for Out-of-Process Applications

Out-of-process applications and components, including ISAPI filters and extensions, will not be able to access metabase properties. This restriction is primarily one of security, and exists to prevent unauthorized changes to the metabase. If you want to allow out-of-process applications to access the metabase, you must do one of the following:

  1. Give the IWAM_<machine> account access to the metabase (this is probably a bad idea from a system security standpoint.)
  2. Change the identity of the out-of-process MTS package from the interactive user to a specific user account, and give that account access to the metabase (this is also somewhat risky, but limited to a single package.)

For more information on changing package identity, see Setting MTS Package Properties in the Microsoft Transaction Server documentation.


Debugging Your Application

You've written your application, but it doesn't quite work as you expected. Sometimes you get an error message, but sometimes you get nothing. How do you track down pesky bugs in a system that provides little feedback?

This section introduces some debugging techniques that have been used with great success by developers of ASP components and ISAPI extensions.

  • Disabling ASP Exception Handling: How and when to disable the try/catch exception handler.
  • Establishing a Debugging Environment: Step-by-step instructions for debugging components and ISAPI extensions.
  • Verifying Component Permissions: How to track down a problem with permissions.


Disabling ASP Exception Handling

ASP experts should recognize this error code.

ASP 0115
Unexpected error
A trappable error occurred in an external object. The script cannot continue running.

This error is caused by an access violation in a component process. The reason ASP is able to display a message after faults like this is because the crash is detected by the built-in exception handling of the ASP process. With IIS 4.0, it is possible to run an ASP application in a isolated process. The extra overhead in system resources required to do this may be worth the added security of knowing a crash will not affect other applications.

When you are debugging an application component, however, it is often easier to detect where faults occur when exception handling is disabled. You can disable exception handling from the Process Options page of the ASP Configuration property sheets. However, the page only appears when you are editing a process level application. This only happens

  1. When the application has been marked as isolated (in its own process), or
  2. When editing the master level properties, which affects all the in-process applications as well.

When you deselect the Enable debug exception handling check box on the Process Options property page, serious application errors will not be captured by ASP. Instead, they will appear as faults in the application process and components running in the same process.


Establishing a Debugging Environment

There are several ways to establish an environment for debugging your server components and ISAPI extensions. If you are using a debugging tool capable of attaching to a Windows NT process, you can use this functionality to debug your component or extension. For example, if you are debugging an ISAPI extension with Microsoft Visual Studio™ you should take the following steps.

  1. Start the iisadmin process. This can be done from the command line with the command net start iisadmin. You can also use the Services dialog box from the Control Panel to start the IIS Admin Service, which will start iisadmin.
  2. Launch Visual Studio and select the Attach to Process command from the Start Debug sub-menu of the Build menu.
  3. Click the Show System Process check box.
  4. Select the inetinfo process from the list and click OK.
  5. Start the w3svc service. This can be done from the command line with the command net start w3svc. You may also use the Services dialog box in the Control Panel to start the World Wide Web Publishing Service.

If the debugging tool you are using is not capable of attaching to a Windows NT process, you should take the following steps to establish an appropriate debugging environment.

  1. Open the Services dialog box in the Control Panel.
  2. Select the IIS Admin service and click the Startup button.
  3. Select the Allow Service to Interact with Desktop check box and click OK.
  4. Repeat steps 2 and 3 for all processes that run under the IIS Admin process, for example World Wide Web Publishing Service, and FTP Publishing Service.
  5. Use the Registry Editor (REGEDIT) to add a subkey named Inetinfo.Exe to the HKEY_LOCAL_MACHINE/Software/Microsoft/WindowsNT/CurrentVersion/Image File Execution Options key.
  6. Add the following entry to this new key:
    Debugger = <DebuggerExeName> where DebuggerExeName is the full path to the debugger you are using.

When the World Wide Web Publishing Service is started, your debugger will also be launched. You can now set appropriate break points in your ISAPI extension.

You won't be able to set breakpoints in a component's source code until the component has been loaded into memory. First, you will need to start Internet Explorer and view the .ASP page containing the object. As soon as the page is loaded, you should be able to set breakpoints in your component. Select Refresh to view the page again, and trigger the breakpoints you selected. If the component cannot be loaded even once (for instance, if the fault occurs in component startup code) you will need to load the component DLL prior to starting the debugging session. (See step 11 below.)

In some cases, you may not be able to use either of the two procedures outlined above. If you have difficulty using either of these strategies, there is a third approach, which has been described in previous releases of IIS. This third approach requires the establishing of NT security privileges as well as making changes to the registry. It will also disable your ability to run IIS as a service. This approach should only be attempted if the previous two strategies have failed.

  1. Use the User Manager for Domains administration tool (USRMGR) to add the Log on as Service, Act as part of the operating system and Generate security audits rights on the local computer to the NT account you will use when debugging the ISAPI extension.
  2. Use the Distributed COM Configuration utility (DCOMCNFG) to change the identity of the IIS Admin Service to the user account you will use for debugging.
  3. Use the Registry Editor (REGEDIT) to remove the LocalService keyword from all IISADMIN-related subkeys under HKEY_CLASSES_ROOT/AppID. This keyword may be found in the following subkeys:
    {61738644-F196-11D0-9953-00C04FD919C1} // IIS WAMREG admin Service
    {9F0BD3A0-EC01-11D0-A6A0-00A0C922E752} // IIS Admin Crypto Extension
    {A9E69610-B80D-11D0-B9B9-00A0C922E750} // IISADMIN Service
    The LocalService keyword may be found in additional subkeys of AppID.
  4. Add LocalServer32 subkeys to all IISADMIN related subkeys under the CLSID node of the registry. This will include subkeys corresponding to all of the subkeys you removed in the previous step. Set the default value of these new keys to <path>\inetinfo.exe -e w3svc. (<path> is normally "c:\winnt\system32\inetsrv".)
  5. Stop the WWW and FTP services from the Microsoft Management Console, or from the Services dialog box in the Control Panel.
  6. Start Visual Studio and select the Debug tab in Project Settings window.
  7. Enter C:\WINNT\System32\Inetsrv\inetinfo.exe in the Executable for debug session field.
  8. Enter "-e w3svc" in the Program Arguments field.
  9. Select the Link tab in the Visual Studio Project Settings Window.
  10. Enter the name and path of the ISAPI extension you are debugging in the Output file name field.
  11. Optionally, add your component DLL to the list of Additional DLLs that are loaded before the application starts. This will allow you to set breakpoints in component startup code.
  12. Click the Go button to start the debugging session.

Note After you have completed the debugging session, you must reverse steps five through one to restore the previous settings and allow IIS to be run as a service.


Verifying Component Permissions

Sometimes Server.CreateObject fails with an ASP 0177: Server.CreateObject Failed error. This can happen even if the component works fine on the same computer in Microsoft® Visual Basic® or using ASP on other computers.

One likely cause for this behavior: the authenticated user does not have permission to invoke the COM object. In the simplest scenario, the authenticated user doesn't have access to the component's DLL or executable. In many cases, however, the component depends on other DLLs that the authenticated user does not have permission to access.

Remember that a majority of your users will be accessing the site anonymously, using the IUSR_<servername> account. Although you may be tempted to grant blanket administrative privileges to this account, it is a better first step to try invoking the component from another tool such as Visual Basic. This approach is preferred because it checks for permission problems, as well as verifying that the component is registered properly on the server. If the component cannot be created from Visual Basic, you are probably not dealing with a permissions problem at all.

If you believe you are dealing with a permissions problem, check permissions on the component and any dependent files such as other DLLs. If you still are unable to track down the problem, you may need to resort to other means such as a systematic file system permissions search, or enabling Windows NT File and Object Auditing.


Programmer's Reference

Welcome to the IIS Programmer's Reference. This section provides detailed information about special event methods and interfaces available for components running on a Web server that supports Active Server Pages (ASP), the storage of your custom IIS configuration data and how you use built-in objects to manipulate that data, creating and maintaining logging modules, and a set of interfaces that you can use to create HTTP server extensions.

This section contains:

  • Creating Components for ASP, which provides overviews and object reference material to help you develop server components for use with ASP.
  • IIS Administration, which provides overviews and reference material to help you manage the IIS configuration programmatically.
  • Logging Interface, which provides overviews and reference material to help you generate server activity logs without interfering with other server processes.
  • ISAPI, which provides overviews and reference material to help you create extensions and filters for HTTP servers.


Creating Components for ASP

You can create ActiveX™ components for use in a variety of Internet and intranet scenarios. For example, you might create a component that determines if a customer placing an order through the Internet has sufficient credit to make a purchase. In an intranet environment you might create a component that managers could use to update employee records in the company database. This document describes the special event methods and interfaces available to components running on a Web server that supports Active Server Pages (ASP).

You can use any language that supports Automation to develop your component. The choice of language involves many considerations: your familiarity with it, tools support, run-time performance, threading models, code complexity, and the size of the compiled code. Languages and products that can be used to write Automation components include Microsoft® Visual C++®, Microsoft Visual Basic®, and Java.

This section contains:

  • Planning for Component Development
  • Developing and Deploying Your Component
  • Built-in Object Reference
  • Additional Resources on Creating Components

To make best use of this document, you should be familiar with the Microsoft Component Object Model (COM). For information on COM, see COM Concepts. For a step-by-step tutorial on building components with Visual Basic and Visual J++, see Writing Active Server Components in Web Applications. For similar instruction on building a transactional component, see Developing Applications for Microsoft Transaction Server with Visual Basic.


Planning for Component Development

There are a number of decisions involved when you design IIS components. Each of these decisions affects the others; decisions you make about scope will impact your choice of a threading model, for example.

This section contains:

  • Defining Component Functionality.
  • Determining Component Scope.
  • Selecting a Threading Model.

Although it is impossible to prescribe exact rules for designing components, there are some specific issues you should be aware of before you develop a component for ASP. The component design guidelines provide these details.


Defining Component Functionality

Your first task in developing your component for ASP will be to determine the component's purpose. You can create components that perform a simple function, such as maintaining a page count, or a complex function, such as finding the probability of your company attaining a future value. The following functional areas are some examples of ways in which you can classify component functions.

Business Components

Business objects rely on business rules. You should create them to fit a wide variety of business situations, but with enough specific functionality to be useful. For example, a Quantity on Hand component would be useful in a wide variety of business application scenarios. The following are examples of business rules you could build into your component:

  • Inputs (primary keys for product identification, quantity required, and so on).
  • Queries (pre-defined query strings).
  • Persistence/Transaction (update rules).
  • Security (roles, permissions, and so on).

You should create business components that are sufficiently granular to provide meaningful functionality and sufficiently general to work as building blocks. Your organization, for example, may need to aggregate components to a higher level. For example, rather than a Quantity on Hand component, you may choose to aggregate several components into an Inventory Control component. The problem with this level of aggregation, of course, is that there may be subcomponents in Inventory Control, such as Quantity on Hand, that would be useful in addressing business functions that are not limited to inventory control, such as a Sales Order function.

Utility Components

If you decide that there is some general function that many people writing ASP scripts will want to do, you should consider writing a utility component. Your utility components should offer a very high degree of flexibility, and should not rely on specific business rules. A utility can be applied to a wider variety of situations than, for example, a business component. Content Rotator and Counters are both good examples of utility components.

Data Components

If you are developing an application that shares data you should consider merging that data into a single component. In the context of COM the term data object is used to mean any object that supports an implementation of the IDataObject interface. Implementations vary, depending on what the data object is required to do.

Presentation Components

You should create presentation components in order to obtain information from users. The ASP Request and Response objects are built-in objects that you can use to create your presentation components. For example, you might want to create an object that combines data access capabilities with security information so that you can provide your users with a consistent way of validating client access.

Presentation components compose the presentation tier in a multitiered application. It is important that your application design include a presentation tier to provide adequate separation of your business components from particular physical implementations. The following scenario illustrates why presentation components are needed.

You have developed an inventory control component that is called both by a Microsoft Visual Basic client running on the Inventory Manager's desktop and by remote inventory warehouse managers using ASP. The Visual Basic client relies on a data structure that the Inventory Control object passes back. The .asp file can not use this data structure, because its scripting language is designed only to interpret variant data. In this scenario you should create a presentation component that reads ASP requests and passes them on to the business component. Inserting the presentation layer allows your business component to remain unchanged when new clients are added. For more information on multitiered applications, see Advanced Web Application Development.


Determining Component Scope

Scope refers to how you instantiate your component in IIS. You do not have any direct control over the scope that a script writer will assign to your component. They can place it in applications, sessions, or pages. In designing your component, however, you should be aware of the implications scope has on performance. The component design guidelines summarize these implications.

An object instance can be created either with the Server.CreateObject command or with the <OBJECT> tag. For a majority of components, the most appropriate way for you to create an object instance is to use the <OBJECT> tag in the ASP script that requires the functionality offered by your component. This is known as page level scope.

For more information on setting scope, see Web Applications.


Selecting a Threading Model

Whether it is used over the Internet or an intranet, your component will need to deal with simultaneous calls. How it deals with simultaneous calls is largely determined by the threading model you choose. This choice will have significant implications on your component's responsiveness, particularly in large volume Internet scenarios:

Your options for threading models are:

  • Single (not recommended)
  • Apartment (recommended for components that have page scope)
  • Free (not recommended)
  • Both (recommended for all components)

The threading recommendations outlined in Component Design Guidelines summarize the technical implications for choosing between the threading model options.


Component Design Guidelines

All of your component design decisions are interrelated. Your component's function will impact what scope script writers will give it, which, in turn, will impact your selection of a threading model. The guidelines below represent two possible ways you can approach making these decisions:

  • Scope
  • Threading

These guidelines are not hard-and-fast rules, but are design recommendations to help you develop high-performance components faster.

Scope view

You should give the majority of your components page-level scope. Most components that you develop around a set of business rules (business objects) should be given page scope. If the components are going to participate in transactions, they should be registered with the Microsoft® Transaction Server (MTS) explorer. Any components that you give page-level scope to should support either the Apartment or Both threading model.

You should consider using session scope if you want a component to manage an aspect of an ASP application that spans multiple scripts, but relates to a particular user. For example, if you know the application design requires multiple ASP scripts to access a database, you should create a single database access component and give it session scope. The database access component retrieves the required record set, and shares the data between all scripts in the session.

Be very cautious about giving a component application scope. Some general utility components, such as a counter component, could require application scope, but there are very few situations where a component will require application scope. You should store the data required by the component at the application level and give it session or page scope. Components with application scope should be developed with the Both threading model and should aggregate the FreeThreadedMarshaler. You should not give application scope to transactional components (those registered with MTS explorer).

Threading view

Although it is possible for you to use any of the four threading models, it is recommended that you develop your components with either the Apartment or Both model. There are serious performance limitations with the Single and Free models. For a detailed explanation see the following:

Single Threaded

and

Free Threaded

You can use the Both threading model for all types of ASP components. All Both threaded components should use the COM Library function CoCreateFreeThreadedMarshaler to create a free threaded marshaler object. If you aggregate the free threaded marshaler object, you can make calls between threads without any marshaling or thread switches. For more information on free threaded marshaler objects, see In-process Server Threading Issues and CoCreateFreeThreadedMarshaler in the COM section of the Platform SDK.

The only disadvantage of building components using the Both model is that it does not allow for serialization of calls to the component. This means that your component will need to guarantee thread safety. Building in thread safety may slow down your development time, but will allow your component to be more suitable for use in session or application scope.

You can use the Apartment model for components with page or session scope. However, when you create Apartment model components in a session, the session is locked down to a single thread. This slows access time.

You should not use the Apartment threading model for components that you plan to give application scope. Creating an instance of an Apartment model object with Server.CreateObject will generate an error. For example, if in the following script MyObj was an apartment-threaded object, the script would generate an error.

MyObj = Server.CreateObject("MyObj")
Set Application("Myapp") = MyObj

If you place an Apartment-threaded component in an application with the <OBJECT> tag, it will not generate an error. However, it will cause access to be slow. In addition, if you develop a component with the Apartment model and give it application scope, it will run in the System security context, rather than the context of the current user, thereby making it unacceptable for scenarios which rely on Windows NT® security.


Single-Threaded

This threading model is not recommended for components to be called by ASP pages. Single-threaded objects are not suited for applications that need to accommodate a large volume of users simultaneously. Using these objects can result in a deadlock when multiple users try to access the object simultaneously. All calls to Single-threaded objects are serialized through one thread, the COM Main thread. Calls to these objects from other threads are marshaled to this thread. Only one thread at a time can enter a set of Single-threaded objects, and it must be the same thread each time.

Finally, Single-threaded objects work in the context of the SYSTEM account and have all permissions associated with the SYSTEM account. In most cases, this is not desirable for Web sites.


Free-Threaded

Building Free-threaded components is not recommended; if possible, you should use the Both model instead. One disadvantage of Free-threaded components is that you must register them with the MTS explorer in order to access the ObjectContext object, whereas all Both- or Apartment-threaded components can access ObjectContext. This means that Free-threaded components that you have not registered with MTS explorer can only access the ASP built-in objects through the ScriptingContext object. This method of accessing the built-in objects is considered less suitable for ASP components than using ObjectContext. For more information, see accessing the ASP built-in objects.

The final problem with Free-threaded components is that, like Single-threaded components, they run in the SYSTEM context, rather than the context of the logged on user. As a result, the Free-threaded model is not acceptable for scenarios which will rely on Windows NT® security to control access to objects.


Developing and Deploying Your Component

Once you have a plan for developing your component, you will need to implement this plan using an appropriate development environment. Although you can develop components using any environment that is capable of creating COM components, there are some minor discrepancies in how the various environments view COM components. This section will explain how to implement your component design in the C++, Microsoft® Visual Basic®, and Java development environments. It is divided into five areas:

  • Implementing Your Component
  • Deploying Your Component
  • Accessing the ASP Built-in Objects
  • Application Isolation Issues
  • Security Issues


Implementing Your Component

You can implement your component using any development environment that is suitable for creating COM components. There are, however, some differences in how different environments approach this procedure. This section briefly outlines the approaches to implementation taken by Visual Basic, Visual J++ Visual C++. More information on implementation can be found through the section titled Additional Resources on Creating Components.

You should implement your server component as a DLL (in-process) server. Because you implement your component as a DLL, it will run in the same process as the Web application that contains the ASP script that creates the component instance. Running a component in-process with applications provides superior performance to out-of-process servers.

If you implement your component as an out-of-process server there are several issues which you should consider. These issues are discussed in the Advanced Web Application Development topic, Simplifying Development with Process Isolation.

If you have trouble registering components on Windows NT Server and Windows NT Workstation, you may be using the wrong version of Regsvr32.exe. Use the version that is installed with Internet Information Server or Personal Web Server. By default, this file is installed in C:\Winnt\System32\Inetsrv.


Implementing with Visual Basic

If you use Microsoft® Visual Basic® to implement your component, you will create an ActiveX™ DLL file. An ActiveX DLL is a COM component that exposes its methods to clients through Automation. The Visual Basic 5.0 New Project window provides a tool to assist you in creating the basic framework for an ActiveX DLL.

ActiveX components use Automation to present an easy way of creating object instances. Components that use Automation are known as Automation servers. Clients of Automation servers are known as Automation controllers. When an ASP script creates an instance of an object from your component, it is acting as an Automation controller.

For more information on Automation, see Automation in the COM and ActiveX Object Services book of the Platform SDK.


Implementing with Visual J++

The component model supported by Microsoft® Visual J++™ is known as JavaBeans, the Java equivalent of ActiveX™. If you choose to develop your component with Visual J++, you will create classes that expose methods. When an ASP script calls your component, it is hosted by the Microsoft Virtual Machine (VM). ActiveX components and JavaBeans are completely integrated in the VM. To a Java programmer, an ActiveX component can be treated as just another JavaBean, and to a Visual Basic programmer, a JavaBean can be treated as an ActiveX component.

One key difference between JavaBeans and ActiveX components is the tool that you use for registration. You register ActiveX components with regsrv32.exe, while you can register JavaBeans with the javareg.exe tool, which is installed with the VM. When you use JavaReg you must specify the Progid switch. For example, the following code creates a Progid for a Java class called MyClass.

javareg /register /class:MyClass /progid:MyClasses.FirstClass

Another difference between the two models is that you can create an instance of a JavaBean by using a Java Moniker. A Java Moniker is a name that describes the path of the Java class file to the VM. You use the Java Moniker to create an instance of an object from your component in exactly the same way as a Progid is used with Server.CreateObject. For example, if a Java Bean was defined in the path C:\MyBeans\coolbean.class, the following script would create an instance of coolbean.

<%GetObject ("Java:C:\MyBeans\coolbean.class")
%>

Notice that when you create an instance of a Java class using a Java Moniker you must use GetObject rather than Server.CreateObject. When you create an object with GetObject, the object will not have access to the ObjectContext object. You should not create an object instance with a Java Moniker if the object needs to access the ASP Built-in Objects or participate in transactions.

As with ActiveX components, you can develop JavaBeans with a dual interface to support v-table access. The Microsoft SDK for Java includes a tool called jactivex.exe which you can use for vtable access to COM interfaces and methods.

Your Java component can access the ASP Built-in objects by calling the Java class files which are created when you install IIS. The classes use native Java types, and support native Java interfaces.You can refer to these classes directly, however, the Java Component Framework (JCF) simplifies creating Active Server Components. The JCF creates new interfaces that expose the ASP object model. The goal is to retain all of the features and flavor of the ASP Programming model, but to expose it in a way that is more natural for the Java programmer.

For more information, see the Java Component Framework Reference.

For more information on developing JavaBeans, see the Microsoft SDK for Java.


Implementing with Visual C++

Implementing your component with Microsoft Visual C++ provides you with a great deal of flexibility. In addition to this flexibility, Visual C++ provides you with more direct access to the mechanisms used by COM for creating and using object instances. The mechanism for creating an instance of a COM object, for example, is largely hidden from Visual Basic developers. If you are developing COM components with C++ you will need a more complete understanding of COM. Visual C++ provides you with the Active Template Library, a tool to assist you in developing COM components. See COM Concepts for additional resources on COM.

Please note that the Microsoft Transaction Server (MTS) headers and library files must be copied into your development environment before building Server Components that use the IObjectContext interface to access the Active Server Pages (ASP) intrinsics. MTS installs its headers and library files in the \program files\mts\ directory. These files are only installed if you select Developer Tools from the Setup dialog for MTS options.


Type Libraries

Type libraries are files that provide information about your component. Development tools use the information contained in type libraries to make it easier for you to determine the methods and properties supported by your component objects. It is recommended that you create a type library for use with your component. If you develop an ActiveX DLL with Visual Basic, a type library is automatically generated when you make the DLL.

For more information on type libraries see the Automation section of the Platform SDK.


Deploying Your Component

Your component's functionality will be exposed in ASP through a script contained in a file with the .asp extension. When you group ASP script files into applications they share access to the built-in Application object. Another important aspect of applications is that you can isolate them from each other by running them in a separate memory space from IIS. If you choose to do this, you should review the Application Isolation Issues.

The way you define applications has changed in IIS 4.0. In previous versions, you defined an application by creating a virtual directory. In IIS 4.0 you can use the Microsoft Management Console to define an application starting point. The application boundary will extend down the virtual directory structure until it reaches the starting point of another application. The following table illustrates these two approaches to defining applications.

IIS 3.0 Application Structure | IIS 4.0 Application Structure
Virtual directory = /Myapp | Virtual directory = /Myapps/Toplevel
Physical directory = C:\Myapps | Physical directory = C:\Myapps
Files: C:\Myapps\Global.asa, C:\Myapps\Default.asp | Virtual directory = /Myapps/Nextlevel
 | Physical directory = \\Remote1\remoteasps
 | Files : C:\Myapps\Global.asa, \\Remote1\remoteasps\default.asp

Notice that in IIS 4.0 you can create multiple levels of virtual directories, which allow your applications to span multiple physical locations.

In addition to using the Management Console to define applications, you can use ASP scripts to perform these tasks by accessing the IIS Admin Objects.


Application Isolation Issues

With IIS 4.0 you have the option of running an application in a separate process from IIS. To accomplish this, select the Run in separate memory space box in the property page for a directory, or by using the AppCreate method exposed by the IIS Admin Objects.

If you isolate an application, any ASP scripts and ISAPI DLLs stored on the physical directories included within the application boundary will be run in an isolated process. The following diagram illustrates the difference between an isolated application and an application run in the same server process as IIS.


Security Issues

If you store your server component in the Session object, the server will free the component in the security context of the Web server instead of the security context of the client who owns the session.

If your component requires that its cleanup or destructor method run in the security context of the client, it should save the client's security context during its creation method so that it can recall this context during its cleanup.

You can obtain the security context of the client by calling the OpenThreadToken function. In your component's destructor method you can call the SetThreadToken function to set the security context to the previously saved client's context. This procedure is outlined in the following pseudo code example which includes the necessary Win32 API functions. This is not a working example, the italicized functions all require additional parameters.

//saving the client's security context
OpenThreadToken(hTokenClient,);
// . . . creation code

//make a copy of the current security context
Success = OpenThreadToken(
          GetCurrentThread(),
          TOKEN_QUERY|TOKEN_IMPERSONATE|TOKEN_EXECUTE,
          TRUE,
          HToken);
//set the security context to the previously-saved client context
SetThreadToken(hTokenClient);
// . . . destruction code
//reset the thread to its standard security context
SetThreadToken(hTokenSave);

Note In the previous example, the standard security context is saved in hTokenSave before the object calls the SetThreadToken function. This enables you to reset the thread to its normal security context after the object instance is destroyed. This is not a working sample.


Accessing the ASP Built-in Objects

In IIS 3.0, components could access ASP built-in objects through the IScriptingContext interface. Components that needed to access the built-in objects did so through page-level event methods. While this is still supported, an alternative now exists and is recommended as an improvement over page-level event methods.

You can now use the ObjectContext object to access the built-in objects. ObjectContext makes IIS applications better suited for large scale scenarios and provides support for transaction processing. It is highly recommended that you convert your existing ASP-based applications to this new approach if they are high-volume applications. This conversion is required if your applications support transaction processing.

If your ASP application includes transaction processing scripts, any object instances from your component that participate in transactions must be registered with the Microsoft Transaction Server (MTS). By registering your component with MTS, you will be able to take advantage of the MTS run-time environment benefits.

In the following sample, a script calls two objects, CheckInventory and PostSale. Because both objects participate in the transaction, each must be registered with MTS.

<%@Transaction = Required%>
Dim Quantitytocheck, Accountocheck, Invstatus, Acctstatus
   Set Invstatus = Server.CreateObject(MyObj.CheckInventory)
   Set Acctstatus = Server.CreateObject(MyObj.PostSale)
      quantityout = Response("Currentquantity")
      accountout = Response("Currentaccout")
   Set Quantitytocheck = Invstatus.checkqoh(quantityout)
      If Quantitytocheck = OKStatus
            Set Accounttocheck = Acctstatus.postit(accountout)
        Else Context.SetAbort
      End if
%>

In the above example, MyObj.CheckInventory and MyObj.PostSale would access ASP built-in objects through the MTS ObjectContext. The following sample demonstrates accessing the Response object.

Public Function GetResponse(ByVal stringin As Variant)
   Dim curres As ObjectContext
   Set curres = GetObjectContext ()
   GetResponse = curres("Response").Write (stringin)
End Function

To see complete sample components that use ObjectContext to access the ASP built-in objects, see Developer Samples.


Page-level Event Methods

In IIS 3.0, objects accessed the built-in objects by creating an instance of the ScriptingContext object in a page-level event method. This approach is supported in order to be compatible with existing ASP applications. This method of accessing the built-in objects is not recommended. Any new components that you develop should use ObjectContext to access the built-in objects. It is recommended that you modify any components that rely on ScripingContext to use ObjectContext instead.

You can implement two page-level event methods, OnStartPage and OnEndPage , in your component. These methods are optional. ASP pages will work with any Automation object, regardless of whether these methods are implemented.

When the server creates an object instance, it looks for OnStartPage and OnEndPage methods associated with that object's IDispatch interface. If the object has implemented these methods, the server will automatically call the OnStartPage method during script processing before the object is used and call the OnEndPage method when all scripts on the ASP page have been processed.

The only exceptions are objects created with application scope, which never receive OnStartPage or OnEndPage method calls. As the component design guidelines indicate, very few objects should be given application scope. For more information about application-scope objects, see the Global.asa Reference.

Because objects that have been given application scope do not receive a call to the OnStartPage method, they cannot depend on its functionality.

It is recommended that your object, regardless of scope, handle the situation in which the OnStartPage method fails or is not called. A common example of the latter is occurs when the object is created in a way other than the Server.CreateObject method provided by ASP.


Built-in Object Reference

You can use the Active Server Pages (ASP) built-in objects to provide a connection between your component and clients accessing them through IIS. The way you access the built-in objects from a component is determined by your development environment. This section defines the built-in objects from the perspective of three different languages: C++, Java, and Microsoft® Visual Basic®. ASP scripts always access the built-in objects through the Visual Basic Object Model. These views are provided in:

  • C++ Interfaces
  • Java Class and Interface Definitions
  • Visual Basic Object Model


C++ Interfaces

ASP implements interfaces that enable your component to access the properties and methods of the ASP built-in objects. You should use the IObjectContext interface to access the built-in object interfaces. Your component can then use these object interfaces to access the properties, methods, and collections of the built-in objects.

The following table lists the built-in object interfaces.

Interface | Description
IApplicationObject | Calls the methods and properties of the Application object.
IObjectContext | Provides access to the Built-in Objects and transaction context.
IReadCookie | Retrieves the values stored in the read-only Cookies collection.
IRequest | Calls the methods and properties of the Request object.
IRequestDictionary | Indexes the subcollections of the IRequest interface. You can also use it to retrieve the individual values stored in the ClientCertificate collection.
IResponse | Calls the methods and properties of the Response object.
IScriptingContext (Obsolete) | Returns a pointer to an interface on one of the built-in objects: IApplicationObject, IRequest, Iresponse, IServer, or ISessionObject.
IServer | Calls the methods and properties of the Server object.
ISessionObject | Calls the methods and properties of the Session object.
IStringList | Retrieves the values stored in a string list, such as that in the QueryString, Form, or ServerVariables collections.
IVariantDictionary | Retrieves the items stored in the Application and Session Contents and StaticObjects collections.
IWriteCookie | Sets the values and attributes of a cookie stored in the write-only Cookies collection.

To use the IScriptingContext and object interfaces in a C++ component, you must include the header file Asptlb.h as shown in the following code.

#include "asptlb.h"

IIS installs the asptlb.h file in the \iissamples\sdk\include directory.

If you want to create a component that uses the ActiveX™ Template Library (ATL) 1.1, install ATL on your machine and select ATL COM Appwizard when creating a new project workspace in Microsoft® Visual C++®.

For more information about the built-in objects, see Built-in ASP Objects Reference.


IApplicationObject

The IApplicationObject interface exposes the methods of the Application object.

Method | Description
IApplicationObject::get_Contents | Retrieves the Contents collection.
IApplicationObject::get_StaticObjects | Retrieves the StaticObjects collection.
IApplicationObject::get_Value | Retrieves the value of a variable stored in the Application object.
IApplicationObject::Lock | Prevents other clients from accessing the variables stored in the Application object until the IApplication::Unlock method is called.
IApplicationObject::Putref_Value | Stores a variable in the Application object by reference.
IApplicationObject::put_Value | Stores a variable in the Application object by value.
IApplicationObject::Unlock | Releases a variable that was locked by the IApplication::Lock method.

Note This interface also supports all IUnknown and IDispatch interface methods. For more information, see \inetsrv\asp\cmpnts\asptlb.h, the header file installed with ASP.


IApplicationObject::get_Contents

The IApplicationObject::get_Contents method retrieves the Application.Contents collection.

HRESULT get_Contents(
  IVariantDictionary **ppProperties   //pointer to an
                                      // IVariantDictionary interface
                                      // pointer that receives the
                                      // Contents collection
);

Parameters

ppProperties
Points to an IVariantDictionary interface pointer that receives the Contents collection.

Remarks

The Application.Contents collection contains all variables and objects that have been given application scope with the Server.CreateObject command. You can iterate through the Contents collection with the get__NewEnum method exposed by the IRequestDictionary interface. You can also retrieve a specific member of the collection with the get_Item method.

See Also

IVariantDictionary


IApplicationObject::get_StaticObjects

The IApplicationObject::get_StaticObjects method retrieves the Application.StaticObjects collection.

HRESULT get_StaticObjects(
  IVariantDictionary **ppProperties  //pointer to an
                                     // IVariantDictionary interface
                                     // pointer that receives the
                                     // Contents collection
);

Parameters

ppProperties
Points to an IVariantDictionary interface pointer that receives the StaticObjects collection.

Remarks

You can iterate through the StaticObjects collection with the get__NewEnum method exposed by the IVariantDictionary interface. You can also retrieve a specific member of the collection with the get_Item method.

See Also

IVariantDictionary


IApplicationObject::get_Value

The IApplicationObject::get_Value method retrieves the value of a variable stored in the Application object.

HRESULT get_Value(
  BSTR bstrValue, //binary string that contains the name of the
                  // variable
  VARIANT * pvar  //pointer to a VARIANT that receives the variable
                  // value
);

Parameters

bstrValue
A binary string that contains the name of the variable to retrieve.
pvar
Points to a variant that holds the value for the variable specified in bstrValue.

Remarks

You can use this method to access variables that have been given application scope.

See Also

Application Object


IApplicationObject::Lock

The IApplicationObject::Lock method prevents other clients from accessing the variables stored in the Application object until the Unlock method has been called. For more information see the Lock method of the Application object.

HRESULT Lock(VOID);

See Also

Application Object


IApplicationObject::putref_Value

The IApplicationObject::putref_Value method stores an Automation object in the Application object. Equivalent to put_Value for non-Automation objects.

HRESULT putref_Value(
  BSTR bstrValue,
               //binary string that contains the name of the object
  VARIANT var  //VARIANT that contains the object reference
);

Parameters

bstrValue
A binary string that contains the name of the object to retrieve.
var
A variant that contains the reference to the Automation object.

Remarks

You can use this method to create a reference to an Automation object. You should be careful about using this method, because giving some Automation objects application scope will have a negative impact on server performance. For more information, see Selecting a Threading Model.


IApplicationObject::put_Value

The put_Value method stores a VARIANT in the Application object.

HRESULT put_Value(
  BSTR bstrValue,  //binary string that contains the name of the
                   // variable
  VARIANT var      //VARIANT that contains the variable value
);

Parameters

bstrValue
A binary string that contains the name of the variable.
var
A variant that stores the variable value.

Remarks

If the VARIANT being stored is an Automation object, ASP will attempt to store the default value of that object into the application. If ASP cannot get the default value, then the call will fail.

See Also

Application Object


IApplicationObject::UnLock

The IApplicationObject::UnLock method releases a variable that was locked by the Lock method.

HRESULT UnLock(VOID);

See Also

Lock


IReadCookie

You can use the IReadCookie interface to access the object returned from the read-only Cookies collection. Calling IRequestDictionary::get_Item on the read-only Cookies collection will always return an object that implements the IReadCookie interface.

Method | Description
IReadCookie::get_HasKeys | Retrieves a Boolean indicating whether the cookie has keys.
IReadCookie::get_Item | Retrieves the specified item from a cookie dictionary.
IReadCookie::get__NewEnum | Retrieves an enumerator for the Cookies collection.

Note IReadCookie and IWriteCookie are interfaces for the same object. If you have an IReadCookie pointer, you can use the IUnknown::QueryInterface method on an IWriteCookie pointer.

This interface also supports the IUnknown and IDispatch interface methods. For more information, see \inetsrv\asp\cmpnts\asptlb.h, the header file installed with ASP.

See Also

Cookies


IReadCookie::get_HasKeys

The IReadCookie::get_HasKeys method returns a Boolean value which indicates whether or not the cookie has keys.

HRESULT get_HasKeys(
  VARIANT_BOOL * pfHasKeys  //pointer to a Boolean that indicates
                            // whether or not the cookie has keys
);

Parameters

pfHasKeys
Points to a Boolean that indicates whether or not the cookie has keys.

Remarks

If the cookie has been implemented as a collection, this method will return TRUE. If the cookie has keys, you can use the IReadCookie::get__NewEnum method to retrieve an enumerator for iterating through the collection.

See Also

Cookies, IReadCookie::get_NewEnum


IReadCookie::get_Item

The IReadCookie::get_Item method retrieves the specified item from a cookie object.

HRESULT get_Item(
  VARIANT Var,  //VARIANT that contains the name of the item in the
                // collection
  VARIANT * pVariantReturn
                //pointer to a VARIANT that receives the item value
);

Parameters

Var
A variant that contains the name of the item in the collection.
pVariantReturn
Points to a variant that receives the item value.

Remarks

If Var is a string, the cookie is assumed to be a dictionary cookie, and Var is treated as the key. If Var is a varaint with type VT_ERROR and error code DISP_E_PARAMNOTFOUND, then the cookie is assumed to be a simple cookie and the primary value is returned. (If the cookie is a dictionary, the sequence of key/value pairs are URL-encoded and returned.)

If a dictionary lookup is performed and the item is not found, then pVariantReturn returns VT_EMPTY. Otherwise a VT_BSTR is always returned.

See Also

Cookies


IReadCookie::get__NewEnum

The IReadCookie::get__NewEnum method returns an enumerator interface which can be used to iterate through the items in a cookie.

HRESULT get__NewEnum(
  IUnknown ** ppEnumReturn  //pointer to an IUnknown interface
                            // pointer that receives the enumerator
);

Parameters

ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.

Remarks

If a cookie has been implemented as a collection, you can use this method to iterate through all the members of its collection.

See Also

Cookies, IWriteCookie::get__NewEnum


IRequest

The IRequest interface exposes methods that access the collections of the Request object.

Method | Description
IRequest::BinaryRead | Retrieves the current request and places it into a safe array.
IRequest::get_ClientCertificate | Retrieves the ClientCertificate collection.
IRequest::get_Cookies | Retrieves the Cookies collection.
IRequest::get_Form | Retrieves the Form collection.
IRequest::get_Item | Retrieves an item from the Request collection by looking for the first match in the QueryString, Form, Cookies, ClientCertificate, and ServerVariables collections.
IRequest::get_QueryString | Retrieves the QueryString collection.
IRequest::get_ServerVariables | Retrieves the ServerVariables collection.
IRequest::get_TotalBytes | Returns the size, in bytes, of the current request.

Note This interface also supports the IUnknown and IDispatch interface methods. For more information, see \inetsrv\asp\cmpnts\asptlb.h, the header file installed with ASP.


IRequest::BinaryRead

The IRequest::BinaryRead method retrieves the current Request object in a safe array.

HRESULT BinaryRead(
  Variant *pvarCountToRead,
  Variant *pvarReturn
);

Parameters

pvarCountToRead
Points to a variant that contains an integer value of the bytes to read.
pvarReturn
Points to a safe array that contains the bytes that were read by an HTTP Post.

Remarks

A safe array is an array that contains information about the number of dimensions and the bounds of its dimensions.

See Also

IRequest::get_TotalBytes


IRequest::get_ClientCertificate

The IRequest::get_ClientCertificate method retrieves the ClientCertificate collection of the Request object.

HRESULT get_ClientCertificate(
  IRequestDictionary ** ppDictReturn  //pointer to an
                                      // IRequestDictionary interface
                                      // pointer that receives the
                                      // ClientCertificate collection
);

Parameters

ppDictReturn
Points to an IRequestDictionary interface pointer that receives the ClientCertificate collection.

Remarks

You can iterate through the ClientCertificate collection with the get__NewEnum method exposed by the IRequestDictionary interface. You can also retrieve a specific ClientCertificate value with the get_Item method.

See Also

IRequestDictionary


IRequest::get_Cookies

The IRequest::get_Cookies method retrieves the Cookies collection of the Request object.

HRESULT get_Cookies(
  IRequestDictionary ** ppDictReturn  //pointer to an
                                      // IRequestDictionary interface
                                      // pointer that receives the
                                      // Cookies collection
);

Parameters

ppDictReturn
Points to an IRequestDictionary interface pointer that receives the Cookies collection.

Remarks

You can iterate through the Cookies collection with the get__NewEnum method exposed by the IRequestDictionary interface. You can also retrieve a specific Cookie value with the get_Item method.

See Also

IRequestDictionary


IRequest::get_Form

The IRequest::get_Form method retrieves the Form collection of the Request object.

HRESULT get_Form(
  IRequestDictionary ** ppDictReturn  //pointer to an
                                      // IRequestDictionary interface
                                      // pointer that receives the
                                      // Form collection
);

Parameters

ppDictReturn
Points to an IRequestDictionary interface pointer that receives the Cookies collection.

Remarks

You can iterate through the Form collection with the get__NewEnum method exposed by the IRequestDictionary interface. You can also retrieve a specific Form value with the get_Item method.

See Also

IRequestDictionary


IRequest::get_Item

The IRequest::get_Item method retrieves a pointer to an interface pointer of the first item in the Request object's collections that contains the specified string. The collections are searched in the following order: QueryString, Form, Cookies, ClientCertificate, ServerVariables.

HRESULT get_Item(
  BSTR bstrVar,  //binary string that contains the name of the item
                 // to retrieve
  IDispatch ** ppObjReturn
                 //pointer to an IDispatch interface pointer that
                 // receives the object that contains the binary
                 // string specified in bstrVar
);

Parameters

bstrVar
A binary string that contains the name of the item to retrieve.
ppObjReturn
Points to an IDispatch interface pointer that receives the object that contains the value specified in bstrVar.

Return Values

The datatype of the variant that is returned is VT_DISPATCH. If you need to convert the returned item to a BSTR, you should call the Win32 API function VariantChangeType. For more information on VariantChangeType, see the Platform SDK.

If the object containing bstrVar is found in the QueryString, Form, or ServerVariables collection, then ppObjReturn points to an object which supports the IStringList interface.

If the object is found in the ClientCertificate collection, then ppObjReturn points to an object that supports the IRequestDictionary interface.

If the object is found in the Cookies collection, ppObjReturn points to an object which supports the IReadCookie interface.

See Also

IStringList, IRequestDictionary


IRequest::get_QueryString

The IRequest::get_QueryString method retrieves the QueryString collection of the Request object.

HRESULT get_QueryString(
  IRequestDictionary ** ppDictReturn  //pointer to an
                                      // IRequestDictionary interface
                                      // pointer that receives the
                                      // QueryString collection
);

Parameters

ppDictReturn
Points to an IRequestDictionary interface pointer that receives the QueryString collection.

Remarks

You can iterate through the QuerySting collection with the IRequestDictionary::get__NewEnum, or you can retrieve a specific QueryString value with the IRequestDictionary::get_Item method.

See Also

IRequestDictionary


IRequest::get_ServerVariables

The IRequest::get_ServerVariables method retrieves the ServerVariables collection of the Request object.

HRESULT get_ServerVariables(
  IRequestDictionary ** ppDictReturn  //pointer to an
                                      // IRequestDictionary interface
                                      // pointer that receives the
                                      // ServerVariables collection
);

Parameters

ppDictReturn
Points to an IRequestDictionary interface pointer that receives the ServerVariables collection.

Remarks

You can iterate through the ServerVariables collection with the IRequestDictionary::get__NewEnum, or you can retrieve a specific ServerVariable with the IRequestDictionary::get_Item method.

See Also

IRequestDictionary


IRequest::get_TotalBytes

The IRequest::get_TotalBytes method retrieves the size of the current request in bytes.

get_TotalBytes(
  long pcbTotal  //a pointer to a long integer that contains the
                 // size of the current request in bytes
);

Parameters

pcbTotal
Points to a long integer that contains the size of the current request in bytes.

See Also

IRequest::BinaryRead


IRequestDictionary

The IRequestDictionary interface is a general interface wrapper that can wrap the following collections.

  • Request.ClientCertificate
  • Request.ClientCertificate(item)
  • Request.Cookies
  • Request.Form
  • Request.QueryString
  • Request.ServerVariables
  • Response.Cookies

The behavior of the IRequestDictionary interface depends on how the Request or Response object implements the get_Item method.

Method | Description
IRequestDictionary::get_Count | Retrieves the number of items in a dictionary.
IRequestDictionary::get_Item | Retrieves the specified item from a dictionary.
IRequestDictionary::get_Key | Retrieves the identifier of the item to be retrieved from the collection.
IRequestDictionary::get__NewEnum | Retrieves an enumerator for the collection.

Note This interface also supports the IUnknown and IDispatch interface methods. For more information, see \iissamples\sdk\include\asptlb.h, the header file installed with ASP.

See Also

Application Collections, Response Collections, Request Collections, Session Collections


IRequestDictionary::get_Count

The IRequestDictionary::get_Count method determines the total number of items in a collection.

HRESULT STDMETHODCALLTYPE get_Count(
     int*cStrRet       //a pointer to an integer containing
                       // the number of items
)

Return Values

cStrRet
Points to an integer that contains a total of the number of items in the collection.

See Also

IRequestDictionary, IReadCookie, IWriteCookie


IRequestDictionary::get_Item

The IRequestDictionary::get_Item method retrieves the specified item from a Request object dictionary.

HRESULT get_Item(
  VARIANT Var,  //VARIANT that contains the name of the item in the
                // collection
  VARIANT * pVariantReturn
                //pointer to a VARIANT that receives the item value
);

Parameters

Var
A variant that contains the name of the item in the collection.
pVariantReturn
Points to a variant that receives the item value.

Remarks

Automation objects can specify that one or more variant parameters are optional. This is done by passing the parameter with the type set to VT_ERROR and a value of DISP_E_PARAMNOTFOUND. For example, if you want to do this with the Var parameter, the value it returns will depend on the object's implementation of the IRequestDictionary interface. The QueryString object would then return the entire query string.

  • For Request.QueryString, pVariantReturn contains the unparsed query string data.
  • For Request.Form, pVariantReturn contains the unparsed form data.
  • For Request.Cookies, pVariantReturn contains a URL-encoded list of the cookies.
  • For Request.ClientCertificate, pVariantReturn contains a URL-encoded list of the items in the certificate.
  • Request.ServerVariables and Response.Cookies do not accept an optional variant parameter, and will raise a COM Automation exception if Var is DISP_E_PARAMNOTFOUND.

If Var is not an optional parameter then it must be a VT_BSTR or a VT_DISPATCH pointer with a default value that can be converted to a BSTR. In this case, the BSTR value of Var is looked up in the appropriate dictionary, and the value of Var is returned. If Var is not in the dictionary, then a VARIANT equal to VT_EMPTY is returned if the IRequestDictionary is covering one of the Request object's collections. If the IRequestDictionary pointer is the Response.Cookies collection, a new cookie with the name of Var is created, and that cookie is returned. If Var is not a BSTR (and not DISP_E_PARAMNOTFOUND), then the get_Item method will raise an OLE Automation exception.

See Also

IRequestDictionary


IRequestDictionary::get_Key

HRESULT STDMETHODCALLTYPE get_Item(
  VARIANT VarKey,    //the identifier fot the item to return
  VARIANT*pvar       //a pointer to the item that is returned
);

Parameters

VarKey
Identifier that indicates which item to retrieve from the collection.
pVar
Points to the item that is returned.

Remarks

You can use this method to get the a unique indentifer for items in the ClientCertificates, Cookies, Form, and QueryString collections.

See Also

IRequestDictionary, IReadCookie, IWriteCookie IRequest


IRequestDictionary::get__NewEnum

The IRequestDictionary::get__NewEnum method returns an enumerator interface which can be used to iterate through the items in the collection.

HRESULT get__NewEnum(
  IUnknown ** ppEnumReturn  //pointer to an IUnknown interface
                            // pointer that receives the enumerator
);

Parameters

ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.

Remarks

You can use this method to iterate through the items in any collection. Members of the Cookies collection may be implemented as collections themselves. IReadCookie and IWriteCookie both support this method as well, which you can use to iterate through the members of these sub-collections.

See Also

IRequestDictionary, IReadCookie, IWriteCookie IRequest


IResponse

The IResponse interface exposes the methods of the Response object.

Method | Description
IResponse::AddHeader | Adds a header to the HTML output.
IResponse::AppendToLog | Adds a string to the end of the Web server log for the current request.
IResponse::BinaryWrite | Writes data to the HTTP output without any character conversion.
IResponse::Clear | Erases any buffered HTML output.
IResponse::End | Causes the server to stop processing script and return the current response.
IResponse::Flush | Sends buffered HTML output immediately.
IResponse::get_Buffer | Retrieves the value of the Buffer property.
IResponse::get_CacheControl | Retrieves the value for the CacheControl property.
IResponse::get_CharSet | Retrieves the name of a character set to append to the content-type header.
IResponse::get_ContentType | Retrieves the value of the ContentType property.
IResponse::get_Cookies | Retrieves the write-only Cookies collection.
IResponse::get_Expires | Retrieves the value of the Expires property.
IResponse::get_ExpiresAbsolute | Retrieves the value of the ExpiresAbsolute property.
IResponse::get_Status | Retrieves the value of the Status property.
IResponse::IsClientConnected | Determines if the client has disconnected from the server.
IResponse::PICS | Adds a value to the PICS label field of the Response header.
IResponse::put_Buffer | Sets the value of the Buffer property.
IResponse::putCacheControl | Set the value for the CacheControl property.
IResponse::putCharSet | Adds a character set to the ContentType header.
IResponse::put_ContentType | Sets the value of the ContentType property.
IResponse::put_Expires | Sets the value of the Expires property.
IResponse::put_ExpiresAbsolute | Sets the value of the ExpiresAbsolute property.
IResponse::put_Status | Sets the value of the Status property.
IResponse::Redirect | Causes the browser to attempt to connect to a different URL.
IResponse::Write | Writes a variant to the HTTP output.

Note This interface also supports the IUnknown and IDispatch interface methods. For more information, see \inetsrv\asp\cmpnts\asptlb.h, the header file installed with ASP.


IResponse::AddHeader

The IResponse::AddHeader method adds an HTTP header to the HTTP response. For more information, see the AddHeader method of the Response object.

HRESULT AddHeader(
  BSTR bstrHeaderName,  //a binary string that contains the name of
                        // the HTTP header
  BSTR bstrHeaderValue  //a binary string that contains the header
                        // value
);

Parameters

bstrHeaderName
A binary string that contains the name of the HTTP header.
bstrHeaderValue
A binary string that contains the HTTP header value.

Remarks

This method adds an HTTP header with a specified value; it also always adds a new HTTP header to the response. It will not replace an existing header of the same name. Once a header has been added, it cannot be removed.

See Also

Response Object


IResponse::AppendToLog

The IResponse::AppendToLog method adds a string to the end of the Web server log entry for the current request. The log entry can contain a maximum of 80 bytes. For more information, see the AppendToLog method of the Response object.

HRESULT AppendToLog(
  BSTR bstrLogEntry  //binary string to append to the log entry
);

Parameters

bstrLogEntry
A binary string to append to the log entry.

Remarks

This method adds a string to the end of the Web server log entry for this request. You can call it multiple times in one section of script. Each time the method is called it appends the specified string to the existing entry.

See Also

Response Object


IResponse::BinaryWrite

The IResponse::BinaryWrite method writes data to the HTTP output without converting Unicode characters to ANSI. For more information, see the BinaryWrite method of the Response object.

HRESULT BinaryWrite(
  VARIANT varBuffer  //VARIANT containing the data as a SAFEARRAY
);

Parameters

varBuffer
A variant containing the data as a SAFEARRAY.

Remarks

This method writes the specified information to the current HTTP output without any character conversion. This method is useful for writing nonstring information, such as binary data, required by a custom application.

See Also

Response Object


IResponse::Clear

The IResponse::Clear method erases any buffered HTML output. For more information, see the Clear method of the Response object.

HRESULT Clear(VOID);

Remarks

This method only erases the response body; it does not erase response headers. You can use this method to handle error cases. Note that this method will cause a run-time error if Response.Buffer has not been set to TRUE.

See Also

Response Object


IResponse::End

The IResponse::End method causes the server to stop processing the script and to return the current response. For more information, see the End method of the Response object.

HRESULT End(VOID);

Remarks

When this method is called, the remaining contents of the file are not processed.

See Also

Response Object


IResponse::Flush

The IResponse::Flush method sends buffered output immediately.

HRESULT Flush(VOID);

Remarks

If this method is called on an ASP page, the server does not honor Keep-Alive requests for that page. This method will cause a run-time error if Response.Buffer has not been set to TRUE.

See Also

Response Object


IResponse::get_Buffer

The IResponse::get_Buffer method retrieves the current value of the Buffer property of the Response object.

HRESULT get_Buffer(
  VARIANT_BOOL * fIsBuffering  //pointer to a Boolean VARIANT that
                               // receives the Buffer value.
);

Parameters

fIsBuffering
Points to a Boolean VARIANT that receives the Buffer value

Remarks

When page output is buffered, the server does not send a response to the client until all of the server scripts on the current page have been processed, or until the Flush or End method has been called.

The Buffer property cannot be set after the server has sent output to the client. For this reason, the call to Response.Buffer should be the first line of the .asp file.

See Also

Response Object, IResponse::put_Buffer


IResponse::get_CacheControl

The IResponse::get_CacheControl method retrieves a value for the CacheControl property.

HRESULT get_CacheControl(
  BSTR *pbstrCacheControl // pointer to a binary string that receives
                          // the CacheControl value
)

Parameters

pbstrCacheControl
Points to a binary string that receives the CacheControl value.

Remarks

You can use the CacheControl value to override the default value which is False. By setting the value to TRUE, proxy servers will be able to cache output from ASP pages.

See Also

Response Object


IResponse::get_CharSet

The IResponse::get_CharSet method retrieves a character set to append to the content type header.

HRESULT get_CharSet(
  BSTR *pbstrCharSetRet //pointer to a binary string that receives
                        // the CharSet value
   );

Parameters

pbstrCharSetRet
Points to a binary string that receives the CharSet value.

Remarks

You can use the CharSet value to determine the character set to use when displaying the current Response object.

See Also

IResponse::get_ContentType


IResponse::get_ContentType

The IResponse::get_ContentType method retrieves the current value of the ContentType property of the Response object.

HRESULT get_ContentType(
  BSTR * pbstrContentTypeRet  //pointer to a binary string that
                              // receives the ContentType value
);

Parameters

pbstrContentTypeRet
Points to a binary string that receives the Content Type value.

Remarks

You can use the ConentTypeRet value to determine the content type of the current Response object.

See Also

Response Object


IResponse::get_Cookies

The IResponse::get_Cookies method retrieves the write-only Cookies collection of the Response object.

HRESULT get_Cookies(
  IRequestDictionary ** ppCookies  //pointer to the
                                   // IRequestDictionary interface
                                   // pointer that receives the
                                   // write-only Cookies collection
);

Parameters

ppCookies
Points to an IRequestDictionary interface pointer that receives the write-only Cookies collection.

Remarks

You can iterate through the Cookies collection with the IRequestDictionary::get__NewEnum method, or you can retrieve a specific cookie with the IRequestDictionary::get_Item method.

See Also

Response Object


IResponse::get_Expires

The IResponse::get_Expires method retrieves the current value of the Expires property of the Response object.

HRESULT get_Expires(
  VARIANT * pvarExpiresMinutesRet  //a pointer to a VARIANT that
                                   // receives the Expires value
);

Parameters

pvarExpiresMinutesRe
Points to a variant that receives the Expires value. This value specifies the number of minutes until the page will expire.

Remarks

If the user returns to the same page before it expires, the cached version is displayed. If this property is set more than once on a page, the shortest time is used.

See Also

Response Object, IResponse::put_Expires


IResponse::get_ExpiresAbsolute

The IResponse::get_ExpiresAbsolute method retrieves the current value of the ExpiresAbsolute property of the Response object.

HRESULT get_ExpiresAbsolute(
  VARIANT * pvarExpiresRet  //pointer to a VARIANT that receives the
                            // ExpiresAbsolute value
);

Parameters

pvarExpiresRet
Points to a variant that receives the ExpiresAbsolute value. The variant should specify date and time.

Remarks

If the user returns to the same page before the set date and time, the cached version is displayed. If a time is not specified, the page expires at midnight of that day. If a date is not specified, the page expires at the given time on the day that the script is run. If this property is set more than once on a page, the earliest expiration date or time is used. The date value sent in the expires header conforms to the RFC-1123 date format. The time value is converted to Greenwich Mean Time before an Expires header is sent.

See Also

Response Object, IResponse::get_Expires


IResponse::get_Status

The IResponse::get_Status method retrieves the current value of the Status property of the Response object.

HRESULT get_Status(
  BSTR * pbstrStatusRet  //pointer to a binary string that receives
                         // the Status value
);

Parameters

pbstrStatusRet
Points to a binary string that receives the Status value.

Remarks

You use this property to modify the status line returned by the server. Status values are defined in the HTTP specification.

See Also

Response Object


IResponse::IsClientConnected

The IResponse::IsClientConnected method determines if the client has disconnected from the server since the last Response.Write operation.

HRESULT IsClientConnected(
  VARIANT_BOOL pfIsClientConnected  //pointer to a boolean that
                                    // indicates whether or not the
                                    // client is connected
);

Parameters

pfIsClientConnected
Points to a boolean that indicates whether or not the client is connected.

See Also

Response Object


IResponse::PICS

The IResponse::PICS method adds a value to the PICS label field of the response header.

HRESULT Pics(
  BSTR bstrHeaderValue    //A binary string that contains the new
                          // pics value
);

Parameters

bstrHeaderValue
A binary string that contains the new PICS value.

Remarks

The IResponse::PICS method inserts any string in the header, whether or not it represents a valid PICS label.

If a single page contains multiple tags containing Response.PICS, each instance will replace the PICS label set by the previous one. As a result, the PICS label will be set to the value specified by the last instance of Response.PICS in the page.

Because PICS labels contain quotes, the author must replace each quote with the ASCII equivalent for the quote symbol [& chr(34) &].

For more details on the PICS standard, see http://www.w3.org/PICS/.

See Also

Response Object


IResponse::put_Buffer

Th IResponse::put_Buffer method sets the value of the Buffer property of the Response object.

HRESULT put_Buffer(
  VARIANT_BOOL fIsBuffering  //Boolean VARIANT that contains the new
                             // Buffer value
);

Parameters

fIsBuffering
A Boolean variant that contains the new Buffer value.

Remarks

When page output is buffered, the server does not send a response to the client until all of the server scripts on the current page have been processed, or until the Flush or End method has been called.

The Buffer property cannot be set after the server has sent output to the client. For this reason, the call to Response.Buffer should be the first line of the .asp file.

See Also

Response Object, IResponse::get_Buffer


IResponse::putCacheControl

The IResponse::putCacheControl method sets the value of the CacheControl property of the Response object.

HRESULT put_CacheControl(
  BSTR bstrCacheControl  //a binary string that contains the new
                        // Character Set value
);

Parameters

bstrCacheControl
A binary string that contains the new CacheControl value.

Remarks

You can use the CacheControl value to determine whether or not proxy servers should cache ASP output.

See Also

Response Object, IResponse::get_CacheControl


IResponse::putCharSet

The IResponse::putCharSet method sets the value of the Charset property of the Response object.

HRESULT put_CharSet(
  BSTR bstrCharset      //a binary string that contains the new
                        // Character Set value
);

Parameters

bstrCharSet
A binary string that contains the new Character Set value.

Remarks

You can use the CharSet value to set the character set to use when displaying the current Response object.

See Also

Response Object, IResponse::get_CharSet


IResponse::put_ContentType

The IResponse::put_ContentType method sets the value of the ContentType property of the Response object.

HRESULT put_ContentType(
  BSTR bstrContentType  //a binary string that contains the new
                        // ContentType value
);

Parameters

bstrContentType
A binary string that contains the new ContentType value.

Remarks

You can use the ContentType value to set the content type to use when displaying the current Response object.

See Also

Response Object, IResponse::get_ContentType


IResponse::put_Expires

The IResponse::put_Expires method sets the current value of the Expires property of the Response object.

HRESULT put_Expires(
  LONG lExpiresMinutes  //LONG that contains the new Expires value
);

Parameters

lExpiresMinutes
A Long integer that contains the new Expires value.

Remarks

If the user returns to the same page before it expires, the cached version is displayed. If this method is set more than once on a page, the shortest time is used.

See Also

Response Object, IResponse::get_Expires


IResponse::put_ExpiresAbsolute

The IResponse::put_ExpiresAbsolute method sets the value of the ExpiresAbsolute property of the Response object.

HRESULT put_ExpiresAbsolute(
  DATE dtExpires  //date that contains the new ExpiresAbsolute value
);

Parameters

dtExpires
A date that contains the new ExpiresAbsolute value

Remarks

If the user returns to the same page before the set date and time, the cached version is displayed. If a time is not specified, the page expires at midnight of that day. If a date is not specified, the page expires at the given time on the day that the script is run. If this property is set more than once on a page, the earliest expiration date or time is used. The date value sent in the expires header conforms to the RFC-1123 date format. The time value is converted to Greenwich Mean Time before an Expires header is sent.

See Also

Response Object, IResponse::put_Expires


IResponse::put_Status

The IResponse::put_Status method sets the value of the Status property of the Response object.

HRESULT put_Status(
  BSTR bstrStatus  //binary string that contains the new Status value
);

Parameters

bstrStatus
A binary string that contains the new Status value.

Remarks

You can use this property to modify the status line returned by the server. Status values are defined in the HTTP specification.

See Also

Response Object, IResponse::get_Status


IResponse::Redirect

The IResponse::Redirect method first stops the server from processing the current script and then causes the browser to attempt to connect to a different URL. For more information, see the Redirect method of the Response object.

HRESULT Redirect(
  BSTR bstrURL      //binary string that contains the URL
);

Parameters

bstrURL
A binary string that contains the URL.

Remarks

If you have set any response body content in the page, it will be ignored. However, this method does send to the client other HTTP headers set by this page. An automatic response body containing the redirect URL as a link is generated. The IResponse::Redirect method sends the following explicit header,

HTTP/1.0 302 Object Moved
Location URL

where URL is the value passed to the method.

See Also

Response Object


IResponse::Write

The IResponse::Write method writes the specified VARIANT to the HTTP output. For more information, see the Write method of the Response object.

HRESULT Write(
  VARIANT varText  //variant to write to the HTTP output
);

Parameters

varText
A variant to write to the HTTP output.

Remarks

If VBScript is your primary scripting language, variant cannot be a string literal that contains more than 1022 characters. This is because VBScript limits static strings to 1022 bytes. You can, however, specify variant as the name of a variable that contains greater than 1022 bytes.

See Also

Response Object


IScriptingContext

The IScriptingContext interface is considered obsolete. You should not use it except in legacy ASP applications. The interface exposes methods that your component can use to retrieve the ASP built-in objects.

Method | Description
IScriptingContext::get_Application | Retrieves the Application object. This object implements the IApplicationObject interface.
IScriptingContext::get_Request | Retrieves the Request object. This object implements the IRequest interface.
IScriptingContext::get_Response | Retrieves the Response object. This object implements the IResponse interface.
IScriptingContext::get_Server | Retrieves the Server object. This object implements the IServer interface.
IScriptingContext::get_Session | Retrieves the Session object. This object implements the ISessionObject interface.

Note This interface also supports the IUnknown and IDispatch interface methods. For more information, see \winnt\system32\inetsrv\asptlb.h, the header file installed with ASP.


IScriptingContext::get_Application

The IScriptingContext::get_Application method retrieves a pointer to the IApplicationObject interface of the Application object.

Syntax

HRESULT get_Application(
  IApplicationObject ** ppApplication  //pointer to an
                                       // IApplicationObject interface
                                       // pointer
);

Parameters

ppApplication
Points to an IApplicationObject interface.

Remarks

You can use IApplicationObject to gain access to variables and objects that have been given application scope. IApplicationObject also exposes methods to lock and unlock an application to prevent concurrent access to application objects and variables.

See Also

IApplicationObject


IScriptingContext::get_Request

The IScriptingContext::get_Request method retrieves a pointer to the IRequest interface of the Request object.

HRESULT get_Request(
  Irequest ** ppRequest  //pointer to an IRequest interface pointer
);

Parameters

ppRequest
Points to an IRequest interface pointer.

Remarks

You can use the IRequest interface to access the methods, properties, and collections of the Request object.

See Also

IRequest


IScriptingContext::get_Response

The IScriptingContext::get_Response method retrieves a pointer to the IResponse interface of the Response object.

HRESULT get_Response(
  Iresponse ** ppResponse  //pointer to an IResponse interface
                           // pointer
);

Parameters

ppResponse
Points to an IResponse interface pointer.

Remarks

You can use the IResponse interface to access the methods, properties, and collections of the Response object.

See Also

IResponse


IScriptingContext::get_Server

The IScriptingContext::get_Server method retrieves a pointer to the IServer interface of the Server object.

HRESULT get_Server(
  Iserver ** ppServer  //pointer to an IServer interface pointer
);

Parameters

ppServer
Points to an IServer interface pointer.

Remarks

You can use the IServer interface to access the methods exposed by the Server object.

See Also

IServer


IScriptingContext::get_Session

The IScriptingContext::get_Session method retrieves a pointer to the ISessionObject interface of the Session object.

HRESULT get_Session(
  ISessionObject ** ppSession  //pointer to an ISessionObject
                               // interface pointer
);

Parameters

ppSession
Points to an ISessionObject interface pointer.

Remarks

You can use the ISessionObject interface to access variables and objects that have been given session scope.

See Also

ISessionObject


IServer

The IServer interface exposes the methods and properties of the Server object.

Method | Description
IServer::CreateObject | Creates an instance of a server object.
IServer::get_ScriptTimeout | Retrieves the value of the ScriptTimeout property.
IServer::HTMLEncode | Applies HTML encoding to the specified string.
IServer::MapPath | Maps the specified relative or virtual path to the corresponding physical directory on the server.
IServer::put_ScriptTimeout | Sets the value of the ScriptTimeout property.
IServer::URLEncode | Applies URL encoding rules, including escape characters, to the specified string.

Note This interface also supports the IUnknown and IDispatch interface methods. For more information, see \inetsrv\asp\cmpnts\asptlb.h, the header file installed with ASP.


IServer::CreateObject

The IServer::CreateObject method creates an instance of a server component. For more information, see the CreateObject method of the Server object.

HRESULT CreateObject(
  BSTR bstrProgID,  //binary string that contains the progID of the
                    // component
  IDispatch ** ppDispObject
                    //pointer to an IDispatch interface pointer
);

Parameters

bstrProgID
A binary string that contains the progID of the object.
ppDispObject
Points to an IDispatch interface pointer.

Remarks

By default, objects created by the Server.CreateObject method have page scope. This means that they are automatically destroyed by the server when it finishes processing the current ASP page.

To create an object with session or application scope, you can either use the <OBJECT> tag and set the SCOPE attribute to SESSION or APPLICATION, or store the object in a session or application variable.

See Also

Server Object


IServer::get_ScriptTimeout

The IServer::get_ScriptTimeout method retrieves the value of the ScriptTimeout property of the Server object.

HRESULT get_ScriptTimeout(
  LONG * plTimeoutSeconds  //pointer to a LONG that receives the
                           // ScriptTimeout value
);

Parameters

plTimeoutSeconds
Points to a LONG that receives the ScriptTimeout value.

Remarks

A default ScriptTimeout can be set for a Web Service or Web Server by using the AspScriptTimeout property in the Metabase. The ScriptTimeout property cannot be set to a value less than that specified in the metabase.

For more information about using the Metabase, see About the Metabase

See Also

AspScriptTimeout, IIS Metabase


IServer::HTMLEncode

The IServer::HTMLEncode method applies HTML encoding to the specified string. For more information, see the HTMLEncode method of the Server object.

HRESULT HTMLEncode(
  BSTR bstrIn,         //binary string that contains the text
                       //to be encoded
  BSTR * pbstrEncoded  //pointer to a binary string that receives
                       //the encoded text
);

Parameters

bstrIn
A binary string that contains the text to be encoded.
pbstrEncoded
Points to a binary string that receives the encoded text.

Remarks

If your component returns the encoded text to a browser, the browser will display it in HTML format, rather than in plain text. For example, if the bstrIn contained the following string, < >, the pbstrEncoded parameter would contain the HTML code for those characters, &lt &gt. If your component returned this to a browser, however, it would display it as < >.

See Also

Server Object


IServer::MapPath

The IServer::MapPath method maps the specified relative or virtual path to the corresponding physical directory on the server. For more information, see the MapPath method of the Server object.

HRESULT MapPath(
  BSTR bstrLogicalPath,  //binary string that contains the relative
                         // or virtual path
  BSTR * pbstrPhysicalPath  //pointer to a binary string that
                            // receives the physical path
);

Parameters

bstrLogicalPath
A binary string that contains the relative or virtual path.
pbstrPhysicalPath
Points to a binary string that receives the physical path.

Remarks

This method does not check whether the path it returns is valid or exists on the server.

Because the IServer::MapPath method maps a path regardless of whether the specified directories currently exist, you can use it to map a path to a physical directory structure, and then pass that path to a component that creates the specified directory or file on the server.

See Also

Server Object


IServer::put_ScriptTimeout

The IServer::put_ScriptTimeout method sets the value of the ScriptTimeout property of the Server object.

HRESULT put_ScriptTimeout(
  LONG lTimeoutSeconds  //LONG that contains the new ScriptTimeout
                        // value
);

Parameters

lTimeoutSeconds
A LONG integer that contains the new ScriptTimeout value.

Remarks

A default ScriptTimeout can be set for a Web Service or Web Server by using the AspScriptTimeout property in the Metabase. The ScriptTimeout property cannot be set to a value less than that specified in the metabase.

See Also

Server Object, IServer::get_ScriptTimeout, Metabase Structure


IServer::URLEncode

The IServer::URLEncode method applies URL encoding rules, including escape characters, to the specified string. For more information, see the URLEncode method of the Server object.

HRESULT URLEncode(
  BSTR bstrIn,         //binary string that contains the text to be
                       // encoded
  BSTR * pbstrEncoded  //pointer to a binary string that receives
                       // the encoded text
);

Parameters

bstrIn
A binary string that contains the text to be encoded.
pbstrEncoded
Points to a binary string that receives the encoded text.

See Also

Server Object, IServer::HTMLEncode


ISessionObject

The ISessionObject interface exposes the methods of the Session object.

Method | Description
ISessionObject::Abandon | Destroys all the objects stored in the Session object and releases their resources.
ISessionObject::get_CodePage | Retrieves the CodePage property for the Session object.
ISessionObject::get_Contents | Retrieves the Contents collection.
ISessionObject::get_LCID | Retrieves the LCID property for the Session object.
ISessionObject::get_SessionID | Retrieves the value of the SessionID property.
ISessionObject::get_StaticObjects | Retrieves the StaticObjects collection.
ISessionObject::get_Timeout | Retrieves the value of the Timeout property.
ISessionObject::get_Value | Retrieves the value of a variable stored in the Session object.
ISessionObject::put_CodePage | Set a value for the CodePage property.
ISessionObject::put_LCID | Sets a value for the LCID property.
ISessionObject::put_Timeout | Sets a value for the Timeout property.
ISessionObject::putref_Value | Stores a variable in the Session object by reference.
ISessionObject::put_Value | Stores a variable in the Session object by value.

Note This interface also supports the IUnknown and IDispatch interface methods. For more information, see \iissamples\sdk\include\asptlb.h, the header file installed with ASP.

For more information, see Managing Sessions.


ISessionObject::Abandon

The ISessionObject::Abandon method destroys all the objects stored in the current session and releases their resources. For more information see the Abandon method of the Session object.

HRESULT Abandon(VOID);

Remarks

When this method is called, the current Session object is queued for deletion, but is not actually deleted until all of the script commands on the current page have been processed. This means that you can access variables stored in the Session object on the same page as the call to Abandon, but not in any subsequent Web pages.

See Also

Session Object


ISessionObject::get_CodePage

The ISessionObject::get_CodePage method retrieves the value of the CodePage property.

HRESULT get_Contents(
  long *plvar  //pointer to a long integer
);

Parameters

plvar
Points to a long integer that contains the current value for the CodePage property.

Remarks

The CodePage property determines how characters are displayed.

See Also

Session Object, CodePage


ISessionObject::get_Contents

The ISessionObject::get_Contents method retrieves the value of the Contents property.

HRESULT get_Contents(
  IVariantDictionary **ppProperties  // IVariantDictionary interface
                                      // pointer that receives the
                                      // Contents collection
);

Parameters

ppProperties
Points to an IVariantDictionary interface pointer that receives the Contents collection.

Remarks

The SessionContents collection contains all variables and objects that have been given application scope with the Server.CreateObject command. You can iterate through the Contents collection with the get__NewEnum method exposed by the IVariantDictionary interface. You can also retrieve a specific member of the collection with the get_Item method.

See Also

Session Object IVariantDictionary


ISessionObject::get_LCID

The ISessionObject::get_LCID method retrieves the value of the LCID property.

HRESULT get_LCID(
  BSTR * plvar  //pointer to a long that contains the LCID value
);

Parameters

plvar
Points to a long integer that contains the LCID value.

Remarks

The LCID property specifies the locale identifier which is a standard international abbreviation that uniquely identifies one of the system-defined locales.

See Also

Session Object, LCID


ISessionObject::get_SessionID

The ISessionObject::get_SessionID method retrieves the value of the SessionID property.

HRESULT get_SessionID(
  BSTR * pbstrRet  //pointer to a binary string that receives the
                   // SessionID value
);

Parameters

pbstrRet
Points to a binary string that receives the SessionID value.

Remarks

You should not use the SessionID property to generate primary key values for a database application. This is because if the Web server is restarted, some SessionID values may be the same as those generated before the server was stopped. Instead, you should use an auto-increment column data type, such as IDENTITY with Microsoft® SQL Server, or COUNTER with Microsoft® Access.

See Also

Session Object


ISessionObject::get_StaticObjects

The ISessionObject::get_StaticObjects method retrieves the StaticObjects collection of the Session object.

HRESULT get_StaticObjects(
  IVariantDictionary **ppProperties  //pointer to an
                                     // IVariantDictionary interface
                                     // pointer that receives the
                                     // Contents collection
);

Parameters

ppProperties
Points to an IVariantDictionary interface pointer that receives the StaticObjects collection.

Remarks

You can iterate through the StaticObjects collection with the get__NewEnum method exposed by the IVariantDictionary interface. You can also retrieve a specific member of the collection with the get_Item method.

See Also

Session Object, IVariantDictionary


ISessionObject::get_Timeout

The ISessionObject::get_Timeout method retrieves the value of the Timeout property of the Session object.

HRESULT get_Timeout(
  LONG * plvar  //pointer to a LONG that receives the Timeout value
);

Parameters

plvar
Points to a LONG integer that receives the Timeout value.

See Also

Session Object, IServer::get_ScriptTimeout


ISessionObject::get_Value

The ISessionObject::get_Value method retrieves the value of a variable stored in the Session object.

HRESULT get_Value(
  BSTR bstrValue, //binary string that contains the variable name
  VARIANT * pvar  //pointer to a VARIANT that receives the variable
                  // value
);

Parameters

bstrValue
A binary string that contains the variable name.
pvar
Points to a variant that receives the variable value.

Remarks

You can store values in the Session object. Information stored in the Session object is available throughout the session and has session scope.

See Also

Session Object


ISessionObject::put_CodePage

The ISessionObject::put_CodePage method sets the value of the CodePage property of the Session object.

HRESULT put_CodePage(
  LONG , lvar//long integer that contains the code page identifier
);

Parameters

lvar
A LONG integer that contains the new Code Page value.

Remarks

The CodePage property determines how characters are displayed.

See Also

Session Object, CodePage


ISessionObject::put_LCID

The ISessionObject::put_LCID method sets the LCID property value for the Session object.

HRESULT put_LCID(
  LONG lvar  //LONG that contains the new Timeout value
);

Parameters

lvar
A LONG integer that contains the new LCID value.

Remarks

The LCID property specifies the locale identifier which is a standard international abbreviation that uniquely identifies one of the system-defined locales.

See Also

Session Object, LCID


ISessionObject::put_Timeout

This ISessionObject::put_Timeout method sets the value of the Timeout property of the Session object.

HRESULT put_Timeout(
  LONG lvar  //LONG that contains the new Timeout value
);

Parameters

lvar
A LONG integer that contains the new Timeout value.

See Also

Session Object


ISessionObject::putref_Value

The ISessionObject::putref_Value method stores a COM Automation object in the Session object. Equivalent to put_Value for non-COM objects.

HRESULT putref_Value(
  BSTR bstrValue,
               //binary string that contains the new variable name
  VARIANT var  //VARIANT to store in the variable
);

Parameters

bstrValue
A binary string that contains the new variable name.
var
A variant to store in the variable.

Remarks

Before you store an object in the Session object, you should know what threading model it uses. For more information, see Component Design Guidelines.

See Also

Session Object


ISessionObject::put_Value

This method stores a variant in the Session object. If the variant is a COM Automation object, then ASP will attempt to store the default value of that object into the application. If ASP cannot get the default value, then the call will fail.

HRESULT put_Value(
  BSTR bstrValue,  //binary string that contains the variable name
  VARIANT var      //VARIANT that contains the variable value
);

Parameters

bstrValue
A binary string that contains the variable name.
var
A variant that contains the variable value.

Remarks

If you store an array in a Session object, you should not attempt to alter the elements of the stored array directly. For example, the following script will not work.

<% Session("StoredArray")(3) = "new value" %>

This is because the Session object is implemented as a collection. The array element StoredArray(3) does not receive the new value. Instead, the value is indexed into the collection, overwriting any information stored at that location.

It is strongly recommended that if you store an array in the Session object, you retrieve a copy of the array before retrieving or changing any of the elements of the array. When you are done with the array, you should store the array in the Session object again so that any changes you made are saved.

See Also

Session Object, ISessionObject::get_Value


IStringList

The IStringList interface to retrieve individual items from the string lists contained in the QueryString, Form, or ServerVariables collections.

Method | Description
IStringList::get_Count | Retrieves the number of items in the string list.
IStringList::get_Item | Retrieves the specified item from a string list.
IStringList::get__NewEnum | Retrieves an enumerator for the string list.

Note This interface also supports the IUnknown and IDispatch interface methods. For more information, see \inetsrv\asp\cmpnts\asptlb.h, the header file installed with ASP.


IStringList::get_Count

The IStringList::get_Count method retrieves the number of items in a string list.

HRESULT get_Count(
  INT * cStrRet  //pointer to an integer that receives the number of
                 // items
);

Parameters

cStrRet
Points to an integer that receives the number of items.

Remarks

The Form, QueryString, and ServerVariables collections return parameter values as an array. If the collection does not contain multiple values, the cStrRet will contain 1, if the parameter is not found, it will contain 0.

You can use this method to determine the number of items in the array. For example, if a Form included an Items ordered parameter, you could use the get_Count method to determine the number of items that had been ordered in the Form.

See Also

QueryString, Form, ServerVariables


IStringList::get_Item

The IStringList::get_Item method retrieves an individual item from a string list.

HRESULT get_Item(
  VARIANT Var,  //VARIANT that contains the name of the item in the
                // collection
  VARIANT * pVariantReturn
                //pointer to a VARIANT that receives the item value
);

Parameters

Var
A variant that contains the name of the item in the collection.
pVariantReturn
Points to a variant that receives the item value.

Remarks

You can use this method to retrieve a particular item from an array that has been returned by a Form, QueryString, or ServerVariables collection.

See Also

QueryString, Form, ServerVariables


IStringList::get__NewEnum

The IStringList::get__NewEnum method retrieves an enumerator interface which can be used to iterate through the items in the string list.

HRESULT get__NewEnum(
  IUnknown ** ppEnumReturn  //pointer to an IUnknown interface
                            // pointer that receives the enumerator
);

Parameters

ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.

Remarks

The Form, QueryString, and ServerVariables collections return parameter values as an array. You can use this method to retrieve an enumerator to iterate through one of the string list collections.

See Also

QueryString, Form, ServerVariables


IVariantDictionary

The IVariantDictionary interface exposes methods that you can use to access the members of the Application Contents, Application StaticObjects, Session Contents, and Session StaticObjects collections.

Method | Description
IVariantDictionary::get_Count | Retrieves the number of items in the collection.
IVariantDictionary::get_Item | Retrieves an item from the specified collection.
IVariantDictionary::get_Key | Retrieves an identifier for an item.
IVariantDictionary::get__NewEnum | Retrieves an enumerator for the collection.
IVariantDictionary::put_Item | Adds an item to the specified collection.


IVariantDictionary::get_Count

The IVariantDictionary::get_Count method returns the number of items in either the Contents or StaticObjects collection.

HRESULT STDMETHODCALLTYPE get_Count(
     int*cStrRet\\a pointer to an integer containing the number of items
)

Return Values

cStrRet
Points to an integer that contains a total of the number of items in the collection.

See Also

Application Contents Collection, Application StaticObjects Collection, Session Contents Collection, Session StaticObjects Collection


IVariantDictionary::get_Item

The IVariantDictionary::get_Item method retrieves the specified item from either the Contents or StaticObjects colleciton. Both the Application and Session objects provide these collections.

HRESULT STDMETHODCALLTYPE get_Item(
    VARIANT VarKey,//the identifier fot the item to return
    VARIANT*pvar //a pointer to the item that is returned.
);

Parameters

VarKey
Identifier that indicates which item to retrieve from the collection.

Return Values

pVar
Points to the item that is returned.

See Also

Application Contents Collection, Application StaticObjects Collection, Session Contents Collection, Session StaticObjects Collection


IVariantDictionary::get_Key

The IVariantDictionary::get_Key method returns a unique identifier for an item in either the Contents or StaticObjects collection.

HRESULT STDMETHODCALLTYPE get_Item(
    VARIANT VarKey,//the identifier fot the item to return
    VARIANT*pvar //a pointer to the item that is returned.
);

Parameters

VarKey
Identifier that indicates which item to retrieve from the collection.
pVar
Points to the item that is returned.

See Also

Application Contents Collection, Application StaticObjects Collection, Session Contents Collection, Session StaticObjects Collection


IVariantDictionary::get__NewEnum

The IVariantDictionary::get__NewEnum method retrieves an enumerator interface which can be used to iterate through the items in the collection.

HRESULT STDMETHODCALLTYPE get__NewEnum(
    IUnknown*ppEnumReturn//a pointer to an IUnkwown interface.
)

Parameters

ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.

See Also

Application Contents Collection, Application StaticObjects Collection, Session Contents Collection, Session StaticObjects Collection


IVariantDictionary::put_Item

The IVariantDictionary::put_Item method adds an item to either the Contents or StaticObjects collection.

HRESULT put_Item(
     VARIANT VarKey,//the identifier fot the item to return
     VARIANT var//the item to add to the collection.
);

Parameters

VarKey
Identifier that indicates which item to add to the collection.
Var
The item to add to the collection.

See Also

Application Contents Collection, Application StaticObjects Collection, Session Contents Collection, Session StaticObjects Collection


IWriteCookie

The IWriteCookie interface exposes methods that you can use to alter the values and attributes of the cookies stored in the write-only Cookies collection.

Method | Description
IWriteCookie::get__NewEnum | Retrieves an enumerator for the Cookies collection.
IWriteCookie::get_HasKeys | Retrieves a Boolean indicating whether the cookie has keys.
IWriteCookie::put_Domain | Sets the Domain attribute of the cookie to the specified value.
IWriteCookie::put_Expires | Sets the Expires attribute of the cookie to the specified value.
IWriteCookie::put_Item | Adds an item to the Cookies collection.
IWriteCookie::put_Path | Sets the Path attribute of the cookie to the specified value.
IWriteCookie::put_Secure | Sets the Secure attribute of the cookie to the specified value.

Note IWriteCookie and IReadCookie are interfaces for the same object. If you have an IWriteCookie pointer, you can call the IUnknown::QueryInterface method on an IReadCookie pointer.

This interface also supports the IUnknown and IDispatch interface methods. For more information, see \iissamples\sdk\include\asptlb.h, the header file installed with ASP.


IWriteCookie::get__NewEnum

The IWriteCookie::get__NewEnum method retrieves an enumerator interface which can be used to iterate through the items in a cookie.

HRESULT get__NewEnum(
  IUnknown ** ppEnumReturn  //pointer to an IUnknown interface
                            // pointer that receives the enumerator
);

Parameters

ppEnumReturn
Points to an IUnknown interface pointer that receives the enumerator.

Remarks

If a cookie has been implemented as a collection, you can use this method to iterate through all the members of its collection.

See Also

Cookies, IReadCookie::get__NewEnum


IWriteCookie::get_HasKeys

The IWriteCookie::get_HasKeys method retrieves a Boolean value which indicates whether or not the cookie has keys.

HRESULT get_HasKeys(
  VARIANT_BOOL * pfHasKeys  //pointer to a Boolean that indicates
                            // whether or not the cookie has keys
);

Parameters

pfHasKeys
Points to a Boolean that indicates whether or not the cookie has keys.

Remarks

If the cookie has been implemented as a collection, this method will return TRUE. If the cookie has keys, you can use the IWriteCookie::get__NewEnum method to retrieve an enumerator for iterating through the collection.

See Also

Cookies, IReadCookie::get_HasKeys, IReadCookie::get__NewEnum


IWriteCookie::put_Domain

ThE IWriteCookie::put_Domain method sets the Domain attribute of the write-only Cookies collection to the specified value.

HRESULT put_Domain(
  BSTR bstrDomain  //binary string that contains the new domain value
);

Parameters

bstrDomain
A binary string that contains the new domain value.

Remarks

You can use this method to specify particular domains for a cookie. This method only applies to the Response.Cookies collection.

See Also

Cookies


IWriteCookie::put_Expires

The IWriteCookie::put_Expires method sets the Expires attribute of the write-only Cookies collection to the specified value.

HRESULT put_Expires(
  DATE dtExpires  //date that contains the new expiration value
);

Parameters

dtExpires
A date that contains the new expiration value.

Remarks

This date must be set in order for the cookie to be maintained after the session ends. If this attribute is not set to a date beyond the current date, the cookie will expire when the session ends.

See Also

Cookies


IWriteCookie::put_Item

The IWriteCookie::put_Item method adds a specified cookie to the write-only Cookie collection.

HRESULT put_Item(
  VARIANT key,    //VARIANT that contains the name of the cookie
  BSTR bstrValue  //binary string that contains the cookie value
);

Parameters

key
A variant that contains the name of the cookie.
bstrValue
A binary string that contains the cookie value.

Remarks

Automation objects can specify that one or more variant parameters are optional. This is done by passing the parameter with the type set to VT_ERROR and a value of DISP_E_PARAMNOTFOUND. If you pass key as an Automation optional parameter, the cookie is treated as a simple cookie and its value is set to bstrValue. Otherwise, the cookie is treated as a dictionary cookie and bstrValue is the value for the cookie's key.

See Also

Cookies


IWriteCookie::put_Path

The IWriteCookie::put_Path method sets the Path attribute of the write-only Cookies collection to the specified value.

HRESULT put_Path(
  BSTR bstrPath  //binary string that contains the new path
);

Parameters

bstrPath
A binary string that contains the new path.

Remarks

You can use this method to specify that the cookie should be sent only to requests on a particular path. If this attribute is not set, the application path is used.

See Also

Cookies


IWriteCookie::put_Secure

The IWriteCookie::put_Secure method sets the Secure attribute of the write-only Cookies collection to the specified value.

HRESULT put_Secure(
  VARIANT_BOOL fSecure  //Boolean that contains the new value for
                        // the Secure attribute
);

Parameters

fSecure
A Boolean that contains the new value for the Secure attribute.

Remarks

You can use this method to specify that a cookie is secure. If you set this value to true, a Secure flag will be added to the Set-Cookie header sent to the client. The Secure flag instructs the client to use only secure means to access the server when sending back the cookie.

See Also

Cookies


Java Class and Interface Definitions

When IIS 4.0 is installed a set of Java class files are created that define the ASP built-in objects. The classes use native Java types, and support native Java interfaces.You can refer to these classes directly, however, the Java Component Framework (JCF) simplifies creating Active Server Components. The JCF creates new interfaces that expose the ASP object model. The goal is to retain all of the features and flavor of the ASP Programming model, but to expose it in a way that is more natural for the Java programmer.

For more information, see the Java Component Framework Reference.

ASP provides the ObjectContext Object that contains methods which return interfaces to the built-in objects. Your component can then use these object interfaces to access the methods and properties of the built-in objects. The reference pages for the Java version of the built-in objects list the method names. For details on the methods, see the C++ equivalent reference pages.

Interface | Description
IApplicationObject | Calls the methods and properties of the Application object.
IObjectContext | Returns an interface to one of the built-in objects: IApplicationObject, IRequest, IResponse, IServer, or ISessionObject.
IReadCookie | Retrieves the values and attributes of a cookie stored in the read-only Cookies collection.
IRequest | Calls the methods and properties of the Request object.
IRequestDictionary | Indexes the subcollections of the IRequest interface. Also retrieves the individual values stored in the ClientCertificate collection.
IResponse | Calls the methods and properties of the Response object.
IScriptingContext (Obsolete) | Provided as support for legacy ASP applications that use the IScriptingContext to access the built-in objects.
IServer | Calls the methods and properties of the Server object.
ISessionObject | Calls the methods and properties of the Session object.
IStringList | Retrieves the values stored in a string list such as that in the QueryString, Form, or ServerVariables collections.
IVariantDictionary | Provides an index of the Application and Session collections.
IWriteCookie | Sets the values and attributes of a cookie stored in the write-only Cookies collection.

To use the built-in object interfaces in a Java component, you must import the ASP classes into your code as shown below.

import com.ms.asp.*;

For more information about the built-in objects, see Built-in ASP Objects Reference.


Class Application

The Application class implements the IApplicationObject interface.

Syntax

public class asp.Application
    extends java.lang.Object
{
}

See Also

IApplicationObject


Class Request

The Request class implements the IRequest interface.

Syntax

public class asp.Request
    extends java.lang.Object
{
}

See Also

IRequest


Class Response

The Response class implements the IResponse interface.

Syntax

public class asp.Response
    extends java.lang.Object
{
}

See Also

IResponse


Class ScriptingContext

The ScriptingContext class implements the IScriptingContext interface.

Syntax

public class asp.ScriptingContext
    extends java.lang.Object implements IScriptingContext
{
}

Remarks

You can use the ScriptingContext class to gain access to the other built-in objects. If you use this method of accessing the built-in objects you should call the IScriptingContext interface in the OnStartPage method. Built-in objects can also be accessed through the ObjectContext object, which is the recommended method for components running on IIS 4.0 or later.

See Also

IScriptingContext Interface, ObjectContext Object


Class Server

The Server class implements the IServer interface.

Syntax

public class asp.Server
    extends java.lang.Object
{
}

See Also

IServer


Class Session

The Session class implements the ISessionObject interface.

Syntax

public class asp.Session
    extends java.lang.Object
{
}

See Also

ISessionObject


IApplicationObject Interface

The IApplicationObject interface enables your component to use the methods and properties of the Application object.

Syntax

public interface asp.IApplicationObject
    extends com.ms.com.IUnknown
{
           //Methods
    public abstract asp.IVariantDictionary getStaticObjects();
    public abstract asp.IVariantDictionary getContents();
    public abstract void Lock();
    public abstract void UnLock();
    public abstract com.ms.com.Variant getValue(java.lang.String);
    public abstract void putValue(java.lang.String, com.ms.com.Variant);
}

See Also

IApplicationObject


IReadCookie Interface

The IReadCookie interface enables your component to retrieve the values stored in the read-only Cookies collection.

Syntax

public interface asp.IReadCookie
    extends com.ms.com.IUnknown
{
           //Methods
    public abstract com.ms.com.IUnknown get_NewEnum();
    public abstract boolean getHasKeys();
    public abstract com.ms.com.Variant getItem(com.ms.com.Variant);
}

See Also

IReadCookie


IRequest Interface

The IRequest interface enables your component to use the methods and properties of the Request object.

Syntax

public interface asp.IRequest
    extends com.ms.com.IUnknown
{
    public abstract asp.IRequestDictionary getBody();
    public abstract com.ms.com.Variant BinaryRead(com.ms.com.Variant);
    public abstract asp.IRequestDictionary getQueryString();
    public abstract asp.IRequestDictionary getCookies();
    public abstract asp.IRequestDictionary getServerVariables();
    public abstract int getTotalBytes();
    public abstract asp.IRequestDictionary getForm();
    public abstract asp.IRequestDictionary getClientCertificate();
    public abstract java.lang.Object getItem(java.lang.String);
}

See Also

IRequest


IRequestDictionary Interface

The IRequestDictionary interface enables your component to retrieve values from the ClientCertificate collection.

Syntax

public interface asp.IRequestDictionary
    extends com.ms.com.IUnknown
{
    public abstract com.ms.com.IUnknown get_NewEnum();
    public abstract com.ms.com.Variant getItem(com.ms.com.Variant);
    public abstract com.ms.com.Variant getKey(com.ms.com.Variant);
    public abstract int getCount();
}

See Also

IRequestDictionary


IResponse Interface

The IResponse interface enables your component to use the methods and properties of the Response object.

Syntax

public interface asp.IResponse
    extends com.ms.com.IUnknown
{
           //Methods
    public abstract void Add(java.lang.String, java.lang.String);
    public abstract com.ms.com.Variant getExpires();
    public abstract void BinaryWrite(com.ms.com.Variant);
    public abstract void putExpires(int);
    public abstract java.lang.String getCacheControl();
    public abstract void putCacheControl(java.lang.String);
    public abstract java.lang.String getContentType();
    public abstract void AppendToLog(java.lang.String);
    public abstract void BinaryWrite(com.ms.com.SafeArray);
    public abstract java.lang.String getCharSet();
    public abstract void putCharSet(java.lang.String);
    public abstract void Pics(java.lang.String);
    public abstract void WriteBlock(short);
    public abstract boolean getBuffer();
    public abstract void putBuffer(boolean);
    public abstract void Clear();
    public abstract asp.IRequestDictionary getCookies();
    public abstract void putExpiresAbsolute(double);
    public abstract void End();
    public abstract void AddHeader(java.lang.String, java.lang.String);
    public abstract void putContentType(java.lang.String);
    public abstract java.lang.String getStatus();
    public abstract void putStatus(java.lang.String);
    public abstract void Flush();
    public abstract void Redirect(java.lang.String);
    public abstract com.ms.com.Variant getExpiresAbsolute();
    public abstract void Write(com.ms.com.Variant);
}

See Also

IResponse


IScriptingContext Interface

The IScriptingContext interface enables your component to retrieve interfaces to the built-in objects provided by ASP. You should not use this interface; use IObjectContext instead.

Syntax

public interface asp.IScriptingContext
    extends com.ms.com.IUnknown
{
           //Methods
    public abstract asp.IRequest getRequest();
    public abstract asp.IResponse getResponse();
    public abstract asp.IApplicationObject getApplication();
    public abstract asp.IServer getServer();
    public abstract asp.ISessionObject getSession();
}

Remarks

You can use the methods exposed by the IScriptingContext interface to access any of the ASP built-in objects. IScriptingContext, however, has been replaced by ObjectContext as the prefered way to access the built-in objects. You should use ObjectContext instead of IScriptingContext.

See Also

IScriptingContext


IServer Interface

The IServer interface enables your component to use the methods and properties of the Server object.

Syntax

public interface asp.IServer
    extends com.ms.com.IUnknown
{
           //Methods
    public abstract java.lang.Object CreateObject(java.lang.String);
    public abstract java.lang.String MapPath(java.lang.String);
    public abstract java.lang.String HTMLEncode(java.lang.String);
    public abstract java.lang.String URLEncode(java.lang.String);
    public abstract void putScriptTimeout(int);
    public abstract int getScriptTimeout();
}

See Also

IServer


ISessionObject Interface

The ISessionObject interface enables your component to use the methods and properties of the Session object.

Syntax

public interface asp.ISessionObject
    extends com.ms.com.IUnknown
{
           //Methods
    public abstract void Abandon();
    public abstract com.ms.com.Variant getValue(java.lang.String);
    public abstract void putValue(java.lang.String, com.ms.com.Variant);
    public abstract int getCodePage();
    public abstract void putCodePage(int);
    public abstract asp.IVariantDictionary getContents()
    public abstract int getLCID();
    public abstract asp.IVariantDictionary getStaticObjects();
    public abstract java.lang.String getSessionID();
    public abstract int getTimeout();
    public abstract void putTimeout(int);
    public abstract void putLCID(int);
}

See Also

ISessionObject


IStringList Interface

The IStringList interface enables your component to retrieve values from the QueryString, Form, or ServerVariables collections.

Syntax

public interface asp.IStringList
    extends com.ms.com.IUnknown
{
    public abstract int getCount();
    public abstract com.ms.com.IUnknown get_NewEnum();
    public abstract com.ms.com.Variant getItem(com.ms.com.Variant);
}

See Also

IStringList


IVariantDictionary Interface

You can use the IVariantDictionary interface to retrieve values from the Application Contents, Application StaticObjects, Session Contents and Session StaticObjects collections.

Syntax

public interface asp.IVariantDictionary extends com.ms.com.IUnknown
{
    public abstract com.ms.com.Variant getItem(com.ms.com.Variant);
    public abstract void putItem(com.ms.com.Variant, com.ms.com.Variant);
    public abstract com.ms.com.IUnknown get_NewEnum();
    public abstract com.ms.com.Variant getKey(com.ms.com.Variant);
    public abstract int getCount();
}

See Also

IVariantDictionary


IWriteCookie Interface

The IWriteCookie interface enables your component to add new values and set the attributes of the write-only Cookie collection.

Syntax

public interface asp.IWriteCookie
    extends com.ms.com.IUnknown
{
           //Methods
    public abstract void putExpires(double);
    public abstract void putSecure(boolean);
    public abstract void putPath(java.lang.String);
    public abstract com.ms.com.IUnknown get_NewEnum();
    public abstract boolean getHasKeys();
    public abstract void putDomain(java.lang.String);
    public abstract void putItem(com.ms.com.Variant, java.lang.String);
}

See Also

IWriteCookie


Visual Basic Object Model

Active Server Pages (ASP) implement classes that enable your component to access the properties and methods of the ASP built-in objects. The ObjectContext object exposes methods that return an interface to one of the ASP built-in objects. Your component can use these interfaces to access the methods and properties of the built-in objects.

The following table lists the built-in object classes:

Class | Use to
Application | Call the methods and properties of the Application object.
ObjectContext | Returns the built-in objects and provides methods used in transaction processing.
Request | Call the methods and properties of the Request object.
Response | Calls the methods and properties of the Response object.
ScriptingContext | Returns the built-in objects: Application, Request, Response, Server, or Session.
Server | Calls the methods and properties of the Server object.
Session | Calls the methods and properties of the Session object.

To use the ScriptingContext and built-in object in a Visual Basic component, you must load the Microsoft® ASP Object Library (asp.dll) into your available references. This file is installed with the ASP feature in the \inetsrv\asp\ directory.

For more information about the built-in objects see Built-in ASP Objects Reference.

Note If you are using Visual Basic 5.0, you should create your component as an ActiveX DLL and not an ActiveX control.


Application

This class contains methods that enable your component to call the methods of the Application object.

Method

Lock | Prevents other scripts from modifying variables stored in the Application object.
Unlock | Enables other scripts to modify variables stored in the Application object.

Collections

Contents | Contains all of the items that have been added to the session through script commands.
StaticObjects | Contains all of the objects added to the session with the <OBJECT> tag.


ObjectContext

This class contains methods that enable your component to use the methods and properties of the ObjectContext Object. An ASP script has access to only two of the ObjectContext methods: SetComplete and SetAbort. A component, however, can access all of the methods exposed by ObjectContext.

Method

SetComplete | Overrides any previous SetAbort method that has been called in a script.
SetAbort | Aborts a transaction initiated by an ASP.

For more information see ObjectContext Object in the MTS Reference.


Request

This class contains methods that enable your component to use the methods, properties, and collections of the Request object.

Methods

ClientCertificate as IRequestDictionary | Collection of client certificate fields (specified in the X.509 standard).
Cookies as IRequestDictionary | Collection of cookies sent as part of the request (read-only).
Form as IRequestDictionary | Collection of form elements.
QueryString as IRequestDictionary | Collection of query string values.
ServerVariables as IRequestDictionary | Collection of predetermined environment variables.
BinaryRead as Safe Array | Reads data sent to the server from the client as part of a POST request
TotalBytes as Variant | Specifies the total number of bytes the client sent in the body of the request.

Collections

ClientCertificate | The values of fields stored in the client certificate that is sent in the HTTP request.
Cookies | The values of cookies sent in the HTTP request.
Form | The values of form elements in the HTTP request body.
QueryString | The values of variables in the HTTP query string.
ServerVariables | The values of predetermined environment variables.


Response

This class contains methods that enable your component to use the methods and properties of the Response object.

Methods

AddHeader | Adds an HTTP header.
AppendToLog | Adds a string to the end of a Web server log entry for this request.
BinaryWrite | Writes content without any character conversion (Unicode to ANSI).
Buffer | Indicates whether page output is buffered.
CacheControl | Overrides the Private default value. By setting this property to Public, proxy servers will be able to cache the output generated by ASP.
Charset | Appends the name of the character set (for example, ISO-LATIN-7) to the content-type header in the Response object.
Clear | Erases any buffered output.
ContentType | The HTTP content type.
Cookies | Write-only. Collection of cookies sent as part of the response.
End | Causes ASP to stop processing and return any buffered output.
Expires | The length of time in minutes until the response expires.
ExpiresAbsolute | The absolute date and time that the response expires.
Flush | Sends buffered output immediately.
IsClientConnected | Indicates if the client has disconnected from the server since the last Response.Write
PICS | Adds a value to the PICS-label field of the response header.
Redirect | Sends a 302 Redirect status line.
Status | The HTTP server status line.
Write | Writes content with character conversion (Unicode to ANSI).

Collection

Cookies Specifies cookie values. Using this collection, you can set cookie values.


ScriptingContext

This class contains methods that your component can use to retrieve the built-in objects provided by ASP. This class is obsolete. You should not use it. Use ObjectContext instead.

Methods | Description
Application as IApplicationObject | Returns a copy of the Application object.
Request as IRequest | Returns a copy of the Request object.
Response as IResponse | Returns a copy of the Response object.
Server as IServer | Returns a copy of the Server object.
Session as ISession | Returns a copy of the Session object.


Server

This class contains methods that enable your component to use the methods and properties of the Server object.

Methods

CreateObject | Creates an instance of a server component.
HTMLEncode | Applies HTML encoding to a specified string.
MapPath | Maps the specified relative or virtual path to the corresponding physical directory on the server.
ScriptTimeout | The maximum length of time in seconds before a script is terminated.
URLEncode | Applies URL encoding rules, including escape characters, to a specified string.


Session

This class contains methods that enable your component to use the methods and properties of the Session object.

Methods

Abandon | Destroys a Session object and releases its resources.
CodePage | Determines the codepage that will be used to display dynamic content.
LCID | Specifies the locale identifier which is a standard international abbreviation that uniquely identifies one of the system-defined locales.
SessionID | Returns the session identifier of the user.
Timeout | The length of time, in minutes, of the Timeout period.

Collections

Contents
StaticObjects


Additional Resources on Creating Components

There are a number of tools available to help you develop components that run in IIS. Microsoft® Visual Interdev™ provides an excellent environment for inserting your components into ASP pages. In addition, the ActiveX™ Template Library will help you get started in creating COM components.

COM architecture has been thoroughly documented both through Microsoft publications and by third parties. The COM Concepts section summarizes some of these sources for more information.


COM Concepts

Microsoft developed COM as its programming paradigm for component-based application development. COM defines a set of principles to achieve three goals: encapsulation, polymorphism, and inheritance. In addition, COM provides a structure which facilitates distribution and avoids the problems associated with reusing components.

As an IIS component developer, you need to understand some basic COM concepts. Microsoft provides many resources which describe COM. The topics below present some of the major concepts that you will need to master, along with references to resources so that you can learn more.

  • General Overviews of COM
  • Interfaces and Objects


General Overviews of COM

Many informative books on COM have been released recently. Two books that give an excellent summary are Inside COM, by Dale Rogerson, published by Microsoft Press and Understanding ActiveX and OLE by David Chappell, also published by Microsoft Press.

In addition, COM is thoroughly documented in the Microsoft Developer Network Library. Some good sources for general descriptions of COM are:

Component Object Model Specification, Chapters 1 and 2 (MSDN Library, Specifications)

The Rules of the Component Object Model (MSDN Library, Technical Articles)

The Distributed Component Object Model: A Business Overview (MSDN Library, Backgrounders)


Interfaces and Objects

The COM library provides a standard set of interfaces that you can use to develop components. If you find that these interfaces do not meet your exact requirements, you can create your own interfaces. Microsoft has published guidelines to assist you in desiging COM interfaces and objects. Two good sources for information on this area are:

Designing COM Interfaces (Platform SDK, Object Services)

Component Object Model Specification, Chapter 3 (MSDN Library, Specifications)


IIS Administration

The Microsoft® Internet Information Server (IIS) offers you substantial configuration flexibility through a wealth of parameter settings so that you can tailor your installation to best suit your needs. In addition to the interactive administration user interface, IIS provides powerful, yet easy-to-use programming tools for you to create automated configuration administration programs.

The IIS Admin Objects enable you programmatically to administer your IIS configuration settings, which are stored in the IIS Metabase. You can use these objects with Automation languages such as Microsoft® Visual Basic® Scripting Edition (VBScript), Microsoft JScript™, C++, or any other language that supports automation. The IIS Admin Objects provide a simple and effective way to use Active Server Pages (ASP) scripts to build custom administration programs. Details of the IIS administration programming tools for Automation languages are presented in the following sections:

  • The IIS Metabase describes the structure, storage, features, performance, and security of the metabase, which stores IIS configuration data.
  • The IIS Admin Objects details the use of Automation languages to administer IIS configuration parameter values in the metabase, and to manage your Web applications programmatically.
  • The Administration Property Reference provides details of IIS configuration parameters you can manage with the IIS Admin Objects.

Sample code segments in many of the topics illustrate usage of the IIS Admin Objects. The Developer Samples include simple site administration task demonstrations, and the Sample Administration Scripts provide a collection of scripts that you may customize for your needs.

C++ Interfaces for IIS Administration

IIS also provides additional interfaces specifically designed for C++ programs that you can use to extend and enhance your IIS installation. These interfaces are intended for use by experienced programmers who have in-depth knowlege of IIS internals. Details of these interfaces and reference information are presented in the following sections:

  • IIS Admin Base Object provides details about using the IMSAdminBase interface with C++ programs to extend the metabase and manage your IIS configuration.
  • Metabase Identifier Reference provides details of IIS configuration parameters that you can manage with the IIS Admin Base Object.
  • Web Application Management Interface provides details on using the IWamAdmin interface with your custom C++ programs to manage Web applications.
  • Custom Extensions Interface provides detailed information on using the IADMEXT interface to integrate your custom C++ programs into IIS operation.
  • Replication Extension Interface provides detailed information on using the IMSAdminReplication interface with your custom C++ programs to augment site replication functionality provided with IIS.


IIS Metabase

The metabase stores your IIS configuration parameter values in a fast-access, memory-resident data store. The metabase is specifically designed for use with IIS and is faster, more flexible, and more expandable than the Windows NT® registry. You can use the IIS Admin Objects with Automation and scripting languages to administer your IIS installation by setting IIS configuration parameter values in the metabase.

Details of the IIS metabase are presented in the following sections:

  • Structure details the organization of data in the metabase.
  • Key Names and Paths describes how metabase keys are addressed.
  • Property Inheritance describes a metabase feature that simplifies configuration operations and reduces storage requirements.
  • Performance addresses optimization and locking strategies for the metabase.
  • Security provides strategy and implementation details for protecting and backing up the metabase.

For custom use and extension of the metabase with C++ programs, see IIS Admin Base Object.


Structure

The IIS metabase keys correspond to the elements of IIS and each key contains properties that affect the configuration of its associated element. Each node in the metabase structure is called a key and may contain one or more IIS configuration values, called metabase properties. The metabase is organized in a hierarchical structure that mirrors the structure of your IIS installation. Most of the IIS configuration keys and values stored in the system registry for previous versions of IIS are now stored as properties in the metabase. New keys and values have been added for finer and more flexible control of IIS. The structure of the metabase facilitates different settings of a property for different keys. For example, the MaxBandwidth property setting can be a different value for each server.

The general structure of IIS is shown in the following figure. Your system's structure may include more or fewer elements depending on your installation choices. Metabase keys associated with IIS elements are addressed by their paths within the metabase. See Key Names and Paths.

The top level metabase key, Computer, contains properties such as MaxBandwidth that affect the overall execution of IIS on your computer. Two keys directly subordinate to the top level key are associated with FTP services and Web services, respectively, and contain properties that affect all FTP servers and all Web servers. Other keys directly subordinate to the top level key contain properties that affect logging and MIME mappings. The IISADMIN key is used to record DCOM extensions to IIS.

Keys directly subordinate to the FTP service key are associated with individual FTP servers and contain properties specific to each FTP server. A key subordinate to each FTP server key is associated with the root virtual directory for that server. Other keys are added below the root virtual directory key as you add virtual directories to your FTP servers. Each of these keys contains properties that affect the operation or configuration of the associated virtual directory. The Info key, directly subordinate to the FTP Service key, also contains some properties associated with the FTP service.

Keys subordinate to the Web service key are associated with individual Web servers, their root virtual directories, subordinate virtual directories, and disk directories and files. A key directly subordinate to the Web service key affects the configuration of filters used by Web service operations. The Info key, directly subordinate to the Web Service key, also contains some properties associated with the Web service.

Keys can also contain references to objects that can be used by the IIS Admin Objects. For example, the CertMapper key contains no metabase properties but does provide access to the IIsCertMapper object and its methods for mapping certificates.


Key Names and Paths

A metabase key is a location in the metabase analogous to a directory in the file system. A metabase path is a sequence of keys separated by a forward slash (/) that uniquely identifies the location of a key in the metabase. Key names in the metabase are not unique unless qualified by their metabase paths, just as different files with the same name may exist in different directories.

You can use a metabase key's path with the IIS Admin Objects to access the specific IIS Admin Object associated with that key. The IIS Admin Objects use the Active Directory Service Interfaces (ADSI) path, called the ADsPath, to refer to the object associated with a key. The ADsPath starts with IIS:// and then uses the term LocalHost, or a specific computer name, to refer to the IIsComputer object, which is associated with the highest key in the metabase.

The paths to objects associated with other metabase keys are an extension of the ADsPath to the computer key. For example, the ADsPath for the first Web site in your IIS installation would be IIS://LocalHost/W3SVC/1. You could also use the path IIS://ComputerName/W3SVC/1 to access the metabase on a different computer.

Each Web site is a server instance (virtual server), and is referred to in the path by its number. For example, IIS://LocalHost/MSFTPSVC/3 represents the third FTP server instance, and IIS://MachineName/W3SVC/4 represents the fourth Web server instance.

Each virtual server instance has an associated root virtual directory. All other virtual directories and directories associated with a server instance are subordinate to this root virtual directory. The name of the root virtual directory is ROOT, so that IIS://LocalHost/MSFTPSVC/3/ROOT refers to the root virtual directory for the third FTP server on the local computer, and IIS://LocalHost/W3SVC/4/ROOT refers to the root virtual directory for the fourth Web server on the same computer.

You can establish the structure below the root virtual directory of a server instance by adding virtual directories, directories, and files. For FTP servers, metabase properties can be set to the level of virtual directory. For Web servers, you can also set properties to the level of directories and files. For example, you could use the path IIS://LocalHost/W3SVC/2/ROOT/MyVdir1/Dir1/File1 to set file properties such as read, write, and execute permissions.


Property Inheritance

The property inheritance feature of the metabase enables you to configure your IIS installation with few repetitious settings, and to minimize the amount of memory required for the metabase. Most metabase properties are inheritable—properties that are not explicitly set at a specific key inherit values assigned at higher level keys. For example, you can set file and directory permissions such as AccessRead and AccessWrite at the W3SVC level to apply to all files and directories in all Web site server instances, or you can set them at the W3SVC/2/ROOT level to apply to all files and directories for the second Web server only. You can then set different permissions for individual directories and files by explicitly setting them at lower levels. For example, you might set the AccessExecute permission property to FALSE for the second Web server (...W3SVC/2/ROOT) and then explicitly set it to TRUE for specific virtual directories, directories, or files on that server, such as ...W3SVC/2/ROOT/VDir1/VDir1a, ...W3SVC/2/ROOT/VDir2/Dir2d, and ...W3SVC/2/ROOT/VDir2/Dir3/File1, and so on.

Most metabase properties are inheritable. A few are used only at specific keys and are not inheritable. Some properties in the metabase are lists of values, such as the ServerBindings property (a list of server binding values). Modifications to an inherited list repeat the entire list at the key where it is modified, with some exceptions such as lists of errors that inherit a default list and only store changes at keys where you modify the list.

Flag properties, such as file access permissions, are often combined into one DWORD. The entire set of flags stored together inherits together. For example, if you change one of the file access permissions, such as AccessRead for a directory, the entire set of file access permissions, in the property AccessFlags, is stored at the metabase key for that directory. This means that if you change other default file access permissions, such as AccessWrite or AccessScript, at a key above that directory's key, the changes will not be inherited because they are already stored at the directory's key.

Metabase properties are individually described in detail, including whether or not they are inheritable, in the Administration Property Reference. Properties such as access permission properties that are stored as part of a set are so identified, along with the other properties in the set and the property associated with the entire set.


Performance

The metabase is memory-resident and optimized for read operations. When you use one of the IIS Admin Objects to modify metabase properties, the property values are cached in the object so IIS can continue to operate efficiently while your program is making changes. Your changes actually take place in the object, not in the metabase. After changing property values, you must use the SetInfo method to save the changed values back to the metabase. Your changes will be discarded if you release the object before using the SetInfo method.

If you create multiple programs that make changes to the metabase you should be careful to design your programs so they don't independently change values for the same properties at the same key.


Security

The metabase key values are stored in a disk file. The metabase is loaded from disk when IIS starts, stored to disk when IIS shuts down, and saved periodically while IIS is running. It is important to protect this file from unauthorized use, even though secure data is stored in a secure manner within the file. It is recommended that you store this file on an NTFS partition and use Windows NT® security to protect it.

The metabase is stored in a special format file, by default named METABASE.BIN in the INETSRV directory in which you installed IIS. You can move or rename the file and change the Windows NT® registry setting that tells IIS where to find the file on startup. To relocate or rename the metabase file, you will need to stop IIS, move or rename the file, and modify the registry key LOCAL_MACHINE\\SOFTWARE\\Microsoft\\INetMgr\\Parameters. Add a REG_SZ value to this key named MetadataFile that specifies the new complete path of the metabase file including the drive letter and file name.

Metabase Backup

You can implement your own custom backup policy for the metabase using simple ASP scripts. The IISComputer object in the IIS Admin Objects provides methods to manage metabase backups. These methods allow you to store multiple backup versions in long-term storage, restore the metabase from a backup version of your choice, and enumerate and delete backups. You can also use the IIS Admin Base Object with C++ programs to implement the same backup management functionality.


IIS Admin Objects

Your custom programs can administer your IIS configuration by using the IIS Admin Objects to modify IIS configuration settings that are stored as data in the metabase. The structure of the metabase parallels the structure of your IIS installation, and the property inheritance feature of the metabase enables you to establish IIS configuration settings efficiently. The IIS Metabase topic provides details of how the metabase stores your configuration settings.

The IIS Admin Objects are COM Automation-based, and can be used with any language that supports Automation, such as Microsoft® Visual Basic® Scripting Edition (VBScript) or JScript™ in ASP pages, Visual Basic, Java, or C++.

This section includes:

  • About the IIS Admin Objects discusses the Object Hierarchy and ADSI Features.
  • Using the IIS Admin Objects presents information about creating programs, and a Sample Program that displays the structure of your IIS installation.
  • IIS Admin Objects Reference provides details of each object, specific object methods, and metabase properties accessible by the object.

For custom use and extension of the metabase with C++ programs, you can also use the IIS Admin Base Object.


About the IIS Admin Objects

The IIS Admin Objects (IISAO) are COM objects that your ASP script or custom application can use to change IIS configuration values stored in the IIS Metabase. For example, metabase properties AccessRead, AccessWrite, AccessExecute, and other file and directory access permissions used by IIS are stored in the metabase; you can efficiently set these permissions for one or many files and directories with a simple ASP script.

Individual IIS Admin Objects correspond to keys in the metabase and are addressed by their paths within the metabase. Each object has properties and each property corresponds to a property in the metabase. Modifying an IIS Admin Object property changes the corresponding value of a metabase property, enabling you to configure individual elements of IIS such as the Computer, FTP server, or Web server. Because of the hierarchical structure of the metabase and its property inheritance feature, you can easily configure properties for a single file, a single server, all Web servers, all FTP servers, or the common properties of many other groups of objects

The IIS Admin Objects also implement properties and methods of the Microsoft® Active Directory Services Interface (ADSI) specification, so the IIS Admin Objects together implement an ADSI namespace provider for IIS. This provides a common set of address paths, properties, and methods for your program to use.

This section contains:

  • The Object Hierarchy topic describes the relationship of the IIS Admin Objects to the metabase and how you address these objects in your program.
  • The ADSI Features topic describes how the IIS Admin Objects implement common properties and methods that you can use.


Object Hierarchy

The IIS Admin Objects are organized in a hierarchical structure that mirrors the structures of the metabase and IIS. Objects contain other objects to create the object structure illustrated in the diagram below. Details of the IIS structure and the metabase are found in the Structure topic of the IIS Metabase section. This object hierarchy enables you to access metabase properties that determine configuration settings for specific IIS elements.


ADSI Features

The IIS Admin Objects are namespace providers in support of the ADSI standard for remote administration of directory service namespaces. This provides a standard syntax for addressing IIS configuration data. The IIS namespace is composed of the IIS Admin Objects and the metabase. The remote Internet Service Manager (HTML) for IIS uses the IIS Admin Objects.

You can reference one of the IIS Admin Objects by its path, which is the same as the path to the associated key in the metabase. For example, the IIS Admin Object for the first virtual Web server on the computer named MyComputer would be addressed by the ADSI path (ADsPath) IIS://MyComputer/W3SVC/1. The following VBScript code uses the path to the first virtual Web server to open the IIS Admin Object associated with the metabase key for that server on the computer named MyComputer. You can use LocalHost instead of MyComputer to access the computer on which IIS is running.

<%
Dim VSvrObj
Set VSvrObj = GetObject("IIS://MyComputer/W3SVC/1")
%>

ADSI Objects

The IIS Admin Objects each implement the IADs interface defined by the ADSI standard. The IADs interface for the IIS Admin Objects provides the following basic functionality:

  • identification information that indicates the name and type of the object
  • binding information that uniquely identifies the object instance in a directory tree
  • a way to retrieve the path of the object's parent container object
  • a way to retrieve the schema definition of the object
  • a way to retrieve namespace properties
  • a simple caching system

The IIS Admin Objects implement the IADs interface, supporting the Name, ADsPath, Class, GUID, Parent, and Schema properties in addition to IIS-specific metabase properties. The IADs GetInfo, SetInfo, Get, Put, GetEx, PutEx, and GetInfoEx methods are also supported in addition to others needed for IIS configuration administration. See the ADSI Object Properties and ADSI Object Methods topics in the Using the IIS Admin Objects section.

ADSI Container Objects

All of the IIS Admin Objects that can contain other objects also implement the IADsContainer interface defined by the ADSI standard, in addition to the IADs interface. Examples of IIS Admin Objects that support IADsContainer include IIsComputer, which can contain IIsWebService and IIsFtpService objects among others, and the IIsWebVirtualDir object, which can contain IIsWebDirectory and IIsWebFile objects, as well as additional IIsWebVirtualDir objects.

The IADsContainer interface permits objects to contain other objects and provides the following basic functionality:

  • a way to count the number of objects within the container
  • a way to enumerate through the contained objects
  • a way to access contained objects
  • a way to create objects within the container
  • a way to delete objects from the container

The IIS Admin Objects that can contain other objects implement container object properties and methods by supporting the IADsContainer interface Count and _NewEnum properties and the GetObject, Create, and Delete methods. IIS Admin Objects also support the basic IADs interface properties and methods, and any IIS-specific properties and methods. For more information, see ADSI Container Object Properties and ADSI Container Object Methods.


Using the IIS Admin Objects

You can use the IIS Admin Objects to configure your IIS installation, creating new FTP and Web servers, virtual directories, and other IIS elements, and also changing settings that affect IIS operation. Your IIS configuration information is stored as values in the metabase, called metabase properties, and you use the IIS Admin Objects to change these configuration values. Individual IIS Admin Objects correspond to specific types of keys in the metabase. With simple ASP scripts, you can use the IIS Admin Objects to create powerful and flexible custom administration applications for remote administration of your IIS installation. The remote Internet Service Manager (HTML) for IIS was developed using the IIS Admin Objects with VBScript and JScript™. The source code files for this program are located in \system32\inetsev\iisadmin in your system directory.

The IIS Admin Objects expose a hierarchical namespace of objects where each object has an ADsPath, similar to a Uniform Resource Locator (URL), that is prefixed with IIS:// followed by the name of the computer on which IIS is running, followed by the path of the object in the metabase. For example, IIS://MyComputer/W3SVC refers to the IIsWebService object for the machine named MyComputer. The object associated with the machine on which IIS is running is the IIsComputer object, and contains all of the other IIS Admin Objects directly or indirectly. To get a reference to a named object, you use the GetObject function in Visual Basic®, VBScript or other scripting languages. For example, you can retrieve the current value of MaxBandwidth for the computer named MyComputer with the following VBScript in an .asp file. You can use LocalHost instead of MyComputer to access the computer on which IIS is running.

<%
Dim ComputerObj
Dim MaxBW
Set ComputerObj = GetObject("IIS://MyComputer")
MaxBW = ComputerObj.Get("MaxBandwidth")
' You could also use MaxBW = ComputerObj.MaxBandwidth
%>

Note ASP scripts that access the metabase require administrator privileges on the machine on which IIS is running. When you execute these scripts from a remote machine, you must connect through a secure connection, such as the Windows NT Challenge/Response authentication method. It is suggested that you create a server or directory for your administrative .asp files and set the directory security authentication method to Windows NT Challenge/Response for the server or directory.

Note For security purposes, out-of-process applications cannot access the metabase. It is recommended that you retain this default behavior unless special circumstances require otherwise. There are two ways you can modify this behavior, but each introduces some security risk. One approach is to give the IWAM_machinename account access to the metabase, which will allow access to the metabase for all out-process-applications created with this default identity. Another approach is to change the identity of the specific out-of-process-package to some other account identity and give that account access to the metabase. This introduces some risk but less than that introduced by giving metabase access to the IWAM_machinename account.

The topics in this section explain how to use the ADSI methods for the IIS Admin Objects, and provide a sample program using these methods.

  • ADSI Object Properties describes the ADSI-specified properties of the IIS Admin Objects.
  • ADSI Object Methods describes the ADSI-specified methods used by Automation languages such as VBScript.
  • ADSI Container Object Properties describes the ADSI-specified properties of those IIS Admin Objects that are also container objects.
  • ADSI Container Object Methods describes the ADSI-specified methods of those IIS Admin Objects that are also container objects.
  • Common Object Methods describes those methods, other than ADSI methods, that can be used by any of the IIS Admin Objects.
  • The Sample Program uses ADSI container features and ADSI properties and methods in an ASP script to display the structure of your IIS namespace.


ADSI Object Properties

The IIS Admin Objects implement the six basic properties that ADSI objects require. These properties are all of data type string.

ADSI Property | Description
Name | The name of the object used within the underlying namespace.
ADsPath | The path that uniquely identifies the object, and which is used in GetObject to retrieve the object.
Class | The name of the schema class of the object.
GUID | A unique identifier for objects of this schema class. IIS uses the Globally Unique Identifier (GUID).
Parent | The ADsPath of the parent container object.
Schema | The ADsPath of the object that represents this schema class in the schema.

The ADSI object properties are read-only and are provided for use with ADSI-aware programs for ADSI namespace administration. The following table provides an example of the ADSI properties for the IIsWebService object. "LocalHost" is the string that specifies the local computer on which IIS is running.

ADSI Property | Value
Name | W3SVC
ADsPath | IIS://LocalHost/W3SVC
Class | IIsWebService
GUID | {8B645280-7BA4-11CF-B03D-00AA006E0975}
Parent | IIS://LocalHost
Schema | IIS://LocalHost/schema/IIsWebService

You can use the ADSI Name property to document the structure of your IIS installation. The Sample Program provides an ASP file that will recursively walk the structure of your installation and display the IIS ADSI object properties in your browser.

You use the metabase properties supported by the IIS Admin Objects to control the configuration of your IIS installation. See ADSI Object Methods and the specific metabase properties supported by each of the individual IIS Admin Objects.


ADSI Object Methods

You use the ADSI methods of the IIS Admin Objects to change metabase property values that control your IIS configuration. To configure a specific element of IIS, you open the IIS Admin Object that corresponds to the metabase key associated with that element, modify the property values cached in the object, and direct the object to store the modified values into the metabase.

These ADSI methods of the IIS Admin Objects manipulate metabase properties.

Method | Description
Get | Retrieves value for a named property from the object.
GetEx | Retrieves value(s) for a named single- or multi-valued property of the object.
GetInfo | Reloads the object with property values that exist in the metabase.
GetInfoEx | Reloads the object with property values from the metabase.
Put | Sets the value for a named property of an object.
PutEx | Sets value(s) for a named single- or multi-valued property of the object.
SetInfo | Writes object property values to the metabase.

The GetInfo method reloads the property values from the metabase into the object. When one of the IIS Admin Objects is created or opened with the GetObject function, its properties are initialized from the metabase. You can refresh these values from the metabase using the GetInfo or GetInfoEx methods, overwriting any changes you have made to the property values cached in the object. You then use the Get or GetEx methods to retrieve the object properties into variables, and the Put and PutEx methods to modify property values in the object. The IIS Admin Objects also support the object.property syntax when used with languages such as VBScript or JScript. You use the SetInfo method to write property values from the object to the metabase. When you call SetInfo, only the properties that you changed in the object are written back to the metabase. If you do not call SetInfo, your changes will not be written to the metabase.

Note When you retrieve metabase properties into one of the IIS Admin Objects, the metabase is not locked while you are changing property values in the object. Other programs may make changes to values in the metabase after you have retrieved values and before you save them back into the metabase. The final values in the metabase will reflect the last change written. Your program should minimize the time between retrieving and saving values.

ADSI properties apply only to the object, and non-ADSI properties apply to the metabase. You must use the object.property syntax when retrieving ADSI properties, whereas you may use either the object.property syntax or the ADSI methods such as Get and Put when manipulating metabase properties.

Example

This sample VBScript code shows how you use the ADSI methods of the IIS Admin Objects to change values in the metabase, and illustrates the use of metabase property inheritance for efficiency. You can use LocalHost instead of MyComputer to access the computer on which IIS is running.

<%
Dim WebServerObj
Dim VDirObj
Dim WritePerm

' Open the object for the first virtual Web server root
Set WebServerObj = GetObject("IIS://MyComputer/W3SVC/1/Root")

' Deny write access for all directories and files
' for the server (except those already specifically set)
' Using the Put method
WebServerObj.Put "AccessWrite", False

' Save the changed value to the metabase
WebServerObj.SetInfo

' Get a directory subordinate to the Web server root
Set VDirObj = GetObject("IIS://MyComputer/W3SVC/1/Root/Vdir1/Dir1a")

' Overwrite the inherited value for write access
' Using the dot method equivalent to Put
VDirObj.AccessWrite = True

' Save the changed value to the metabase
VDirObj.SetInfo
%>


Get

The ADSI Get method for IIS Admin Objects retrieves a metabase property value from the object into a variable. Some languages such as VBScript also support the object.property syntax as an alternative to the Get and Put methods.

Syntax

value = object.Get(property)
or
value = object.property

Parts

value
Receives the returned value of the property.
object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
property
A property of the object that has been retrieved from the metabase.

Code Example

<%
Dim IIsObj, vRead, vWrite
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/1/Root")
' Get the value from the object
vRead = IIsObj.Get("AccessRead")
' Can also use object.property syntax
vWrite = IIsObj.AccessWrite
' Set the values
vRead = True
vWrite = False
' Put the values back in the object
IIsObj.Put "AccessRead", vRead
' Use optional object.property syntax
IIsObj.AccessWrite = vWrite
' Save the changes back to the metabase
IIsObj.SetInfo
%>

See Also

GetInfo, SetInfo, Put, GetEx, PutEx, GetInfoEx


GetEx

The ADSI GetEx method retrieves a single- or multi-valued property value from the object into a variant-array variable.

Syntax

value = object.GetEx(property)

Parts

value
Receives the returned property value from the method.
object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
property
A property of the object that has been retrieved from the metabase.

Return Values

Returns the value of the property.

Code Example

<%
Dim IIsObj, vList
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/Info")
' Get the value from the object
vList = IIsObj.GetEx("CustomErrorDescriptions")
' Modify the list

' Put the values back in the object
IIsObj.PutEx 2, "CustomErrorDescriptions", vList
IIsObj.SetInfo
%>

See Also

GetInfo, SetInfo, Get, Put, PutEx, GetInfoEx


GetInfo

The ADSI GetInfo method re-initializes the object's properties from the metabase. Because the object's properties are automatically initialized when the object is created, you only need to use this method if you want to refresh properties in the object with current values from the metabase.

Syntax

object.GetInfo

Parts

object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.

Code Example

<%
Dim IIsObj
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/1/Root")
' Make some changes to properties
' . . .
' Discard changes and refresh property values in the object
IIsObj.GetInfo
%>

See Also

SetInfo, Get, Put, GetEx, PutEx, GetInfoEx


GetInfoEx

The ADSI GetInfoEx method reinitializes the object's properties from the metabase. As implemented by IIS, this method performs the same function as the GetInfo method.

Syntax

object.GetInfoEx

Parts

object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.

Code Example

<%
Dim IIsObj
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/1/Root")
' Make some changes to properties
' . . .
' Discard changes and refresh property values in the object
IIsObj.GetInfoEx
%>

See Also

GetInfo, SetInfo, Get, Put, GetEx, PutEx


Put

The ADSI Put method sets the value for a metabase property in the object. Some languages, such as VBScript, also support the object.property syntax as an alternative to the Get and Put methods.

Syntax

object.Put property, value
or
object.property = value

Parts

object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.
property
A property of the object that has been retrieved from the metabase.
value
The value for the property.

Code Example

<%
Dim IIsObj, vRead, vWrite
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/1/Root")
' Get the value from the object
vRead = IIsObj.Get("AccessRead")
' Can also use object.property syntax
vWrite = IIsObj.AccessWrite
' Set the values
vRead = True
vWrite = False
' Put the values back in the object
IIsObj.Put "AccessRead", vRead
' Use optional object.property syntax
IIsObj.AccessWrite = vWrite
' Save the changes back to the metabase
IIsObj.SetInfo
%>

See Also

GetInfo, SetInfo, Get, GetEx, PutEx, GetInfoEx


PutEx

The ADSI PutEx method sets the value for a single- or multi-valued metabase property in the object. You can use PutEx to remove (also called clear) a property from a metabase key.

Syntax

object.PutEx controlcode, property, value

Parts

object
Contains the IIS Admin Object, usually as a result of a previous GetObject operation.
controlcode
Specifies whether to update the property or to remove the property from the object. One of: ADS_PROPERTY_CLEAR (value 1) to remove the property, or ADS_PROPERTY_UPDATE (value 2) to update the property.
property
A property of the object that has been retrieved from the metabase.
value
The value for the property. An empty string when removing the property (controlcode = ADS_PROPERTY_CLEAR).

Remarks

For a metabase property to use inherited data at a key, the property must not exist at the key. You can remove it by using ADS_PROPERTY_CLEAR. You can use the GetDataPaths method common to all IIS Admin Objects to locate the keys where a property exists.

Code Example

<%
Dim IIsObj, vList
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/Info")
' Get the value from the object
vList = IIsObj.GetEx("CustomErrorDescriptions")
' Modify the list

' Put the values back in the object
IIsObj.PutEx 2, "CustomErrorDescriptions", vList
' Remove another property from the object
IIsObj.PutEx 1, "ObsoleteProperty", ""
IIsObj.SetInfo
%>

See Also

GetInfo, SetInfo, Get, Put, GetEx, GetInfoEx


SetInfo

The ADSI SetInfo method saves changed property values from the object into the metabase. After you have changed some or all of the values in the object properties, you must use the SetInfo method to save the new values back into the metabase. Only the values you changed will be saved back into the metabase; unchanged values will not be written.

Syntax

object.SetInfo

Parts

object
Contains an IIS Admin Object, usually as a result of a previous GetObject operation.

Code Example

<%
Dim IIsObj
Set IIsObj = GetObject("IIS://LocalHost/W3SVC/1/Root")
' Make some changes to properties
' . . .
' Save the changes back to the metabase
IIsObj.SetInfo
%>

See Also

GetInfo, Get, Put, GetEx, PutEx, GetInfoEx


ADSI Container Object Properties

IIS Admin Objects that can contain other objects also implement the ADSI container methods and properties. This includes the following read-only ADSI container properties:

ADSI Container Property | Description
_NewEnum | Returns an Enumerator object that can be used to retrieve the contained objects. This property enables Automation languages such as VBScript to enumerate contained objects using the "For Each Object in ContainerObject" syntax.
Count | The number of objects in the container object.


ADSI Container Object Methods

You use the ADSI container object methods of the IIS Admin Objects to manipulate keys in the metabase. You create, delete, and move keys by creating, deleting, and moving IIS Admin Objects within container objects. You can also enumerate contained objects such as virtual directories or servers with container object methods.

These ADSI container object methods manipulate IIS Admin Objects and metabase keys:

Method | Description
CopyHere | Copies an object into a container
Create | Creates a new object in a container
Delete | Deletes an object from a container
GetObject | Accesses an object in a container
MoveHere | Copies an object into a container and deletes the original object

Note When one of the IIS Admin Objects is a container object, it still retains its own ADSI object properties and methods, as well as any IIS-specific methods and associated metabase properties.


CopyHere

The ADSI container object CopyHere method copies an object into a container.

Syntax

Set CopiedObj = Object.CopyHere(SourceName, NewName)

Parts

CopiedObj
Accesses the copied object in the container.
object
The IIS Admin Object that contains the object. Usually the result of a previous GetObject operation.
SourceName
The name of the object to be copied.
NewName
The new name for the copied object.

Remarks

The CopiedObj variable receives a pointer to the object itself, which remains in the container.

When the contained object to be copied is part of an application, the CopyHere method will remove the application definition before copying the object. See the AppDelete method of the IIsWebVirtualDir and IIsWebDirectory objects.

Code Example

<%
Dim ToVDirObj, FromVDirObj, RootVDirObj
' Get the root virtual directory object for a server
Set RootVDirObj = GetObject("IIS://LocalHost/W3SVC/4/ROOT")
' Copy a virtual directory object
' Also get a pointer to the new object
Set ToVdirObj = RootVDirObj.CopyHere("VDir1", "VDir2")
RootVDirObj.SetInfo
%>

See Also

GetObject, Create, Delete, MoveHere


Create

The ADSI container object Create method creates a new object in a container.

Syntax

Set NewObj = Object.Create(KeyType, Name)

Parts

NewObj
Accesses the new object created in the container.
object
The IIS Admin Object that contains the object. Usually the result of a previous GetObject operation.
KeyType
The type of IIS Admin Object to create.
Name
The name for the new object.

Code Example

<%
Dim WebServiceObj, ServerObj
' Get the web service object, which contains servers
Set WebServiceObj = GetObject("IIS://LocalHost/W3SVC")
' Create a new web server object in the container
Set ServerObj = WebServiceObj.Create("IIsWebServer", "3")
' Add code to configure server and create Root virtual directory
%>

See Also

GetObject, Delete, CopyHere, MoveHere


Delete

The ADSI container object Delete method deletes an object from a container.

Syntax

Object.Delete KeyType, Name

Parts

object
The IIS Admin Object that contains the object. Usually the result of a previous GetObject operation.
KeyType
The type of IIS Admin Object to delete.
Name
The name of the object to delete.

Remarks

When the contained object to be deleted is part of an application, the Delete method will remove the application definition before deleting the object. See the AppDelete method of the IIsWebVirtualDir and IIsWebDirectory objects.

Code Example

<%
Dim WebServiceObj
' Get the web service object, which contains servers
Set WebServiceObj = GetObject("IIS://LocalHost/W3SVC")
' Delete the fourth server
WebServiceObj.Delete "IIsWebServer", "4"
%>

See Also

GetObject, Create, CopyHere, MoveHere


GetObject

The ADSI container object GetObject method accesses an object in a container.

Syntax

Set ChildObj = Object.GetObject(Class, ChildName)

Parts

ChildObj
Accesses the object like the ASP GetObject function.
Object
The IIS Admin Object that contains the object. Usually the result of a previous GetObject operation.
Class
Specifies the class of the object to be accessed.
ChildName
The name of the object to be accessed.

Remarks

The ChildObj variable receives a pointer to the object itself, which remains in the container.

Code Example

<%
Dim WebServiceObj, ServerObj
' Get the web service object, which contains servers
Set WebServiceObj = GetObject("IIS://LocalHost/W3SVC")
' Access the object for the third web server
Set ServerObj = WebServiceObj.GetObject("IIsWebServer", "3")
%>

See Also

Create, Delete, CopyHere, MoveHere


MoveHere

The ADSI container object MoveHere method moves an object into a container and removes the object from its origin.

Syntax

Set MovedObj = Object.MoveHere(SourceName, NewName)

Parts

MovedObj
Accesses the object moved into the container.
object
The IIS Admin Object that contains the object. Usually the result of a previous GetObject operation.
SourceName
The name of the object to be moved.
NewName
The name for the moved object.

Remarks

The MovedObj variable receives a pointer to the object itself, which remains in the container.

The MoveHere method is equivalent to CopyHere followed by Delete.

When the contained object to be moved is part of an application, the MoveHere method will disable the application definition before moving the object. See the AppDisable method of the IIsWebVirtualDir and IIsWebDirectory objects.

Code Example

<%
Dim ToVDirObj, FromVDirObj, RootVDirObj
' Get the root virtual directory object for a server
Set RootVDirObj = GetObject("IIS://LocalHost/W3SVC/3/ROOT")
' Get the object to be moved
Set FromVDirObj = GetObject("IIS://LocalHost/W3SVC/3/ROOT/VDir1")
' Move the object and give it a new name
Set ToVdirObj = RootVDirObj.MoveHere("VDir1", "VDir2")
' Release the source object because it has been deleted
Set FromVDirObj = nothing
%>

See Also

GetObject, Create, Delete, CopyHere


Common Object Methods

The following method is common to all IIS Admin Objects unless otherwise noted.

Method | Description
GetDataPaths | Returns the paths to all locations of a metabase property subordinate to a specified starting path.


GetDataPaths

The GetDataPaths method can be used with any of the IIS Admin Objects to find the paths to metabase keys where a specified property is located. This method can be used to find occurrences of a property that may be blocking inherited values from subordinate keys. The path search will start at the key associated with the object you use this method with and will return the starting path if the property is located at that key. For example, if you use this method with the IIsWebServer object for the third Web server, the search path would start at IIS://LocalHost/W3Svc/3 and would return the paths IIS://LocalHost/W3Svc/3, IIS://LocalHost/W3Svc/3/ROOT/VDir1, and IIS://LocalHost/W3Svc/3/ROOT/VDir1/Dir1/File1 if those were the keys where the property was found.

A parameter to the method enables you to specify whether to search for the paths of an inheritable property or for the paths of a property regardless of whether or not it is inheritable. You can use this method to determine if a property is inheritable as well as where occurrences of it are located.

Syntax

PathList = object.GetDataPaths(Property, AttributeFlag)

Parts

PathList
Receives the list of paths to occurrences of the specified property.
object
An IIS Admin Object. Usually the result of a previous GetObject operation.
Property
The name of the property whose paths are to be located.
AttributeFlag
One of the following flags:
IIS_ANY_PROPERTY | Retrieve paths regardless of whether or not the property is inheritable.
IIS_INHERITABLE_ONLY | Retrieve paths only if the property is inheritable. Return MD_ERROR_DATA_NOT_FOUND if property is not inheritable.

Remarks

You can use the For each Path in PathList...Next statement to retrieve individual paths from PathList.

Code Example

<%
Const IIS_ANY_PROPERTY = 0
Const IIS_INHERITABLE_ONLY = 1
Const MD_ERROR_DATA_NOT_FOUND = &H800CC801
Dim WebSvrObj, PathList, vProperty
On Error Resume Next
' Get the object for the first Web server
Set WebSvrObj = GetObject("IIS://LocalHost/W3SVC/1")
' Get the paths where a property is located
vProperty = "AccessFlags"
PathList = WebSvrObj.GetDataPaths(vProperty, IIS_INHERITABLE_ONLY)
If Err.Number = 0 Then
    Response.Write "Paths for property " & vProperty & "<BR>"
    For each Path in PathList
        Response.Write Path & "<BR>"
    Next
ElseIf Err.Number = MD_ERROR_DATA_NOT_FOUND Then
    Response.Write "Property is not inheritable.<BR>"
ElseIf Err.Number = &H80005006 Then
    Response.Write "Property does not exist.<BR>"
Else
    Response.Write "Error " & Err.Number & "  " & Err.Description
End If
%>


Sample Program

You can use the IIS Admin Objects to recursively walk the metabase on your computer. The following sample program uses VBScript code in an .asp file to list the nodes in the metabase structure, optionally printing the ADSI properties, mandatory properties, optional properties, whether each property is inheritable, and the data type of the property.

<HTML>
<HEAD>
<TITLE>SchemaA.asp (IIS Property Schema)</TITLE>
</HEAD>
<BODY BGCOLOR=#FFFFFF>
<FONT FACE="Courier" SIZE=2>
<%
' This program will list metabase nodes installed on LocalHost,
' optionally printing ADSI properties, mandatory properties,
' optional properties, whether the properties are inheritable,
' and the data type of the property.

' Option usage .../SchemaA.asp?ShowProp={param}&ShowInh={T|F}
'     &ShowType={T|F}&StartKey={Path}&Recurse={T|F}
' ShowProp={All|None|(one or more of AMO)}
'   All or AMO => All properties [Default]
'   None or N => No properties
'   A => ADSI properties
'   M => Mandatory properties
'   O => Optional properties
' ShowInh={T|F} (Show property inheritance attribute}
' ShowType={T|F} (Show property data type)
' StartKey={Path of starting key e.g. IIS://LocalHost/W3SVC}
' Recurse={T|F} (Recurse from the starting key)
' Default: All, T, T, IIS://LocalHost, T

Dim MachName      ' Holds machine name (LocalHost)
Dim ADsObj        ' Holds object
Dim SchemaPath    ' Path to object's schema object
Dim SchemaObj     ' Holds object's schema object
Dim PropSchemaObj ' Holds schema for individual property
Dim MandPropList  ' Holds object's mandatory property list
Dim OptPropList   ' Holds object's optional property list

Dim Level         ' Recursive indent level
Dim LevelWidth    ' Number of indent spaces per level (default 3)
Dim Indent        ' String spaces for indentation
Dim ShowProp      ' Input parameter
Dim ShowInh       ' Input parameter
Dim StartKey      ' Input parameter
Dim Recurse       ' Input parameter
Dim PropArgs      ' Temporary variable
Dim InhArgs       ' Temporary variable
Dim KeyArgs       ' Temporary variable
Dim RecurseArgs   ' Temporary variable

Dim InhList(2)    ' Holds output text
InhList(0) = "  Inh  "
InhList(1) = "Not Inh"
InhList(2) = "Invalid Property"

MachName = "LocalHost"

' Get arguments from command line
ShowProp = "AMO"  ' Default to all options
PropArgs = Request.QueryString("ShowProp")
If PropArgs <> "" Then
    ShowProp = UCase(PropArgs)
    If ShowProp = "NONE" Then ShowProp = "N"
    If ShowProp = "ALL" Then ShowProp = "AMO"
End If

ShowInh = "T"
InhArgs = Request.QueryString("ShowInh")
If InhArgs <> "" Then
    ShowInh = UCase(InhArgs)
    If ShowInh = "YES" or ShowInh = "TRUE" Then ShowInh = "T"
    If ShowInh = "FALSE" or ShowInh = "F" Then ShowInh = "F"
End If

ShowType = "T"
InhArgs = Request.QueryString("ShowType")
If InhArgs <> "" Then
    ShowType = UCase(InhArgs)
    If ShowType = "YES" or ShowType = "TRUE" Then ShowType = "T"
    If ShowType = "FALSE" or ShowType = "F" Then ShowType = "F"
End If

StartKey = "IIS://" & MachName
KeyArgs = Request.QueryString("StartKey")
If KeyArgs <> "" Then
    StartKey = KeyArgs
End If

Recurse = "T"
RecurseArgs = Request.QueryString("Recurse")
If RecurseArgs <> "" Then
    Recurse = UCase(RecurseArgs)
End If

on error resume next
Set ADsObj = GetObject(StartKey)
If err.number <> 0 then
    response.write "Error " & err.number & "  =  " & err.description
    Err.Raise ,,"Unable to open path object"
end if

REM Use HTML <PRE> tag to prevent white space compression
Response.Write "<PRE>"

Response.Write "<B>" & ADsObj.ADsPath & "</B>  Structure/Property Schema</B><BR>"
Response.Write "    [ShowProp = " & ShowProp & "]<BR>"
Response.Write "    [ShowInh  = " & ShowInh & "]<BR>"
Response.Write "    [ShowType = " & ShowType & "]<BR>"
Response.Write "    [StartKey = " & StartKey & "]<BR>"
Response.Write "    [Recurse  = " & Recurse & "]<BR>"

Response.Write "<BR>"
Response.Write " <B>Option usage:</B> .../SchemaA.asp?ShowProp={param}&ShowInh={T|F}"
Response.Write "&ShowType={T|F}&StartKey={Path}&Recurse={T|F} <BR>"
Response.Write "   ShowProp={All|None|(one or more of AMO)}  <BR>"
Response.Write "     All or AMO => All properties [Default]  <BR>"
Response.Write "     None or N => No properties  <BR>"
Response.Write "     A => ADSI properties  <BR>"
Response.Write "     M => Mandatory properties  <BR>"
Response.Write "     O => Optional properties  <BR>"
Response.Write "   ShowInh={T|F} (Show property inheritance attribute}  <BR>"
Response.Write "   ShowType={T|F} (Show property data type)  <BR>"
Response.Write "   StartKey={Path of starting key e.g. IIS://LocalHost/W3SVC}  <BR>"
Response.Write "   Recurse={T|F} (Recurse from the starting key)  <BR>"
Response.Write "   Default: All, T, T, IIS://LocalHost, T  <BR>"

Response.Write "<HR>"

' Recursively retrieve and print object names and properties
LevelWidth = 3
Level = -1
PrintProps(ADsObj)

' Complete the page
Response.Write "</PRE>"
Response.Write "<HR>"

Sub PrintProps(ThisObj)
On error Resume next
If Err.Number <> 0 Then
    Err.Clear
    Level = Level - 1
    Exit Sub
End If
Level = Level + 1
Response.write Space(LevelWidth*Level)
If ShowProp <> "N" Then
    Response.write "<B>"
End If
Response.Write ThisObj.Name
If IsNumeric(ThisObj.Name) Then
    Response.write " (Virtual Server - " & ThisObj.ServerComment & ")"
End If
If ShowProp <> "N" Then
    Response.write "</B>"
End If
Response.Write "<BR>"

If Instr(ShowProp, "A") > 0 Then
    ' Print the ADSI properties
    Indent = Space(LevelWidth*(Level+1))
    Response.Write Indent & "<I>ADSI Properties</I><BR>"
    Indent = Space(LevelWidth*(Level+2))
    Response.write Indent & "Name    = " & ThisObj.Name
    Response.write "<BR>"
    Response.write Indent & "ADsPath = " & ThisObj.AdsPath
    Response.write "<BR>"
    Response.write Indent & "Class   = " & ThisObj.Class
    Response.write "<BR>"
    Response.write Indent & "GUID    = " & ThisObj.GUID
    Response.write "<BR>"
    Response.write Indent & "Parent  = " & ThisObj.Parent
    Response.write "<BR>"
    Response.write Indent & "Schema  = " & ThisObj.Schema
    Response.write "<BR>"
End If  ' Show ADSI

If Instr(ShowProp, "M") > 0 Then
    ' Print the mandatory properties
    SchemaPath = ThisObj.Schema
    Set SchemaObj = GetObject(SchemaPath)
    Indent = Space(LevelWidth*(Level+1))
    Response.Write Indent & "<I>Mandatory Properties</I><BR>"
    MandPropList = SchemaObj.MandatoryProperties
    Indent = Space(LevelWidth*(Level+2))
    For Each PropName in MandPropList
        Response.Write Indent & PropName
        If ShowInh = "T" Then
            Response.Write Space(35-Len(PropName))
            Response.Write InhList(IsInheritable(PropName))
        End If
        If ShowType = "T" Then
            If ShowInh = "T" Then
                ' Already vertically aligned - just move on a little
                Response.Write Space(4)
            Else
                ' Pad out to align vertically
                Response.Write Space(35-Len(PropName))
            End If
            Set PropSchemaObj = GetObject("IIS://" & MachName & "/Schema/" & PropName)
            Response.Write PropSchemaObj.Syntax
        End If
        Response.Write "<BR>"
    Next
    End If   ' Show Mandatory

If Instr(ShowProp, "O") > 0 Then
    ' Print the optional properties
    SchemaPath = ThisObj.Schema
    Set SchemaObj = GetObject(SchemaPath)
    Indent = Space(LevelWidth*(Level+1))
    Response.Write Indent & "<I>Optional Properties</I><BR>"
    OptPropList = SchemaObj.OptionalProperties
    Indent = Space(LevelWidth*(Level+2))
    For Each PropName in OptPropList
        Response.Write Indent & PropName
        If ShowInh = "T" Then
            Response.Write Space(35-Len(PropName))
            Response.Write InhList(IsInheritable(PropName))
        End If
        If ShowType = "T" Then
            If ShowInh = "T" Then
                ' Already vertically aligned - just move on a little
                Response.Write Space(4)
            Else
                ' Pad out to align vertically
                Response.Write Space(35-Len(PropName))
            End If
            Set PropSchemaObj = GetObject("IIS://" & MachName & "/Schema/" & PropName)
            Response.Write PropSchemaObj.Syntax
        End If
        Response.Write "<BR>"
    Next
End If   ' Show Optional

' Enumerate children recursively
If Recurse <> "T" Then
    Exit Sub
End If
If ShowProp <> "N" Then    ' Add a blank separator line if props show
    Response.Write "<BR>"
End If
For Each Child in ThisObj
    If Err.Number <> 0 Then
        ' Skip objects that have no children
        Err.Clear
    Else
        ' Recurse into the children of this object
        PrintProps(Child)
    End If
Next
Level = Level - 1
Err.Clear
End Sub

Function IsInheritable(PropNameIn)
' Returns 0 if inheritable
' Returns 1 if a valid property and not inheritable
' Returns 2 if not a valid property
Const IIS_INHERITABLE_ONLY = 1
Const MD_ERROR_DATA_NOT_FOUND = &H800CC801
Const NOT_A_VALID_PROPERTY = &H80005006
Dim IsInheritableObj
Dim IsInheritablePaths
On Error Resume Next
Set IsInheritableObj = GetObject("IIS://" & MachName)
IsInheritablePaths = IsInheritableObj.GetDataPaths(PropNameIn, IIS_INHERITABLE_ONLY)
Select Case Err.Number
    Case 0                        ' Valid property, inheritable
        IsInheritable = 0
    Case MD_ERROR_DATA_NOT_FOUND  ' Valid property, not inheritable
        IsInheritable = 1
    Case NOT_A_VALID_PROPERTY     ' Not a valid property
        IsInheritable = 2
End Select
Err.Clear
End Function

%>
</BODY>
</HTML>


IIS Admin Objects Reference

The reference page for each of the IIS Admin Objects includes ADSI and ADSI Container information, the ADsPath for the object, the metabase properties accessible by the object, and any additional methods specific to the object.

The KeyType Property

Each IIS Admin Object references a unique type of key, specified by the KeyType property, the value of which is the same as the class of the object. For example, the KeyType property value for the IIsWebServer object is IIsWebServer. The KeyType property is used when creating or deleting objects. The value of the KeyType property at a key in the metabase specifies the schema that determines the properties available at that key.

Note Physical directories and files are not automatically reflected in the metabase. You may find a metabase key for a directory or file that does not have the KeyType property set. In this case, when you use the GetObject function to access the key, the only property available will be KeyType. You should set the KeyType value to IIsWebDirectory or IIsWebFile as appropriate, and then use the SetInfo method to store the value in the metabase. You must then use the GetObject function again to access the object with the appropriate set of properties determined by the KeyType value and the schema.

Constants provides a list of constants and their values used with the IIS Admin Objects. You can copy and paste these into your scripts.

The individual IIS Admin Objects are:

IIsCertMapper | Maps certificates to Windows NT® accounts
IIsComputer | Establishes global settings for IIS configuration
IIsFilter | Provides information about a specific filter
IIsFilters | Manages filters
IIsFtpInfo | Establishes configuration properties for Ftp servers in addition to those set at IIsFtpService
IIsFtpServer | Establishes configuration for a single Ftp server
IIsFtpService | Establishes configuration common to all Ftp servers
IIsFtpVirtualDir | Sets properties for an individual Ftp virtual directory
IIsLogModule | Contains information about a specific logging module
IIsLogModules | Maintains information about installed logging modules
IIsMimeMap | Manages Multipurpose Internet Mail Extension (MIME) mappings
IIsWebDirectory | Sets properties for an individual Web directory
IIsWebFile | Sets properties for an individual Web file
IIsWebInfo | Establishes configuration properties for Web servers in addition to those set at IIsWebService
IIsWebServer | Establishes configuration for a single Web server
IIsWebService | Establishes configuration common to all Web servers
IIsWebVirtualDir | Sets properties for an individual Web virtual directory


IIsCertMapper

The IIsCertMapper object manages mapping of client certificates and Windows NT® user accounts. The client certificate is mapped to the Windows NT Account, Windows NT Password, Friendly Name, and an Enabled flag. This object is not involved in setting inheritable properties in the metabase.

IIsCertMapper is an ADSI object, but not an ADSI Container object. See ADSI Features for more information.

ADsPath

IIS://MachineName/W3SVC/n/IIsCertMapper

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = IIsCertMapper.{Method}

Parts

varReturn
A variable that receives the return value from the method.
Method
The object method chosen.

Methods

ADSI Object Methods | Standard methods for ADSI objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects
CreateMapping | Creates a mapping between a certificate and a Windows NT® account
DeleteMapping | Deletes an existing certificate mapping
GetMapping | Retrieves an existing certificate mapping
SetAcct | Sets a new value for the Windows NT® account string in an existing certificate mapping
SetEnabled | Enables or disables an existing certificate mapping
SetName | Sets a new value for the name string in an existing certificate mapping
SetPwd | Sets a new value for the Windows NT® password string in an existing certificate mapping


CreateMapping

The CreateMapping method of the IIsCertMapper object creates a mapping between a certificate and a Windows NT® account.

Syntax

IIsCertMapper.CreateMapping vCert, NtAcct, NtPwd, strName, IEnabled

Parameters

vCert
Contains the certificate. The certificate is either a string or an array of bytes, usually obtained from the ClientCertificate collection of the built-in ASP Request object.
NtAcct
Contains the Windows NT account string.
NtPwd
Contains the password string for NtAcct.
strName
Contains the friendly name for the account.
IEnabled
Specifies True to enable the mapping, False to disable the mapping.

Code Example

<%
Dim CertObj, vCert
vCert = Request.ClientCertificate("CERTIFICATE")
Set CertObj = GetObject("IIS://..path../IIsCertMapper")
CertObj.CreateMapping vCert, "MYACCT", "MYPASS", "My Name", True
%>

See Also

GetMapping, DeleteMapping, SetEnabled, SetName, SetPwd, SetAcct


DeleteMapping

The DeleteMapping method of the IIsCertMapper object deletes an existing certificate mapping. Four seek methods are available to search for the mapping.

Syntax

IIsCertMapper.DeleteMapping IMethod, vKey

Parameters

IMethod
Specifies the seek method to use for searching the mappings. Valid seek methods are 1, 2, 3, or 4. Seek method 1 specifies search by certificate, seek method 2 searches by name, method 3 searches by Windows NT® account, and method 4 searches by a 1-based numeric string index (for example "1", "2", and so on).
vKey
Specifies the key to use in the search specified by IMethod. For seek method 1, vKey specifies a certificate. For seek method 2, vKey specifies a name. For seek method 3, vKey specifies a Windows NT account. For seek method 4, vKey specifies a numeric string index (for example, "1", "2", and so on).

Code Example

<%
Dim CertObj
Set CertObj = GetObject("IIS://..path../IIsCertMapper")
' Search by Windows NT account
CertObj.DeleteMapping 3, "MYACCT"
%>

See Also

CreateMapping, GetMapping, SetEnabled, SetName, SetPwd, SetAcct


GetMapping

The GetMapping method of the IIsCertMapper object retrieves a certificate and the mapping data from an existing certificate mapping. Four seek methods are available to search for the mapping. The retrieved mapping is returned in parameter variables you provide.

Syntax

IIsCertMapper.GetMapping IMethod, vKey, vCert, NtAcct, NtPwd, strName, IEnabled

Parameters

IMethod
Specifies the seek method to use for searching the mappings. Valid seek methods are 1, 2, 3, or 4. Seek method 1 specifies search by certificate, seek method 2 searches by name, method 3 searches by Windows NT account, and method 4 searches by a 1-based numeric string index (for example, "1", "2", and so on).
vKey
Specifies the key to use in the search specified by IMethod. For seek method 1, vKey specifies a certificate. For seek method 2, vKey specifies a name. For seek method 3, vKey specifies a Windows NT account. For seek method 4, vKey specifies a numeric string index (for example, "1", "2", and so on).
vCert
Receives the returned certificate.
NtAcct
Receives the returned Windows NT account.
NtPwd
Receives the returned Windows NT account password.
strName
Receives the returned Windows NT account friendly name.
IEnabled
Receives the returned value True for an enabled mapping, or False for a disabled mapping.

Code Example

<%
Dim CertObj, vCert, NtAcct, NtPwd, strName, IEnabled
Set CertObj = GetObject("IIS://..path../IIsCertMapper")
' Search by Windows NT account
CertObj.GetMapping 3, "MYACCT", vCert, NtAcct, NtPwd, strName, IEnabled
%>

See Also

CreateMapping, DeleteMapping, SetEnabled, SetName, SetPwd, SetAcct


SetAcct

The SetAcct method of the IIsCertMapper object sets a new value for the Windows NT account string in an existing certificate mapping. Four seek methods are available to search for the mapping.

Syntax

IIsCertMapper.SetAcct IMethod, vKey, NTAcct

Parameters

IMethod
Specifies the seek method to use for searching the mappings. Valid seek methods are 1, 2, 3, or 4. Seek method 1 specifies search by certificate, seek method 2 searches by name, method 3 searches by Windows NT account, and method 4 searches by a 1-based numeric string index (for example "1", "2", and so on).
vKey
Specifies the key to use in the search specified by IMethod. For seek method 1, vKey specifies a certificate. For seek method 2, vKey specifies a name. For seek method 3, vKey specifies a Windows NT account. For seek method 4, vKey specifies a numeric string index (for example "1", "2", and so on).
NTAcct
Specifies a new value for the Windows NT account string.

Code Example

<%
Dim CertObj
Set CertObj = GetObject("IIS://..path../IIsCertMapper")
' Search by Windows NT account
CertObj.SetAcct 3, "MYACCT", "NewAccount"
%>

See Also

CreateMapping, GetMapping, DeleteMapping, SetEnabled, SetName, SetPwd


SetEnabled

The SetEnabled method of the IIsCertMapper object enables or disables an existing certificate mapping. Four seek methods are available to search for the mapping.

Syntax

IIsCertMapper.SetEnabled IMethod, vKey,IEnabled

Parameters

IMethod
Specifies the seek method to use for searching the mappings. Valid seek methods are 1, 2, 3, or 4. Seek method 1 specifies search by certificate, seek method 2 searches by name, method 3 searches by Windows NT account, and method 4 searches by a 1-based numeric string index (for example "1", "2", and so on).
vKey
Specifies the key to use in the search specified by IMethod. For seek method 1, vKey specifies a certificate. For seek method 2, vKey specifies a name. For seek method 3, vKey specifies a Windows NT account. For seek method 4, vKey specifies a numeric string index (for example "1", "2", and so on).
IEnabled
Specifies True to enable the mapping, False to disable the mapping.

Code Example

<%
Dim CertObj
Set CertObj = GetObject("IIS://..path../IIsCertMapper")
' Search by Windows NT account
CertObj.SetEnabled 3, "MYACCT", True
%>

See Also

CreateMapping, GetMapping, DeleteMapping, SetName, SetPwd, SetAcct


SetName

The SetName method of the IIsCertMapper object sets a new value for the name string in an existing certificate mapping. Four seek methods are available to search for the mapping.

Syntax

IIsCertMapper.SetName IMethod, vKey, strName

Parameters

IMethod
Specifies the seek method to use for searching the mappings. Valid seek methods are 1, 2, 3, or 4. Seek method 1 specifies search by certificate, seek method 2 searches by name, method 3 searches by Windows NT account, and method 4 searches by a 1-based numeric string index (for example "1", "2", and so on).
vKey
Specifies the key to use in the search specified by IMethod. For seek method 1, vKey specifies a certificate. For seek method 2, vKey specifies a name. For seek method 3, vKey specifies a Windows NT® account. For seek method 4, vKey specifies a numeric string index (for example "1", "2", and so on).
strName
Specifies a new value for the name string.

Code Example

<%
Dim CertObj
Set CertObj = GetObject("IIS://..path../IIsCertMapper")
' Search by Windows NT account
CertObj.SetName 3, "MYACCT", "NewName"
%>

See Also

CreateMapping, GetMapping, DeleteMapping, SetEnabled, SetPwd, SetAcct


SetPwd

The SetPwd method of the IIsCertMapper object sets a new value for the Windows NT password string in an existing certificate mapping. Four seek methods are available to search for the mapping.

Syntax

IIsCertMapper.SetPwd IMethod, vKey, NTPwd

Parameters

IMethod
Specifies the seek method to use for searching the mappings. Valid seek methods are 1, 2, 3, or 4. Seek method 1 specifies search by certificate, seek method 2 searches by name, method 3 searches by Windows NT account, and method 4 searches by a 1-based numeric string index (for example "1", "2", and so on).
vKey
Specifies the key to use in the search specified by IMethod. For seek method 1, vKey specifies a certificate. For seek method 2, vKey specifies a name. For seek method 3, vKey specifies a Windows NT account. For seek method 4, vKey specifies a numeric string index (for example "1", "2", and so on).
strPwd
Specifies a new value for the Windows NT password string.

Code Example

<%
Dim CertObj
Set CertObj = GetObject("IIS://..path../IIsCertMapper")
' Search by Windows NT account
CertObj.SetPwd 3, "MYACCT", "NewPassword"
%>

See Also

CreateMapping, GetMapping, DeleteMapping, SetEnabled, SetName, SetAcct


IIsComputer

You can use the IIsComputer object to set values of global metabase properties that determine how IIS operates. The MaxBandwidth property value is also used by Web servers if not specified at the server level. The IIsComputer object also provides methods to manage metabase backups. These methods allow you to store multiple backup versions in long-term storage, restore the metabase from a backup version of your choice, and enumerate and delete backups.

The IIsComputer object is an ADSI container object.

ADsPath

IIS://MachineName

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsComputer object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May contain

IIsFtpService | IIsWebService | IIsMimeMap
IIsLogModules |  |

Properties

ADSI Object Properties

Metabase Properties

MaxBandwidth | MimeMap
MaxBandwidthBlocked |

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI Container Object Methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects
Backup | Saves the metabase to long-term storage
DeleteBackup | Deletes a metabase backup from long-term storage
EnumBackups | Enumerates metabase backups in long-term storage
Restore | Restores a metabase backup from long-term storage


Backup

You can use the Backup method of the IIsComputer object to backup the metabase to a backup location you specify by providing a backup location name of up to 100 characters in length. Multiple metabase backups can be stored in a backup location.

Syntax

IIsComputer.Backup BackupLocation, BackupVersion, BackupFlags

Parameters

BackupLocation
A string of up to 100 characters that specifies the backup location. The storage mechanism will be determined by IIS. If an empty string is specified, the backup will be stored in the default location.
BackupVersion
Specifies the version number to be assigned to the backup. Must be less than or equal to MD_BACKUP_MAX_VERSION. Can be set to one of the following values.
MD_BACKUP_HIGHEST_VERSION | Overwrite the highest existing backup version in the specified backup location.
MD_BACKUP_NEXT_VERSION | Use the next backup version number available in the specified backup location.

BackupFlags
One or more of the following flags.
MD_BACKUP_FORCE_BACKUP | Force the backup even if the SaveData operation specified by MD_BACKUP_SAVE_FIRST fails.
MD_BACKUP_OVERWRITE | Back up even if a backup of the same name and version exists in the specified backup location, overwriting if necessary.
MD_BACKUP_SAVE_FIRST | Perform a SaveData operation before the backup.

Remarks

IIS determines the backup storage mechanism, so the backup location name you provide does not necessarily translate to a particular directory, file, or database storage mechanism. As implemented in this release, metabase backups are stored as files in the SYSTEM32\INETSRV\METABACK directory. This mechanism may change in future releases.

Code Example

<%
Dim ComputerObj, iFlags
Set ComputerObj = GetObject("IIS://LocalHost")
' Backup to next available version number
' Set flags to save the metabase first and
' force the backup even if save fails
iFlags = (MD_BACKUP_SAVE_FIRST or MD_BACKUP_FORCE_BACKUP)
ComputerObj.Backup "MyBackups", MD_BACKUP_NEXT_VERSION, iFlags
%>

See Also

DeleteBackup, EnumBackups, Restore


DeleteBackup

You can use the DeleteBackup method of the IIsComputer object to delete a metabase backup from a backup location.

Syntax

IIsComputer.DeleteBackup BackupLocation, BackupVersion

Parameters

BackupLocation
A string of up to 100 characters that specifies the backup location. If an empty string is specified, the backup will be deleted from the default location.
BackupVersion
Specifies the version number of the backup to be deleted from the backup location, or may be the following constant.
MD_BACKUP_HIGHEST_VERSION Delete the highest existing backup version in the specified backup location.

Code Example

<%
Dim ComputerObj
Set ComputerObj = GetObject("IIS://LocalHost")
' Delete version 1 backup
ComputerObj.DeleteBackup "MyBackups", 1
%>

See Also

Backup, EnumBackups, Restore


EnumBackups

You can use the EnumBackups method of the IIsComputer object to enumerate metabase backups stored in one or more backup locations, retrieving the location, version number and date of each backup.

Syntax

IIsComputer.EnumBackups BkupLocIn, IndexIn, BkupVerOut, BkupLocOut, BkupDateTimeOut

Parameters

BkupLocIn
A string of up to 100 characters that specifies the backup location. If an empty string is specified, all backup locations will be searched.
IndexIn
Specifies the index of the backup to enumerate. Start the index at 0 and increment by 1 until MD_ERROR_DATA_NOT_FOUND is returned.
BkupVerOut
Receives the version number of the backup enumerated.
BkupLocOut
Receives the backup location of the backup enumerated.
BkupDateTimeOut
Receives the date and time of the backup, in Universal Time Coordinate (UTC), formerly GMT.

Code Example

<%@ LANGUAGE=VBScript %>
<SCRIPT LANGUAGE = "JScript" RUNAT = SERVER>
var TempDate = new Date();
TempDif = TempDate.getTimezoneOffset();
Session("sTempDif") = TempDif;
</SCRIPT>
<%
Dim CompObj, Index, Version, Location, GMTDate, LocDate, MinDif
MinDif = Session("sTempDif")
On Error Resume Next
Set CompObj = GetObject("IIS://LocalHost")
Index = 0
' Iterate until method returns an error
Do While True
    ' Empty location input string means enumerate all locations
    CompObj.EnumBackups "", Index, Version, Location, GMTDate
    If Err.Number <> 0 Then
        ' If error returned, no more backups to enumerate
        Exit Do
    End If
    Response.Write Version & ", "
    Response.Write Location & ", "
    Response.Write GMTDate & ", "
    ' Convert to server local date time
    LocDate = DateAdd("n", (-MinDif), GMTDate)
    Response.Write "(" & LocDate & ")"
    Response.Write "<BR>"
    Index = Index + 1
Loop
%>

See Also

Backup, DeleteBackup, Restore


Restore

You can use the Restore method of the IIsComputer object to restore the metabase from a backup. The restore operation stops all services dependent on IISADMIN, including all servers, until the restore has completed, then restarts all services. Because of this, if you are restoring the metabase using an ASP script, you must specify a machine name different from the one on which your script is executing. You may not use LocalHost as the machine name. You should be careful to plan for this service interruption when restoring the metabase from a backup.

Syntax

IIsComputer.Restore BackupLocation, BackupVersion, BackupFlags

Parameters

BackupLocation
A string of up to 100 characters that specifies the backup location. If an empty string is specified, the backup will be retrieved from the default location.
BackupVersion
Specifies the version number of the backup to be restored from the backup location, or may be the following constant.
MD_BACKUP_HIGHEST_VERSION Restore from the highest existing backup version in the specified backup location.

BackupFlags
Reserved. Must be zero.

Code Example

<%
Dim ComputerObj, ComputerName
' Restore metabase on a different computer
ComputerName = "MyOtherComputer"
' You can use LocalHost if running under Windows Scripting Host
Set ComputerObj = GetObject("IIS://" & ComputerName)
' Restore the highest number version in MyBackups
ComputerObj.Restore "MyBackups", MD_BACKUP_HIGHEST_VERSION, 0
%>

Remarks

You can use the Restore method with the LocalHost computer object in scripts running in a command window using Cscript.exe. See Windows Scripting Host Programmer's Reference.

See Also

Backup, EnumBackups, DeleteBackup


IIsFilter

You can use the IIsFilter object to set metabase properties that affect the operation of ISAPI filters. You can set filter properties at the WebService level or at an individual Web server.

The IIsFilter object is an ADSI object, but not an ADSI container object.

ADsPath

IIS://MachineName/W3SVC/Filters/FilterName

Where MachineName can be any name or "LocalHost".

or

IIS://MachineName/W3SVC/n/Filters/FilterName

Where MachineName can be any name or "LocalHost", and n is the number of a Web server.

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFilter object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

Properties

ADSI Object Properties

Metabase Properties

FilterDescription | NotifyNonSecurePort
FilterEnabled | NotifyOrderHigh
FilterFlags | NotifyOrderLow
FilterPath | NotifyOrderMedium
FilterState | NotifyPreProcHeaders
NotifyAccessDenied | NotifyReadRawData
NotifyAuthentication | NotifySecurePort
NotifyEndOfNetSession | NotifySendRawData
NotifyEndOfRequest | NotifySendResponse
NotifyLog | NotifyUrlMap

Methods

ADSI Object Methods | Standard methods for ADSI objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects


IIsFilters

The IIsFilters object is an ADSI container object that contains the collection of IIsFilter objects. You can use the IIsFilters object to set the FilterLoadOrder property to specify the sequence in which filters are to be loaded, and to enumerate through filters. You can use the IIsFilters object to manage filters at the Web service level or at an individual Web server.

The IIsFilters object is an ADSI container object.

ADsPath

IIS://MachineName/W3SVC/Filters

Where MachineName can be any name or "LocalHost".

or

IIS://MachineName/W3SVC/n/Filters

Where MachineName can be any name or "LocalHost", and n is the number of a Web server.

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFilters object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May contain

IIsFilter

Properties

ADSI Object Properties

Metabase Properties

FilterLoadOrder

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI Container Object Methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects


IIsFtpInfo

Some metabase properties associated with the Ftp service are stored at the Info key subordinate to the MSFTPSVC key. You can use the IIsFtpInfo object to set values for these properties.

The IIsFtpInfo object is an ADSI object, but not an ADSI container object.

ADsPath

IIS://MachineName/MSFTPSVC/Info

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFtpInfo object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

Properties

ADSI Object Properties

Metabase Properties

LogModuleList

Methods

ADSI Object Methods | Standard methods for ADSI objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects


IIsFtpServer

You can use the IIsFtpServer object to set metabase properties that apply to a specific FTP server and to set inheritable metabase properties for FTP virtual directories. Specific methods are also available to control server operation. FTP servers are identified in the metabase by their index numbers. The first FTP server is number 1, the second is number 2, and so on.

The IIsFtpServer object is an ADSI Container object. For more information on ADSI container objects, see ADSI Features.

ADsPath

IIS://MachineName/MSFTPSVC/n

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFtpServer object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May Contain

IIsFtpVirtualDir

Properties

ADSI Object Properties

Metabase Properties

A – I |
AccessFlags | AnonymousUserPass
AccessRead | ConnectionTimeout
AccessWrite | DefaultLogonDomain
AdminACL | DontLog
AllowAnonymous | ExitMessage
AnonymousOnly | GreetingMessage
AnonymousPasswordSync | IPSecurity
AnonymousUserName |
Log... |
LogAnonymous | LogExtFileTimeTaken
LogExtFileBytesRecv | LogExtFileUriQuery
LogExtFileBytesSent | LogExtFileUriStem
LogExtFileClientIp | LogExtFileUserAgent
LogExtFileComputerName | LogExtFileUserName
LogExtFileCookie | LogExtFileWin32Status
LogExtFileDate | LogFileDirectory
LogExtFileFlags | LogFilePeriod
LogExtFileHttpStatus | LogFileTruncateSize
LogExtFileMethod | LogNonAnonymous
LogExtFileProtocolVersion | LogOdbcDataSource
LogExtFileReferer | LogOdbcPassword
LogExtFileServerIp | LogOdbcTableName
LogExtFileServerPort | LogOdbcUserName
LogExtFileSiteName | LogPluginClsId
LogExtFileTime | LogType
M – S |
MaxClientsMessage | ServerBindings
MaxConnections | ServerComment
MaxEndpointConnections | ServerListenBacklog
MSDOSDirOutput | ServerListenTimeout
Realm | ServerSize
ServerAutoStart | ServerState

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI container object methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects
Continue | Resumes the server
Pause | Pauses the server
Start | Starts the server
Stop | Stops the server


Continue

The Continue method of the IIsFtpServer object continues the server operation after it has been paused.

Syntax

IIsFtpServer.Continue

Code Example

<%
Dim ServerObj
' Continue the second FTP server
Set ServerObj = GetObject("IIS://LocalHost/MSFTPSVC/2"
ServerObj.Continue
%>

See Also

Start, Pause, Stop


Pause

The Pause method of the IIsFtpServer object pauses the server operation.

Syntax

IIsFtpServer.Pause

Code Example

<%
Dim ServerObj
' Pause the second FTP server
Set ServerObj = GetObject("IIS://LocalHost/MSFTPSVC/2"
ServerObj.Pause
%>

See Also

Start, Continue, Stop


Start

The Start method of the IIsFtpServer object starts the server operation.

Syntax

IIsFtpServer.Start

Code Example

<%
Dim ServerObj
' Start the second FTP server
Set ServerObj = GetObject("IIS://LocalHost/MSFTPSVC/2"
ServerObj.Start
%>

See Also

Pause, Continue, Stop


Stop

The Stop method of the IIsFtpServer object stops the server operation.

Syntax

IIsFtpServer.Stop

Code Example

<%
Dim ServerObj
' Stop the second FTP server
Set ServerObj = GetObject("IIS://LocalHost/MSFTPSVC/2"
ServerObj.Stop
%>

See Also

Start, Pause, Continue


IIsFtpService

You can use the IIsFtpService object to set the metabase property values that control FTP virtual servers and FTP virtual directories. The DownlevelAdminInstance property indicates the specific FTP server instance to administer for IIS 2.0 Internet Server Manager clients.

The IIsFtpService object is an ADSI container object.

ADsPath

IIS://MachineName/MSFTPSVC

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFtpService object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May Contain

IIsFtpServer IIsFtpInfo

Properties

ADSI Object Properties

Metabase Properties

A – I |
AccessFlags | ConnectionTimeout
AccessRead | DefaultLogonDomain
AccessWrite | DirectoryLevelsToScan
AdminACL | DontLog
AllowAnonymous | DownlevelAdminInstance
AnonymousOnly | ExitMessage
AnonymousPasswordSync | GreetingMessage
AnonymousUserName | IPSecurity
AnonymousUserPass |
Log...I |
LogAnonymous | LogExtFileTimeTaken
LogExtFileBytesRecv | LogExtFileUriQuery
LogExtFileBytesSent | LogExtFileUriStem
LogExtFileClientIp | LogExtFileUserAgent
LogExtFileComputerName | LogExtFileUserName
LogExtFileCookie | LogExtFileWin32Status
LogExtFileDate | LogFileDirectory
LogExtFileFlags | LogFilePeriod
LogExtFileHttpStatus | LogFileTruncateSize
LogExtFileMethod | LogNonAnonymous
LogExtFileProtocolVersion | LogOdbcDataSource
LogExtFileReferer | LogOdbcPassword
LogExtFileServerIp | LogOdbcTableName
LogExtFileServerPort | LogOdbcUserName
LogExtFileSiteName | LogPluginClsId
LogExtFileTime | LogType
M – S |
MaxClientsMessage | ServerBindings
MaxConnections | ServerComment
MaxEndpointConnections | ServerListenBacklog
MSDOSDirOutput | ServerListenTimeout
Realm | ServerSize
ServerAutoStart |

Methods

ADSI Object Methods | Standard methods for ADSI objects.
ADSI container object methods | Standard methods for ADSI container objects.
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects.


IIsFtpVirtualDir

You can use the IIsFtpVirtualDir object to set metabase properties that apply to one or all Ftp virtual directories for an Ftp virtual server. If you use this object at the server's root virtual directory (for example, .../MSFTPSVC/2/Root), inheritable property values will apply to all FTP virtual directories subordinate to the root virtual directory of the second Ftp server. You can set properties for a specific Ftp virtual directory by using the IIsFtpVirtualDir object for a specific virtual directory (e.g. .../MSFTPSVC/2/Root/AVDir).

The IIsFtpVirtualDir object is an ADSI Container object.

ADsPath

For the server's root virtual directory,

IIS://MachineName/MSFTPSVC/n/Root

Where MachineName can be any name or "LocalHost".

For a specific virtual directory,

IIS://MachineName/MSFTPSVC/n/Root/vdirName

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsFtpVirtualDir object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May Contain

IIsFtpVirtualDir

Properties

ADSI Object Properties

Metabase Properties

AccessFlags | IPSecurity
AccessRead | Path
AccessWrite | UNCPassword
DontLog | UNCUserName

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI container object methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects


IIsLogModule

You can use the IIsLogModule object to set metabase properties that affect the operation of logging modules. You can set filter properties at the computer level, at the Ftp and Web service level, or for an individual Ftp or Web server.

The IIsLogModule object is an ADSI object, but not an ADSI container object.

ADsPath

IIS://MachineName/logging/LogModuleName

Where MachineName can be any name or "LocalHost", and LogModuleName is the name of a log module.

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsLogModule object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

Properties

ADSI Object Properties

Metabase Properties

LogModuleId LogModuleUiId

Methods

ADSI Object Methods | Standard methods for ADSI objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects


IIsLogModules

The IIsLogModules object is an ADSI container object that contains the collection of IIsLogModule objects. You can use the IIsLogModules object to manage log modules at the computer level.

The IIsLogModules object is an ADSI container object.

ADsPath

IIS://MachineName/logging

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsLogModules object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May contain

IIsLogModule

Properties

ADSI Object Properties

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI Container Object Methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects

Code Example

<%
' Get log properties for a log module at a server
Dim LoggingModules, CurrentObj
' Get the object for the first web server
Set CurrentObj = GetObject("IIS://LocalHost/W3SVC/1")
' Access the log modules at the computer level
Set LoggingModules = GetObject("IIS://LocalHost/logging")
' Loop through the installed modules to find the currently
' selected module at this server
If CurrentObj.LogPluginClsid <> "" Then
    For Each LogModule in LoggingModules
        If LogModule.LogModuleID = CurrentObj.LogPluginClsid Then
            Response.Write LogModule.Name & "<BR>"
        End If
    Next
    ' Display a property of the current module
    Response.Write CurrentObj.LogFileDate
End If
%>


IIsMimeMap

You can use the IIsMimeMap object to set the inherited Multipurpose Internet Mail Extension (MIME) mappings used by the Web servers.

The IIsMimeMap object is an ADSI object, but not an ADSI container object.

ADsPath

IIS://MachineName/MimeMap

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsMimeMap object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

Properties

ADSI Object Properties

Metabase Properties

MimeMap

Methods

ADSI Object Methods | Standard methods for ADSI objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects

Code Example

<%
Dim MimeMapObj, aMimeMap, MMType, MMExtension, i, aMimeMapNew()
Const ADS_PROPERTY_UPDATE = 2
' Get the mimemap object
Set MimeMapObj = GetObject("IIS://LocalHost/MimeMap")
' Get the mappings from the MimeMap property
aMimeMap = MimeMapObj.GetEx("MimeMap")
' Display the mappings
ShowMM(MimeMapObj)
' Add a new mapping
i = UBound(aMimeMap) + 1
Redim Preserve aMimeMap(i)
Set aMimeMap(i) = CreateObject("MimeMap")
aMimeMap(i).Extension = ".jnq"
aMimeMap(i).MimeType = "junque/my-junque"
MimeMapObj.PutEx ADS_PROPERTY_UPDATE, "MimeMap", aMimeMap
MimeMapObj.SetInfo
' Display the mappings
ShowMM(MimeMapObj)
' Delete a mapping by copying to a new map array
i = 0
For Each MMItem in aMimeMap
    If MMItem.Extension <> ".jnq" Then
        Redim Preserve aMimeMapNew(i)
        Set aMimeMapNew(i) = CreateObject("MimeMap")
        aMimeMapNew(i).Extension = MMItem.Extension
        aMimeMapNew(i).MimeType = MMItem.MimeType
        i = i + 1
    End If
Next
MimeMapObj.PutEx ADS_PROPERTY_UPDATE, "MimeMap", aMimeMapNew
MimeMapObj.SetInfo
' Display the mappings
ShowMM(MimeMapObj)
' Subroutine to display the mappings in a table
Sub ShowMM(MMObj)
aMM = MMObj.GetEx("MimeMap")
' Set up table to display mappings
Response.Write "<HR><TABLE BORDER><CAPTION><B>MIME Maps</B></CAPTION>"
Response.Write "<TR><TH>Type</TH><TH>Extension</TH>"
' Display the mappings in the table
For Each MM in aMM
    Response.Write "<TR><TD>" & MM.MimeType & "</TD>"
    Response.Write "<TD>" & MM.Extension & "</TD></TR>"
Next
Response.Write "</TABLE>"
End Sub
%>


IIsWebDirectory

The IIsWebDirectory object is used to set metabase properties that apply to one or more Web directories for a Web virtual server. When you use the IIsWebDirectory object to set metabase properties for a Web directory, inheritable properties will apply to all subordinate Web directories and files.

You can also use IIsWebDirectory methods to create and manage Web applications in Web directories and subordinate directories. Applications may also be defined and managed in web virtual directories. For more information, see IIsWebVirtualDir.

The IIsWebDirectory object is an ADSI Container object.

ADsPath

IIS://MachineName/W3SVC/n/Root/vdirName/DirName

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebDirectory object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May Contain

IIsWebDirectory IIsWebFile

Properties

ADSI Object Properties

Metabase Properties

A – Asp... |
AccessExecute | AppOopRecoverLimit
AccessFlags | AppPackageID
AccessNoRemoteExecute | AppPackageName
AccessNoRemoteRead | AppRoot
AccessNoRemoteScript | AppWamClsid
AccessNoRemoteWrite | AspAllowOutOfProcComponents
AccessRead | AspAllowSessionState
AccessScript | AspBufferingOn
AccessSSL | AspCodepage
AccessSSL128 | AspEnableParentPaths
AccessSSLFlags | AspExceptionCatchEnable
AccessSSLMapCert | AspLogErrorRequests
AccessSSLNegotiateCert | AspMemFreeFactor
AccessSSLRequireCert | AspQueueTimeout
AccessWrite | AspScriptEngineCacheMax
AnonymousPasswordSync | AspScriptErrorMessage
AnonymousUserName | AspScriptErrorSentToBrowser
AnonymousUserPass | AspScriptFileCacheSize
AppAllowClientDebug | AspScriptLanguage
AppAllowDebugging | AspScriptTimeout
AppFriendlyName | AspSessionTimeout
AppIsolated |
Auth... – U |
AuthAnonymous | EnableDefaultDoc
AuthBasic | EnableDirBrowsing
AuthFlags | EnableDocFooter
AuthNTLM | EnableReverseDns
AuthPersistence | HttpCustomHeaders
CacheControlCustom | HttpErrors
CacheControlMaxAge | HttpExpires
CacheControlNoCache | HttpPics
ContentIndexed | HttpRedirect
CreateCGIWithNewConsole | IPSecurity
CreateProcessAsUser | LogonMethod
DefaultDoc | MimeMap
DefaultDocFooter | PoolIDCTimeout
DefaultLogonDomain | PutReadSize
DirBrowseFlags | Realm
DirBrowseShowDate | RedirectHeaders
DirBrowseShowExtension | ScriptMaps
DirBrowseShowLongDate | SSIExecDisable
DirBrowseShowSize | UNCAuthenticationPassthrough
DirBrowseShowTime | UploadReadAheadSize
DontLog |

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI Container Object Methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects
AppCreate | Creates an application at a specified metabase key
AppDelete | Deletes an application definition at a specified key
AppDeleteRecursive | Deletes application definitions at a specified key and subordinate keys
AppDisable | Disables an application at a specified key
AppDisableRecursive | Disables applications at a specified key and subordinate keys
AppEnable | Enables an application that was previously disabled at a specified key
AppEnableRecursive | Enables applications that were previously disabled at a specified key and subordinate keys
AppGetStatus | Retrieves the status of an application
AppUnload | Unloads an application at a specified key
AppUnloadRecursive | Unloads applications at a specified key and subordinate keys

Remarks

Web directories may be nested, and are addressed with the path to the directory, including the directory name (for example .../vdirName/Dir1/Dir1a/Dir1ab, and so on).


AppCreate

You can use the AppCreate method of the IIsWebDirectory object to create a Web application definition and mark it as running in-process or out-of-process. If an application already exists at the specified path, you can use this method to reconfigure the application from in-process to out-of-process or vice versa.

Syntax

IIsWebDirectory.AppCreate InProcFlag

Parameters

InProcFlag
Specifies whether the application being created is to run in-process (True) or out-of-process (False). If the application already exists and is running in-process, specifying this flag as False will cause the application definition to be deleted and a new application created to run out-of-process. If the application already exists and is running out-of-process, specifying this flag as True will cause the application definition to be deleted and a new application created to run in-process. If the application exists and the setting of InProcFlag matches the application's existing in-process/out-of-process status then this method will cause no change to the application definition.

Code Example

<%
Dim DirObj
Const INPROC = True
Const OUTPROC = False
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Create an application in-process
DirObj.AppCreate INPROC
%>

See Also

AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppDelete

You can use the AppDelete method of the IIsWebDirectory object to delete a Web application definition from a metabase key. If the application is running, it will be shut down. All resources associated with the application, such as out-of-process packages, will be released. This action cannot be undone.

Syntax

IIsWebDirectory.AppDelete

Code Example

<%
Dim DirObj
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Delete the application at this directory
DirObj.AppDelete
%>

See Also

AppCreate, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppDeleteRecursive

You can use the AppDeleteRecursive method of the IIsWebDirectory object to delete Web application definitions from a metabase key and all subordinate keys. If the applications are running, they will be shut down. All resources associated with the applications, such as out-of-process packages, will be released. This action cannot be undone.

Syntax

IIsWebDirectory.AppDeleteRecursive

Code Example

<%
Dim DirObj
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Delete the application at this directory
' and all subordinate directories
DirObj.AppDeleteRecursive
%>

See Also

AppCreate, AppDelete, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppDisable

You can use the AppDisable method of the IIsWebDirectory object to disable a Web application that is running out-of-process. All of the application's resources are released and the application's process is terminated. Attempts to access this application will fail. You can use the AppEnable method to re-enable a disabled application. You use the AppDisable and AppEnable methods primarily when moving, copying, or renaming metabase keys. This method has no effect if the application is running in-process.

Syntax

IIsWebDirectory.AppDisable

Code Example

<%
Dim DirObj
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Disable the application at this directory
DirObj.AppDisable
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisableRecursive, AppEnable, AppEnableRecursive


AppDisableRecursive

You can use the AppDisableRecursive method of the IIsWebDirectory object to disable Web applications that are running out-of-process. The applications at the specified key and at all subordinate keys will be disabled. All of the application resources are released and the application processes are terminated. Attempts to access this application will fail. You can use the AppEnableRecursive method to reenable disabled applications. You use the AppDisableRecursive and AppEnableRecursive methods primarily when moving, copying, or renaming metabase keys. This method has no effect if the applications are running in-process.

Syntax

IIsWebDirectory.AppDisableRecursive

Code Example

<%
Dim DirObj
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Disable the application at this directory
' and at all subordinate directories
DirObj.AppDisableRecursive
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppEnable, AppEnableRecursive


AppEnable

You can use the AppEnable method of the IIsWebDirectory object to reinstate a Web application definition that was previously disabled with the AppDisable method. If the application specified was not previously deleted, it will be reregistered with MTS.

Syntax

IIsWebDirectory.AppEnable

Code Example

<%
Dim DirObj
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Enable the application at this directory
DirObj.AppEnable
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnableRecursive


AppEnableRecursive

You can use the AppEnableRecursive method of the IIsWebDirectory object to reinstate Web application definitions that were previously disabled with the AppDisableRecursive method. If the applications specified were not previously deleted, they will be reregistered with MTS.

Syntax

IIsWebDirectory.AppEnableRecursive

Code Example

<%
Dim DirObj
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Enable the application at this directory
' and at all subordinate directories
DirObj.AppEnableRecursive
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable


AppGetStatus

You can use the AppGetStatus method of the IIsWebDirectory object to retrieve the current status of a Web application.

Syntax

vReturn = IIsWebDirectory.AppGetStatus

Parameters

vReturn
Receives the status of the application.

Return Values

APPSTATUS_NOTDEFINED | No application is defined at the specified path.
APPSTATUS_RUNNING | The application is running.
APPSTATUS_STOPPED | The application is not running.

Code Example

<%
Dim DirObj, vStatus
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Get the status of the application
vReturn = DirObj.AppGetStatus
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppUnload

You can use the AppUnload method of the IIsWebDirectory object to unload a Web application that is running out-of-process. All of the application's resources are released and the application's process is terminated. If the application is running in-process, the application is released if it is not being referenced by any other applications.

Syntax

IIsWebDirectory.AppUnload

Code Example

<%
Dim DirObj
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Unload the application at this directory
DirObj.AppUnload
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppUnloadRecursive

You can use the AppUnloadRecursive method of the IIsWebDirectory object to unload Web applications that are running out-of-process. The applications at the specified key and at all subordinate keys will be unloaded. All of the application resources are released and the application processes are terminated. If the application is running in-process, the application is released if it is not being referenced by any other applications.

Syntax

IIsWebDirectory.AppUnloadRecursive

Code Example

<%
Dim DirObj
Set DirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppDir")
' Unload the application at this directory
' and all subordinate directories
DirObj.AppUnloadRecursive
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


IIsWebFile

You can use the IIsWebFile object to set metabase key values that apply to a file in a Web directory for a Web virtual server. Metabase property values set for a specific file will override inherited values that have been set at a higher level in the metabase hierarchy.

The IIsWebFile object is an ADSI object, but not an ADSI Container object..

ADsPath

IIS://MachineName/W3SVC/n/Root/vdirName/DirName/FileName

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebFile object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

Properties

ADSI Object Properties

Metabase Properties

AccessExecute | CacheControlNoCache
AccessFlags | CreateCGIWithNewConsole
AccessNoRemoteExecute | CreateProcessAsUser
AccessNoRemoteRead | DefaultDocFooter
AccessNoRemoteScript | DefaultLogonDomain
AccessNoRemoteWrite | DontLog
AccessRead | EnableDocFooter
AccessScript | EnableReverseDns
AccessSSL | HttpCustomHeaders
AccessSSL128 | HttpErrors
AccessSSLFlags | HttpExpires
AccessSSLMapCert | HttpPics
AccessSSLNegotiateCert | HttpRedirect
AccessSSLRequireCert | IPSecurity
AccessWrite | LogonMethod
AnonymousPasswordSync | MimeMap
AnonymousUserName | PoolIDCTimeout
AnonymousUserPass | PutReadSize
AuthAnonymous | Realm
AuthBasic | RedirectHeaders
AuthFlags | ScriptMaps
AuthNTLM | SSIExecDisable
AuthPersistence | UNCAuthenticationPassthrough
CacheControlCustom | UploadReadAheadSize
CacheControlMaxAge |

Methods

ADSI Object Methods | Standard methods for ADSI objects.
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects.


IIsWebInfo

Some metabase properties associated with the Web service are stored at the Info key subordinate to the W3SVC key. You can use the IIsWebInfo object to set values for these properties.

The IIsWebInfo object is an ADSI object, but not an ADSI container object.

ADsPath

IIS://MachineName/W3SVC/Info

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebInfo object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

Properties

ADSI Object Properties

Metabase Properties

AdminServer | ServerConfigFlags
CustomErrorDescriptions | ServerConfigSSL128
LogModuleList | ServerConfigSSL40
ServerConfigAutoPWSync | ServerConfigSSLAllowEncrypt

Methods

ADSI Object Methods | Standard methods for ADSI objects.
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects.


IIsWebServer

You can use the IIsWebServer object to set metabase properties that apply to a specific Web virtual server, and to set inheritable metabase properties for Web virtual directories, Web directories, and Web files. Specific methods are also available to control server operation. Web virtual servers are identified in the metabase by their index numbers. The first Web server is number 1, the second is number 2, and so on.

The IIsWebServer object is an ADSI container object.

ADsPath

IIS://MachineName/W3SVC/n

Where MachineName can be any computer name or "LocalHost".

Syntax

varReturn = objWebServer.{Method}

Parts

varReturn
Specifies result value.
ObjWebServer
Refers to the IIS Admin object.
Method
Specifies the method called.

May Contain

IIsCertMapper IIsFilters IIsWebVirtualDir

Properties

ADSI Object Properties

Metabase Properties

A... – Asp... |
AccessExecute | AppFriendlyName
AccessFlags | AppIsolated
AccessNoRemoteExecute | AppOopRecoverLimit
AccessNoRemoteRead | AppPackageID
AccessNoRemoteScript | AppPackageName
AccessNoRemoteWrite | AppRoot
AccessRead | AppWamClsid
AccessScript | AspAllowOutOfProcComponents
AccessSSL | AspAllowSessionState
AccessSSL128 | AspBufferingOn
AccessSSLFlags | AspCodepage
AccessSSLMapCert | AspEnableParentPaths
AccessSSLNegotiateCert | AspExceptionCatchEnable
AccessSSLRequireCert | AspLogErrorRequests
AccessWrite | AspMemFreeFactor
AdminACL | AspQueueTimeout
AllowKeepAlive | AspScriptEngineCacheMax
AllowPathInfoForScriptMappings | AspScriptErrorMessage
AnonymousPasswordSync | AspScriptErrorSentToBrowser
AnonymousUserName | AspScriptFileCacheSize
AnonymousUserPass | AspScriptLanguage
AppAllowClientDebug | AspScriptTimeout
AppAllowDebugging | AspSessionTimeout
Auth... – I |
AuthAnonymous | DirBrowseShowDate
AuthBasic | DirBrowseShowExtension
AuthFlags | DirBrowseShowLongDate
AuthNTLM | DirBrowseShowSize
AuthPersistence | DirBrowseShowTime
CacheControlCustom | DontLog
CacheControlMaxAge | EnableDefaultDoc
CacheControlNoCache | EnableDirBrowsing
CacheISAPI | EnableDocFooter
CGITimeout | EnableReverseDns
ConnectionTimeout | FrontPageWeb
CreateCGIWithNewConsole | HttpCustomHeaders
CreateProcessAsUser | HttpErrors
DefaultDoc | HttpExpires
DefaultDocFooter | HttpPics
DefaultLogonDomain | HttpRedirect
DirBrowseFlags | IPSecurity
Log... |
LogExtFileBytesRecv | LogExtFileUriQuery
LogExtFileBytesSent | LogExtFileUriStem
LogExtFileClientIp | LogExtFileUserAgent
LogExtFileComputerName | LogExtFileUserName
LogExtFileCookie | LogExtFileWin32Status
LogExtFileDate | LogFileDirectory
LogExtFileFlags | LogFilePeriod
LogExtFileHttpStatus | LogFileTruncateSize
LogExtFileMethod | LogOdbcDataSource
LogExtFileProtocolVersion | LogOdbcPassword
LogExtFileReferer | LogOdbcTableName
LogExtFileServerIp | LogOdbcUserName
LogExtFileServerPort | LogonMethod
LogExtFileSiteName | LogPluginClsId
LogExtFileTime | LogType
LogExtFileTimeTaken |
M – U |
MaxBandwidth | RedirectHeaders
MaxBandwidthBlocked | ScriptMaps
MaxConnections | SecureBindings
MaxEndpointConnections | ServerAutoStart
MimeMap | ServerBindings
NetLogonWorkstation | ServerComment
NTAuthenticationProviders | ServerListenBacklog
PasswordCacheTTL | ServerListenTimeout
PasswordChangeFlags | ServerSize
PasswordExpirePrenotifyDays | ServerState
PoolIDCTimeout | SSIExecDisable
ProcessNTCRIfLoggedOn | UNCAuthenticationPassthrough
PutReadSize | UploadReadAheadSize
Realm | UseHostName

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI container object methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects
Continue | Resumes the server
Pause | Pauses the server
Start | Starts the server
Stop | Stops the server


Continue

The Continue method of the IIsWebServer object continues the server operation after it has been paused.

Syntax

IIsWebServer.Continue

Code Example

<%
Dim ServerObj
' Continue the second Web server
Set ServerObj = GetObject("IIS://LocalHost/W3SVC/2"
ServerObj.Continue
%>

See Also

Start, Pause, Stop


Pause

The Pause method of the IIsWebServer object pauses the server operation.

Syntax

IIsWebServer.Pause

Code Example

<%
Dim ServerObj
' Pause the second Web server
Set ServerObj = GetObject("IIS://LocalHost/W3SVC/2"
ServerObj.Pause
%>

See Also

Start, Continue, Stop


Start

The Start method of the IIsWebServer object starts the server operation.

Syntax

IIsWebServer.Start

Code Example

<%
Dim ServerObj
' Start the second Web server
Set ServerObj = GetObject("IIS://LocalHost/W3SVC/2"
ServerObj.Start
%>

See Also

Pause, Continue, Stop


Stop

The Stop method of the IIsWebServer object stops the server operation.

Syntax

IIsWebServer.Stop

Code Example

<%
Dim ServerObj
' Stop the second Web server
Set ServerObj = GetObject("IIS://LocalHost/W3SVC/2"
ServerObj.Stop
%>

See Also

Start, Pause, Continue


IIsWebService

You can use the IIsWebService object to set inheritable metabase properties for Web virtual servers and web virtual directories. The DownlevelAdminInstance property indicates the specific web server instance to administer for IIS 2.0 Internet Server Manager clients.

The IIsWebService object is an ADSI Container object. For more information, see ADSI Features.

ADsPath

IIS://MachineName/W3SVC

Where MachineName can be any computer name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebServer object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May Contain

IIsFilters IIsWebInfo IIsWebServer

Properties

ADSI Object Properties

Metabase Properties

A... – Asp... |
AccessExecute | AppFriendlyName
AccessFlags | AppIsolated
AccessNoRemoteExecute | AppPackageID
AccessNoRemoteRead | AppPackageName
AccessNoRemoteScript | AppRoot
AccessNoRemoteWrite | AppWamClsid
AccessRead | AspAllowOutOfProcComponents
AccessScript | AspAllowSessionState
AccessSSL | AspBufferingOn
AccessSSL128 | AspCodepage
AccessSSLFlags | AspEnableParentPaths
AccessSSLMapCert | AspExceptionCatchEnable
AccessSSLNegotiateCert | AspLogErrorRequests
AccessSSLRequireCert | AspMemFreeFactor
AccessWrite | AspQueueTimeout
AdminACL | AspScriptEngineCacheMax
AllowPathInfoForScriptMappings | AspScriptErrorMessage
AnonymousPasswordSync | AspScriptErrorSentToBrowser
AnonymousUserName | AspScriptFileCacheSize
AnonymousUserPass | AspScriptLanguage
AppAllowClientDebug | AspScriptTimeout
AppAllowDebugging | AspSessionTimeout
Auth... – I |
AuthAnonymous | DirBrowseShowLongDate
AuthBasic | DirBrowseShowSize
AuthFlags | DirBrowseShowTime
AuthNTLM | DirectoryLevelsToScan
AuthPersistence | DontLog
CacheControlCustom | DownlevelAdminInstance
CacheControlMaxAge | EnableDefaultDoc
CacheControlNoCache | EnableDirBrowsing
ConnectionTimeout | EnableDocFooter
CreateCGIWithNewConsole | EnableReverseDns
CreateProcessAsUser | HttpCustomHeaders
DefaultDoc | HttpErrors
DefaultDocFooter | HttpExpires
DefaultLogonDomain | HttpPics
DirBrowseFlags | HttpRedirect
DirBrowseShowDate | InProcessIsapiApps
DirBrowseShowExtension | IPSecurity
Log... |
LogExtFileBytesRecv | LogExtFileUriQuery
LogExtFileBytesSent | LogExtFileUriStem
LogExtFileClientIp | LogExtFileUserAgent
LogExtFileComputerName | LogExtFileUserName
LogExtFileCookie | LogExtFileWin32Status
LogExtFileDate | LogFileDirectory
LogExtFileFlags | LogFilePeriod
LogExtFileHttpStatus | LogFileTruncateSize
LogExtFileMethod | LogOdbcDataSource
LogExtFileProtocolVersion | LogOdbcPassword
LogExtFileReferer | LogOdbcTableName
LogExtFileServerIp | LogOdbcUserName
LogExtFileServerPort | LogonMethod
LogExtFileSiteName | LogPluginClsId
LogExtFileTime | LogType
LogExtFileTimeTaken |
M... – U |
MaxConnections | ScriptMaps
MaxEndpointConnections | ServerAutoStart
MimeMap | ServerBindings
NetLogonWorkstation | ServerComment
NTAuthenticationProviders | ServerListenBacklog
PasswordCacheTTL | ServerListenTimeout
PasswordChangeFlags | ServerSize
PasswordExpirePrenotifyDays | SSIExecDisable
PoolIDCTimeout | UNCAuthenticationPassthrough
ProcessNTCRIfLoggedOn | UploadReadAheadSize
PutReadSize | UseHostName
Realm | WAMUserName
RedirectHeaders | WAMUserPass

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI container object methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects


IIsWebVirtualDir

You can use the IIsWebVirtualDir object to set metabase properties that apply to one or all Web virtual directories for a Web virtual server. If you use the IIsWebVirtualDir object at the server's root virtual directory (.../W3SVC/2/Root), inheritable property values will apply to all subordinate virtual directories. You can set properties for a specific virtual directory by using the IIsWebVirtualDir object for a specific virtual directory (.../W3SVC/2/Root/AVdir).

You can also use IIsWebVirtualDir methods to create and manage Web applications in Web virtual directories and subordinate virtual directories. Applications may also be defined and managed in web directories. See IIsWebDirectory.

The IIsWebVirtualDir object is an ADSI container object.

ADsPath

For the server's root virtual directory,

IIS://MachineName/W3SVC/n/Root

Where MachineName can be any name or "LocalHost".

For a specific virtual directory,

IIS://MachineName/W3SVC/n/Root/vdirName

Where MachineName can be any name or "LocalHost".

Syntax

varReturn = object.{Method}

Parts

varReturn
A variable that receives the return value from the method.
object
A variable that contains the IIsWebVirtualDir object, usually as a result of a previous GetObject operation.
Method
The object method chosen.

May Contain

IIsWebVirtualDir IIsWebDirectory IIsWebFile

Properties

ADSI Object Properties

Metabase Properties

A – Asp... |
AccessExecute | AppOopRecoverLimit
AccessFlags | AppPackageID
AccessNoRemoteExecute | AppPackageName
AccessNoRemoteRead | AppRoot
AccessNoRemoteScript | AppWamClsid
AccessNoRemoteWrite | AspAllowOutOfProcComponents
AccessRead | AspAllowSessionState
AccessScript | AspBufferingOn
AccessSSL | AspCodepage
AccessSSL128 | AspEnableParentPaths
AccessSSLFlags | AspExceptionCatchEnable
AccessSSLMapCert | AspLogErrorRequests
AccessSSLNegotiateCert | AspMemFreeFactor
AccessSSLRequireCert | AspQueueTimeout
AccessWrite | AspScriptEngineCacheMax
AnonymousPasswordSync | AspScriptErrorMessage
AnonymousUserName | AspScriptErrorSentToBrowser
AnonymousUserPass | AspScriptFileCacheSize
AppAllowClientDebug | AspScriptLanguage
AppAllowDebugging | AspScriptTimeout
AppFriendlyName | AspSessionTimeout
AppIsolated |
Auth – U |
AuthAnonymous | EnableDirBrowsing
AuthBasic | EnableDocFooter
AuthFlags | EnableReverseDns
AuthNTLM | HttpCustomHeaders
AuthPersistence | HttpErrors
CacheControlCustom | HttpExpires
CacheControlMaxAge | HttpPics
CacheControlNoCache | HttpRedirect
ContentIndexed | IPSecurity
CreateCGIWithNewConsole | LogonMethod
CreateProcessAsUser | MimeMap
DefaultDoc | Path
DefaultDocFooter | PoolIDCTimeout
DefaultLogonDomain | PutReadSize
DirBrowseFlags | Realm
DirBrowseShowDate | RedirectHeaders
DirBrowseShowExtension | ScriptMaps
DirBrowseShowLongDate | SSIExecDisable
DirBrowseShowSize | UNCAuthenticationPassthrough
DirBrowseShowTime | UNCPassword
DontLog | UNCUserName
EnableDefaultDoc | UploadReadAheadSize

Methods

ADSI Object Methods | Standard methods for ADSI objects
ADSI container object methods | Standard methods for ADSI container objects
Common Object Methods | Methods, other than ADSI methods, common to all IIS Admin Objects
AppCreate | Creates an application at a specified metabase key
AppDelete | Deletes an application definition at a specified key
AppDeleteRecursive | Deletes application definitions at a specified key and subordinate keys
AppDisable | Disables an application at a specified key
AppDisableRecursive | Disables applications at a specified key and subordinate keys
AppEnable | Enables an application at a specified key, that was previously disabled
AppEnableRecursive | Enables applications at a specified key and subordinate keys, that were previously disabled
AppGetStatus | Retrieves the status of an application
AppUnload | Unloads an application at a specified key
AppUnloadRecursive | Unloads applications at a specified key and subordinate keys


AppCreate

You can use the AppCreate method of the IIsWebVirtualDir object to create a Web application definition and mark it as running in-process or out-of-process. If an application already exists at the specified path, you can use this method to reconfigure the application from in-process to out-of-process or vice versa.

Syntax

IIsWebVirtualDir.AppCreate InProcFlag

Parameters

InProcFlag
Specifies whether the application being created is to run in-process (True) or out-of-process (False). If the application already exists and is running in-process, specifying this flag as False will cause the application definition to be deleted and a new application created to run out-of-process. If the application already exists and is running out-of-process, specifying this flag as True will cause the application definition to be deleted and a new application created to run in-process. If the application exists and the setting of InProcFlag matches the application's existing in-process/out-of-process status then this method will cause no change to the application definition.

Code Example

<%
Dim VDirObj
Const INPROC = True
Const OUTPROC = False
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Create an application in-process
VDirObj.AppCreate INPROC
%>

See Also

AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppDelete

You can use the AppDelete method of the IIsWebVirtualDir object to delete a Web application definition from a metabase key. If the application is running, it will be shut down. All resources associated with the application, such as out-of-process packages, will be released. This action cannot be undone.

Syntax

IIsWebVirtualDir.AppDelete

Code Example

<%
Dim VDirObj
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Delete the application at this virtual directory
VDirObj.AppDelete
%>

See Also

AppCreate, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppDeleteRecursive

You can use the AppDeleteRecursive method of the IIsWebVirtualDir object to delete Web application definitions from a metabase key and all subordinate keys. If the applications are running, they will be shut down. All resources associated with the applications, such as out-of-process packages, will be released. This action cannot be undone.

Syntax

IIsWebVirtualDir.AppDeleteRecursive

Code Example

<%
Dim VDirObj
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Delete the application at this directory
' and all subordinate directories
VDirObj.AppDeleteRecursive
%>

See Also

AppCreate, AppDelete, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppDisable

You can use the AppDisable method of the IIsWebVirtualDir object to disable a Web application that is running out-of-process. All of the application's resources are released and the application's process is terminated. Attempts to access this application will fail. You can use the AppEnable method to re-enable a disabled application. You use the AppDisable and AppEnable methods primarily when moving, copying, or renaming metabase keys. This method has no effect if the application is running in-process.

Syntax

IIsWebVirtualDir.AppDisable

Code Example

<%
Dim VDirObj
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Disable the application at this directory
VDirObj.AppDisable
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisableRecursive, AppEnable, AppEnableRecursive


AppDisableRecursive

You can use the AppDisableRecursive method of the IIsWebVirtualDir object to disable Web applications that are running out-of-process. The applications at the specified key and at all subordinate keys will be disabled. All of the application resources are released and the application processes are terminated. Attempts to access this application will fail. You can use the AppEnableRecursive method to re-enable disabled applications. You use the AppDisableRecursive and AppEnableRecursive methods primarily when moving, copying, or renaming metabase keys. This method has no effect if the applications are running in-process.

Syntax

IIsWebVirtualDir.AppDisableRecursive

Code Example

<%
Dim VDirObj
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Disable the application at this directory
' and at all subordinate directories
VDirObj.AppDisableRecursive
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppEnable, AppEnableRecursive


AppEnable

You can use the AppEnable method of the IIsWebVirtualDir object to reinstate a Web application definition that was previously disabled with the AppDisable method. If the application specified was not previously deleted, it will be reregistered with MTS.

Syntax

IIsWebVirtualDir.AppEnable

Code Example

<%
Dim VDirObj
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Enable the application at this directory
VDirObj.AppEnable
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnableRecursive


AppEnableRecursive

You can use the AppEnableRecursive method of the IIsWebVirtualDir object to reinstate Web application definitions that were previously disabled with the AppDisableRecursive method. If the applications specified were not previously deleted, they will be reregistered with MTS.

Syntax

IIsWebVirtualDir.AppEnableRecursive

Code Example

<%
Dim VDirObj
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Enable the application at this directory
' and at all subordinate directories
VDirObj.AppEnableRecursive
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable


AppGetStatus

You can use the AppGetStatus method of the IIsWebVirtualDir object to retrieve the current status of a Web application.

Syntax

vReturn = IIsWebVirtualDir.AppGetStatus

Parameters

vReturn
Receives the status of the application.

Return Values

APPSTATUS_NOTDEFINED | No application is defined at the specified path.
APPSTATUS_RUNNING | The application is running.
APPSTATUS_STOPPED | The application is not running.

Code Example

<%
Dim VDirObj, vStatus
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Get the status of the application
vReturn = VDirObj.AppGetStatus
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppUnloadRecursive, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppUnload

You can use the AppUnload method of the IIsWebVirtualDir object to unload a Web application that is running out-of-process. All of the application's resources are released and the application's process is terminated. If the application is running in-process, the application is released if it is not being referenced by any other applications.

Syntax

IIsWebVirtualDir.AppUnload

Code Example

<%
Dim VDirObj
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Unload the application at this directory
VDirObj.AppUnload
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnloadRecursive, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


AppUnloadRecursive

You can use the AppUnloadRecursive method of the IIsWebVirtualDir object to unload Web applications that are running out-of-process. The applications at the specified key and at all subordinate keys will be unloaded. All of the application resources are released and the application processes are terminated. If the application is running in-process, the application is released if it is not being referenced by any other applications.

Syntax

IIsWebVirtualDir.AppUnloadRecursive

Code Example

<%
Dim VDirObj
Set VDirObj = GetObject("IIS://LocalHost/W3SVC/1/ROOT/MyAppVDir")
' Unload the application at this directory
' and all subordinate directories
VDirObj.AppUnloadRecursive
%>

See Also

AppCreate, AppDelete, AppDeleteRecursive, AppUnload, AppGetStatus, AppDisable, AppDisableRecursive, AppEnable, AppEnableRecursive


Constants

These constants are used with methods and properties of the IIS Admin Objects. You can copy and paste them into your programs, or place them in an include file for use in ASP scripts.

<%
Const IIS_ANY_PROPERTY = 0                   ' GetDataPaths
Const IIS_INHERITABLE_ONLY = 1               ' GetDataPaths
Const MD_ERROR_DATA_NOT_FOUND = &H800CC801   ' GetDataPaths
Const ADS_PROPERTY_CLEAR = 1                 ' PutEx
Const ADS_PROPERTY_UPDATE = 2                ' PutEx
Const MD_BACKUP_MAX_VERSION = 9999           ' Limit
Const MD_BACKUP_MAX_LEN = 100                ' Limit
Const MD_BACKUP_NEXT_VERSION = &HFFFFFFFF    ' Backup
Const MD_BACKUP_HIGHEST_VERSION = &HFFFFFFFE ' Backup, Delete, Restore
Const MD_BACKUP_OVERWRITE = 1                ' Backup
Const MD_BACKUP_SAVE_FIRST = 2               ' Backup
Const MD_BACKUP_FORCE_BACKUP = 4             ' Backup
Const APPSTATUS_UNLOADED = 1                 ' AppStatus
Const APPSTATUS_RUNNING = 2                  ' AppStatus
Const APPSTATUS_STOPPED = 3                  ' AppStatus
Const APPSTATUS_NOTDEFINED = 4               ' AppStatus
Const NOT_A_VALID_PROPERTY = &H80005006      ' Various methods
Const MD_SERVER_STATE_STARTING = 1           ' ServerState
Const MD_SERVER_STATE_STARTED = 2            ' ServerState
Const MD_SERVER_STATE_STOPPING = 3           ' ServerState
Const MD_SERVER_STATE_STOPPED = 4            ' ServerState
Const MD_SERVER_STATE_PAUSING = 5            ' ServerState
Const MD_SERVER_STATE_PAUSED = 6             ' ServerState
Const MD_SERVER_STATE_CONTINUING = 7         ' ServerState
%>


Administration Property Reference

Administration properties are associated with key values in the metabase. This reference provides a description for each property, including the data type, default value, default inheritance attributes, and usage notes. For each property, the IIS Admin Objects are listed that can access that property..

The Alphabetical Property List provides quick access to individual property descriptions.

The Property Inheritance Charts provide easy-to-use tables that relate each individual property with the Admin Objects that have access to it.

  • FTP Property Inheritance chart showing properties that apply to FTP services.
  • Web Property Inheritance chart showing properties that apply to Web services.
  • Miscellaneous Property Inheritance chart showing properties that apply to objects other than FTP or Web services.


Alphabetical Property List

A – Anon… |
AccessExecute` | AccessSSLNegotiateCert
AccessFlags | AccessSSLRequireCert
AccessNoRemoteExecute | AccessWrite
AccessNoRemoteRead | AdminACL
AccessNoRemoteScript | AdminServer
AccessNoRemoteWrite | AllowAnonymous
AccessRead | AllowKeepAlive
AccessScript | AllowPathInfoForScriptMappings
AccessSSL | AnonymousOnly
AccessSSL128 | AnonymousPasswordSync
AccessSSLFlags | AnonymousUserName
AccessSSLMapCert | AnonymousUserPass
App… – Asp… |
AppAllowClientDebug | AspEnableParentPaths
AppAllowDebugging | AspExceptionCatchEnable
AppFriendlyName | AspLogErrorRequests
AppIsolated | AspMemFreeFactor
AppOopRecoverLimit | AspQueueTimeout
AppPackageID | AspScriptEngineCacheMax
AppPackageName | AspScriptErrorMessage
AppRoot | AspScriptErrorSentToBrowser
AppWamClsid | AspScriptFileCacheSize
AspAllowOutOfProcComponents | AspScriptLanguage
AspAllowSessionState | AspScriptTimeout
AspBufferingOn | AspSessionTimeout
AspCodepage |
Auth… – D |
AuthAnonymous | CustomErrorDescriptions
AuthBasic | DefaultDoc
AuthFlags | DefaultDocFooter
AuthNTLM | DefaultLogonDomain
AuthPersistence | DirBrowseFlags
CacheControlCustom | DirBrowseShowDate
CacheControlMaxAge | DirBrowseShowExtension
CacheControlNoCache | DirBrowseShowLongDate
CacheISAPI | DirBrowseShowSize
CGITimeout | DirBrowseShowTime
ConnectionTimeout | DirectoryLevelsToScan
ContentIndexed | DontLog
CreateCGIWithNewConsole | DownlevelAdminInstance
CreateProcessAsUser |
E – K |
EnableDefaultDoc | FrontPageWeb
EnableDirBrowsing | GreetingMessage
EnableDocFooter | HttpCustomHeaders
EnableReverseDns | HttpErrors
ExitMessage | HttpExpires
FilterDescription | HttpPics
FilterEnabled | HttpRedirect
FilterFlags | InProcessIsapiApps
FilterLoadOrder | IPSecurity
FilterPath | KeyType
FilterState |
Log... |
LogAnonymous | LogExtFileUriStem
LogExtFileBytesRecv | LogExtFileUserAgent
LogExtFileBytesSent | LogExtFileUserName
LogExtFileClientIp | LogExtFileWin32Status
LogExtFileComputerName | LogFileDirectory
LogExtFileCookie | LogFilePeriod
LogExtFileDate | LogFileTruncateSize
LogExtFileFlags | LogModuleId
LogExtFileHttpStatus | LogModuleList
LogExtFileMethod | LogModuleUiId
LogExtFileProtocolVersion | LogNonAnonymous
LogExtFileReferer | LogOdbcDataSource
LogExtFileServerIp | LogOdbcPassword
LogExtFileServerPort | LogOdbcTableName
LogExtFileSiteName | LogOdbcUserName
LogExtFileTime | LogonMethod
LogExtFileTimeTaken | LogPluginClsid
LogExtFileUriQuery | LogType
M – R |
MaxBandwidth | NotifyPreProcHeaders
MaxBandwidthBlocked | NotifyReadRawData
MaxClientsMessage | NotifySecurePort
MaxConnections | NotifySendRawData
MaxEndpointConnections | NotifySendResponse
MimeMap | NotifyUrlMap
MSDOSDirOutput | NTAuthenticationProviders
NetLogonWorkstation | PasswordCacheTTL
NotifyAccessDenied | PasswordChangeFlags
NotifyAuthentication | PasswordExpirePrenotifyDays
NotifyEndOfNetSession | Path
NotifyEndOfRequest | PoolIDCTimeout
NotifyLog | ProcessNTCRIfLoggedOn
NotifyNonSecurePort | PutReadSize
NotifyOrderHigh | Realm
NotifyOrderLow | RedirectHeaders
NotifyOrderMedium |
Script...– Z |
ScriptMaps | ServerListenTimeout
SecureBindings | ServerSize
ServerAutoStart | ServerState
ServerBindings | SSIExecDisable
ServerComment | UNCAuthenticationPassthrough
ServerConfigAutoPWSync | UNCPassword
ServerConfigFlags | UNCUserName
ServerConfigSSL128 | UploadReadAheadSize
ServerConfigSSL40 | UseHostName
ServerConfigSSLAllowEncrypt | WAMUserName
ServerListenBacklog | WAMUserPass


AccessExecute

When set to True, this file permission property permits execution of .asp scripts and other executable files. AccessExecute is one of the access permission flags contained in the AccessFlags property. The AccessScript property provides more restrictive permission for execution of .asp files only.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessFlags

This single property contains the following file access permission flags:

AccessExecute | AccessNoRemoteWrite
AccessNoRemoteExecute | AccessRead
AccessNoRemoteRead | AccessScript
AccessNoRemoteScript | AccessWrite

All permissions are applicable to Web service, servers, directories, and files. AccessRead and AccessWrite are the only permissions applicable to FTP service, servers, and directories.

The following table describes this property:

Data type | Long
Default value | AccessRead = True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsFtpService | IIsFtpServer | IIsFtpVirtualDir | IIsWebService
IIsWebServer | IIsWebVirtualDir | IIsWebDirectory | IIsWebFile

See Also

MD_ACCESS_PERM for hexadecimal values when setting flags in AccessFlags.


AccessNoRemoteExecute

When set to True, this file permission property prohibits the file from being executed by remote clients. If AccessExecute is set to True, the file can be executed by the Web server. AccessNoRemoteExecute is one of the access permission flags contained in the AccessFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessNoRemoteRead

When set to True, this file permission property prohibits the file from being read by remote clients. If AccessRead is set to True, the file can be read by the Web server. AccessNoRemoteRead is one of the access permission flags contained in the AccessFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessNoRemoteScript

When set to True, this file permission property prohibits a script file from being executed by remote clients. If AccessExecute or AccessScript is set to True, the script file can be executed by the Web server. AccessNoRemoteScript is one of the access permission flags contained in the AccessFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessNoRemoteWrite

When set to True, this file permission property prohibits the file from being written to by remote clients. If AccessWrite is set to True, the file can be written to by the Web server. AccessNoRemoteWrite is one of the access permission flags contained in the AccessFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessRead

When set to True, this file permission property permits the file to be read. AccessRead is one of the access permission flags contained in the AccessFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AccessScript

When set to True, this file permission property permits an .asp file to be executed by the ASP engine. AccessScript is one of the access permission flags contained in the AccessFlags property. The AccessExecute property allows execution of other types of executable files in addition to .asp files.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessSSL

When set to True, file access requires Secure Socket Layer (SSL) file permission processing, with or without a client certificate. AccessSSL is one of the SSL file permission flags contained in the AccessSSLFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessSSL128

When set to True, file access requires Secure Socket Layer (SSL) file permission processing with a minimum key size of 128 bits, with or without a client certificate. AccessSSL128 is one of the SSL file permission flags contained in the AccessSSLFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessSSLFlags

This single property contains the following Secure Socket Layer (SSL) file permission flags:

AccessSSL | AccessSSLNegotiateCert
AccessSSL128 | AccessSSLRequireCert
AccessSSLMapCert |

The following table describes this property:

Data type | Long
Default value | Zero (no SSL permissions)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |

See Also

MD_SSL_ACCESS_PERM for hexadecimal values when setting flags in AccessSSLFlags.


AccessSSLMapCert

When set to True, this property indicates that Secure Socket Layer (SSL) file permission processing will map a client certificate to a Microsoft® Windows NT® account. The AccessSSLNegotiateCert property must also be set to True for the mapping to occur. AccessSSLMapCert is one of the SSL file permission flags contained in the AccessSSLFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessSSLNegotiateCert

When set to True, Secure Socket Layer (SSL) file access processing will request a certificate from the client. If AccessSSLRequireCert is False, access will continue if the client does not have a certificate. Note that some versions of Internet Explorer will close the connection if the server requests a certificate and one is not available, whether or not AccessSSLRequireCert is also set to True. AccessSSLNegotiateCert is one of the SSL file permission flags contained in the AccessSSLFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessSSLRequireCert

When set to True, Secure Socket Layer (SSL) file access processing will request a certificate from the client. If no certificate is provided by the client, the connection will be closed. AccessSSLNegotiateCert must also be set to True when using AccessSSLRequireCert. This property is one of the SSL file permission flags contained in the AccessSSLFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AccessWrite

When set to True, this file permission property permits writing to the file. AccessWrite is one of the access permission flags contained in the AccessFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AdminACL

The AdminACL property contains a Microsoft® Windows NT® security descriptor that can be used to control access to any metabase subtree. This property can be used to grant read access, restricted write access, or unrestricted write access. See MD_ADMIN_ACL for details of the flags used in this property.

The following table describes this property:

Data type | Windows NT security descriptor
Default value | Empty (No ACL)
Default inheritance | True

Accessible by IIS Admin Objects:


AdminServer

This property identifies the Web server instance being administered by the remote administration program. This property is for read-only usage.

The following table describes this property:

Data type | String
Default value | 1 (String)
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsWebInfo


AllowAnonymous

This property specifies whether the FTP or Web server should allow anonymous access.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AllowKeepAlive

This property specifies whether keep alive processing is permitted.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AllowPathInfoForScriptMappings

This property indicates whether clients are permitted to specify path information in script mapped requests.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AnonymousOnly

This property indicates whether FTP servers limit access to anonymous users only.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AnonymousPasswordSync

This value specifies whether the IIS sub-authenticator is to be used to provide an automatically synchronized password for the anonymous user. If true, no anonymous user password is required. See also AnonymousUserName, and AnonymousUserPass.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AnonymousUserName

The server associates a user name and password with every server action. This value specifies the name of the registered local user that will be used for anonymous users. See also AnonymousUserPass, and AnonymousPasswordSync.

The following table describes this property:

Data type | String
Default value | I_USR_Local machine name
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AnonymousUserPass

The server associates a user name and password with every server action. This value specifies the password of the registered local user that will be used for anonymous users. See also AnonymousUserName and AnonymousPasswordSync.

The following table describes this property:

Data type | String
Default value | Random string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppAllowClientDebug

This flag specifies whether ASP client-side debugging is enabled. This property is independent of AppAllowDebugging, which applies to server-side debugging.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppAllowDebugging

This flag specifies whether ASP debugging is enabled on the server. This property is independent of the AppAllowClientDebug property, which applies to client-side debugging.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppFriendlyName

This property specifies the user-friendly name of the package or application.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppIsolated

This property indicates whether an application is to run in a separate process. This property should be considered read-only. Use the application management methods of the IIsWebVirtualDir and IIsWebDirectory objects, described in the IIS Admin Objects documentation, or the Web Application Management Interface to indicate that an application is to run out-of-process.

The following table describes this property:

Data type | Long
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppOopRecoverLimit

This identifier specifies the maximum number of times an out-of-process application will be restarted after a failure. The server will not service requests from components that have exceeded this limit.

The following table describes this property:

Data type | Long
Default value | 5
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppPackageID

This property provides the MTS package ID for a transaction. This property should be considered read-only.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppPackageName

This property provides the MTS package name for a transaction. This property should be considered read-only.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppRoot

This property provides the URL for the base of the application name space. This property should be considered read-only. To mark a node as an application root, use the application management methods of the IIsWebVirtualDir and IIsWebDirectory objects described in the IIS Admin Objects documentation, or the Web Application Management Interface.

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AppWamClsID

This property provides the class ID for the application's Web Application Management (WAM) package. This property is for read-only usage.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspAllowOutOfProcComponents

This property specifies whether an ASP script is allowed to create out-of-process components.

This property specifies whether an ASP script is allowed to call out-of-process components, executables that are launched from within an application. If set to TRUE at the Web Service level, all in-process applications will be able to launch out-of-process components. If set to TRUE at the root key (virtual directory key) of a specific application, only that application can launch out-of-process components. See Simplifying Development With Process Isolation in Advanced Web Application Development for information on out-of-process components, applications, and related security issues.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspAllowSessionState

This value specifies whether a session state will be created for an ASP page. If False, session state is not allowed, the ASPSessionID cookie will not be sent to clients that access the Web site, and any attempts to store anything in the session or to use Session_OnStart or Session_OnEnd will generate an error.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspBufferingOn

This property specifies whether browser output of an ASP page is buffered. If True, all output is collected before any is sent to the browser. The Response.Buffer method can be used to override this setting for an executing ASP page.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspCodepage

This property determines the default codepage for an application. The Web administrator can designate that a range of the namespace is written in a specific language and prevent individual ASP pages in an application from specifying different languages.

The following table describes this property:

Data type | Long
Default value | 0 (CP_ACP, System ANSI codepage)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspEnableParentPaths

This property specifies whether an ASP page can allow paths relative to the current directory (using the ..\ notation). When True, this constitutes a minor security risk because an include path could access files outside the server's virtual root space. Setting this value to False prevents this.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspExceptionCatchEnable

This value specifies whether exceptions thrown by components are trapped by ASP pages. If False (disabled), the ASP Debugger will not catch exceptions thrown by the component you are debugging.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspLogErrorRequests

This property controls whether the Web server writes unsuccessful client requests to the Microsoft ® Windows NT® event log file. If True, error requests are logged.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspMemFreeFactor

IIS caches memory blocks, called free memory blocks, for active server page execution. When memory blocks are deallocated within IIS they are moved from the used memory list to the free memory list and retained by IIS for reuse. AspMemFreeFactor specifies the ratio, in percent, of free memory blocks to used memory blocks. When the ratio of free blocks to used blocks exceeds the value of this parameter, free blocks are released by IIS and returned to the virtual memory pool. For example, a value of 500 will cause IIS to release memory when the free memory list is 5 times (500% of) the length of the used memory list.

If your server is performing many tasks in addition to running active server pages under IIS, you may wish to set this parameter low. If your server is primarily dedicated to serving ASP pages, a higher value for this parameter will improve performance. A value of zero eliminates IIS memory block caching for ASP page processing and is not recommended.

If this parameter is changed, the change will not take effect until the Web server is stopped and restarted.

The following table describes this property:

Data type | Long
Default value | 50 (percent)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspQueueTimeout

This property specifies the amount of time, in seconds, that an ASP script request will wait in the queue for execution. When requests are pulled from the queue for execution, they are checked to see if they have expired (have waited longer than the value of this parameter). Expired requests are rejected with a message indicating the server is too busy.

The following table describes this property:

Data type | Long
Default value | &HFFFFFFFF (-1)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspScriptEngineCacheMax

This property specifies the maximum number of scripting engines that ASP pages will keep cached in memory.

The following table describes this property:

Data type | Long
Default value | 30
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspScriptErrorMessage

This property specifies the error message that will be sent to the browser if specific debugging errors are not sent to the client (if AspScriptErrorSentToBrowser is False).

The following table describes this property:

Data type | String
Default value | An error occurred on the server when processing the URL. Please contact the system administrator.
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspScriptErrorSentToBrowser

This property specifies whether the Web server writes debugging specifics (file name, error, line number, description) to the client browser in addition to logging them to the Microsoft® Windows NT® event log. The AspScriptErrorMessage property provides the default generic error message to be sent if this property is False.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspScriptFileCacheSize

This property specifies the number of precompiled script files to cache. If 0, no script files will be cached. If -1 (default), all script files requested will be cached. This property can be used to tune performance, depending on the amount of memory available and the amount of script file traffic.

The following table describes this property:

Data type | Long
Default value | -1 (All scripts cached)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspScriptLanguage

This property specifies the default script language for all ASP applications for the Web server. This default language will be used within the script language delimiters (<% and %>) unless specifically overridden by the <%@ LANGUAGE = ScriptingLanguage %> directive.

The following table describes this property:

Data type | String
Default value | VBScript
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspScriptTimeout

This property specifies the default length of time in seconds that ASP pages will allow a script to run before terminating it and writing an event to the event log. The script can override this default value by using the Server.ScriptTimeout method. The minimum value for this property is 1 second. See also AspSessionTimeout.

The following table describes this property:

Data type | Long
Default value | 90 seconds
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AspSessionTimeout

This property specifies the default amount of time in minutes a Session object will be maintained after the last request associated with the object is made. This can be overridden in script using the Session.Timeout method. See also AspScriptTimeout.

The following table describes this property:

Data type | Long
Default value | 20 minutes
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


AuthAnonymous

This property specifies Anonymous authentication as one of the possible Microsoft® Windows NT® authentication schemes returned to clients as being available. AuthAnonymous is one of the authentication scheme flags contained in the AuthFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AuthBasic

This property specifies Basic authentication as one of the possible Microsoft® Windows NT® authentication schemes returned to clients as being available. AuthBasic is one of the authentication scheme flags contained in the AuthFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AuthFlags

This single property contains the settings for the Microsoft® Windows NT® authorization schemes that will be returned to clients as being available. AuthFlags contains the flags: AuthAnonymous, AuthBasic, and AuthNTLM.

The following table describes this property:

Data type | Long
Default value | AuthAnonymous = True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |

See Also

MD_AUTHORIZATION for hexadecimal values when setting flags in AuthFlags.


AuthNTLM

This property specifies NTLM authentication as one of the possible Microsoft® Windows NT® authentication schemes returned to clients as being available. AuthNTLM is one of the authentication scheme flags contained in the AuthFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


AuthPersistence

This property specifies authentication persistence across requests on a connection. If the value is 0x40, then authentication persists only for a single request. If the value is 0x80, then authentication persists only for a single request if it is a proxy request and the request is not handled by Microsoft® Proxy Server. (i.e. If Proxy Server is running on the local IIS server and the request is targeted to a non-local server.) If the value is 0x100, then authentication is valid for a single request if the request is by proxy.

The following table describes this property:

Data type | Long
Default value | 0x80 (Single request, if proxy)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


CacheControlCustom

This property specifies custom HTTP 1.1 cache control directives. Multiple directives may be specified if they are separated by carriage return/line feed (CRLF) pairs. There should not be a trailing carriage return/line feed after the final directive.

The following table describes this property:

Data type | String
Default value | Not applicable. By default, this property is not set and cache control directives are not sent.
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


CacheControlMaxAge

This property specifies the HTTP 1.1 cache control maximum age value. The range is 0 to &HFFFFFFFF seconds.

The following table describes this property:

Data type | Long
Default value | Not applicable. By default, this property is not set and cache control directives are not sent.
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


CacheControlNoCache

This property specifies the HTTP 1.1 directive to prevent caching of content.

The following table describes this property:

Data type | Boolean
Default value | Not applicable. By default, this property is not set and cache control directives are not sent.
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


CacheISAPI

If True, then the web server caches ISAPI DLLs. If False, they are unloaded after running.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebServer


CGITimeout

This property specifies the timeout in seconds for CGI applications. Its range is 10-0x80000000.

The following table describes this property:

Data type | Long
Default value | 900 (15 minutes)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebServer


ConnectionTimeout

This property specifies the time in seconds the server will wait before disconnecting an inactive connection.

The following table describes this property:

Data type | Long
Default value | 900 (15 minutes)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


ContentIndexed

This property specifies whether the content under this directory tree should be indexed by the installed content indexer.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


CreateCGIWithNewConsole

This property specifies whether CGI applications are to run with their own console windows.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


CreateProcessAsUser

This property specifies whether a CGI process will be created in the system context or in the context of the requesting user.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


CustomErrorDescriptions

This property provides custom error descriptions in a list of strings. Each string is in the format ErrorCode, ErrorSubcode, ErrorText, ErrorSubcodeText, followed by another comma and either a 0 for file and URL support, or a 1 for file support only.

The following table describes this property:

Data type | List (String)
Default value | Empty list
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsWebInfo


DefaultDoc

This property contains one or more file names of default documents that will be returned to the client if no file is included in the client's request. The default document will be returned if the EnableDefaultDoc property is True for the directory. This property may contain a list of default document file names separated by a comma and a space, as in default1.htm, default2.htm.

The following table describes this property:

Data type | String
Default value | default.htm
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


DefaultDocFooter

This value specifies the custom footer that is appended to files that are returned to the client. The custom footer will be sent only if the EnableDocFooter property is True. This can be a string such as "This is a custom footer," or a reference to a file such as c:\wwwroot\footers\footer.htm.

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


DefaultLogonDomain

This property specifies the default domain for logon. If this value is not specified, the default domain will be the domain name controlled by the computer if the computer is a domain controller. If the computer is not a domain controller, the default domain will be the computer name.

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


DirBrowseFlags

This single property contains the following directory browsing flags:

DirBrowseShowDate | DirBrowseShowTime
DirBrowseShowExtension | EnableDefaultDoc
DirBrowseShowLongDate | EnableDirBrowsing
DirBrowseShowSize |

The following table describes this property:

Data type | Long
Default value | DirBrowseShowDate, DirBrowseShowExtension, DirBrowseShowSize, DirBrowseShowTime, EnableDefaultDoc
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService IIsWebServer IIsWebVirtualDir IIsWebDirectory

See Also

MD_DIRECTORY_BROWSING for hexadecimal values when setting flags in DirBrowseFlags.


DirBrowseShowDate

This property specifies that date information will be displayed when browsing directories. DirBrowseShowDate is one of the settings contained in the DirBrowseFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


DirBrowseShowExtension

This property specifies that file extensions will be displayed when browsing directories. DirBrowseShowExtension is one of the settings contained in the DirBrowseFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


DirBrowseShowLongDate

This property specifies that date information will be displayed in extended format when browsing directories. DirBrowseShowLongDate is one of the settings contained in the DirBrowseFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


DirBrowseShowSize

This property specifies that file size information will be displayed when browsing directories. DirBrowseShowSize is one of the settings contained in the DirBrowseFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


DirBrowseShowTime

This property specifies that file time information will be displayed when browsing directories. DirBrowseShowTime is one of the settings contained in the DirBrowseFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


DirectoryLevelsToScan

This property specifies the number of virtual directory levels to scan in the metabase from the top of the tree (i.e., the ROOT virtual directory for a server) to build a list of directories to be monitored for file system changes. The valid range is 0 to 0xFFFFFFFF (unlimited). If a virtual directory is not included in the list then the IIS cache will not be flushed when a file change occurs in the directory. This list is also used for downlevel administration from previous versions (1.0 to 3.0) of IIS.

The following table describes this property:

Data type | Long
Default value | 2
Default inheritance | False

Accessible by IIS Admin Objects:


DontLog

This property specifies whether client requests should be written to the log file. By default (False), requests are written to the file. You can set this value to True to turn logging off.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


DownlevelAdminInstance

This property indicates the server instance for remote administration clients.

The following table describes this property:

Data type | String
Default value | 1 (String)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


EnableDefaultDoc

This property specifies that the default document (specified by the DefaultDoc property) for a directory will be loaded when the directory is being browsed. EnableDefaultDoc is one of the settings contained in the DirBrowseFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


EnableDirBrowsing

This property specifies that directory browsing is enabled. EnableDirBrowsing is one of the settings contained in the DirBrowseFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


EnableDocFooter

This property enables or disables custom footers specified by the DefaultDocFooter property. Higher performance will be achieved if custom footers are disabled.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


EnableReverseDns

This property enables or disables reverse Domain Name Server (DNS) lookups (finding name from IP address) are allowed. Reverse DNS lookups can use significant resources and time.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


ExitMessage

This property specifies the message text an FTP server will transmit to a client when the client sends a quit command.

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


FilterDescription

This property is a description of a filter supplied by the filter.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


FilterEnabled

This property indicates whether the filter is enabled.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


FilterFlags

This property contains flags that indicate for which events the ISAPI filter has registered to be notified. This property, and all its component flags, should be considered read-only. For more information, see the ISAPI documentation. FilterFlags contains the following flags:

NotifyAccessDenied | NotifyNonSecurePort | NotifyReadRawData
NotifyAuthentication | NotifyOrderHigh | NotifySecurePort
NotifyEndOfNetSession | NotifyOrderLow | NotifySendRawData
NotifyEndOfRequest | NotifyOrderMedium | NotifySendResponse
NotifyLog | NotifyPreProcHeaders | NotifyUrlMap

The following table describes this property:

Data type | Long
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter

See Also

MD_FILTER_FLAGS for hexadecimal values when setting flags in FilterFlags.


FilterLoadOrder

This property, a comma-delimited list, specifies the order in which filters are to be loaded, such as Filter1, Filter2, and so on. .

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilters


FilterPath

This property specifies the full path to a filter DLL; for example c:\wwwroot\bin\filter.dll.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


FilterState

This property indicates whether the filter is loaded (value 1) or unloaded (value 4). This property should be considered read-only.

The following table describes this property:

Data type | Long
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


FrontPageWeb

This property indicates whether this server instance will be targeted by FrontPage®. Setting this value to True causes the Front Page Manager to create the files required for Front Page Extensions. Setting this value to False causes the files to be deleted.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsWebServer


GreetingMessage

This property contains a greeting message (in a multiple-line string) for an FTP server to send to new clients when they connect.

The following table describes this property:

Data type | List (String)
Default value | Empty list
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


HttpCustomHeaders

This property contains custom headers that are sent to the client in addition to the default header of the HTML file. Each string in this property is formatted as a key name and value pair, Keyname, Value.

The following table describes this property:

Data type | List (String)
Default value | Empty list
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


HttpErrors

This property specifies the custom error string to be sent to clients in response to HTTP 1.1 errors. Each string in the list specifies the HTTP error code and subcode, indicates whether the handler will be a URL or a file, and specifies which URL or file the client will be sent. Each string can be in one of two formats. To send a URL to the client, use HTTPErrorCode, HTTPErrorSubcode, URL, HanderlerURL. To send a file, use HTTPErrorCode, HTTPErrorSubcode, FILE, Filename.

The following table describes this property:

Data type | List (String)
Default value | Empty list
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


HttpExpires

This property specifies the expiration of HTML document content by returning the value to the browser in the HTML file header. The browser compares the value of this property with the current date to determine whether to display a cached page or to request an updated page from the server. This property can be relative, or dynamic, using the format D, #SecondsUntilExpiration (with 0xFFFFFFFF indicating no expiration date), or absolute, with the format S,ValidGMTString.

The following table describes this property:

Data type | String
Default value | D,0xFFFFFFFF (No expiration)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


HttpPics

This property specifies the World Wide Web Consortium's (W3C) Platform for Internet Content Selection (PICS) rating header. For more information on PICS, see the W3C website at http://www.w3.org.

The following table describes this property:

Data type | List (String)
Default value | Empty List
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


HttpRedirect

This property specifies the directory or URL to which a client is redirected when they attempt to access a specific resource. There are two general forms that the value for this property can take, one simple and one more powerful.

The simple format is Destination, Flag, where Destination can specify either a URL or a virtual path to a file. Flag can have one of three values: EXACT_DESTINATION indicates that the value provided for Destination should be considered an absolute target location; CHILD_ONLY indicates that the value should be prepended to the filename of the request to be redirected; and PERMANENT indicates that this redirection will be permanent for this resource.

The more complex form of specification for this property involves the use of wildcards. The format is *; Wildcard1; Destination1; Wildcard2; Destination2, Flag. Each Wildcard; Destination pair indicates that requests matching the wildcard are redirected to the specified destination. Flag can have the same values as the simple string format.

The following table describes this property:

Data type | String
Default value | Empty string (No redirects)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


InProcessIsapiApps

This property specifies a list of ISAPI Applications that must be run in the web server process. The string format is Fullpath\Appname.DLL.

The following table describes this property:

Data type | List (String)
Default value | httpodbc.dl ssinc.dll
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService


IPSecurity

This value specifies the IP access restrictions for this URL.

The following table describes this property:

Data type | Binary Reference
Default value | No IP restrictions
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


KeyType

The KeyType property specifies the type of a metabase key, and the IIS Admin Object that relates to that key. The KeyType property is used to specify the class of the object associated with the key, such as IIsWebServer or IIsWebVirtualDir. The KeyType determines the set of properties accessible at the key.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by all IIS Admin Objects. The value is the name of the IIS Admin Object accessed, and is the same as the ADSI Class property.


LogAnonymous

This property specifies whether anonymous hits are logged to the event log.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileBytesRecv

This property indicates whether the total number of bytes received is written to the log file during logging events. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileBytesSent

This property indicates whether the total number of bytes sent is written to the log file during logging events. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileClientIp

This property indicates whether the client's IP address is written to the log file during logging events. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileComputerName

This property enables the logging of the local machine's name during logging events. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileCookie

This property indicates whether information from the client cookie is written to the log file during logging events. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileDate

This property indicates whether the date is included in the information written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileFlags

This property contains flags that indicate to Microsoft® Windows NT® Server what categories of information are written to the log file (or ODBC data source) during logging events. The following individual flags are included in this property:

LogExtFileBytesRecv | LogExtFileMethod | LogExtFileTimeTaken
LogExtFileBytesSent | LogExtFileProtocolVersion | LogExtFileUriQuery
LogExtFileClientIp | LogExtFileReferer | LogExtFileUriStem
LogExtFileComputerName | LogExtFileServerIp | LogExtFileUserAgent
LogExtFileCookie | LogExtFileServerPort | LogExtFileUserName
LogExtFileDate | LogExtFileSiteName | LogExtFileWin32Status
LogExtFileHttpStatus | LogExtFileTime |

The following table describes this property:

Data type | Long
Default value | LogExtFileClientIp, LogExtFileHttpStatus, LogExtFileMethod, LogExtFileTime, LogExtFileUriStem, bits set to True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsFtpService IIsFtpServer IIsWebService IIsWebServer

See Also

MD_LOGEXT_FIELD_MASK for hexadecimal values when setting flags in LogExtFileFlags.


LogExtFileHttpStatus

This property indicates whether HTTP status information is written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileMethod

This property indicates whether the logging method is written to the log file during a logging event. This property is one of the flags contained in LogExtFileFlags.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileProtocolVersion

This property indicates whether the client server protocol version is written to the log file during a logging event. This property is one of the flags contained in LogExtFileFlags.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileReferer

This property indicates whether the referer field, sent by the client, is written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileServerIp

This property indicates whether the server's IP address is written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileServerPort

This property indicates whether the active server port is written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileSiteName

This property indicates whether the site name is written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileTime

This property indicates whether the time is written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileTimeTaken

This property enables the writing into the log file, during logging events, of the total time taken for a request to be completed. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileUriQuery

This property indicates whether the Universal Resource Identifier (URI) query information is written to the log file during logging events. The URI query usually consists of parameters passed to the URL using the URL?Parameters format. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileUriStem

This property indicates whether the Universal Resource Identifier (URI) stem information is written to the log file during logging events. The URI stem usually consists of the actual resource being requested. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileUserAgent

This property indicates whether the contents of the user agent field, sent by the client, is written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileUserName

This property indicates whether the user's name is written to the log file during logging events. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogExtFileWin32Status

This property indicates whether the current Microsoft® Win32® error status is written to the log file during a logging event. This property is one of the flags contained in the LogExtFileFlags property.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogFileDirectory

This property specifies the default logging directory, in which the log file and logging-related support files are stored.

The following table describes this property:

Data type | String
Default value | %WinDir%\System32\LogFiles
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogFilePeriod

This property specifies how often Microsoft® Windows NT® should create a new log file. If this property is set to 0, a new file will be created when the maximum size designated in LogFileTruncateSize is reached. If this property is set at 1, 2, or 3, a new log file will be created daily, weekly, or monthly, respectively.

The following table describes this property:

Data type | Long
Default value | 1 (Create new log file daily)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogFileTruncateSize

This property specifies the maximum size of the log file, in bytes. A new log file is created if a logging event causes the original log file to exceed the size specified in this property.

The following table describes this property:

Data type | Long
Default value | 2048 (2 MB)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogModuleId

This property specifies the CLSID for the logging module.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsLogModule


LogModuleList

This property specifies a string that contains a comma-delimited list that names the logging modules that are available.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogModuleUiId

This property specifies the CLSID for the logging module's user interface.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsLogModule


LogNonAnonymous

This property specifies whether non-anonymous hits are logged to the event log.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogOdbcDataSource

This property specifies the name of the ODBC data source to which Microsoft® Windows NT® will write data during logging events.

The following table describes this property:

Data type | String
Default value | HTTPLOG
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogOdbcPassword

This property specifies the ODBC database password to be used when writing information to the database during logging events.

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogOdbcTableName

This property specifies the name of the ODBC database table to which Microsoft® Windows NT® will write information during logging events.

The following table describes this property:

Data type | String
Default value | InternetLog
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogOdbcUserName

This property specifies the ODBC database user name to be used when writing information to the database during logging events.

The following table describes this property:

Data type | String
Default value | InternetAdmin
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogonMethod

This property specifies the logon method for clear text logons. Valid settings are: interactive (value set to 0), batch (1) , and network (2). Each user attempting to log on to the server must have access permissions corresponding to the appropriate logon method.

The following table describes this property:

Data type | Long
Default value | 0 (Interactive)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


LogPluginClsid

This property specifies the order of the logging modules.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


LogType

This property indicates whether logging is enabled. A value of 0 indicates that logging is disabled, while a value of 1 indicates that logging is enabled. This property should be considered read-only.

The following table describes this property:

Data type | Long
Default value | 1 (Logging enabled)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


MaxBandWidth

This property specifies the maximum network bandwidth used for IIS. This setting can be used to help to prevent overloading the network with IIS activity. This is not an inheritable property, but the value set at the machine level is globally available to all server instances. MaxBandWidth can be set individually for specific server instances to be used instead of the global value, and may exceed the global setting established at the machine level. A server instance must be stopped and restarted for a changed MaxBandWidth value to take effect.

The following table describes this property:

Data type | Long
Default value | 0xFFFFFFFF (unlimited)
Default inheritance | Global - Not inheritable

Accessible by IIS Admin Objects:


MaxBandwidthBlocked

This property specifies the maximum number of asynchronous requests to be queued in the outstanding idle queue when the maximum bandwidth of the server is exceeded. The value range for this property is 0 to &HFFFFFFFF (unlimited).

This is not an inheritable property, but the value set at the machine level is globally available to all server instances.

The following table describes this property:

Data type | Long
Default value | &HFFFFFFFF (unlimited)
Default inheritance | Global - Not inheritable

Accessible by IIS Admin Objects:


MaxClientsMessage

This property contains the text of a message to send to clients when the current connection exceeds the maximum connections established by the MaxConnections property. The message is a single line of text.

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


MaxConnections

This property specifies the maximum number of simultaneous connections to a server. The valid range is 0 to 0xFFFFFFFF (unlimited). The MaxClientsMessage property can be used to send a message to clients when this value has been exceeded.

The following table describes this property:

Data type | Long
Default value | 0xFFFFFFFF (Unlimited) for NTS, 10 for NTW
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


MaxEndpointConnections

This property specifies the maximum number of listen sockets that will be aggregated on a network endpoint. For example, if this value is set to 15, then a maximum of 15 total connections can be made to a single port, even if more than one domain is bound to the port.

The following table describes this property:

Data type | Long
Default value | 0xFFFFFFFF (Unlimited)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


MimeMap

This property provides a list of the file name extensions for Multipurpose Internet Mail Extensions (MIME) mappings. The MimeMap key at the local machine level of the metabase establishes the default list, which can be overridden at the web service and web server level keys. See the IIsMimeMap object for details on managing this property.

The following table describes this property:

Data type | List (Objects)
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


MSDOSDirOutput

This property specifies the style of directory output for a list operation request from an FTP client. If the value is True, the format is in MS-DOS style, if False, it is produced in UNIX style.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


NetLogonWorkstation

This property specifies Microsoft® Windows NT® Workstation logon restrictions from a primary domain controller. The Windows NT Workstation logon field is empty if this value is 0, contains the Internet Protocol (IP) address if the value is 1, and contains the Domain Name System (DNS) name if the value is 2.

The following table describes this property:

Data type | Long
Default value | 0 (Workstation restrictions only)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


NotifyAccessDenied

This property specifies whether the filter has registered to be notified of access denial messages. If the value is True, the filter will be notified when the server is about to send the 401 Access Denied error message. If the value is False, the filter ignores access denial messages. This property is one of the flags contained in the property FilterFlags, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyAuthentication

This property indicates whether the filter has registered to be notified of authentication events. If the value is True, the filter will be notified when the server is initially authenticating the client. This property is one of the flags contained in the property FilterFlags, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyEndOfNetSession

This property indicates whether the filter has registered to be notified of network sessions that are ending. This property is one of the flags contained in the property FilterFlags, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyEndOfRequest

This property indicates whether the filter has registered to be notified at the end of every client request. This property is one of the flags contained in the property FilterFlags, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyLog

This property indicates whether the filter has registered to be notified when the server is writing to the log. This property is one of the flags contained in the property FilterFlags, and should be considered read-only.

The following table describes this property:

Data type | Bool
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyNonSecurePort

This property indicates whether the filter has registered to be notified only for sessions on nonsecure ports. This property is one of the flags contained in the FilterFlags property, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyOrderHigh

This property indicates whether the filter has registered as high priority. When a notification occurs, if the filter has registered for that notification, high priority filters are processed first. If other filters have also registered as high priority, then the filters will be processed in the order they appear in the FilterLoadOrder property.

This property is one of the flags contained in the FilterFlags property, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyOrderLow

This property indicates whether the filter has registered as low priority. When a notification occurs, if the filter has registered for that notification, low priority filters are processed last. If other filters have also registered as low priority, then the filters will be processed in the order they appear in the FilterLoadOrder property.

This property is one of the flags contained in the FilterFlags property, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyOrderMedium

This property indicates whether the filter has registered as medium priority. When a notification occurs, if the filter has registered for that notification, medium priority filters are processed after high priority filters, but before low priority filters. If other filters have also registered as low priority, then the filters will be processed in the order they appear in the FilterLoadOrder property.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyPreProcHeaders

This property indicates whether the filter has registered to be notified when the server has preprocessed the headers of a request. This property is one of the flags contained in the FilterFlags, and should be considered read-only property.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyReadRawData

This property indicates whether the filter has registered to be given raw data as input, before any processing has taken place. This property is one of the flags contained in the FilterFlags property, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifySecurePort

This property indicates whether the filter has registered to be notified only for sessions on secure ports. This property is one of the flags contained in the FilterFlags property, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifySendRawData

This property indicates whether the filter has registered to be notified when the server is sending raw data back to the client. This property is one of the flags contained in the FilterFlags property, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifySendResponse

This property indicates whether the filter has registered to be notified when the server is sending a response to the client. This property is one of the flags contained in the FilterFlags property, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NotifyUrlMap

This property indicates whether the filter has registered to be notified when the server maps a logical URL to a physical path. This property is one of the flags contained in the FilterFlags property, and should be considered read-only.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsFilter


NTAuthenticationProviders

This property contains a comma-delimited list of Microsoft® Windows NT® authentication providers, such as NTLM.

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


PasswordCacheTTL

This property is used for password types of security authentication schemes. The value specifies the amount of time in seconds that an expired password will be held in the memory cache.

The following table describes this property:

Data type | Long
Default value | 600 (10 minutes)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


PasswordChangeFlags

This property specifies the flags that control password expiration and password change processing between the server and client. A value of 0 (default) indicates that an SSL connection is required, 1 indicates that changing is allowed on nonsecure ports, 2 indicates that changing is disabled, and 4 indicates that password expiration notification is disabled.

The following table describes this property:

Data type | Long
Default value | 0 (Changes allowed on nonsecure ports)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


PasswordExpirePrenotifyDays

This property specifies the number of days remaining before the client's password will expire, and is used to indicate when a password prenotify message will be sent.

The following table describes this property:

Data type | Long
Default value | 14 Days
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


Path

This property specifies the physical path associated with a virtual directory.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


PoolIDCTimeout

This property specifies the timeout value in seconds for internet database connection pooling. A value of zero specifies no pooling.

The following table describes this property:

Data type | Long
Default value | 30 seconds
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


ProcessNTCRIfLoggedOn

This property enables processing of Microsoft® Windows NT® Challenge/Response (NTLM) authentication even if a user has already logged on using an alternate authorization scheme.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


PutReadSize

This property specifies the chunk size to be sent to the client in the HTTP 1.1 Transfer Encoding header field. Normal values for this property are in the range of 1K to 64K bytes. Intranet applications may benefit from values for this property at the upper end of the range. For internet applications, values at the lower end of the range are more appropriate.

The following table describes this property:

Data type | Long
Default value | 8192 (8K)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


Realm

This property specifies the realm when the server requests a client to authenticate because the client was denied access to a resource when using Basic (clear text) authentication. This value appears in the browser's user name-password prompt.

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


RedirectHeaders

This property specifies additional redirection headers. Multiple headers may be specified if they are separated by carriage return/line feed (CRLF) pairs. There should not be a trailing carriage return/line feed after the final header.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


ScriptMaps

This property specifies the file name extensions of applications for script processor mappings. The string format is Extension, ScriptProcessor, Flags. Flags can be 1 (allowed on read directory) or 4 (check path info).

The following table describes this property:

Data type | List (String)
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


SecureBindings

This property specifies a string that is used by IIS to determine what secure network endpoints are used by the server instance. The string format is IP:Port.

The following table describes this property:

Data type | List (String)
Default value | Empty list if no keys installed, :443: if server keys installed
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebServer


ServerAutoStart

This property indicates if the server instance should start automatically when the service is started.

The following table describes this property:

Data type | Boolean
Default value | True
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


ServerBindings

This property specifies a string that is used by IIS to determine what network endpoints are used by the server instance. The string format is IP:Port:Hostname. Both the IP and Hostname parameter of the string are optional. Any unspecified parameters default to an all-inclusive wildcard.

The following table describes this property:

Data type | List (String)
Default value | :80: for Web service, :21: for FTP service
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


ServerComment

This property specifies a comment for the server instance.

The following table describes this property:

Data type | String
Default value | Empty string
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


ServerConfigAutoPWSync

This property is a flag that participates in the ServerConfigFlags server configuration specification property. A value of True indicates that the subauthenticator is installed.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsWebInfo


ServerConfigFlags

This property contains flags that specify the server configuration established at startup. This property is used by the administration user interface. The flags contained in this property are individually defined in the following properties:

ServerConfigAutoPWSync | ServerConfigSSL128
ServerConfigSSLAllowEncrypt | ServerConfigSSL40

The following table describes this property:

Data type | Long
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsWebInfo

See Also

MD_SERVER_CONFIGURATION_INFO for hexadecimal values when setting flags in ServerConfigFlags.


ServerConfigSSL128

This property is a flag that participates in the ServerConfigFlags server configuration specification property. A value of True indicates that 128-bit Secure Socket Layer (SSL) processing is installed.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsWebInfo


ServerConfigSSL40

This property is a flag that participates in the ServerConfigFlags server configuration specification property. A value of True indicates that 40-bit Secure Socket Layer (SSL) processing is installed.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsWebInfo


ServerConfigSSLAllowEncrypt

This property is a flag that participates in the ServerConfigFlags server configuration specification property. A value of True indicates that the locality allows encryption.

The following table describes this property:

Data type | Boolean
Default value | Not applicable
Default inheritance | Not inheritable

Accessible by IIS Admin Objects:

IIsWebInfo


ServerListenBacklog

This property specifies the number of outstanding sockets that can be queued. The value is based on the AcceptEx operating system parameter and the server size specified in the ServerSize property. Valid values for this property range from 5 to 500.

The following table describes this property:

Data type | Long
Default value | Based on ServerSize
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


ServerListenTimeout

This property specifies the amount of time in seconds the server should wait before disconnecting a client that has connected but not sent any data.

The following table describes this property:

Data type | Long
Default value | 120 (2 minutes)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


ServerSize

This property specifies the general size of the server in terms of number of client requests handled per day. A value of 0 indicates a small Web site that would expect to receive fewer than 10,000 requests per day, a value of 1 indicates a medium site handling between 10,000 and 100,000 a day, and a value of 2 designates a large site processing more than 100,000 requests a day. The value of this property is used in calculating the value for the ServerListenBacklog property.

The following table describes this property:

Data type | Long
Default value | 1 (Medium)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


ServerState

This property presents the current state of the server instance. The states, and the corresponding state code, are as follows: 1 (starting), 2 (started), 3 (stopping), 4 (stopped), 5 (pausing), 6 (paused), or 7 (continuing).

This property should be treated as read-only.

The following table describes this property:

Data type | Long
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


SSIExecDisable

This property specifies whether Server-Side Includes (SSI) #exec directives are disabled under this path.

The following table describes this property:

Data type | Boolean
Default value | False (SSIs enabled)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


UNCAuthenticationPassthrough

This property enables user authentication passthrough for Universal Naming Convention (UNC) virtual root access for authentication schemes that support delegation.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


UNCPassword

This property specifies the encrypted password used to gain access to Universal Naming Convention (UNC) virtual roots.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


UNCUserName

This property specifies the user name for Universal Naming Convention (UNC) virtual roots.

The following table describes this property:

Data type | String
Default value | Not applicable
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


UploadReadAheadSize

This property establishes the number of bytes a Web server will read into a buffer and pass to an ISAPI application. This occurs once. The ISAPI application receives any additional data directly from the client. The range is 0 to &HFFFFFFFF (4GB).

The following table describes this property:

Data type | Long
Default value | 49152 (48K bytes)
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService | IIsWebServer | IIsWebVirtualDir | IIsWebDirectory
IIsWebFile |  |  |


UseHostName

This property specifies whether the server returns its DNS host name (the computer name, by default) when doing redirects. If the value of this property is False, then the host's Internet protocol (IP) address is returned instead of a host name.

The following table describes this property:

Data type | Boolean
Default value | False
Default inheritance | Inheritable

Accessible by IIS Admin Objects:


WAMUserName

This property specifies the account user name that IIS uses by default as the MTS package identity for newly created IIS out-of-process application packages. The values of this property and its companion property, WAMUserPass, are set when IIS is installed, and match the user name and password values in the Microsoft® Windows NT® user account established at the same time. It is recommended that you do not change the value of this property. If you do change this value, be certain to change it to a valid Windows NT user account, and change WAMUserPass to the corresponding password for the new account.

Note Changes to the value of this property and WAMUserPass may disrupt operation of existing IIS out-of-process application packages. You can synchronize package identities using the MTS Explorer to edit the user name and password values found on the Identity tab of the property sheet for each package. See WAMUserPass for additional information. In-process application packages are not affected by these property values.

The following table describes this property:

Data type | String
Default value | IWAM_MachineName, where MachineName is the name of the machine on which IIS is installed.
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService


WAMUserPass

This property specifies the password for the account that IIS uses by default as the MTS package identity for newly created IIS out-of-process application packages. The values of this property and its companion property, WAMUserName, are set when IIS is installed, and match the password and user name values in the Microsoft® Windows NT® user account (IWAM_MachineName, where MachineName is the name of the machine on which IIS is installed) established at the same time. It is recommended that you do not change the value of this property. If you do change this value, the Windows NT account password must be changed to the identical value, and you must also synchronize existing IIS out-of-process package identities using MTS Explorer to edit the user name and password values found on the Identity tab of the property sheet for each package. In-process application packages are not affected by these property values.

The following table describes this property:

Data type | String
Default value | Generated by the setup program when IIS is installed.
Default inheritance | Inheritable

Accessible by IIS Admin Objects:

IIsWebService


Property Inheritance Charts

These charts provide a quick visual map of properties to IIS Admin Objects, and the inheritance attribute of the property. An X in a cell shows which objects can access a specific property. There are three charts.

  • The FTP Property Inheritance chart shows properties that apply to FTP services.
  • The Web Property Inheritance chart shows properties that apply to Web services.
  • The Miscellaneous Property Inheritance chart shows properties that apply to objects other than FTP or Web services.


FTP Property Inheritance

This chart shows the properties associated with the IIS FTP services. For each property you can see the default setting of its inheritance attribute and the IIS Admin Objects you can use to access the value of the property in the metabase. The inheritance is indicated as:

Inh | Inherits
Inh | Contained in another inherited property
Inh* | Contains more than one property
NoAtt | Does not inherit

 |  | FTP
Property | Inherit | Service | Info | Server | VirtualDir
AccessFlags | Inh | x |  | x | x
AccessRead | Inh* | x |  | x | x
AccessWrite | Inh* | x |  | x | x
AdminACL | Inh | x |  | x |
AllowAnonymous | Inh | x |  | x |
AnonymousOnly | Inh | x |  | x |
AnonymousPasswordSync | Inh | x |  | x |
AnonymousUserName | Inh | x |  | x |
AnonymousUserPass | Inh | x |  | x |
ConnectionTimeout | Inh | x |  | x |
DefaultLogonDomain | Inh | x |  | x |
DirectoryLevelsToScan | NoAtt | x |  |  |
DontLog | Inh | x |  | x | x
DownlevelAdminInstance | NoAtt | x |  |  |
ExitMessage | Inh | x |  | x |
GreetingMessage | Inh | x |  | x |
IPSecurity | Inh | x |  | x | x
KeyType | NoAtt | x | x | x | x
LogAnonymous | Inh | x |  | x |
Property | Inherit | Service | Info | Server | VirtualDir
LogExtFileBytesRecv | Inh* | x |  | x |
LogExtFileBytesSent | Inh* | x |  | x |
LogExtFileClientIp | Inh* | x |  | x |
LogExtFileComputerName | Inh* | x |  | x |
LogExtFileCookie | Inh* | x |  | x |
LogExtFileDate | Inh* | x |  | x |
LogExtFileFlags | Inh | x |  | x |
LogExtFileHttpStatus | Inh* | x |  | x |
LogExtFileMethod | Inh* | x |  | x |
LogExtFileProtocolVersion | Inh* | x |  | x |
LogExtFileReferer | Inh* | x |  | x |
LogExtFileServerIp | Inh* | x |  | x |
LogExtFileServerPort | Inh* | x |  | x |
LogExtFileSiteName | Inh* | x |  | x |
LogExtFileTime | Inh* | x |  | x |
LogExtFileTimeTaken | Inh* | x |  | x |
LogExtFileUriQuery | Inh* | x |  | x |
LogExtFileUriStem | Inh* | x |  | x |
LogExtFileUserAgent | Inh* | x |  | x |
Property | Inherit | Service | Info | Server | VirtualDir
LogExtFileUserName | Inh* | x |  | x |
LogExtFileWin32Status | Inh* | x |  | x |
LogFileDirectory | Inh | x |  | x |
LogFilePeriod | Inh | x |  | x |
LogFileTruncateSize | Inh | x |  | x |
LogModuleList | Inh |  | x |  |
LogNonAnonymous | Inh | x |  | x |
LogOdbcDataSource | Inh | x |  | x |
LogOdbcPassword | Inh | x |  | x |
LogOdbcTableName | Inh | x |  | x |
LogOdbcUserName | Inh | x |  | x |
LogPluginClsId | Inh | x |  | x |
LogType | Inh | x |  | x |
MaxClientsMessage | Inh | x |  | x |
MaxConnections | Inh | x |  | x |
MaxEndpointConnections | Inh | x |  | x |
MSDOSDirOutput | Inh | x |  | x |
Property | Inherit | Service | Info | Server | VirtualDir
Path | Inh |  |  |  | x
Realm | Inh | x |  | x |
ServerAutoStart | Inh | x |  | x |
ServerBindings | Inh | x |  | x |
ServerComment | Inh | x |  | x |
ServerListenBacklog | Inh | x |  | x |
ServerListenTimeout | Inh | x |  | x |
ServerSize | Inh | x |  | x |
ServerState | Inh |  |  | x |
UNCPassword | Inh |  |  |  | x
UNCUserName | Inh |  |  |  | x


Web Property Inheritance

This chart shows the properties associated with the IIS Web services. For each property you can see the default setting of its inheritance attribute and the IIS Admin Objects you can use to access the value of the property in the metabase. The inheritance is indicated as:

Inh | Inherits
Inh | Contained in another inherited property
Inh* | Contains more than one property
NoAtt | Does not inherit

 |  | Web
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
AccessExecute | Inh* | x |  | x | x | x | x
AccessFlags | Inh | x |  | x | x | x | x
AccessNoRemoteExecute | Inh* | x |  | x | x | x | x
AccessNoRemoteRead | Inh* | x |  | x | x | x | x
AccessNoRemoteScript | Inh* | x |  | x | x | x | x
AccessNoRemoteWrite | Inh* | x |  | x | x | x | x
AccessRead | Inh* | x |  | x | x | x | x
AccessScript | Inh* | x |  | x | x | x | x
AccessSSL | Inh* | x |  | x | x | x | x
AccessSSL128 | Inh* | x |  | x | x | x | x
AccessSSLFlags | Inh | x |  | x | x | x | x
AccessSSLMapCert | Inh* | x |  | x | x | x | x
AccessSSLNegotiateCert | Inh* | x |  | x | x | x | x
AccessSSLRequireCert | Inh* | x |  | x | x | x | x
AccessWrite | Inh* | x |  | x | x | x | x
AdminACL | Inh | x |  | x |  |  |
AdminServer | NoAtt |  | x |  |  |  |
AllowKeepAlive | Inh | x |  | x |  |  |
AllowPathInfoForScriptMappings | Inh | x |  | x |  |  |
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
AnonymousPasswordSync | Inh | x |  | x | x | x | x
AnonymousUserName | Inh | x |  | x | x | x | x
AnonymousUserPass | Inh | x |  | x | x | x | x
AppAllowClientDebug | Inh | x |  | x | x | x |
AppAllowDebugging | Inh | x |  | x | x | x |
AppFriendlyName | Inh | x |  | x | x | x |
AppIsolated | Inh | x |  | x | x | x |
AppOopRecoverLimit | Inh |  |  | x | x | x |
AppPackageID | Inh | x |  | x | x | x |
AppPackageName | Inh | x |  | x | x | x |
AppRoot | Inh | x |  | x | x | x |
AppWamClsid | Inh | x |  | x | x | x |
AspAllowOutOfProcComponents | Inh | x |  | x | x | x |
AspAllowSessionState | Inh | x |  | x | x | x |
AspBufferingOn | Inh | x |  | x | x | x |
AspCodepage | Inh | x |  | x | x | x |
AspEnableParentPaths | Inh | x |  | x | x | x |
AspExceptionCatchEnable | Inh | x |  | x | x | x |
AspLogErrorRequests | Inh | x |  | x | x | x |
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
AspMemFreeFactor | Inh | x |  | x | x | x |
AspQueueTimeout | Inh | x |  | x | x | x |
AspScriptEngineCacheMax | Inh | x |  | x | x | x |
AspScriptErrorMessage | Inh | x |  | x | x | x |
AspScriptErrorSentToBrowser | Inh | x |  | x | x | x |
AspScriptFileCacheSize | Inh | x |  | x | x | x |
AspScriptLanguage | Inh | x |  | x | x | x |
AspScriptTimeout | Inh | x |  | x | x | x |
AspSessionTimeout | Inh | x |  | x | x | x |
AuthAnonymous | Inh* | x |  | x | x | x | x
AuthBasic | Inh* | x |  | x | x | x | x
AuthFlags | Inh | x |  | x | x | x | x
AuthNTLM | Inh* | x |  | x | x | x | x
AuthPersistence | Inh | x |  | x | x | x | x
CacheControlCustom | Inh | x |  | x | x | x | x
CacheControlMaxAge | Inh | x |  | x | x | x | x
CacheControlNoCache | Inh | x |  | x | x | x | x
CacheISAPI | Inh |  |  | x |  |  |
CGITimeout | Inh |  |  | x |  |  |
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
ConnectionTimeout | Inh | x |  | x |  |  |
ContentIndexed | Inh |  |  |  | x | x |
CreateCGIWithNewConsole | Inh | x |  | x | x | x | x
CreateProcessAsUser | Inh | x |  | x | x | x | x
CustomErrorDescriptions | NoAtt |  | x |  |  |  |
DefaultDoc | Inh | x |  | x | x | x |
DefaultDocFooter | Inh | x |  | x | x | x | x
DefaultLogonDomain | Inh | x |  | x | x | x | x
DirBrowseFlags | Inh | x |  | x | x | x |
DirBrowseShowDate | Inh* | x |  | x | x | x |
DirBrowseShowExtension | Inh* | x |  | x | x | x |
DirBrowseShowLongDate | Inh* | x |  | x | x | x |
DirBrowseShowSize | Inh* | x |  | x | x | x |
DirBrowseShowTime | Inh* | x |  | x | x | x |
DirectoryLevelsToScan | NoAtt | x |  |  |  |  |
DontLog | Inh | x |  | x | x | x | x
DownlevelAdminInstance | NoAtt | x |  |  |  |  |
EnableDefaultDoc | Inh* | x |  | x | x | x |
EnableDirBrowsing | Inh* | x |  | x | x | x |
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
EnableDocFooter | Inh | x |  | x | x | x | x
EnableReverseDns | Inh | x |  | x | x | x | x
FrontPageWeb | NoAtt |  |  | x |  |  |
HttpCustomHeaders | Inh | x |  | x | x | x | x
HttpErrors | Inh | x |  | x | x | x | x
HttpExpires | Inh | x |  | x | x | x | x
HttpPics | Inh | x |  | x | x | x | x
HttpRedirect | Inh | x |  | x | x | x | x
InProcessIsapiApps | NoAtt | x |  |  |  |  |
IPSecurity | Inh | x |  | x | x | x | x
KeyType | NoAtt | x | x | x | x | x | x
LogExtFileBytesRecv | Inh* | x |  | x |  |  |
LogExtFileBytesSent | Inh* | x |  | x |  |  |
LogExtFileClientIp | Inh* | x |  | x |  |  |
LogExtFileComputerName | Inh* | x |  | x |  |  |
LogExtFileCookie | Inh* | x |  | x |  |  |
LogExtFileDate | Inh* | x |  | x |  |  |
LogExtFileFlags | Inh | x |  | x |  |  |
LogExtFileHttpStatus | Inh* | x |  | x |  |  |
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
LogExtFileMethod | Inh* | x |  | x |  |  |
LogExtFileProtocolVersion | Inh* | x |  | x |  |  |
LogExtFileReferer | Inh* | x |  | x |  |  |
LogExtFileServerIp | Inh* | x |  | x |  |  |
LogExtFileServerPort | Inh* | x |  | x |  |  |
LogExtFileSiteName | Inh* | x |  | x |  |  |
LogExtFileTime | Inh* | x |  | x |  |  |
LogExtFileTimeTaken | Inh* | x |  | x |  |  |
LogExtFileUriQuery | Inh* | x |  | x |  |  |
LogExtFileUriStem | Inh* | x |  | x |  |  |
LogExtFileUserAgent | Inh* | x |  | x |  |  |
LogExtFileUserName | Inh* | x |  | x |  |  |
LogExtFileWin32Status | Inh* | x |  | x |  |  |
LogFileDirectory | Inh | x |  | x |  |  |
LogFilePeriod | Inh | x |  | x |  |  |
LogFileTruncateSize | Inh | x |  | x |  |  |
LogModuleList | Inh |  | x |  |  |  |
LogOdbcDataSource | Inh | x |  | x |  |  |
LogOdbcPassword | Inh | x |  | x |  |  |
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
LogOdbcTableName | Inh | x |  | x |  |  |
LogOdbcUserName | Inh | x |  | x |  |  |
LogonMethod | Inh | x |  | x | x | x | x
LogPluginClsId | Inh | x |  | x |  |  |
LogType | Inh | x |  | x |  |  |
MaxBandwidth | NoAtt |  |  | x |  |  |
MaxBandwidthBlocked | NoAtt |  |  | x |  |  |
MaxConnections | Inh | x |  | x |  |  |
MaxEndpointConnections | Inh | x |  | x |  |  |
MimeMap | Inh | x |  | x | x | x | x
NetLogonWorkstation | Inh | x |  | x |  |  |
NTAuthenticationProviders | Inh | x |  | x |  |  |
PasswordCacheTTL | Inh | x |  | x |  |  |
PasswordChangeFlags | Inh | x |  | x |  |  |
PasswordExpirePrenotifyDays | Inh | x |  | x |  |  |
Path | Inh |  |  |  | x |  |
PoolIDCTimeout | Inh | x |  | x | x | x | x
ProcessNTCRIfLoggedOn | Inh | x |  | x |  |  |
PutReadSize | Inh | x |  | x | x | x | x
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
Realm | Inh | x |  | x | x | x | x
RedirectHeaders | Inh | x |  | x | x | x | x
ScriptMaps | Inh | x |  | x | x | x | x
SecureBindings | Inh |  |  | x |  |  |
ServerAutoStart | Inh | x |  | x |  |  |
ServerBindings | Inh | x |  | x |  |  |
ServerComment | Inh | x |  | x |  |  |
ServerConfigAutoPWSync | NoAtt |  | x |  |  |  |
ServerConfigFlags | NoAtt |  | x |  |  |  |
ServerConfigSSL128 | NoAtt |  | x |  |  |  |
ServerConfigSSL40 | NoAtt |  | x |  |  |  |
ServerConfigSSLAllowEncrypt | NoAtt |  | x |  |  |  |
ServerListenBacklog | Inh | x |  | x |  |  |
ServerListenTimeout | Inh | x |  | x |  |  |
ServerSize | Inh | x |  | x |  |  |
ServerState | Inh |  |  | x |  |  |
SSIExecDisable | Inh | x |  | x | x | x | x
UNCAuthenticationPassthrough | Inh | x |  | x | x | x | x
UNCPassword | Inh |  |  |  | x |  |
Property | Inherit | Service | Info | Server | VirtualDir | Directory | File
UNCUserName | Inh |  |  |  | x |  |
UploadReadAheadSize | Inh | x |  | x | x | x | x
UseHostName | Inh | x |  | x |  |  |
WAMUserName | Inh | x |  |  |  |  |
WAMUserPass | Inh | x |  |  |  |  |


Miscellaneous Property Inheritance

This chart shows the properties associated with IIS Admin Objects other than those associated with FTP or Web services. For each property you can see the default setting of its inheritance attribute and the IIS Admin Objects you can use to access the value of the property in the metabase. The inheritance is indicated as:

Inh | Inherits
Inh | Contained in another inherited property
Inh* | Contains more than one property
NoAtt | Does not inherit

Property | Inherit | Computer | Filters | Filter | MimeMap | CertMapper | LogModules | LogModule
FilterDescription | NoAtt |  |  | x |  |  |  |
FilterEnabled | NoAtt |  |  | x |  |  |  |
FilterFlags | NoAtt |  |  | x |  |  |  |
FilterLoadOrder | NoAtt |  | x |  |  |  |  |
FilterPath | NoAtt |  |  | x |  |  |  |
FilterState | NoAtt |  |  | x |  |  |  |
KeyType | NoAtt | x | x | x | x | x | x | x
LogModuleId | NoAtt |  |  |  |  |  |  | x
LogModuleUiId | NoAtt |  |  |  |  |  |  | x
MaxBandwidth | NoAtt | x |  |  |  |  |  |
MaxBandwidthBlocked | NoAtt | x |  |  |  |  |  |
MimeMap | Inh | x |  |  | x |  |  |
NotifyAccessDenied | NoAtt |  |  | x |  |  |  |
NotifyAuthentication | NoAtt |  |  | x |  |  |  |
Property | Inherit | Computer | Filters | Filter | MimeMap | CertMapper | LogModules | LogModule
NotifyEndOfNetSession | NoAtt |  |  | x |  |  |  |
NotifyEndOfRequest | NoAtt |  |  | x |  |  |  |
NotifyLog | NoAtt |  |  | x |  |  |  |
NotifyNonSecurePort | NoAtt |  |  | x |  |  |  |
NotifyOrderHigh | NoAtt |  |  | x |  |  |  |
NotifyOrderLow | NoAtt |  |  | x |  |  |  |
NotifyOrderMedium | NoAtt |  |  | x |  |  |  |
NotifyPreProcHeaders | NoAtt |  |  | x |  |  |  |
NotifyReadRawData | NoAtt |  |  | x |  |  |  |
NotifySecurePort | NoAtt |  |  | x |  |  |  |
NotifySendRawData | NoAtt |  |  | x |  |  |  |
NotifySendResponse | NoAtt |  |  | x |  |  |  |
NotifyUrlMap | NoAtt |  |  | x |  |  |  |


IIS Admin Base Object

You can administer your Internet Information Server (IIS) installation by using the IIS Admin Base Object. The IIS Admin Base Object is a fully-distributable component object model (COM) object that implements the IMSAdminBase interface, with methods that enable your application to manipulate IIS configuration keys and data in the memory-resident metabase. Using the IIS Admin Base Object, your C++ application can administer the configuration of IIS and can also use the metabase to store custom application data.

The IIS Admin Objects provide most of the same functionality as the IIS Admin Base Object for Java, Microsoft® Visual Basic®, or Active Server Pages (ASP)-based applications. In addition, the IIS Admin Objects are a provider for Active Directory Services, with supplemental IIS-specific functionality.

For more information about the metabase and the identifiers used by IIS, see IIS Metabase and Metabase Identifier Reference in the Programmer's Reference, and the Registry and Metabase topics in the Administrator's Reference.

This section contains:

  • About the IIS Admin Base Object, which explains how this object manages your IIS configuration by manipulating data in the metabase, and discusses how you use keys, data entries, handles, inheritance, identifiers, and user types in your program.
  • Using the IIS Admin Base Object, which explains setting, retrieving, and enumerating metabase data, registering an event sink, and backing up and restoring the metabase.
  • IIS Admin Base Object Reference, which provides details of the interface structures, methods, and errors.


About the IIS Admin Base Object

You can use the IIS Admin Base Object to write applications, such as server administration or Web authoring tools, that check and update the server's configuration by manipulating keys and data in the metabase. You can also use the IIS Admin Base Object to store your IIS-related custom application configuration data in the fast-access metabase without filling up the system registry.

This section contains:

  • Keys and Data Entries, which describes how data is organized into hierarchical keys.
  • Handles to Keys, which discusses the use of handles to access keys.
  • Inheritance, which details a feature that minimizes data storage and increases the efficiency of your programs.
  • Reserved Identifiers and User Types, which explains how data is identified and categorized.

Remarks

You can find iadmw.h and other relevant header files in the \inetpub\iissamples\sdk\include directory.


Keys and Data Entries

You can use the IIS Admin Base Object to control the configuration of your IIS installation. IIS configuration data is stored in the metabase in a hierarchical structure that parallels the organization of the elements of your IIS installation. Configuration data is stored in keys that are associated with IIS elements, and the keys are organized in a path structure similar to the Windows NT® registry, or a directory and file system. Keys are identified by their path within the metabase. For example, the path /LM specifies the local machine key, and the path /LM/W3SVC/3 specifies the key for the third web server.

Each key name cannot be longer than the METADATA_MAX_NAME_LEN constant. This applies to each node name separately, not the entire path. In the preceding example, the names LM and W3SVC must each be less than METADATA_MAX_NAME_LEN, but their combined path (/LM/W3SVC) can be longer.

Data entries may be assigned to each key, and each data entry has a unique identifier in the metabase. For example, MD_SERVER_STATE is an identifier for data that specifies the server state, and, when located at the key having the path /LM/MSFTPSVC/1, specifies data that describes the server state of the first virtual FTP server on the local machine. For more information about identifiers, see Reserved Identifiers and User Types.

For each FTP or Web server, the root virtual directory is given the special name ROOT. For example, the path /LM/MSFTPSVC/1/ROOT/Scripts/Script1.asp refers to the key associated with an ASP page in the virtual directory Scripts under the first virtual FTP server on the local machine.


Handles to Keys

The IIS Admin Base Object uses handles to refer to keys in the metabase. When the metabase is initialized at startup, a handle (METADATA_MASTER_ROOT_HANDLE) is automatically opened with read-only permissions. You can use the OpenKey method to get a handle to a key in the metabase by providing the key's path relative to this handle, such as /LM/W3SVC/2, the path to the key for the second Web server. You can also use a handle to any key as a reference point to subordinate keys. For example, if you have opened a handle to /LM/W3SVC/2 as mentioned above, you can then use this handle and the relative path, /ROOT/VDir1, with the OpenKey method to get a handle to the key /LM/W3SVC/2/ROOT/VDir1.

The master handle, METADATA_MASTER_ROOT_HANDLE, does not protect metabase data from multiple-thread access, so data retrieved using this handle may change unexpectedly in the metabase. However, a handle that you open with the OpenKey method locks the metabase data for the key, all of its ancestor keys, and all of its subordinate keys. This insures consistency of metabase data by preventing other threads from changing data in a path containing a key for which you have an open handle.

A handle opened with read-only permission to a key permits other clients to open read-only handles to that key and other keys in its path, both superior and subordinate to it. No client can open a handle with write permission to a key until all handles, read or write, have been closed by all clients to all keys in the path. In addition, once one client has opened a handle with write permission to a key, no other client can open a handle for either reading or writing to that key or to any key above it in its path, or subordinate to it. Because server performance can significantly be reduced while waiting for keys to be available for read-only handles, it is recommended that you call the CloseKey method as soon as you have finished writing data. This frees the handle and releases the key and all keys above and below it to other processes and clients.


Inheritance

You can specify data in the metabase to be inheritable. This means that if you add a data entry to a key and specify it as inheritable, all of the keys subordinate to that key can access that data. This is much more efficient than setting the same data for each key in the metabase. For example, if you add the inheritable data MD_MYDATA for the key /LM, the subkeys /LM/W3SVC and /LM/MSFTPSVC, and others below them can also return MD_MYDATA. Inheritance stops at a subordinate key where the same metabase identifier is set. Inheritance can not skip keys—keys inherit data from the nearest superior key where the identifier is set.

You can specify that an entry is inheritable by setting the METADATA_INHERIT flag in the dwMDAttributes member of the METADATA_RECORD structure that is passed to the SetData method.

When retrieving data, you can specify that inherited data be returned by setting the METADATA_INHERIT flag in the dwMDAttributes member of the METADATA_RECORD structure that is passed to the GetData or EnumData method. For the GetAllData method, you specify this flag in the dwMDAttributes parameter. If this flag is not set, inherited data is not returned.

You can use the METADATA_PARTIAL_PATH flag to specify that inherited data be returned, even if a requested path does not exist. If you add the same inheritable data at the key /LM as in the preceding example, the subkey /LM/MYSVC would return the inheritable data, MD_MYDATA, regardless of whether the key /LM/MYSVC exists in the metabase. The METADATA_PARTIAL_PATH flag only applies if the METADATA_INHERIT flag is also set.

You can use the METADATA_PARTIAL_PATH flag to minimize the number of keys you create in the metabase. For example, when files in a directory have no metabase data of their own, you can specify data as inheritable at the directory key and use the METADATA_PARTIAL_PATH flag to return inherited data for individual files without having to create keys for them.

You can use the METADATA_ISINHERITED flag to determine if retrieved data is local or inherited. If specified on a call to any method that retrieves data, the method will return this flag for those data elements for which the returned data is inherited.


Reserved Identifiers and User Types

Each data entry in the metabase is assigned a unique identifier. An identifier is a DWORD containing a number that uniquely identifies the data in the metabase. Identifiers used by IIS are assigned from a pool of reserved numbers. The first 32K is reserved by the system for IIS data and the second 32K is reserved for Microsoft® FrontPage™ data. If you create identifiers in the metabase, use identifier numbers greater than 65535 (0x0000ffff) to avoid conflicts with current or future system data.

Each identifier is also assigned a user type, which is a DWORD that specifies how the data is used. Current IIS user types include IIS_MD_UT_SERVER for server configuration parameters, IIS_MD_UT_FILE for file and directory properties, IIS_MD_UT_WAM for web application management, and ASP_MD_UT_APP for ASP application configuration. User types enable you to classify your identifiers by application. You must assign a user type to each identifier you create in the metabase, although each identifier is not required to have a unique user type. The numbers from 0 to 2,000 are reserved for current and future system user types. User types you create must be above 2,000 to avoid conflicts with current and future system user types.

You can use the user type to filter data requested from a key. For example, the GetAllData method has a parameter, dwUserType, you can use to specify that only data of a certain user type is to be returned. For example, if this parameter is set to IIS_MD_UT_SERVER during the method call, only data related to the server will be returned.

Note Metabase identifiers must be unique, but multiple identifiers can have the same user type and data type.


Using the IIS Admin Base Object

When IIS starts, it loads the metabase into memory, where it is available until IIS shuts down. The IIS Admin Base Object enables you to manage data in the metabase through the structures and methods of the IMSAdminBase interface.

You use handles to access keys in the metabase as described in Handles to Keys. The METADATA_MASTER_ROOT_HANDLE is provided by IIS and connects to the root key of the metabase. You use this handle with the OpenKey method to open handles to specific keys, and to specify read or write permissions you need for the key. You can also use an existing open handle from an OpenKey call to open additional handles to other keys.

Once you have a handle to a key, you can use the IIS Admin Base Object methods to manipulate that key's data entries. You can also access subkeys of the currently open key by specifying additional path information.

With a valid handle, you can use the GetData method to retrieve a data entry, or the SetData method to add an entry to the metabase. The GetAllData method enables your application to retrieve all or a subset of the values associated with a key with a single method call. The EnumData method enables your application to enumerate all or a subset of the values associated with a key. When a data entry is no longer needed, you can remove it from the metabase by calling the DeleteData method.

In addition to manipulating data entries, you can add, delete, or move keys from one path to another in the metabase. Use the AddKey method to add keys and the DeleteKey method to delete keys in the metabase. Use the CopyKey method to copy or move a key and all of its subkeys and data items.

Your program can also incorporate event sinks for notification when metabase data is changed by other processes, and when IIS shuts down.

This section contains:

  • Setting and Retrieving Data
  • Enumerating Keys and Data
  • Registering an Event Sink


Setting and Retrieving Data

You can set data in the metabase by calling the SetData method. This method takes as one of its parameters a METADATA_RECORD structure. This structure contains information about the data, such as its identifier, attributes, user type, data type, a pointer to the data, and so on. By setting values for the members of the METADATA_RECORD structure when it is passed as an input parameter to the SetData method, you can specify the data's type and storage method. For example, you can specify that the data be stored in a secure manner by setting the METADATA_SECURE flag in the structure's dwMDAttributes member.

In addition to specifying the data to be retrieved, the METADATA_RECORD structure is also used to receive data from the metabase. When you call the GetData or EnumData methods, you pass in a pointer to a METADATA_RECORD structure to specify the data to be retrieved, and to receive the data. Your program must allocate the buffer into which the data will be retrieved, and pass a pointer to it in the pbMDData member of the METADATA_RECORD structure.

The GetAllData method retrieves multiple data entries from a key. In this case, you use parameters of the GetAllData method to specify the data to be retrieved, and provide a buffer where the method returns an array of METADATA_GETALL_RECORD structures.


Enumerating Keys and Data

You can use the EnumKeys method to enumerate the subkeys of a key. The name of one subkey is returned per each enumeration call. ERROR_NO_MORE_ITEMS is returned after the last subkey has been enumerated. To get a total count of the subkeys associated with a key, you can increment the index parameter of the method. See Enumerating Subkeys for details and example code that enumerates keys.

Similarly, you can use the EnumData method to enumerate the data elements of a key. One data item is enumerated per call, but unlike enumerating keys, the EnumData method returns the data as well as the data identifier. ERROR_NO_MORE_ITEMS is returned after the last data item has been enumerated. To get a total count of the data items associated with a key, you must increment the index parameter of the method. See Enumerating Data Items for details and example code that enumerates data items.

Enumerating Subkeys

The following example uses the EnumKeys method to enumerate the number of virtual Web servers defined on the local machine. This example also uses the Active Template Library to demonstrate smart pointers. Smart pointers perform the normal COM QueryInterface, AddRef and Release calls automatically.

#define UNICODE
#define INITGUID
#include "iadmw.h"    // COM Interface header
#include "iiscnfg.h"  // MD_ & IIS_MD_ #defines
#include "atlBase.h"  // ATL support
HRESULT hRes = 0;
DWORD indx = 0;
METADATA_HANDLE MyHandle;
WCHAR SubKeyName[METADATA_MAX_NAME_LEN];
CComPtr <IMSAdminBase> pIMeta;

hRes = CoCreateInstance(CLSID_MSAdminBase, NULL, CLSCTX_ALL,
IID_IMSAdminBase, (void **) &pIMeta);

if (FAILED(hRes))
    return;

//get a handle to the local machine
hRes = pIMeta->OpenKey(METADATA_MASTER_ROOT_HANDLE, TEXT("/LM"), METADATA_PERMISSION_READ, 20, &MyHandle);

//loop until there are no more subkeys
while (SUCCEEDED(hRes)){

    //enumerate the subkeys of the World Wide Web service
    hRes = pIMeta->EnumKeys(MyHandle, TEXT("/W3SVC"), SubKeyName, indx);

    if (SUCCEEDED(hRes)) {
    //store the virtual server names in an array for future use
    //Note: declare a suitable array of names and add
    // array bound checking
    wcscpy (names[indx],SubKeyName);
    }

    //increment the index
    indx++;
}

//release the handle
pIMeta->CloseKey(MyHandle);

Enumerating Data Items

The EnumData method returns the entire data entry, so you must pass in a METADATA_RECORD structure to receive the data. The values that are set for the METADATA_RECORD members when that structure is passed into the EnumData method specify which data items are to be enumerated.

The following example enumerates all of the server-related data entries of the first virtual Web server, including any inherited data. This is an example only, and does not include all appropriate error handling.

#define UNICODE
#define INITGUID
#include "iadmw.h"    // COM Interface header
#include "iiscnfg.h"  // MD_ & IIS_MD_ #defines
#include "atlBase.h"  // ATL support
HRESULT hRes = 0;
DWORD indx = 0;
METADATA_HANDLE MyHandle;
METADATA_RECORD MyRecord;
DWORD dwBufLen = ORIGINAL_BUFFER_SIZE;
DWORD dwReqBufLen = 0;
PBYTE pbBuffer = new BYTE[dwBufLen];
CComPtr <IMSAdminBase> pIMeta;

hRes = CoCreateInstance(CLSID_MSAdminBase, NULL, CLSCTX_ALL,
IID_IMSAdminBase, (void **) &pIMeta);

if (FAILED(hRes))
    return;

//get a handle to the Web service
hRes = pIMeta->OpenKey(METADATA_MASTER_ROOT_HANDLE, TEXT("/LM/W3SVC"), METADATA_PERMISSION_READ, 20, &MyHandle);
if (SUCCEEDED(hRes)) {
//loop until there are no more data items
while (SUCCEEDED(hRes)){

    //initialize the input structure,
    //the values specify what kind of data to enumerate
    MyRecord.dwMDAttributes = METADATA_INHERIT;
    MyRecord.dwMDUserType = IIS_MD_UT_SERVER;
    MyRecord.dwMDDataType = ALL_METADATA;
    MyRecord.dwMDDataLen = dwBufLen;
    MyRecord.pbMDData = pbBuffer;

    //enumerate the data of the first virtual Web server
    //checking to ensure that the data returned does not
    //overflow the buffer

    hRes = pIMeta->EnumData(MyHandle, TEXT("/1"), &MyRecord, indx, &dwReqBufLen);
    if (hres == RETURNCODETOHRESULT(ERROR_INSUFFICIENT_BUFFER)) {
        delete [] (pbBuffer);
        pbBuffer = new BYTE[dwReqBufLen];
        dwBufLen = dwReqBufLen;
        MyRecord->dwMDDataLen = dwReqBufLen;
        MyRecord->pbMDData = pbBuffer;
        hRes = pIMeta->EnumData(MyHandle, TEXT("/1"), &MyRecord, indx, &dwReqBufLen);

    }
    if (SUCCEEDED(hRes)) {
        //store the data identifiers in an array for future use
        //Note: declare a suitable DWORD array for names and add
        // array bound checking
        data[indx] = MyRecord->dwMDIdentifier;
        // Additional code needed to store other data fields.
    }

    //increment the index
    indx++;
} // end while

//release the handle and buffer
pIMeta->CloseKey(MyHandle);
} // end if pIMeta->OpenKey Succeeded
delete pbBuffer;


Registering an Event Sink

You may design your application to be notified when certain events occur. To receive event notifications, your application must implement a COM sink of a class descended from the IMSAdminBaseSink interface. You may implement a sink for the following events.

  • The metabase shuts down.
  • A key or its associated data changes.

Shutdown Notify Sink

This sink method will be called when IISADMIN stops. The metabase will be open during this call, however, there is no guarantee that handles will not be open that prevent you from reading from or writing to portions of the metabase. In addition, your sink must not release its interface during this call. The recommended implementation is, when notified, set a flag and return, then release the interface. The metabase will wait for five seconds or until all interfaces have been released before actually shutting down.

Your callback method must implement the following prototype as a minimum:

HRESULT STDMETHODCALLTYPE ShutdownNotify( void)
{
  return HRESULT_FROM_WIN32(ERROR_NOT_SUPPORTED);
}

Change Notify Sink

If your application needs to be notified whenever a key or its associated data changes, it must implement the SinkNotify method. This method will receive a notification whenever one of the following events occurs.

  • A key that has been changed is closed by the CloseKey method.
  • Permissions on a handle to a key are changed from write or read/write to read-only by the ChangePermissions method.

The SinkNotify method is not called if the handle is closed by the instance of the IMSMetadata interface that registered the sink. In other words, a client only receives notifications of changes made by other clients.

Note Do not open any write handles within your SinkNotify processing or recursive notifications between clients may cause a system lockup. You may open read handles to the metabase within your SinkNotify method.

Your callback method must implement the following prototype as a minimum:

HRESULT SinkNotify(
DWORD dwMDNumElements
MD_CHANGE_OBJECT pcoChangeList[]
);

The parameter dwMDNumElements receives the number of elements that have changed. The maximum number of change entries that are sent on a single call to the callback method is specified by the constant MD_MAX_CHANGE_ENTRIES. If more notifications are required, the method is called multiple times.

Remarks

IIS does not make secure calls to remote machines. If your program implements a sink and is executing on a machine other than the machine on which IIS is running, you must remove security by calling the COM CoInitializeSecurity function with the dwImpLevel parameter set to RPC_C_AUTHN_LEVEL_NONE, as shown in this example:

hRes = CoInitializeSecurity(NULL,
            -1,
            NULL,
            NULL,
            RPC_C_AUTHN_LEVEL_NONE,
            0,
            NULL,
            EOAC_NONE,
            0)

For more information on this function, see the Reference topic in COM and ActiveX Object Services in the Platform SDK, which is also available in the MSDN Library.


IIS Admin Base Object Reference

The following topics specify the structures, methods, and errors of the IIS Admin Base Object:

  • IMSAdminBase Structures
  • IMSAdminBase Methods
  • IMSAdminBase Errors


IMSAdminBase Structures

The following structures are used by the IIS Admin Base Object methods.

MD_CHANGE_OBJECT | Stores information about changes made to a key in the metabase.
METADATA_GETALL_RECORD | Member of an array that receives multiple metabase entries.
METADATA_HANDLE_INFO | Stores information about a handle to the metabase.
METADATA_RECORD | Specifies or receives a single metabase data entry.


MD_CHANGE_OBJECT

The MD_CHANGE_OBJECT structure receives information about the changes made to a key in the metabase. It is used in the SinkNotify method of a change notify sink.

#define MD_CHANGE_OBJECT     MD_CHANGE_OBJECT_W
#define PMD_CHANGE_OBJECT    PMD_CHANGE_OBJECT_W
typedef struct  _MD_CHANGE_OBJECT_W
    {
    /* [string] */ LPWSTR pszMDPath;
    DWORD dwMDChangeType;
    DWORD dwMDNumDataIDs;
    /* [size_is][unique] */ DWORD __RPC_FAR *pdwMDDataIDs;
    }   MD_CHANGE_OBJECT_W;

typedef struct _MD_CHANGE_OBJECT_W __RPC_FAR *PMD_CHANGE_OBJECT_W;

Members

pszMDPath
The path to the modified key.
dwMDChangeType
A DWORD that lists the type of changes made. This member can contain one or more of the following flags:
Flag | Description
MD_CHANGE_TYPE_ADD_OBJECT | The key was added to the metabase.
MD_CHANGE_TYPE_DELETE_DATA | A data entry was deleted from the key.
MD_CHANGE_TYPE_DELETE_OBJECT | The key was deleted from the metabase.
MD_CHANGE_TYPE_RENAME_OBJECT | The key was renamed.
MD_CHANGE_TYPE_SET_DATA | A data entry was added to or set for the key.

dwMDNumDataIDs
The number of data entries that were changed.
pdwMDDataIDs
A pointer to an array containing the identifiers of the data entries that were changed. The array is dwMDNumDataIDs in length.


METADATA_RECORD

The METADATA_RECORD structure contains information about a metabase entry. It is used as an input parameter by the SetData method and as an input/output parameter by methods that retrieve data from the metabase, such as GetData, EnumData, or GetAllData.

typedef struct  _METADATA_RECORD {
    DWORD dwMDIdentifier;
    DWORD dwMDAttributes;
    DWORD dwMDUserType;
    DWORD dwMDDataType;
    DWORD dwMDDataLen;
    unsigned char *pbMDData;
    DWORD dwMDDataTag;
}  METADATA_RECORD;

Members

dwMDIdentifier
A DWORD that uniquely identifies the metabase entry, for example, MD_SERVER_STATE.
dwMDAttributes
Flags that specify how to set or get data from the metabase. This member can be set to one or more of the following values:
Flag Description
METADATA_INHERIT Set: The data can be inherited.

Get: Return inheritable data.
METADATA_INSERT_PATH For a string data item:

Set: Indicates the string contains MD_INSERT_PATH_STRINGW.

Get: Replace MD_INSERT_PATH_STRINGW with the path of the data item relative to the handle
METADATA_ISINHERITED Set: Not valid.

Get: Mark data items that were inherited.
METADATA_NO_ATTRIBUTES Set: The data does not have any attributes.

Get: Not applicable. Data is returned regardless of this flag setting.
METADATA_PARTIAL_PATH Set: Not valid.

Get: Return ERROR_SUCCESS and any inherited data even if the entire path is not present. This flag is only valid if METADATA_INHERIT is also set.

METADATA_REFERENCE Set: The data was retrieved by reference.

Get: Not valid
METADATA_SECURE Set: Store and transport the data in a secure fashion.

Get: Not valid.
METADATA_VOLATILE Set: Do not save the data in long term storage.

Get: Not valid.

dwMDUserType
A DWORD that specifies the user type of the data. When you use the SetData method to create a new data item, specify a user type above 2,000. User types 2,000 and below are reserved. When retrieving or updating data, this specifies the user type assigned to the data item.

IIS currently uses these user types:
User type | Description
ASP_MD_UT_APP | The entry contains information specific to ASP application configuration.
IIS_MD_UT_FILE | The entry contains information about a file, such as access permissions, or log on methods.
IIS_MD_UT_SERVER | The entry contains information specific to the server, such as ports in use and IP addresses.
IIS_MD_UT_WAM | The entry contains information specific to web application management.

dwMDDataType
Identifies the type of data in the metabase entry. This parameter can be one of the following values:
Data type | Description
ALL_METADATA Set: Not valid

Get: Return data regardless of type.
BINARY_METADATA | Binary data in any form.
DWORD_METADATA | An unsigned 32-bit number.
EXPANDSZ_METADATA | A null-terminated string that contains unexpanded environment variables, such as %PATH%. The environment variables are not expanded by the IIS Admin Base Object.
MULTISZ_METADATA | An array of null-terminated strings, terminated by two null characters.
STRING_METADATA | A null-terminated string.

dwMDDataLen
A DWORD that specifies the length of the data in bytes. If the data is a string, this value includes the ending null character. For multisz data, this includes an additional null character after the final string. For example, the length of a multisz string containing two strings would be (wcslen(stringA) + 1) * sizeof(WCHAR) + (wcslen(stringB) + 1) * sizeof(WCHAR) + 1 * sizeof(WCHAR)

In-process clients need to specify dwMDDataLen only when setting binary and multisz values in the metabase. Remote applications must specify dwMDDataLen for all data types.

pbMDData
When setting a value in the metabase, points to a buffer that contains the data. When retrieving data from the metabase, points to a buffer to receive the data.
dwMDDataTag
Reserved.


METADATA_GETALL_RECORD

The METADATA_GETALL_RECORD structure is analogous to the METADATA_RECORD structure, but is only used to return data from a call to the GetAllData method. Data retrieval specifications are provided in GetAllData method parameters, not in this structure (as is the case with METADATA_RECORD). The GetAllData method returns the data from multiple entries as an array of METADATA_GETALL_RECORD structures.

typedef struct  _METADATA_GETALL_RECORD {
    DWORD dwMDIdentifier;
    DWORD dwMDAttributes;
    DWORD dwMDUserType;
    DWORD dwMDDataType;
    DWORD dwMDDataLen;
    union
        {
        DWORD dwMDDataOffset;
        unsigned char *pbMDData;
        };
    DWORD dwMDDataTag;
}  METADATA_GETALL_RECORD;

Members

dwMDIdentifier
A DWORD that identifies the metabase entry. For example, MD_SERVER_STATE.
dwMDAttributes
A set of flags that receives the attributes of the data entry. This member can receive one or more of the following values:
Flag | Description
METADATA_INHERIT | Return inherited data.
METADATA_INSERT_PATH | Indicates the string contains MD_INSERT_PATH_STRINGW.
METADATA_ISINHERITED | Returned data is inherited.
METADATA_NO_ATTRIBUTES | No attributes set.
METADATA_PARTIAL_PATH | Inherited data returned even if the entire path is not present. This flag is only valid if METADATA_INHERIT is also set.
METADATA_REFERENCE | The data was retrieved by reference.
METADATA_SECURE | Not Valid.
METADATA_VOLATILE | Not Valid.

dwMDUserType
A DWORD that specifies the type of user of the data. IIS currently defines the following two types of users:
User type | Description
ASP_MD_UT_APP | The entry contains information specific to ASP application configuration.
IIS_MD_UT_FILE | The entry contains information about a file, such as access permissions, or log on methods.
IIS_MD_UT_SERVER | The entry contains information specific to the server, such as ports in use and IP addresses.
IIS_MD_UT_WAM | The entry contains information specific to Web application management.

dwMDDataType
Specifies the type of data in the metabase entry. This member can be one of the following values:
Data type | Description
ALL_METADATA | All data returns, regardless of type. Not valid when setting values.
BINARY_METADATA | Binary data in any form.
DWORD_METADATA | An unsigned 32-bit number.
EXPANDSZ_METADATA | A null-terminated unicode string that contains unexpanded environment variables, such as %PATH%.
MULTISZ_METADATA | An array of null-terminated strings, terminated by two null characters.
STRING_METADATA | A null-terminated unicode string

dwMDDataLen
A DWORD that receives the length of the data in bytes. If the data is a string, this value includes the ending null character. For multisz data, this includes an additional null character after the final string. For example, the length of a multisz string containing two strings would be (wcslen(stringA) + 1) * sizeof(WCHAR) + (wcslen(stringB) + 1) * sizeof(WCHAR) + 1 * sizeof(WCHAR)
dwMDDataOffset
If the data was returned by value, contains the byte offset of the data in the buffer specified by the parameter pbMDBuffer of the IMSAdminBase::GetAllData method. All out-of-process executions will return data by value. The array of records, excluding the data, is returned in the first part of the buffer. The data associated with the records is returned in the buffer after the array of records, and dwMDDataOffset is the offset to the beginning of the data associated with each record in the array.
pbMDData
Reserved. Do not use.
dwMDDataTag
Reserved. Do not use.

See Also

METADATA_RECORD


METADATA_HANDLE_INFO

The METADATA_HANDLE_INFO structure contains information about a handle to a metabase entry.

typedef struct _METADATA_HANDLE_INFO {
    DWORD dwMDPermissions;
    DWORD dwMDSystemChangeNumber;
} METADATA_HANDLE_INFO;

Members

dwMDPermissions
Specifies the permissions with which the handle was opened. This member can have one or more of the following flags set:
Value | Description
METADATA_PERMISSION_READ | The handle can read keys and data.
METADATA_PERMISSION_WRITE | The handle can write keys and data.

dwMDSystemChangeNumber
Specifies the system change number when the handle was opened. This is a number that tracks how many changes were made to data since the metabase was created. This value is saved to disk between metabase sessions.


IMSAdminBase Methods

The IMSAdminBase COM interface of the IIS Admin Base Object exposes the following methods:

Method | Description
IMSAdminBase::AddKey | Adds a key to the metabase.
IMSAdminBase::Backup | Backs up the metabase to a backup file.
IMSAdminBase::ChangePermissions | Changes read/write permissions on a handle to a key.
IMSAdminBase::CloseKey | Closes a key.
IMSAdminBase::CopyData | Copies or moves data between keys.
IMSAdminBase::CopyKey | Copies or moves a key in the metabase.
IMSAdminBase::DeleteAllData | Deletes all or a subset of the data associated with a key.
IMSAdminBase::DeleteBackup | Deletes a metabase backup from a backup file.
IMSAdminBase::DeleteChildKeys | Deletes all subkeys of a key.
IMSAdminBase::DeleteData | Deletes a data entry.
IMSAdminBase::DeleteKey | Deletes a key from the metabase.
IMSAdminBase::EnumBackups | Enumerates the metabase backups in a backup file.
IMSAdminBase::EnumData | Enumerates the data associated with a key, one entry per call.
IMSAdminBase::EnumKeys | Enumerates the subkeys of a key, one subkey per call.
IMSAdminBase::GetAllData | Retrieves all or a subset of the data associated with a key.
IMSAdminBase::GetData | Retrieves a data entry.
IMSAdminBase::GetDataPaths | Retrieves all paths of a subtree where a specified identifier exists.
IMSAdminBase::GetDataSetNumber | Retrieves the data set number associated with a key.
IMSAdminBase::GetHandleInfo | Retrieves information about a handle.
IMSAdminBase::GetLastChangeTime | Retrieves the last change time for a key.
IMSAdminBase::GetSystemChangeNumber | Retrieves the system change number.
IMSAdminBase::OpenKey | Opens a key.
IMSAdminBase::RenameKey | Renames an existing key.
IMSAdminBase::Restore | Restores the metabase from a backup file.
IMSAdminBase::SaveData | Saves metabase changes to disk.
IMSAdminBase::SetData | Sets a data entry.
IMSAdminBase::SetLastChangeTime | Sets the last change time for a key.


IMSAdminBase::AddKey

The IMSAdminBase::AddKey method creates a key and adds it to the metabase as a subkey of the key at the specified path.

HRESULT AddKey(
  METADATA_HANDLE hMDHandle, //metabase handle
  LPCWSTR pszMDPath          //path to the key, relative to hMDHandle
);

Parameters

hMDHandle
Specifies a handle with write permissions as returned by the IMSAdminBase::OpenKey method. The value METADATA_MASTER_ROOT_HANDLE is not valid for this operation.
pszMDPath
Points to a string that contains the new key's path, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.

This parameter cannot be NULL.

Return Values

Returns an HRESULT that contains one of the following values:

Value | Description
ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_DUP_NAME | A key of that name already exists in the metabase.
ERROR_INVALID_NAME | The specified name is invalid.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_NOT_ENOUGH_MEMORY | Not enough storage is available to process this command.
ERROR_PATH_NOT_FOUND | The specified path is not found in the metabase.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::Backup

The IMSAdminBase::Backup method backs up the metabase to a backup location you specify by providing a backup location name of up to 100 characters in length. Multiple metabase backups can be stored in a backup location.

Note IIS determines the backup storage mechanism, so the backup location name you provide does not necessarily translate to a particular directory, file, or database storage mechanism. As implemented in this release, metabase backups are stored as files in the SYSTEM32\INETSRV\METABACK directory. This mechanism may change in future releases.

HRESULT Backup(
  LPCWSTR pszMDBackupLocation,
  dwMDVersion,
  dwMDFlags
);

Parameters

pszMDBackupLocation
A string of up to MD_BACKUP_MAX_LEN unicode characters that identifies the backup location. The storage mechanism will be determined by IIS. If an empty string is specified, the default backup location will be used.
dwMDVersion
Specifies the version number to be assigned to the backup. Must be less than or equal to MD_BACKUP_MAX_VERSION. Can be set to one of the following values:
MD_BACKUP_HIGHEST_VERSION | Overwrite the highest existing backup version in the specified backup location.
MD_BACKUP_NEXT_VERSION | Use the next backup version number available in the specified backup location.

dwMDFlags
One or more of the following flags:
MD_BACKUP_FORCE_BACKUP | Force the backup even if the SaveData operation specified by MD_BACKUP_SAVE_FIRST fails.
MD_BACKUP_OVERWRITE | Back up even if a backup of the same name and version exists in the specified backup location, overwriting it if necessary.
MD_BACKUP_SAVE_FIRST | Perform a SaveData operation before the backup.

Return Values

Returns an HRESULT that contains one of the values listed in the table below. Other errors may also be returned that are passed through from the file system, or from a crypto api when secure metabase data is being saved.

Value | Description
E_INVALIDARG | An argument was invalid
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory to perform the operation
ERROR_SUCCESS | The method succeeded.
MD_WARNING_SAVE_FAILED | This is a warning, not an error.


IMSAdminBase::ChangePermissions

The IMSAdminBase;:ChangePermissions method changes permissions on an open handle. If the handle was opened with write permission and you change it to read only, this method will cause any callback methods registered to be called.

HRESULT ChangePermissions(
  METADATA_HANDLE hMDHandle,  //metabase handle
  DWORD dwMDTimeOut,          //time, in milliseconds, for the
                              // method to wait before failing
  DWORD dwMDAccessRequested   //specifies the new permissions for
                              // the handle
);

Parameters

hMDHandle
Specifies a handle to the metabase, as returned by the IMSAdminBase::OpenKey method.
dwMDTimeOut
Specifies the time, in milliseconds, for the method to wait for the operation to succeed.
dwMDAccessRequested
Specifies the new permissions for the handle. It must be at least one of the following values:
Value | Description
METADATA_PERMISSION_READ | Open the key for reading.
METADATA_PERMISSION_WRITE | Open the key for writing.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_INVALID_HANDLE | The metabase handle is invalid.
ERROR_PATH_BUSY | The path specified cannot be used at this time.
ERROR_SUCCESS | The method succeeded

Remarks

When you use this method to add permissions, success or failure follows the same rules as apply in IMSAdminBase::OpenKey. Timeout values should be short for this call; it is quite possible for two threads with read permission on the same data to attempt to update to write permission at the same time. Both will block until one read handle is closed.


IMSAdminBase::CloseKey

The IMSAdminBase::CloseKey method closes a handle to a key. If the handle was opened with write permission and changes have been made, this will cause any callback methods registered to be called.

HRESULT CloseKey(
  METADATA_HANDLE hMDHandle  //metabase handle to close
);

Parameters

hMDHandle
Specifies the handle to close, as returned by the IMSAdminBase::OpenKey method.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_INVALID_HANDLE | The handle is not valid.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::CopyData

The IMSAdminBase::CopyData method copies or moves data associated with the source key to the destination key. You can also specify whether the method copies the key's inherited data.

HRESULT CopyData(
  METADATA_HANDLE hMDSourceHandle,  //source metabase handle
  LPCWSTR pszMDSourcePath,          //path to the source key,
                                    // relative to hMDSourceHandle
  METADATA_HANDLE hMDDestHandle,    //destination metabase handle
  LPCWSTR pszMDDestPath,            //path to the source key,
                                    // relative to hMDDestHandle
  DWORD dwMDAttributes,             //attributes of the data
  DWORD dwMDUserType,               //user type of the data
  DWORD dwMDDataType,               //data type of the data
  BOOL bMDCopyFlag                  //flag that specifies whether to
                                    // copy or move the data
);

Parameters

hMDSourceHandle
Specifies METADATA_MASTER_ROOT_HANDLE, or a handle with read permission returned by the IMSAdminBase::OpenKey method.
pszMDSourcePath
Points to a string that contains the path of the key with which the source data is associated, relative to the path of hMDSourceHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
hMDDestHandle
Specifies a handle, returned by IMSAdminBase::OpenKey, that has write permission. METADATA_MASTER_ROOT_HANDLE is not a valid value for this parameter.
pszMDDestPath
Points to the path of the key for data to be copied to, relative to the path of hMDDestHandle.
dwMDAttributes
The flags, contained in the METADATA_RECORD structure, used to get the data.
dwMDUserType
A DWORD that specifies the user type of the data. If not set to ALL_METADATA, only metadata of the specified user type will be copied or moved. The following user types are defined for IIS:
User type | Description
ALL_METADATA | Copy or move all data, regardless of user type.
ASP_MD_UT_APP | The entry contains information specific to ASP application configuration.
IIS_MD_UT_FILE | Copy or move only data specific to a file, such as access permissions or log on methods.
IIS_MD_UT_SERVER | Copy or move only data specific to the server, such as ports in use and IP addresses.
IIS_MD_UT_WAM | The entry contains information specific to Web application management.

dwMDDataType
A DWORD that specifies the type of data to retrieve. If dwMDDataType is not set to ALL_METADATA, only metadata of the specified type will be copied or moved. This parameter can be one of the following values:
Data type | Description
ALL_METADATA | Copy or move all data, regardless of type.
BINARY_METADATA | Binary data in any form.
DWORD_METADATA | An unsigned 32-bit number.
EXPANDSZ_METADATA | A null-terminated string that contains unexpanded environment variables, such as %PATH%.
MULTISZ_METADATA | An array of null-terminated strings, terminated by two null characters.
STRING_METADATA | A null-terminated ASCII string.

bMDCopyFlag
A Boolean that specifies whether to copy or move the data. If this parameter is set to TRUE, the data is copied. If it is FALSE, the data is moved. If dwMDAttributes contains the flag METADATA_INHERIT, this parameter must be set to TRUE.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete the operation.
ERROR_PATH_NOT_FOUND | The specified path is not found.
ERROR_SUCCESS | The method succeeded.

Remarks

If inherited data is copied, (if dwMDAttributes specifys the METADATA_INHERIT flag) it is copied to the destination key, not to the corresponding ancestor keys.

The handle, METADATA_MASTER_ROOT_HANDLE, provides no guarantee against multiple thread access. If your application requires a constant data state, use a handle returned by IMSAdminBase::OpenKey.


IMSAdminBase::CopyKey

The IMSAdminBase::CopyKey method copies or moves a key, including its subkeys and data, to a specified destination. The copied or moved key becomes a subkey of the destination key.

HRESULT CopyKey(
  METADATA_HANDLE hMDSourceHandle, //metabase handle to the source key
  LPCWSTR pszMDSourcePath,         //path of the source, relative to
                                   // hMDSourceHandle
  METADATA_HANDLE hMDDestHandle,   //metabase handle to the destination
  LPCWSTR pszMDDestPath,           //path of the destination, relative to
                                   // hMDDestHandle
  BOOL bMDOverwriteFlag,           //whether to overwrite or merge data with
                                   // an existing version of the key
  BOOL bMDCopyFlag                 //whether to copy or move the key
);

Parameters

hMDSourceHandle
Specifies the handle of the key to be copied or moved. If the key is to be copied (bMDCopyFlag is set to TRUE) hMDSourceHandle must have read permissions. If the key is to be moved (bMDCopyFlag is set to FALSE), hMDSourceHandle must have read/write permissions.
pszMDSourcePath
Points to a string that contains the path of the key to be copied or moved relative to the path of hMDSourceHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
hMDDestHandle
Specifies a handle with write permissions that specifies the destination of the moved or copied key.
pszMDDestPath
Points to a string that contains the path of the new or moved key, relative to hMDDestHandle.
bMDOverwriteFlag
Determines the behavior if the destination key already exists. If set to TRUE, the existing key and all of its data and descendants are deleted prior to copying or moving the source. If FALSE, the existing key, data, and descendants remain, and the source is merged with that data. In cases of data conflicts, the source data overwrites the destination data.
bMDCopyFlag
Specifies whether to copy or move the specified key. If bMDCopyFlag is TRUE, the key is copied. If it is FALSE, the key is moved, and the source key is deleted from its original location.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_DUP_NAME | A key of that name already exists in the metabase.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_NOT_ENOUGH_MEMORY | Not enough memory is available to process this command.
ERROR_PATH_NOT_FOUND | The specified path was not found in the metabase.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::DeleteAllData

The IMSAdminBase::DeleteAllData method deletes all or a subset of local data associated with a particular key.

HRESULT DeleteAllData(
  METADATA_HANDLE hMDHandle,  //metabase handle
  LPCWSTR pszMDPath,          //path to the key, relative to hMDHandle
  DWORD dwMDUserType,         //user type of the data
  DWORD dwMDDataType          //data type of the data
);

Parameters

hMDHandle
Specifies a handle to the metabase.
pszMDPath
Specifies the path of the key with which the data to be deleted is associated, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
dwMDUserType
Specifies the user type of the data to delete. If not set to ALL_METADATA, only data of the specified user type will be deleted.
dwMDDataType
Specifies the data type of the data to delete. If not set to ALL_METADATA, only data of the specified data type will be deleted.

Remarks

The IMSAdminBase::DeleteAllData method only deletes data local to the specified key. Any data that the specified key inherits from keys higher in the metabase is not deleted.

This method can affect subkeys of the specified object if those subkeys inherit data from the key specified in the IMSAdminBase::DeleteAllData call.


IMSAdminBase::DeleteBackup

The IMSAdminBase::DeleteBackup method deletes a metabase backup from a backup location.

HRESULT DeleteBackup(
  LPCWSTR pszMDBackupLocation,
  DWORD dwMDVersion
);

Parameters

pszMDBackupLocation
A string of up to MD_BACKUP_MAX_LEN unicode characters that identifies the backup location.
dwMDVersion
Specifies the version number of the backup to be deleted from the backup location, or can be the following constant:
MD_BACKUP_HIGHEST_VERSION Delete the highest existing backup version in the specified backup location.

Return Values

Returns an HRESULT that contains one of the following values, or any error from the file system converted to an HRESULT.

Value | Description
ERROR_INVALID_NAME | Specified name is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory to perform the operation.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::DeleteChildKeys

The IMSAdminBase::DeleteChildKeys deletes all subkeys of the specified key and any data they contain. It also recursively deletes all keys below the subkeys.

HRESULT DeleteChildKeys(
  METADATA_HANDLE hMDHandle,  //metabase handle
  LPCWSTR pszMDPath           //path to the key
);

Parameters

hMDHandle
Specifies a handle with write permissions, as returned by the IMSAdminBase::OpenKey method. METADATA_MASTER_ROOT_HANDLE is not valid for this operation.
pszMDPath
Points to a string that contains the path of the key whose subkeys are to be deleted, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could use the path /W3SVC to specify the Web services subkey. In this case, all subkeys below /LM/W3SVC would be deleted

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_PATH_NOT_FOUND | The specified path is not found in the metabase.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::DeleteData

The IMSAdminBase::DeleteData method deletes a data from a key in the metabase.

HRESULT DeleteData(
  METADATA_HANDLE hMDHandle,  //metadata handle
  LPCWSTR pszMDPath,          //path to the key, relative to hMDHandle
  DWORD dwMDIdentifier,       //identifier of the data
  DWORD dwMDDataType          //type of data to remove
);

Parameters

hMDHandle
Specifies a handle returned by the IMSAdminBase::OpenKey method with write permission. This parameter cannot be set to METADATA_MASTER_ROOT_HANDLE.
pszMDPath
Specifies the path of the key to have its data deleted, relative to the path of the handle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
dwMDIdentifier
Specifies the identifier of the data, such as MD_CONNECTION_TIMEOUT.
dwMDDataType
Specifies a data type. If this parameter is not set to ALL_METADATA, the data item will be removed only if its data type matches the specified type. This parameter can be one of the following values:
Data type | Description
ALL_METADATA | Specifies all data, regardless of type.
BINARY_METADATA | Binary data in any form.
DWORD_METADATA | An unsigned 32-bit number.
EXPANDSZ_METADATA | A null-terminated string that contains unexpanded environment variables, such as %PATH%.
MULTISZ_METADATA | An array of null-terminated strings, terminated by two null characters.
STRING_METADATA | A null-terminated ASCII string.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_PATH_NOT_FOUND | The specified path was not found in the metabase.
ERROR_SUCCESS | The method succeeded
MD_ERROR_DATA_NOT_FOUND | The specified data is not found in the metabase.


IMSAdminBase::DeleteKey

The IMSAdminBase::DeleteKey method deletes a key and all of its data from the metabase. All of the key's subkeys are recursively deleted.

HRESULT DeleteKey(
  METADATA_HANDLE hMDHandle,  //metabase handle
  LPCWSTR pszMDPath           //path of the key to delete
);

Parameters

hMDHandle
Specifies a handle with write permission returned by the IMSAdminBase::OpenKey method. METADATA_MASTER_ROOT_HANDLE is not valid for this operation.
pszMDPath
Points to a string that contains the path of the key to be deleted, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey be deleted by using the path /W3SVC.

This parameter cannot be NULL.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_PATH_NOT_FOUND | The specified path is not found in the metabase.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::EnumBackups

The IMSAdminBase::EnumBackups method enumerates the metabase backups in a specified backup location, or in all backup locations. Repeated calls to this method, increasing dwMDEnumIndex from 0, will return information for each metabase backup in the backup location until HRESULT_FROM_WIN32 (ERROR_NO_MORE_ITEMS) is returned.

HRESULT EnumBackups(
  LPWSTR pszMDBackupLocation,
  DWORD __RPC_FAR *pdwMDVersion,
  PFILETIME pftMDBackupTime,
  DWORD dwMDEnumIndex
);

Parameters

pszMDBackupLocation
On input, a buffer of length MD_BACKUP_MAX_LEN times sizeof(WChar) containing an empty string or a string of up to MD_BACKUP_MAX_LEN unicode characters that identifies the backup location. If an empty string is input, the method will enumerate backups in all backup locations, returning the backup location in this parameter. If a backup location is specified on input, only backups in the specified backup location will be enumerated.
pdwMDVersion
Receives the version number of the backup.
pftMDBackupTime

Receives the date and time of the backup, in Universal Time Coordinate (UTC), formerly GMT.

dwMDEnumIndex
Specifies the index number of the backup to be enumerated.

Return Values

Returns an HRESULT that contains one of the following values, or any errors from the file system converted to HRESULT.

Value | Description
ERROR_INVALID_NAME | Specified name is invalid.
ERROR_NO_MORE_ITEMS | No more items to enumerate.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory to perform the operation.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::EnumData

The IMSAdminBase::EnumData method enumerates the data entries of a key in the metabase. One entry is enumerated per call. Set dwMDEnumDataIndex to 0 on the first call and increment by 1 on each subsequent call until the method returns ERROR_NO_MORE_ITEMS.

HRESULT EnumData(
  METADATA_HANDLE hMDHandle,    //metadata handle
  LPCWSTR pszMDPath,            //path to a key, relative to hMDHandle
  PMETADATA_RECORD pmdrMDData,  //pointer to a structure that
                                // receives the data
  DWORD dwMDEnumDataIndex,      //index of the current data entry
  DWORD *pdwMDRequiredDataLen   //receives the required buffer size
                                // for the data
);

Parameters

hMDHandle
Specifies the handle to a key in the metabase. The handle can be METADATA_MASTER_ROOT_HANDLE or a handle, with read permission, returned by the IMSAdminBase::OpenKey method.
pszMDPath
Specifies the path of the key to be enumerated, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
pmdrMDData
Points to a METADATA_RECORD structure that specifies the data to retrieve and receives the data.
dwMDEnumDataIndex
Specifies the index of the entry retrieved. Set this to 0 before the first call and increment it by 1 on each successive call until ERROR_NO_MORE_ITEMS is returned.
pdwMDRequiredDataLen
Points to a DWORD that receives the required buffer size if the method returns ERROR_INSUFFICIENT_BUFFER.

Return Values

Returns HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_INSUFFICIENT_BUFFER | The buffer passed into the method call is too small to receive the data.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_NO_MORE_ITEMS | There are no more entries to enumerate.
ERROR_PATH_NOT_FOUND | The specified path is not found in the metabase.
ERROR_SUCCESS | The method succeeded.

Remarks

The handle, METADATA_MASTER_ROOT_HANDLE, provides no guarantee against multiple thread access. If your application requires a constant data state, use a handle returned by IMSAdminBase::OpenKey.


IMSAdminBase::EnumKeys

The IMSAdminBase::EnumKeys method enumerates the subkeys of the specified key. A subkey can be enumerated once per call. Subkeys are numbered from 0 to (NumKeys - 1), with NumKeys equal to the number of subkeys below the key.

If dwMDEnumKeyIndex is greater than or equal to the number of subkeys, ERROR_NO_MORE_ITEMS is returned.

HRESULT EnumKeys(
  METADATA_HANDLE hMDHandle,  //metabase handle
  LPCWSTR pszMDPath,          //path to the key
  LPWSTR pszMDName,           //receives the name of the subkey
  DWORD dwMDEnumKeyIndex      //index of the subkey
);

Parameters

hMDHandle
Specifies a handle to a metabase key. This can be either METADATA_MASTER_ROOT_HANDLE, or a handle with read permissions returned by the IMSAdminBase::OpenKey method.
pszMDPath
Points to a string that contains the path of the key relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC. In this case the subkeys of /LM/W3SVC would be enumerated.
pszMDName
Points to a string buffer that receives the names of the metabase subkeys enumerated. This buffer must be at least METADATA_MAX_NAME_LEN wide characters long.
dwMDEnumKeyIndex
Specifies the index of the subkey to be retrieved. Set this to 0 before the first call and increment it by 1 on each successive call until ERROR_NO_MORE_ITEMS is returned.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_NO_MORE_ITEMS | There are no more subkeys to enumerate.
ERROR_PATH_NOT_FOUND | The specified path was not found in the metabase.
ERROR_SUCCESS | The method succeeded.

Remarks

The handle, METADATA_MASTER_ROOT_HANDLE, provides no guarantee against multiple thread access. If your application requires a constant data state, use a handle returned by IMSAdminBase::OpenKey.


IMSAdminBase::GetAllData

The IMSAdminBase::GetAllData method retrieves all data associated with a key in the metabase. This includes all values that the key inherits.

HRESULT GetAllData(
  METADATA_HANDLE hMDHandle,      //metabase handle
  LPCWSTR pszMDPath,              //path to the key, relative to
                                  // hMDHandle
  DWORD dwMDAttributes,           //attributes of the data to retrieve
  DWORD dwMDUserType,             //user type of the data to retrieve
  DWORD dwMDDataType,             //data type of the data to retrieve
  DWORD *pdwMDNumDataEntries,     //receives the number of entries
                                  // copied to pbMDBuffer
  DWORD *pdwMDDataSetNumber,      //receives the data set number
  DWORD dwMDBufferSize,           //the size, in bytes, of pbMDBuffer
  Unsigned char *pbMDBuffer,      //the buffer that receives the data
  DWORD *pdwMDRequiredBufferSize  //if the method fails, receives
                                  // the required buffer size
);

Parameters

hMDHandle
Specifies a handle to the metabase. This can be either METADATA_MASTER_ROOT_HANDLE or a handle, with read permission, returned by the IMSAdminBase::OpenKey method.
pszMDPath
Specifies the path of the key with which the data to be retrieved is associated, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
dwMDAttributes
The flags, contained in the METADATA_RECORD structure, used to get the data.
dwMDUserType
Specifies the user type of the data. If not set to ALL_METADATA, only data of the specified user type will be returned.

The following user types are defined for IIS:
User type | Description
ALL_METADATA | Return all data, regardless of user type.
ASP_MD_UT_APP | The entry contains information specific to ASP application configuration.
IIS_MD_UT_FILE | Return only data specific to a file, such as access permissions or log on methods.
IIS_MD_UT_SERVER | Return only data specific to the server, such as ports in use and IP addresses.
IIS_MD_UT_WAM | The entry contains information specific to Web application management.

dwMDDataType
Specifies the type of data to retrieve. If dwMDDataType is not set to ALL_METADATA, only metadata of the specified type will be returned. This parameter can be one of the following values:
Data type | Description
ALL_METADATA | Retrieve all data, regardless of type.
BINARY_METADATA | Binary data in any form.
DWORD_METADATA | An unsigned 32-bit number.
EXPANDSZ_METADATA | A null-terminated string that contains unexpanded environment variables, such as %PATH%.
MULTISZ_METADATA | An array of null-terminated strings, terminated by two null characters.
STRING_METADATA | A null-terminated ASCII string.

pdwMDNumDataEntries
Points to a DWORD that receives the number of entries copied to pbBuffer.
pdwMDDataSetNumber
Points to a number associated with this data set.
dwMDBufferSize
Specifies the size, in bytes, of pbMDBuffer.
pbMDBuffer
Points to a buffer that receives the data. If the method call is successful, the buffer will contain an array of METADATA_GETALL_RECORD structures.
pdwMDRequiredBufferSize
Points to a DWORD that contains the buffer length required, in bytes.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_INSUFFICIENT_BUFFER | The buffer passed into the method call is too small to receive the data.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_PATH_NOT_FOUND | The specified path was not found.
ERROR_SUCCESS | The method succeeded.

Remarks

On non-Intel platforms the DWORD data is aligned; this may not be true on remote clients.

The handle, METADATA_MASTER_ROOT_HANDLE, provides no guarantee against multiple thread access. If your application requires a constant data state, use a handle returned by IMSAdminBase::OpenKey.


IMSAdminBase::GetData

The IMSAdminBase::GetData method retrieves an entry from the metabase.

HRESULT GetData(
  METADATA_HANDLE hMDHandle,    //metabase handle
  LPCWSTR pszMDPath,            //path to the key, relative to
                                // hMDHandle
  PMETADATA_RECORD pmdrMDData,  //pointer to a structure that
                                // receives the data
  DWORD *pdwMDRequiredDataLen   //pointer to a DWORD that receives
                                // the required data length in the case
                                // of an overflow
);

Parameters

hMDHandle
Specifies a handle to the metabase. This can be either METADATA_MASTER_ROOT_HANDLE or a handle returned by the IMSAdminBase::OpenKey method with read permission.
pszMDPath
Specifies the path of the key that contains the data. This path is relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
pmdrMDData
Points to a METADATA_RECORD structure that specifies the data to retrieve and receives the retrieved data.
pdwMDRequiredDataLen
Receives the data length of the required buffer size if the buffer size specified by pmdrMDData->dwMDDataLen is not large enough to hold the data returned (ERROR_INSUFFICIENT_BUFFER is returned).

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_INSUFFICIENT_BUFFER | The buffer passed to the method call is too small to receive the data.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_PATH_NOT_FOUND | The specified path is not found in the metabase.
ERROR_SUCCESS | The method succeeded.
MD_ERROR_DATA_NOT_FOUND | The specified data is not found in the metabase.

Remarks

The handle, METADATA_MASTER_ROOT_HANDLE, provides no guarantee against multiple thread access. If your application requires a constant data state, use a handle returned by IMSAdminBase::OpenKey.


IMSAdminBase::GetDataPaths

The IMSAdminBase::GetDataPaths determines which keys in the metabase contain a specified data identifier. This method retrieves the paths of all keys in the subtree relative to a specified starting key that actually contains the identifier. You can use this method to determine the scope of inherited data values, since only keys that contain the identifier itself are returned. Paths to keys that only contain inherited data for the specified identifier will not be returned.

HRESULT GetDataPaths(
  METADATA_HANDLE hMDHandle,      //metabase handle
  LPCWSTR pszMDPath,              //path to the key, relative to hMDHandle
  DWORD dwMDIdentifier,           //identifier of the data
  DWORD dwMDDataType,             //type of data
  DWORD dwMDBufferSize,           //the size, in wchars, of pbBuffer
  LPWSTR pszBuffer,               //the buffer that receives the data
  DWORD *pdwMDRequiredBufferSize  //if the method fails, receives
                                  // the required buffer size
);

Parameters

hMDHandle
Specifies a handle to the metabase. This can either be METADATA_MASTER_ROOT_HANDLE or a handle returned by a previous call to IMSAdminBase::OpenKey.
pszMDPath
Points to a string that contains the path of the key to be opened, relative to hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
dwMDIdentifier
Specifies the identifier of the data, such as MD_ACCESS_PERM.
dwMDDataType
A DWORD that specifies the type of data to be located. This parameter can be one of the following values:
Data type | Description
ALL_METADATA | Copy or move all data, regardless of type.
BINARY_METADATA | Binary data in any form.
DWORD_METADATA | An unsigned 32-bit number.
EXPANDSZ_METADATA | A null-terminated string that contains unexpanded environment variables, such as %PATH%.
MULTISZ_METADATA | An array of null-terminated strings, terminated by two null characters.
STRING_METADATA | A null-terminated ASCII string.

dwMDBufferSize
Specifies the size, in wchars, of the buffer.
pszBuffer
Points to a buffer that receives the data. If the method call is successful, the buffer will contain a double-null terminated multsz of all paths in the subtree that contain the specified identifier. The returned paths are relative to the handle specified. If the identifier exists on the key designated by the handle and path specified, this path will be the first entry in the list.
pdwMDRequiredBufferSize
Points to a DWORD that contains the buffer length required, in wchars. This parameter is only used if the method returns ERROR_INSUFFICIENT_BUFFER.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete the operation.
ERROR_PATH_NOT_FOUND | The specified path is not found.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::GetDataSetNumber

The IMSAdminBase::GetDataSetNumber method retrieves all the data set numbers associated with a key in the metabase. A data set number is a unique number identifying the data items at that key, including inherited data items. Keys with the same data set number have identical data.

HRESULT GetDataSetNumber(
  METADATA_HANDLE hMDHandle,  //metabase handle
  LPCWSTR pszMDPath,          //path to the key, relative to
                              // hMDHandle
  DWORD *pdwMDDataSetNumber   //receives the data set number
                              // associated with the key
);

Parameters

hMDHandle
Specifies a handle to the metabase, either METADATA_MASTER_ROOT_HANDLE or a handle with read permission as returned by the IMSAdminBase::OpenKey method.
pszMDPath
Points to a string that contains the path of the key to have its data set number retrieved, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
pdwMDDataSetNumber
Points to a DWORD that receives the number associated with this data set. You can use this value to identify data sets common to multiple keys.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::GetHandleInfo

The IMSAdminBase::GetHandleInfo method retrieves information associated with the specified metabase handle.

HRESULT GetHandleInfo(
  METADATA_HANDLE hMDHandle,       //metabase handle
  PMETADATA_HANDLE_INFO pmdhiInfo  //receives the information
                                   // associated with hMDHandle
);

Parameters

hMDHandle
Specifies a handle to the metabase, either METADATA_MASTER_ROOT_HANDLE or a handle returned by a previous call to the IMSAdminBase::OpenKey method.
pmdhiInfo
Points to a METADATA_HANDLE_INFO structure that receives the information about the handle.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_INVALID_HANDLE | The handle is invalid.
ERROR_SUCCESS | The method succeeded.

Remarks

The dwMDSystemChangeNumber member of the METADATA_HANDLE_INFO structure pointed to by pmdhiInfo will correspond to the system change number generated at the time the handle was created. It will not change if write operations are done using this handle, or any other handle. You can compare this number with the value returned by the IMSAdminBase::GetSystemChangeNumber method to see if any write operations have been done since the handle was opened.


IMSAdminBase::GetLastChangeTime

The IMSAdminBase::GetLastChangeTime method retrieves the last change time associated with a key.

HRESULT GetLastChangeTime(
  METADATA_HANDLE hMDHandle,     //metabase handle.
  LPCWSTR pszMDPath,             //path to the key, relative to
                                 // hMDHandle
  PFILETIME pftMDLastChangeTime  //receives the last change time
  BOOL bLocalTime                //local or UTC time
);

Parameters

hMDHandle
Specifies a handle to the metabase. This can either be METADATA_MASTER_ROOT_HANDLE or a handle with write permissions returned by the IMSAdminBase::OpenKey method.
pszMDPath
Specifies a string that contains the path of the affected key, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
pftMDLastChangeTime
Points to a FILETIME structure that receives the last change time.
bLocalTime
Specifies whether the value returned in pftMDLastChangeTime is local (TRUE), or UTC time (FALSE)

Return Values

Returns an HRESULT that contains one of the following values:

Value | Description
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_PATH_NOT_FOUND | The specified path is not found.
ERROR_SUCCESS | The method succeeded.

Remarks

Last change times are updated whenever data or subkeys are set, added, renamed, deleted, copied, or moved, or when this method is called.


IMSAdminBase::GetSystemChangeNumber

The IMSAdminBase::GetSystemChangeNumber method retrieves the number of changes made to data since the metabase was created. This value is saved to long term storage between metabase sessions.

HRESULT GetSystemChangeNumber(
  DWORD *pdwSystemChangeNumber  //receives the system change number
);

Parameters

pdwSystemChangeNumber
Points to a DWORD that receives the system change number. This number is incremented each time the metabase is updated.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_SUCCESS The method succeeded.

Remarks

You can compare the value retrieved by this method to the system change number of a handle to see whether changes have been made to the metabase since the handle was opened.


IMSAdminBase::OpenKey

The IMSAdminBase::OpenKey method opens a key for read access, write access or both. The returned handle can be used by several of the other methods.

The first time you call this method, you must pass in the METADATA_MASTER_ROOT_HANDLE.

HRESULT OpenKey(
  METADATA_HANDLE hMDHandle,      //metabase handle
  LPCWSTR pszMDPath,              //path to the key, relative to hMDHandle
  DWORD dwMDAccessRequested,      //specifies read and/or write permissions
  DWORD dwMDTimeOut,              //the time, in milliseconds, before the
                                  // method times out
  PMETADATA_HANDLE phMDNewHandle  //receives the handle to the opened key
);

Parameters

hMDHandle
Specifies a handle to the metabase. This can either be METADATA_MASTER_ROOT_HANDLE or a handle returned by a previous call to IMSAdminBase::OpenKey.
pszMDPath
Points to a string that contains the path of the key to be opened, relative to hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
dwMDAccessRequested
Specifies the requested permissions for the handle. This parameter must be set to at least one of the following values:
Value | Description
METADATA_PERMISSION_READ | Open the key for reading.
METADATA_PERMISSION_WRITE | Open the key for writing.

dwMDTimeOut
Specifies the time, in milliseconds, for the method to wait for the open operation to succeed.
phMDNewHandle
Points to a handle to receive the opened handle.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_PATH_BUSY | The path specified cannot be used at this time because a handle to the key, or one of its ancestors or descendents, is already open.
ERROR_PATH_NOT_FOUND | The specified path is not found.
ERROR_SUCCESS | The method succeeded.

Remarks

Opening a key with read permissions guarantees that the view of the data will not change while the key is open. Opening a key with write permissions guarantees that no other processes will read or write any data until the handle is closed. This applies to the open key and all of its ancestor and descendent keys. Because opening a key locks a portion of the metabase, it is recommended that you open the key, perform any reads or writes, and immediately close the key when done.

If you try to open a key with read access, the method will wait until all open write access handles to the key and to all ancestor and descendent keys are closed. If you try to open a key with write access, the method will wait until all open handles (either read or write) to the key and to all ancestor and descendent keys are closed.

The METADATA_MASTER_ROOT_HANDLE remains open at all times, and does not block other handles of either access type from being opened.


IMSAdminBase::RenameKey

The IMSAdminBase::RenameKey method renames a key in the metabase.

HRESULT RenameKey(
  METADATA_HANDLE hMDHandle,  //metabase handle to the key
  LPCWSTR pszMDPath,          //path of the key, relative to
                              // hMDHandle
  LPCWSTR pszMDNewName        //new name for the key
);

Parameters

hMDHandle
Specifies a handle to a metabase key. This can be either METADATA_MASTER_ROOT_HANDLE, or a handle with write permissions returned by the IMSAdminBase::OpenKey method.
pszMDPath
Points to a string that contains the path of the key, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the virtual directory, VDir1, on the third Web server using the path /W3SVC/3/ROOT/VDir1.
pszMDNewName
Points to a string that contains the new name for the key.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_DUP_NAME | A key of that name already exists in the metabase.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_NOT_ENOUGH_MEMORY | Not enough memory is available to process this command.
ERROR_PATH_NOT_FOUND | The specified path was not found in the metabase.
ERROR_SUCCESS | The method succeeded.


IMSAdminBase::Restore

The IMSAdminBase::Restore method restores the metabase from a backup. The restore operation stops all services dependent on IISADMIN, including all servers, until the restore has completed, then restarts all services. You should be careful to plan for this service interruption when restoring the metabase from a backup.

HRESULT Restore(
  LPCWSTR pszMDBackupLocation,
  DWORD dwMDVersion,
  DWORD dwMDFlags
);

Parameters

pszMDBackupLocation
A string of up to MD_BACKUP_MAX_LEN unicode characters that identifies the backup location containing the backup to be restored.
dwMDVersion
Specifies the version number of the backup to be restored from the backup location, or may be the following constant:
MD_BACKUP_HIGHEST_VERSION Restore from the highest existing backup version in the specified backup location.

dwMDFlags
Reserved. Must be zero.

Return Values

Returns an HRESULT that contains one of the values listed in the table below. Other errors may also be returned that are passed through from the file system, or from a crypto api when secure metabase data is being saved, or from registry operations.

Value | Description
E_INVALIDARG | An argument was invalid
ERROR_INVALID_DATA | The data is invalid.
ERROR_NOT_ENOUGH_MEMORY | Insufficient memory to perform the operation.
ERROR_SUCCESS | The method succeeded.
MD_ERROR_INVALID_VERSION | The specified version is invalid.
MD_WARNING_INVALID_DATA | Invalid metabase data.
MD_WARNING_PATH_NOT_FOUND | Specified path not found.


IMSAdminBase::SaveData

The IMSAdminBase::SaveData method explicitly saves the metabase data to disk. The metabase data is saved in the metabase storage file, by default named metabase.bin in the INETSRV directory in which you installed IIS, or to the file specified in the Windows NT® registry key LOCAL_MACHINE\\SOFTWARE\\Microsoft\\INetMgr\\Parameters if the file has been relocated as discussed in the Security topic of the IIS Metabase section.

You must not have a handle open with write permission when you call this method, or the method will fail. The process waits for a few seconds for handles to close, so other processes with write handles open should not normally interfere with the save operation.

Syntax

HRESULT SaveData( void );

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_PATH_BUSY | The path specified cannot be used at this time.
ERROR_SUCCESS | The method succeeded.
File system error codes | See winerror.h for information about specific error codes.

Remarks

All data in the metabase is saved, including data written by other applications.

This method will fail and return ERROR_PATH_BUSY if there are any open write handles to the metabase.

Metabase data is saved when IIS shuts down, so you usually do not need to call this method. However, for critical data it is recommended that you call it whenever appropriate for your application.


IMSAdminBase::SetData

The IMSAdminBase::SetData method sets a data item. If data with that identifier does not already exist, this method creates and inserts a data item into the list of data items of that type. If data with that identifier already exists, this method sets the new data value. Duplicate data identifers are not allowed even if the entries are of different user types or data types.

HRESULT SetData(
  METADATA_HANDLE hMDHandle,   //metadata handle
  LPCWSTR pszMDPath,           //path of the key relative to
                               // hMDHandle
  PMETADATA_RECORD pmdrMDData  //pointer to data
);

Parameters

hMDHandle
Specifies a handle with write permissions as returned by the IMSAdminBase::OpenKey method. METADATA_MASTER_ROOT_HANDLE is not valid for this operation.
pszMDPath
Specifies a string that contains the path of the key that receives the entry, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
pmdrMDData
Points to a METADATA_RECORD structure that contains the data to set. All the structure members must be filled except dwMDDataTag.

Return Values

Returns an HRESULT that contains one of the following values:

ERROR_ACCESS_DENIED | Access is denied. Either the open handle does not have read or write permission as needed, or the user does not have sufficient permissions to perform the operation.
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_NOT_ENOUGH_MEMORY | There is not enough memory to complete the operation.
ERROR_PATH_NOT_FOUND | The specified path is not found.
ERROR_SUCCESS | The method succeeded.
MD_ERROR_CANNOT_REMOVE_SECURE_ATTRIBUTE | Cannot set data to be not secure when a secure value exists.


IMSAdminBase::SetLastChangeTime

The IMSAdminBase::SetLastChangeTime method sets the last change time associated with a key in the metabase.

HRESULT SetLastChangeTime(
  METADATA_HANDLE hMDHandle,     //handle to the metabase
  LPCWSTR pszMDPath,             //path to the key, relative to
                                 // hMDHandle
  PFILETIME pftMDLastChangeTime  //pointer to the last change time
  BOOL bLocalTime                //local or UTC time
);

Parameters

hMDHandle
Specifies a handle to the metabase. This can either be METADATA_MASTER_ROOT_HANDLE or a handle with write permissions returned by the IMSAdminBase::OpenKey method.
pszMDPath
Specifies the path of the key to be set, relative to the path of hMDHandle. For example, if the handle references the /LM key, you could specify the Web services subkey using the path /W3SVC.
pftMDLastChangeTime
Points to a FILETIME structure that contains the last change time to set for the key
bLocalTime
Specifies whether the value pointed at by pftMDLastChangeTime is local (TRUE), or UTC time (FALSE).

Return Values

Returns an HRESULT that contains one of the following values:

Value | Description
ERROR_INVALID_PARAMETER | The parameter is incorrect.
ERROR_PATH_NOT_FOUND | The specified path is not found.
ERROR_SUCCESS | The method succeeded.

Remarks

In addition to calls to this method, last change times are updated whenever data or subkeys are set, added, renamed, deleted, copied, or moved.


IMSAdminBase Errors

Error codes returned by IIS Admin Base Object are HRESULTS. The errors beginning with MD_ are already HRESULTS, whereas the Win32® errors, beginning with ERROR_, are converted to HRESULTS by the RETURNCODETOHRESULT macro. The conversion adds 80070000 to the Win32® error code. Other COM and RPC HRESULTS can also be returned.

The following error codes are specific to the Metadata Key.

Error Code | Description
MD_ERROR_DATA_NOT_FOUND | The specified data was not found in the metabase.
MD_ERROR_INVALID_VERSION | The version specified in metadata storage was not recognized.
MD_WARNING_DUP_NAME | A key or data was specified more than once. The duplicate was ignored.
MD_WARNING_INVALID_DATA | The specified data is invalid and has been ignored.
MD_WARNING_PATH_NOT_FOUND | The specified key path was not found. The key and its associated metadata were ignored.


Metabase Identifier Reference

This reference section provides descriptions of the metabase identifiers you can use with the IIS Admin Base Object to control your IIS configuration.

The Alphabetical Identifier List provides quick access to individual identifier descriptions.

Each metabase identifier is, by default, accessible through at least one specific metabase path. The following list contains the most common metabase paths.

Metabase Path | Key Type
/LM | IIsComputer
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/INFO (additional FTP Service identifiers) | IIsFtpInfo
/LM/MSFTPSVC/n | IIsFtpServer
/LM/MSFTPSVC/n/ROOT/VDir | IIsFtpVirtualDir
/LM/W3SVC | IIsWebService
/LM/W3SVC/INFO (additional Web Service identifiers) | IIsWebInfo
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT/VDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebDir | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebDir/File | IIsWebFile
/LM/W3SVC/Filters | IIsFilters
/LM/W3SVC/Filters/Filter | IIsFilter
/LM/Logging | IIsLogModules
/LM/Logging/IIsLogModule | IIsLogModule
/LM/MimeMap | IIsMimeMap

For more information on developing applications by using the administrative interfaces and data structures, see the IIS Metabase and the IIS Admin Base Object documentation. For more details about the automation properties and objects, see the IIS Admin Objects overview and the Administration Property Reference.


Local Machine Identifiers

The identifiers listed below are, by default, available at the local machine metabase key /LM.


FTP Service Identifiers

The identifiers listed below are, by default, available at the FTP service metabase key /LM/MSFTPSVC. Additional identifiers for FTP service are found at the /LM/MSFTPSVC/INFO subkey (see /LM/MSFTPSVC/INFO Identifiers table below).

/LM/MSFTPSVC Identifiers

MD_ACCESS_PERM | MD_LOG_TYPE
MD_ADMIN_ACL | MD_LOGEXT_FIELD_MASK
MD_ALLOW_ANONYMOUS | MD_LOGFILE_DIRECTORY
MD_ALLOW_REPLACE_ON_RENAME | MD_LOGFILE_PERIOD
MD_ANONYMOUS_ONLY | MD_LOGFILE_TRUNCATE_SIZE
MD_ANONYMOUS_PWD | MD_LOGSQL_DATA_SOURCES
MD_ANONYMOUS_USE_SUBAUTH | MD_LOGSQL_PASSWORD
MD_ANONYMOUS_USER_NAME | MD_LOGSQL_TABLE_NAME
MD_CONNECTION_TIMEOUT | MD_LOGSQL_USER_NAME
MD_DEFAULT_LOGON_DOMAIN | MD_MAX_CLIENTS_MESSAGE
MD_DONT_LOG | MD_MAX_CONNECTIONS
MD_DOWNLEVEL_ADMIN_INSTANCE | MD_MAX_ENDPOINT_CONNECTIONS
MD_EXIT_MESSAGE | MD_MSDOS_DIR_OUTPUT
MD_GREETING_MESSAGE | MD_REALM
MD_IP_SEC | MD_SERVER_AUTOSTART
MD_KEY_TYPE | MD_SERVER_BINDINGS
MD_LEVELS_TO_SCAN | MD_SERVER_COMMENT
MD_LOG_ANONYMOUS | MD_SERVER_LISTEN_BACKLOG
MD_LOG_NONANONYMOUS | MD_SERVER_LISTEN_TIMEOUT
MD_LOG_PLUGIN_ORDER | MD_SERVER_SIZE

/LM/MSFTPSVC/INFO Identifiers


FTP Server Identifiers

The identifiers listed below are, by default, available at the FTP server metabase key /LM/MSFTPSVC/n.

MD_ACCESS_PERM | MD_LOGFILE_PERIOD
MD_ADMIN_ACL | MD_LOGFILE_TRUNCATE_SIZE
MD_ALLOW_ANONYMOUS | MD_LOGSQL_DATA_SOURCES
MD_ALLOW_REPLACE_ON_RENAME | MD_LOGSQL_PASSWORD
MD_ANONYMOUS_ONLY | MD_LOGSQL_TABLE_NAME
MD_ANONYMOUS_PWD | MD_LOGSQL_USER_NAME
MD_ANONYMOUS_USE_SUBAUTH | MD_MAX_CLIENTS_MESSAGE
MD_ANONYMOUS_USER_NAME | MD_MAX_CONNECTIONS
MD_CONNECTION_TIMEOUT | MD_MAX_ENDPOINT_CONNECTIONS
MD_DEFAULT_LOGON_DOMAIN | MD_MSDOS_DIR_OUTPUT
MD_DONT_LOG | MD_REALM
MD_EXIT_MESSAGE | MD_SERVER_AUTOSTART
MD_GREETING_MESSAGE | MD_SERVER_BINDINGS
MD_IP_SEC | MD_SERVER_COMMENT
MD_KEY_TYPE | MD_SERVER_LISTEN_BACKLOG
MD_LOG_ANONYMOUS | MD_SERVER_LISTEN_TIMEOUT
MD_LOG_NONANONYMOUS | MD_SERVER_SIZE
MD_LOGEXT_FIELD_MASK | MD_SERVER_STATE
MD_LOGFILE_DIRECTORY |


FTP Virtual Directory Identifiers

The identifiers listed below are, by default, available at the FTP virtual directory metabase keys /LM/MSFTPSVC/n/ROOT and /LM/MSFTPSVC/n/ROOT/FtpVirtualDir.

MD_ACCESS_PERM | MD_VR_PASSWORD
MD_DONT_LOG | MD_VR_PATH
MD_IP_SEC | MD_VR_USERNAME
MD_KEY_TYPE |


Web Service Identifiers

The identifiers listed below are, by default, available at the Web service metabase key /LM/W3SVC. Additional identifiers for Web service are found at the /LM/W3SVC/INFO subkey (see /LM/W3SVC/INFO Identifiers table below).

/LM/W3SVC Identifiers

MD_ACCESS... – MD_APP... |
MD_ACCESS_PERM | MD_ANONYMOUS_USER_NAME
MD_ADMIN_ACL | MD_APP_FRIENDLY_NAME
MD_ADV_CACHE_TTL | MD_APP_ISOLATED
MD_ADV_NOTIFY_PWD_EXP_IN_DAYS | MD_APP_PACKAGE_ID
MD_ALLOW_KEEPALIVES | MD_APP_PACKAGE_NAME
MD_ALLOW_PATH_INFO_FOR_SCRIPT_MAPPINGS | MD_APP_ROOT
MD_ANONYMOUS_PWD | MD_APP_WAM_CLSID
MD_ANONYMOUS_USE_SUBAUTH |
MD_ASP... – MD_AUTH... |
MD_ASP_ALLOWOUTOFPROCCOMPONENTS | MD_ASP_SCRIPTENGINECACHEMAX
MD_ASP_ALLOWSESSIONSTATE | MD_ASP_SCRIPTERRORMESSAGE
MD_ASP_BUFFERINGON | MD_ASP_SCRIPTERRORSSENTTOBROWSER
MD_ASP_CODEPAGE | MD_ASP_SCRIPTFILECACHESIZE
MD_ASP_ENABLECLIENTDEBUG | MD_ASP_SCRIPTLANGUAGE
MD_ASP_ENABLEPARENTPATHS | MD_ASP_SCRIPTTIMEOUT
MD_ASP_ENABLESERVERDEBUG | MD_ASP_SESSIONTIMEOUT
MD_ASP_EXCEPTIONCATCHENABLE | MD_AUTH_CHANGE_FLAGS
MD_ASP_LOGERRORREQUESTS | MD_AUTHORIZATION
MD_ASP_MEMFREEFACTOR | MD_AUTHORIZATION_PERSISTENCE
MD_ASP_QUEUETIMEOUT |
MD_CC... – MD_KEY... |
MD_CC_MAX_AGE | MD_DONT_LOG
MD_CC_NO_CACHE | MD_DOWNLEVEL_ADMIN_INSTANCE
MD_CC_OTHER | MD_FOOTER_DOCUMENT
MD_CONNECTION_TIMEOUT | MD_FOOTER_ENABLED
MD_CREATE_PROC_NEW_CONSOLE | MD_HTTP_CUSTOM
MD_CREATE_PROCESS_AS_USER | MD_HTTP_EXPIRES
MD_CUSTOM_ERROR | MD_HTTP_PICS
MD_DEFAULT_LOAD_FILE | MD_HTTP_REDIRECT
MD_DEFAULT_LOGON_DOMAIN | MD_IN_PROCESS_ISAPI_APPS
MD_DIRECTORY_BROWSING | MD_IP_SEC
MD_DO_REVERSE_DNS | MD_KEY_TYPE
MD_LEV... – MD_SCRIPT... |
MD_LEVELS_TO_SCAN | MD_MAX_CONNECTIONS
MD_LOG_PLUGIN_ORDER | MD_MAX_ENDPOINT_CONNECTIONS
MD_LOG_TYPE | MD_MIME_MAP
MD_LOGEXT_FIELD_MASK | MD_NET_LOGON_WKS
MD_LOGFILE_DIRECTORY | MD_NTAUTHENTICATION_PROVIDERS
MD_LOGFILE_PERIOD | MD_POOL_IDC_TIMEOUT
MD_LOGFILE_TRUNCATE_SIZE | MD_PROCESS_NTCR_IF_LOGGED_ON
MD_LOGON_METHOD | MD_PUT_READ_SIZE
MD_LOGSQL_DATA_SOURCES | MD_REALM
MD_LOGSQL_PASSWORD | MD_REDIRECT_HEADERS
MD_LOGSQL_TABLE_NAME | MD_SCRIPT_MAPS
MD_LOGSQL_USER_NAME |
MD_SERVER... – MD_VR... |
MD_SERVER_AUTOSTART | MD_SSL_KEY_REQUEST
MD_SERVER_BINDINGS | MD_SSL_PRIVATE_KEY
MD_SERVER_COMMENT | MD_SSL_PUBLIC_KEY
MD_SERVER_LISTEN_BACKLOG | MD_UPLOAD_READAHEAD_SIZE
MD_SERVER_LISTEN_TIMEOUT | MD_USE_HOST_NAME
MD_SERVER_SIZE | MD_VR_PASSTHROUGH
MD_SSI_EXEC_DISABLED | MD_WAM_PWD
MD_SSL_ACCESS_PERM | MD_WAM_USER_NAME
MD_SSL_KEY_PASSWORD |

/LM/W3SVC/INFO Identifiers

MD_ADMIN_INSTANCE | MD_LOG_PLUGINS_AVAILABLE
MD_CUSTOM_ERROR_DESC | MD_SERVER_CONFIGURATION_INFO
MD_KEY_TYPE |


Web Server Identifiers

The identifiers listed below are, by default, available at the Web server metabase key /LM/W3SVC/n.

MD_ACCESS... – MD_APP... |
MD_ACCESS_PERM | MD_ANONYMOUS_USER_NAME
MD_ADMIN_ACL | MD_APP_FRIENDLY_NAME
MD_ADV_CACHE_TTL | MD_APP_ISOLATED
MD_ADV_NOTIFY_PWD_EXP_IN_DAYS | MD_APP_OOP_RECOVER_LIMIT
MD_ALLOW_KEEPALIVES | MD_APP_PACKAGE_ID
MD_ALLOW_PATH_INFO_FOR_SCRIPT_MAPPINGS | MD_APP_PACKAGE_NAME
MD_ANONYMOUS_PWD | MD_APP_ROOT
MD_ANONYMOUS_USE_SUBAUTH | MD_APP_WAM_CLSID
MD_ASP... – MD_AUTH... |
MD_ASP_ALLOWOUTOFPROCCOMPONENTS | MD_ASP_SCRIPTENGINECACHEMAX
MD_ASP_ALLOWSESSIONSTATE | MD_ASP_SCRIPTERRORMESSAGE
MD_ASP_BUFFERINGON | MD_ASP_SCRIPTERRORSSENTTOBROWSER
MD_ASP_CODEPAGE | MD_ASP_SCRIPTFILECACHESIZE
MD_ASP_ENABLECLIENTDEBUG | MD_ASP_SCRIPTLANGUAGE
MD_ASP_ENABLEPARENTPATHS | MD_ASP_SCRIPTTIMEOUT
MD_ASP_ENABLESERVERDEBUG | MD_ASP_SESSIONTIMEOUT
MD_ASP_EXCEPTIONCATCHENABLE | MD_AUTH_CHANGE_FLAGS
MD_ASP_LOGERRORREQUESTS | MD_AUTHORIZATION
MD_ASP_MEMFREEFACTOR | MD_AUTHORIZATION_PERSISTENCE
MD_ASP_QUEUETIMEOUT |
MD_CACHE... – MD_KEY... |
MD_CACHE_EXTENSIONS | MD_DO_REVERSE_DNS
MD_CC_MAX_AGE | MD_DONT_LOG
MD_CC_NO_CACHE | MD_FOOTER_DOCUMENT
MD_CC_OTHER | MD_FOOTER_ENABLED
MD_CONNECTION_TIMEOUT | MD_FRONTPAGE_WEB
MD_CREATE_PROC_NEW_CONSOLE | MD_HTTP_CUSTOM
MD_CREATE_PROCESS_AS_USER | MD_HTTP_EXPIRES
MD_CUSTOM_ERROR | MD_HTTP_PICS
MD_DEFAULT_LOAD_FILE | MD_HTTP_REDIRECT
MD_DEFAULT_LOGON_DOMAIN | MD_IP_SEC
MD_DIRECTORY_BROWSING | MD_KEY_TYPE
MD_LOG... – MD_SECURE... |
MD_LOG_PLUGIN_ORDER | MD_MAX_CONNECTIONS
MD_LOG_TYPE | MD_MAX_ENDPOINT_CONNECTIONS
MD_LOGEXT_FIELD_MASK | MD_MIME_MAP
MD_LOGFILE_DIRECTORY | MD_NET_LOGON_WKS
MD_LOGFILE_PERIOD | MD_NTAUTHENTICATION_PROVIDERS
MD_LOGFILE_TRUNCATE_SIZE | MD_POOL_IDC_TIMEOUT
MD_LOGON_METHOD | MD_PROCESS_NTCR_IF_LOGGED_ON
MD_LOGSQL_DATA_SOURCES | MD_PUT_READ_SIZE
MD_LOGSQL_PASSWORD | MD_REALM
MD_LOGSQL_TABLE_NAME | MD_REDIRECT_HEADERS
MD_LOGSQL_USER_NAME | MD_SCRIPT_MAPS
MD_MAX_BANDWIDTH | MD_SCRIPT_TIMEOUT
MD_MAX_BANDWIDTH_BLOCKED | MD_SECURE_BINDINGS
MD_SERVER... – MD_VR... |
MD_SERVER_AUTOSTART | MD_SERVER_STATE
MD_SERVER_BINDINGS | MD_SSI_EXEC_DISABLED
MD_SERVER_COMMENT | MD_SSL_ACCESS_PERM
MD_SERVER_LISTEN_BACKLOG | MD_UPLOAD_READAHEAD_SIZE
MD_SERVER_LISTEN_TIMEOUT | MD_USE_HOST_NAME
MD_SERVER_SIZE | MD_VR_PASSTHROUGH


Web Virtual Directory Identifiers

The identifiers listed below are, by default, available at the Web virtual directory metabase keys /LM/W3SVC/n/ROOTand /LM/W3SVC/n/ROOT/WebVirtualDir.

MD_ACCESS... – MD_ASP_E... |
MD_ACCESS_PERM | MD_APP_WAM_CLSID
MD_ANONYMOUS_PWD | MD_ASP_ALLOWOUTOFPROCCOMPONENTS
MD_ANONYMOUS_USE_SUBAUTH | MD_ASP_ALLOWSESSIONSTATE
MD_ANONYMOUS_USER_NAME | MD_ASP_BUFFERINGON
MD_APP_FRIENDLY_NAME | MD_ASP_CODEPAGE
MD_APP_ISOLATED | MD_ASP_ENABLECLIENTDEBUG
MD_APP_OOP_RECOVER_LIMIT | MD_ASP_ENABLEPARENTPATHS
MD_APP_PACKAGE_ID | MD_ASP_ENABLESERVERDEBUG
MD_APP_PACKAGE_NAME | MD_ASP_EXCEPTIONCATCHENABLE
MD_APP_ROOT |
MD_ASP_L... – MD_FOOTER... |
MD_ASP_LOGERRORREQUESTS | MD_CC_NO_CACHE
MD_ASP_MEMFREEFACTOR | MD_CC_OTHER
MD_ASP_QUEUETIMEOUT | MD_CREATE_PROC_NEW_CONSOLE
MD_ASP_SCRIPTENGINECACHEMAX | MD_CREATE_PROCESS_AS_USER
MD_ASP_SCRIPTERRORMESSAGE | MD_CUSTOM_ERROR
MD_ASP_SCRIPTERRORSSENTTOBROWSER | MD_DEFAULT_LOAD_FILE
MD_ASP_SCRIPTFILECACHESIZE | MD_DEFAULT_LOGON_DOMAIN
MD_ASP_SCRIPTLANGUAGE | MD_DIRECTORY_BROWSING
MD_ASP_SCRIPTTIMEOUT | MD_DO_REVERSE_DNS
MD_ASP_SESSIONTIMEOUT | MD_DONT_LOG
MD_AUTHORIZATION | MD_FOOTER_DOCUMENT
MD_AUTHORIZATION_PERSISTENCE | MD_FOOTER_ENABLED
MD_CC_MAX_AGE |
MD_HTTP... – MD_VR... |
MD_HTTP_CUSTOM | MD_REALM
MD_HTTP_EXPIRES | MD_REDIRECT_HEADERS
MD_HTTP_PICS | MD_SCRIPT_MAPS
MD_HTTP_REDIRECT | MD_SSI_EXEC_DISABLED
MD_IP_SEC | MD_SSL_ACCESS_PERM
MD_IS_CONTENT_INDEXED | MD_UPLOAD_READAHEAD_SIZE
MD_KEY_TYPE | MD_VR_PASSTHROUGH
MD_LOGON_METHOD | MD_VR_PASSWORD
MD_MIME_MAP | MD_VR_PATH
MD_POOL_IDC_TIMEOUT | MD_VR_USERNAME
MD_PUT_READ_SIZE |


Web Directory Identifiers

The identifiers listed below are, by default, available at the Web directory metabase key /LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory.

MD_ACCESS... – MD_ASP_SCRIPTE... |
MD_ACCESS_PERM | MD_ASP_ALLOWSESSIONSTATE
MD_ANONYMOUS_PWD | MD_ASP_BUFFERINGON
MD_ANONYMOUS_USE_SUBAUTH | MD_ASP_CODEPAGE
MD_ANONYMOUS_USER_NAME | MD_ASP_ENABLEPARENTPATHS
MD_APP_FRIENDLY_NAME | MD_ASP_EXCEPTIONCATCHENABLE
MD_APP_ISOLATED | MD_ASP_LOGERRORREQUESTS
MD_APP_OOP_RECOVER_LIMIT | MD_ASP_MEMFREEFACTOR
MD_APP_PACKAGE_ID | MD_ASP_QUEUETIMEOUT
MD_APP_PACKAGE_NAME | MD_ASP_SCRIPTENGINECACHEMAX
MD_APP_ROOT | MD_ASP_SCRIPTERRORMESSAGE
MD_APP_WAM_CLSID | MD_ASP_SCRIPTERRORSSENTTOBROWSER
MD_ASP_ALLOWOUTOFPROCCOMPONENTS |
MD_ASP_SCRIPTF – MD_HTTP... |
MD_ASP_SCRIPTFILECACHESIZE | MD_DEFAULT_LOAD_FILE
MD_ASP_SCRIPTLANGUAGE | MD_DEFAULT_LOGON_DOMAIN
MD_ASP_SCRIPTTIMEOUT | MD_DIRECTORY_BROWSING
MD_ASP_SESSIONTIMEOUT | MD_DO_REVERSE_DNS
MD_AUTHORIZATION | MD_DONT_LOG
MD_AUTHORIZATION_PERSISTENCE | MD_FOOTER_DOCUMENT
MD_CC_MAX_AGE | MD_FOOTER_ENABLED
MD_CC_NO_CACHE | MD_HTTP_CUSTOM
MD_CC_OTHER | MD_HTTP_EXPIRES
MD_CREATE_PROC_NEW_CONSOLE | MD_HTTP_PICS
MD_CREATE_PROCESS_AS_USER | MD_HTTP_REDIRECT
MD_CUSTOM_ERROR |
MD_IP... – MD_VR... |
MD_IP_SEC | MD_REALM
MD_IS_CONTENT_INDEXED | MD_REDIRECT_HEADERS
MD_KEY_TYPE | MD_SCRIPT_MAPS
MD_LOGON_METHOD | MD_SSI_EXEC_DISABLED
MD_MIME_MAP | MD_SSL_ACCESS_PERM
MD_POOL_IDC_TIMEOUT | MD_UPLOAD_READAHEAD_SIZE
MD_PUT_READ_SIZE | MD_VR_PASSTHROUGH


Web File Identifiers

The identifiers listed below are, by default, available at the Web file metabase key /LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile.

MD_ACCESS_PERM | MD_HTTP_CUSTOM
MD_ANONYMOUS_PWD | MD_HTTP_EXPIRES
MD_ANONYMOUS_USE_SUBAUTH | MD_HTTP_PICS
MD_ANONYMOUS_USER_NAME | MD_HTTP_REDIRECT
MD_AUTHORIZATION | MD_IP_SEC
MD_AUTHORIZATION_PERSISTENCE | MD_KEY_TYPE
MD_CC_MAX_AGE | MD_LOGON_METHOD
MD_CC_NO_CACHE | MD_MIME_MAP
MD_CC_OTHER | MD_POOL_IDC_TIMEOUT
MD_CREATE_PROC_NEW_CONSOLE | MD_PUT_READ_SIZE
MD_CREATE_PROCESS_AS_USER | MD_REALM
MD_CUSTOM_ERROR | MD_REDIRECT_HEADERS
MD_DEFAULT_LOGON_DOMAIN | MD_SCRIPT_MAPS
MD_DIRECTORY_BROWSING | MD_SSI_EXEC_DISABLED
MD_DO_REVERSE_DNS | MD_SSL_ACCESS_PERM
MD_DONT_LOG | MD_UPLOAD_READAHEAD_SIZE
MD_FOOTER_DOCUMENT | MD_VR_PASSTHROUGH
MD_FOOTER_ENABLED |


Filter Identifiers

The identifiers listed below are, by default, available at the filter metabase keys /LM/W3SVC/Filters, /LM/W3SVC/Filters/Filter, and /LM/W3SVC/n/Filters/Filter. For details, see individual identifier descriptions.

/LM/W3SVC/Filters/Filter and /LM/W3SVC/n/Filters/Filter only:
MD_FILTER_DESCRIPTION MD_FILTER_IMAGE_PATH
MD_FILTER_ENABLED MD_FILTER_STATE
MD_FILTER_FLAGS MD_KEY_TYPE
/LM/W3SVC/Filters only:


Logging Identifiers

The identifiers listed below are, by default, available at the logging metabase keys /LM/Logging and /LM/Logging/IIsLogModule.

/LM/Logging only:
MD_KEY_TYPE
/LM/Logging/IIsLogModule only:
MD_LOG_PLUGIN_MOD_ID
MD_LOG_PLUGIN_UI_ID


MIME Map Identifiers

The identifiers listed below are, by default, available at the MIME map metabase key /LM/MimeMap.

MD_KEY_TYPE
MD_MIME_MAP


Alphabetical Identifier List

MD_ACCESS... – MD_APP... |
MD_ACCESS_PERM | MD_ANONYMOUS_PWD
MD_ADMIN_ACL | MD_ANONYMOUS_USE_SUBAUTH
MD_ADMIN_INSTANCE | MD_ANONYMOUS_USER_NAME
MD_ADV_CACHE_TTL | MD_APP_FRIENDLY_NAME
MD_ADV_NOTIFY_PWD_EXP_IN_DAYS | MD_APP_ISOLATED
MD_ALLOW_ANONYMOUS | MD_APP_OOP_RECOVER_LIMIT
MD_ALLOW_KEEPALIVES | MD_APP_PACKAGE_ID
MD_ALLOW_PATH_INFO_FOR_SCRIPT_MAPPINGS | MD_APP_PACKAGE_NAME
MD_ALLOW_REPLACE_ON_RENAME | MD_APP_ROOT
MD_ANONYMOUS_ONLY | MD_APP_WAM_CLSID
MD_ASP... |
MD_ASP_ALLOWOUTOFPROCCOMPONENTS | MD_ASP_MEMFREEFACTOR
MD_ASP_ALLOWSESSIONSTATE | MD_ASP_QUEUETIMEOUT
MD_ASP_BUFFERINGON | MD_ASP_SCRIPTENGINECACHEMAX
MD_ASP_CODEPAGE | MD_ASP_SCRIPTERRORMESSAGE
MD_ASP_ENABLEPARENTPATHS | MD_ASP_SCRIPTERRORSSENTTOBROWSER
MD_ASP_ENABLECLIENTDEBUG | MD_ASP_SCRIPTFILECACHESIZE
MD_ASP_ENABLESERVERDEBUG | MD_ASP_SCRIPTLANGUAGE
MD_ASP_EXCEPTIONCATCHENABLE | MD_ASP_SCRIPTTIMEOUT
MD_ASP_LOGERRORREQUESTS | MD_ASP_SESSIONTIMEOUT
MD_AUTH... – MD_EXIT... |
MD_AUTH_CHANGE_FLAGS | MD_CUSTOM_ERROR
MD_AUTHORIZATION | MD_CUSTOM_ERROR_DESC
MD_AUTHORIZATION_PERSISTENCE | MD_DEFAULT_LOAD_FILE
MD_CACHE_EXTENSIONS | MD_DEFAULT_LOGON_DOMAIN
MD_CC_MAX_AGE | MD_DIRECTORY_BROWSING
MD_CC_NO_CACHE | MD_DO_REVERSE_DNS
MD_CC_OTHER | MD_DONT_LOG
MD_CONNECTION_TIMEOUT | MD_DOWNLEVEL_ADMIN_INSTANCE
MD_CREATE_PROC_NEW_CONSOLE | MD_EXIT_MESSAGE
MD_CREATE_PROCESS_AS_USER |
MD_FILTER... – MD_LEV... |
MD_FILTER_DESCRIPTION | MD_HTTP_CUSTOM
MD_FILTER_ENABLED | MD_HTTP_EXPIRES
MD_FILTER_FLAGS | MD_HTTP_PICS
MD_FILTER_IMAGE_PATH | MD_HTTP_REDIRECT
MD_FILTER_LOAD_ORDER | MD_IISADMIN_EXTENSIONS
MD_FILTER_STATE | MD_IN_PROCESS_ISAPI_APPS
MD_FOOTER_DOCUMENT | MD_IP_SEC
MD_FOOTER_ENABLED | MD_IS_CONTENT_INDEXED
MD_FRONTPAGE_WEB | MD_KEY_TYPE
MD_GREETING_MESSAGE | MD_LEVELS_TO_SCAN
MD_LOG... – MD_MAX... |
MD_LOG_ANONYMOUS | MD_LOGON_METHOD
MD_LOG_NONANONYMOUS | MD_LOGSQL_DATA_SOURCES
MD_LOG_PLUGIN_MOD_ID | MD_LOGSQL_PASSWORD
MD_LOG_PLUGIN_ORDER | MD_LOGSQL_TABLE_NAME
MD_LOG_PLUGIN_UI_ID | MD_LOGSQL_USER_NAME
MD_LOG_PLUGINS_AVAILABLE | MD_MAX_BANDWIDTH
MD_LOG_TYPE | MD_MAX_BANDWIDTH_BLOCKED
MD_LOGEXT_FIELD_MASK | MD_MAX_CLIENTS_MESSAGE
MD_LOGFILE_DIRECTORY | MD_MAX_CONNECTIONS
MD_LOGFILE_PERIOD | MD_MAX_ENDPOINT_CONNECTIONS
MD_LOGFILE_TRUNCATE_SIZE |
MD_MIME... – MD_SERVER... |
MD_MIME_MAP | MD_SECURE_BINDINGS
MD_MSDOS_DIR_OUTPUT | MD_SERVER_AUTOSTART
MD_NET_LOGON_WKS | MD_SERVER_BINDINGS
MD_NTAUTHENTICATION_PROVIDERS | MD_SERVER_COMMAND
MD_POOL_IDC_TIMEOUT | MD_SERVER_COMMENT
MD_PROCESS_NTCR_IF_LOGGED_ON | MD_SERVER_CONFIGURATION_INFO
MD_PUT_READ_SIZE | MD_SERVER_LISTEN_BACKLOG
MD_REALM | MD_SERVER_LISTEN_TIMEOUT
MD_REDIRECT_HEADERS | MD_SERVER_SIZE
MD_SCRIPT_MAPS | MD_SERVER_STATE
MD_SCRIPT_TIMEOUT |
MD_SSI... – MD_WIN32... |
MD_SSI_EXEC_DISABLED | MD_VR_PASSTHROUGH
MD_SSL_ACCESS_PERM | MD_VR_PASSWORD
MD_SSL_KEY_PASSWORD | MD_VR_PATH
MD_SSL_KEY_REQUEST | MD_VR_USERNAME
MD_SSL_PRIVATE_KEY | MD_WAM_PWD
MD_SSL_PUBLIC_KEY | MD_WAM_USER_NAME
MD_UPLOAD_READAHEAD_SIZE | MD_WIN32_ERROR
MD_USE_HOST_NAME |


MD_ACCESS_PERM

This metabase identifier contains flags that establish the access permissions for files residing on the server.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
MD_ACCESS_READ
Constant | Value | Description
MD_ACCESS_READ | 0x00000001 | Allow read access
MD_ACCESS_WRITE | 0x00000002 | Allow write access
MD_ACCESS_EXECUTE | 0x00000004 | Allow file execution (includes script permission)
MD_ACCESS_SCRIPT | 0x00000200 | Allow script execution
MD_ACCESS_NO_REMOTE_WRITE | 0x00000400 | Local write access only
MD_ACCESS_NO_REMOTE_READ | 0x00001000 | Local read access only
MD_ACCESS_NO_REMOTE_EXECUTE | 0x00002000 | Local execution only
MD_ACCESS_NO_REMOTE_SCRIPT | 0x00004000 | Local host access only

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/MSFTPSVC/n/ROOT | IIsFtpVirtualDir
/LM/MSFTPSVC/n/ROOT/FtpVirtualDir | IIsFtpVirtualDir
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

Permissions established by setting the MD_ACCESS_EXECUTE, MD_ACCESS_SCRIPT, MD_ACCESS_NO_REMOTE_EXECUTE, and MD_ACCESS_NO_REMOTE_SCRIPT bits do not apply to FTP server files.

Remote access flags are operative only when the corresponding general access flag is set. For example, MD_ACCESS_NO_REMOTE_READ has no effect unless MD_ACCESS_READ is also set. If both are set, the local host can read the file, but it cannot be read by the remote client.

See also

AccessFlags


MD_ADMIN_ACL

This identifier contains a Microsoft® Windows NT® security descriptor that can be used to control access to any metabase subtree. Using discretionary ACL (DACL), this identifier can grant read access, restricted write access, or unrestricted write access.

Attributes

Data type | BINARY REFERENCE
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty (No ACL)
Constant | Value | Description
MD_ACR_READ | 0x00000001 | Enable read access to all properties
MD_ACR_WRITE | 0x00000002 | Enable write access to all properties
MD_ACR_ENUM_KEYS | 0x00000008 | Enable key enumeration
MD_ACR_RESTRICTED_WRITE | 0x00000020 | See note below
MD_ACR_UNSECURE_PROPS_READ | 0x00000080 | Enable read access to properties that do not have METADATA_SECURE attribute set
MD_ACR_WRITE_DAC | 0x00040000 | Enable write access to MD_ADMIN_ACL for security descriptor creator (as stored in MD_ADMIN_ACL)

Note MD_ACR_RESTRICTED_WRITE enables write access to the following properties: MD_ADMIN_ACL, MD_APP_ISOLATED, MD_VR_PATH, MD_ACCESS_PERM, MD_ANONYMOUS_USER_NAME, MD_ANONYMOUS_PWD, MD_MAX_BANDWIDTH, MD_MAX_BANDWIDTH_BLOCKED, MD_SECURE_BINDINGS, and MD_SERVER_BINDINGS.

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See also

AdminACL


MD_ADMIN_INSTANCE

This identifier specifies the server instance that is functioning as the HTML Administration instance.

Attributes

Data type | STRING
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
1 (String)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/Info | IIsWebInfo

Remarks

This identifier should be considered read-only.

See Also

AdminServer, MD_DOWNLEVEL_ADMIN_INSTANCE


MD_ADV_CACHE_TTL

This identifier specifies the number of seconds that a password expiration notice will be cached. This has the effect of limiting the frequency at which users will be notified that their password is about to expire. For example, if the value for this identifier is set at its default, ten minutes, then a user whose password is close to expiring will be notified at most every ten minutes.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
0 – 0xFFFFFFFF
Default Value
600 (10 minutes)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

PasswordCacheTTL, MD_ADV_NOTIFY_PWD_EXP_IN_DAYS


MD_ADV_NOTIFY_PWD_EXP_IN_DAYS

This identifier specifies the number of days before a user's password expires that the user is notified of the impending expiration.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
0 – 0xFFFFFFFF
Default Value
14

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

Password expiration notification can be turned off by setting the MD_AUTH_ADVNOTIFY_DISABLE flag in the identifier MD_AUTH_CHANGE_FLAGS.

See Also

PasswordExpirePrenotifyDays


MD_ALLOW_ANONYMOUS

This identifier enables anonymous FTP access to FTP server.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer

See Also

AllowAnonymous, MD_ANONYMOUS_ONLY


MD_ALLOW_KEEPALIVES

This identifier indicates whether HTTP keep-alive processing is enabled.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

AllowKeepAlive


MD_ALLOW_PATH_INFO_FOR_SCRIPT_MAPPINGS

This property indicates whether clients are permitted to specify path information in script mapped requests.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

AllowPathInfoForScriptMappings


MD_ALLOW_REPLACE_ON_RENAME

This identifier indicates whether the rename command, when sent to the FTP server by a client, should replace the existing file with the newly renamed file if a name conflict exists.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer


MD_ANONYMOUS_ONLY

This identifier specifies whether the service or server restricts access to anonymous FTP users. If the value is TRUE, only anonymous users will be allowed to log on to the FTP server. If the value is FALSE, users will be allowed to log on by using a valid user name, as well as anonymously.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer

Remarks

Regardless of the value of this identifier, if the value of the metabase identifier MD_ALLOW_ANONYMOUS is set to FALSE then anonymous users will not be allowed access to the FTP server. If MD_ALLOW_ANONYMOUS is set to FALSE, and MD_ANONYMOUS_ONLY is set to TRUE, no users will be permitted to log on to the FTP server.

See Also

AnonymousOnly


MD_ANONYMOUS_PWD

This identifier specifies the anonymous user password associated with the account specified by MD_ANONYMOUS_USER_NAME. This password is only required if the identifier MD_ANONYMOUS_USE_SUBAUTH is set to FALSE.

The password is stored in an encrypted form in the metabase. It is unencrypted locally, so the value of this identifier, when queried, will be the unencrypted version of the password.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Random string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

AnonymousUserPass, MD_ANONYMOUS_USER_NAME, MD_ANONYMOUS_USE_SUBAUTH


MD_ANONYMOUS_USE_SUBAUTH

This identifier indicates whether the sub-authenticator should be used for users attempting to access resources anonymously. If the value is FALSE, the administrator must set the password, using the MD_ANONYMOUS_PWD identifier, for anonymous access to function properly. If the value is TRUE, no anonymous user password is required.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

AnonymousPasswordSync, MD_ANONYMOUS_USER_NAME, MD_ANONYMOUS_PWD


MD_ANONYMOUS_USER_NAME

This identifier specifies the user name that will be associated with all actions performed by an anonymous user. If the identifier MD_ANONYMOUS_USE_SUBAUTH is set to FALSE, then the MD_ANONYMOUS_PWD identifier must be set to the password associated with this account.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
I_USR_Local machine name

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

AnonymousUserName, MD_ANONYMOUS_PWD, MD_ANONYMOUS_USE_SUBAUTH


MD_APP_FRIENDLY_NAME

This identifier specifies the user-friendly name of the package or application.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AppFriendlyName, MD_APP_PACKAGE_NAME


MD_APP_ISOLATED

This identifier indicates whether an application is to run in-process with the server or out-of-process. Note that there can be significant performance issues if too many applications are forced to run out-of-process.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

This identifier should be considered read-only. Use the application management methods of the IIsWebVirtualDir and IIsWebDirectory objects, described in the IIS Admin Objects documentation, or the Web Application Management Interface to indicate that an application is to run out-of-process.

See Also

AppIsolated, MD_IN_PROCESS_ISAPI_APPS


MD_APP_OOP_RECOVER_LIMIT

This identifier specifies the maximum number of times an out-of-process application will be restarted after a failure. The server will not service requests from components that have exceeded this limit.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Value Range
1 – 5
Default Value
5

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

This identifier does not apply to in-process applications or extensions.

See Also

AppOopRecoverLimit


MD_APP_PACKAGE_ID

This identifier specifies the package ID for an application. This ID is used in all transactions managed by Microsoft Transaction Server (MTS).

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

This identifier should be considered read-only.

See Also

AppPackageID, MD_APP_PACKAGE_NAME


MD_APP_PACKAGE_NAME

This identifier provides Microsoft Transaction Server (MTS) with the application package name.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

This identifier should be considered read-only.

See Also

AppPackageName, MD_APP_PACKAGE_ID, MD_APP_FRIENDLY_NAME


MD_APP_ROOT

This identifier specifies the URL that will be used as the base URL for an application.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

This identifier should be considered read-only. To mark a node as an application root, use the application management methods of the IIsWebVirtualDir and IIsWebDirectory objects described in the IIS Admin Objects documentation, or the Web Application Management Interface.

See Also

AppRoot


MD_APP_WAM_CLSID

This identifier specifies the class ID for a Web Application Manager (WAM) application package.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

This identifier should be considered read-only.

See Also

AppWamClsID


MD_ASP_ALLOWOUTOFPROCCOMPONENTS

This identifier specifies whether an ASP script is allowed to call out of process components, executables that are launched from within an application. If set to TRUE at the Web Service level, all in-process applications will be able to launch out-of-process components. If set to TRUE at the root key (virtual directory key) of a specific application, only that application can launch out-of-process components. See Simplifying Development With Process Isolation in Advanced Web Application Development for information on out-of-process components, applications, and related security issues.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspAllowOutOfProcComponents


MD_ASP_ALLOWSESSIONSTATE

This identifier enables session state persistence for the ASP application. If the value is TRUE, the server will create a new Session object for each connection. Session state will be accessible, session storage will be allowed, the Session_OnStart and Session_OnEnd will occur, and the ASPSessionID cookie will be sent to the client. If the value is FALSE, state access and storage are not allowed, events are not processed, and no cookie is sent.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspAllowSessionState


MD_ASP_BUFFERINGON

This identifier specifies whether output from an ASP application will be buffered. If the value is TRUE, all output from the application is collected in the buffer before the buffer is flushed to the client browser.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

The value of this identifier can be set by an executing ASP script by accessing the Buffer method in the Response built-in object. An ASP script can also call the Flush method to send all buffered output to the client, even if the application has not finished its task.

See Also

AspBufferingOn


MD_ASP_CODEPAGE

This identifier specifies the default codepage for an ASP application.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Value Range
Any valid codepage
Default Value
0 (CP_ACP, System ANSI codepage)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspCodepage


MD_ASP_ENABLEPARENTPATHS

This identifier indicates whether ASP scripts will allow paths relative to the current directory, using the ..\ notation. Note that there is a potential security risk if this identifier is enabled, as directories and files outside of the service's root directory could become accessible.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspEnableParentPaths


MD_ASP_ENABLECLIENTDEBUG

This metabase identifier enables the client-side ASP debugging features.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebDirectory | IIsWebDirectory

Remarks

This identifier is completely independent of the server-side debugging features enabled with the MD_ASP_ENABLESERVERDEBUG

See Also

AppAllowClientDebug, MD_ASP_ENABLESERVERDEBUG


MD_ASP_ENABLESERVERDEBUG

This metabase identifier enables the server-side ASP debugging features.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebDirectory | IIsWebDirectory

Remarks

This identifier is completely independent of the client-side debugging features enabled with the MD_ASP_ENABLECLIENTDEBUG

See Also

AppAllowDebugging, MD_ASP_ENABLECLIENTDEBUG


MD_ASP_EXCEPTIONCATCHENABLE

This identifier indicates whether exceptions thrown by components are trapped by ASP scripts. If the value is TRUE, the script will be allowed to catch the exception. If the value is FALSE, the script will not catch the exception.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspExceptionCatchEnable


MD_ASP_LOGERRORREQUESTS

This identifier indicates whether client requests that generate errors while executing an ASP application will be logged in the Microsoft® Windows NT® event log.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspLogErrorRequests


MD_ASP_MEMFREEFACTOR

IIS caches memory blocks, called free memory blocks, for active server page execution. When memory blocks are deallocated within IIS they are moved from the used memory list to the free memory list and retained by IIS for reuse. MD_ASP_MEMFREEFACTOR specifies the ratio, in percent, of free memory blocks to used memory blocks. When the ratio of free blocks to used blocks exceeds the value of this parameter, free blocks are released by IIS and returned to the virtual memory pool. For example, a value of 500 will cause IIS to release memory when the free memory list is 5 times (500% of) the length of the used memory list.

If your server is performing many tasks in addition to running active server pages under IIS, you may wish to set this parameter low. If your server is primarily dedicated to serving ASP pages, a higher value for this parameter will improve performance. A value of zero eliminates IIS memory block caching for ASP page processing and is not recommended.

If this parameter is changed, the change will not take effect until the Web server is stopped and restarted.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
0 – 0xFFFFFFFF
Default Value
50 (percent)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspMemFreeFactor


MD_ASP_QUEUETIMEOUT

This identifier specifies the amount of time, in seconds, that an ASP script request will wait in the queue for execution. When requests are pulled from the queue for execution, they are checked to see if they have expired (have waited longer than the value of this parameter). Expired requests are rejected with a message indicating the server is too busy.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_APP

Values

Value Range
0 – 0xFFFFFFFF
Default Value
0xFFFFFFFF

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspQueueTimeout


MD_ASP_SCRIPTENGINECACHEMAX

This identifier specifies the maximum number of ActiveX™ scripting engines that the server can have cached in memory.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
0 – 0xFFFFFFFF
Default Value
30

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspScriptEngineCacheMax


MD_ASP_SCRIPTERRORMESSAGE

This identifier specifies a generic error message string that is sent to the client browser if the server encounters an error in an ASP script, and the identifer MD_ASP_SCRIPTERRORSSENTTOBROWSER is set to FALSE.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Default Value
An error occurred on the server when processing the URL. Please contact the system administrator.

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspScriptErrorMessage, MD_ASP_SCRIPTERRORSSENTTOBROWSER


MD_ASP_SCRIPTERRORSSENTTOBROWSER

This identifier indicates whether the server should send error messages to the client browser as well as to the Microsoft® Windows NT® log file. If the value is TRUE, the server will send debugging information to the client, including the file name, the name of the error, the script line number, and a brief description of the error. If the value is FALSE, the generic error message specified in MD_ASP_SCRIPTERRORMESSAGE will be sent to the browser client.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspScriptErrorSentToBrowser, MD_ASP_SCRIPTERRORMESSAGE


MD_ASP_SCRIPTFILECACHESIZE

This identifier specifies the number of precompiled script files to cache. A value of 0xFFFFFFFF indicates that the server is to keep all requested scripts cached, while a value of 0 indicates that no scripts should be cached.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_WAM

Values

Value Range
0 – 0xFFFFFFFF
Default Value
0xFFFFFFFF (All scripts cached)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

This identifier can be used to optimize server performance, based on system resources and script usage.

See Also

AspScriptFileCacheSize


MD_ASP_SCRIPTLANGUAGE

This identifier specifies the default scripting language that is to be used by all ASP applications on the server. The default language will be used to interpret all commands within the scripting delimiters (<% ... %>), unless a different language is specifically declared with the <% @LANGUAGE = NewScriptingLanguage %> directive.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Default Value
Vbscript

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

AspScriptLanguage


MD_ASP_SCRIPTTIMEOUT

This identifier specifies the maximum number of seconds that the server will wait for an ASP script to complete its execution. If more seconds elapse than is specified by this identifier, the script is terminated and a time-out event is written to the Microsoft® Windows NT® log file.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Value Range
1 – 0xFFFFFFFE
Default Value
90

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

The value of this identifier can be accessed and overridden by an ASP script that uses the Server.ScriptTimeout property.

See Also

AspScriptTimeout, MD_ASP_SESSIONTIMEOUT


MD_ASP_SESSIONTIMEOUT

This identifier specifies the maximum length of time, in minutes, that a Session object will be maintained after the last request from the client associated with it has been received.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | ASP_MD_UT_APP

Values

Value Range
1 – 0xFFFFFFFF
Default Value
20

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

This value can be accessed and overridden by an ASP script by using the Session.Timeout property.

See Also

AspSessionTimeout, MD_ASP_SCRIPTTIMEOUT


MD_AUTH_CHANGE_FLAGS

This identifier contains flags that are used to configure password management between the server and client. The default setting indicates that password changing is only enabled over SSL connections.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
0 (SSL connection required)
Constant | Value | Description
MD_AUTH_CHANGE_UNSECURE | 0x00000001 | Password changing allowed on nonsecure ports
MD_AUTH_CHANGE_DISABLE | 0x00000002 | Password changing disabled
MD_AUTH_ADVNOTIFY_DISABLE | 0x00000004 | Advance notification of password expiration disabled

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

PasswordChangeFlags, MD_ADV_NOTIFY_PWD_EXP_IN_DAYS


MD_AUTHORIZATION

This identifier contains flags specifying which Microsoft® Windows NT® authorization schemes are available for the object instance.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
MD_AUTH_ANONYMOUS
Constant | Value | Description
MD_AUTH_ANONYMOUS | 0x00000001 | Anonymous authentication available
MD_AUTH_BASIC | 0x00000002 | Basic authentication available
MD_AUTH_NT | 0x00000004 | NT authentication schemes available

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

AuthFlags


MD_AUTHORIZATION_PERSISTENCE

This identifier specifies authentication persistence across requests on a connection. The value can indicate that authentication is valid for a single request, or that authentication is valid for a single request only when the request was by a proxy. A value of 0 indicates that the authentication is not reset after the first request.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
MD_AUTH_SINGLEREQUESTIFPROXY
Constant | Value | Description
MD_AUTH_SINGLEREQUEST | 0x00000040 | Authentication valid for single request
MD_AUTH_SINGLEREQUESTIFPROXY | 0x00000080 | Authentication valid for single request if request is by proxy and the request is not handled by Microsoft® Proxy Server (i.e., if MS Proxy Server is running on the local IIS server and the request is targeted to a non-local server)
MD_AUTH_SINGLEREQUESTALWAYSIFPROXY | 0x00000100 | Authentication valid for single request if request is by proxy.

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

AuthPersistence


MD_CACHE_EXTENSIONS

This identifier indicates whether ISAPI extensions are cached in memory after use. If the value of this identifier is TRUE, the .DLL file will remain in the cache until the sever is stopped. If the value is FALSE, extensions are unloaded from memory upon completing the task for which they were loaded.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/n | IIsWebServer

Remarks

ISAPI extensions are cached or not cached based on the value of this identifier at the time they were loaded into memory for use. Thus, if this identifier is changed after an extension has been loaded and cached, the change will have no effect on that extension.

See Also

CacheISAPI


MD_CC_MAX_AGE

This identifier specifies the HTTP 1.1 cache control maximum age value.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
0 – 0xFFFFFFFF
Default Value
Not applicable. By default, this property is not set and cache control directives are not sent.

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

CacheControlMaxAge


MD_CC_NO_CACHE

This identifier specifies the HTTP 1.1 directive to prevent caching of content.

Attributes

Data type | BOOL
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
Not applicable. By default, this property is not set and cache control directives are not sent.

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

CacheControlNoCache


MD_CC_OTHER

This identifier specifies custom HTTP 1.1 cache control directives.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Not applicable. By default, this property is not set and cache control directives are not sent.

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

Multiple directives may be specified if they are separated by carriage return/line feed ("\r\n") pairs. There should not be a trailing carriage return/line feed after the final directive.

See Also

CacheControlCustom


MD_CONNECTION_TIMEOUT

This identifier specifies the length of time, in seconds, that the server will maintain an inactive connection. After that time, the connection will be terminated.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value range
0 – 0xFFFFFFFF
Default Value
900 (15 minutes)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

ConnectionTimeout


MD_CREATE_PROC_NEW_CONSOLE

This identifier indicates whether a CGI application runs in its own console window. If the value is TRUE, each CGI application creates a new console window when started. A FALSE value indicates that CGI applications should run without a console window.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

This identifier has significant performance impacts, and should only be set to TRUE if the application relies on piping from another application.

See Also

CreateCGIWithNewConsole


MD_CREATE_PROCESS_AS_USER

This identifier specifies whether a CGI process will be created in the system context or in the context of the requesting user.

Attributes

Data type | BOOL
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

CreateProcessAsUser


MD_CUSTOM_ERROR

This identifier contains a list of custom HTTP error handlers. When a client generates an HTTP error, the server checks to see if the error code and subcode match an entry in this list. If there is a match, the URL indicated in this list is given to the client. Otherwise, the server's default error handlers are used.

Each string in the list specifies the HTTP error code and subcode, indicates whether the handler will be a URL or a file, and specifies which URL or file the client will be sent. Each string can be in one of two formats. To send a URL to the client, use HTTPErrorCode, HTTPErrorSubcode, URL, HanderlerURL. To send a file, use HTTPErrorCode, HTTPErrorSubcode, FILE, Filename.

Attributes

Data type | MULTI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty list

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

HttpErrors, MD_CUSTOM_ERROR_DESC


MD_CUSTOM_ERROR_DESC

This identifier contains a list of custom error messages. Each string in the list specifies an error code and subcode for the custom message, what the specific error text and subcode error text is to be, and whether the custom message is supported by file or URL, or just by file. Each string is in the format ErrorCode, ErrorSubcode, ErrorText, ErrorSubcodeText, followed by another comma and either a 0 for file and URL support, or a 1 for file support only.

Attributes

Data type | MULTI_SZ
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty list

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/INFO | IIsWebInfo

See Also

CustomErrorDescriptions, MD_CUSTOM_ERROR


MD_DEFAULT_LOAD_FILE

This identifier contains a list of possible default HTML document names. If the browser makes a request that lacks a file name, the server will search the list of default files in order. The first file from the list it finds that actually exists in the browser-specified directory will be sent to the browser. Multiple file names can be specified as a comma-delimited list, such as Filename1, Filename2, and so on.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
default.htm

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

If the MD_DIRBROW_LOADDEFAULT flag is not set in the MD_DIRECTORY_BROWSING identifier, the server will not search for a default document.

See Also

DefaultDoc, MD_DIRECTORY_BROWSING


MD_DEFAULT_LOGON_DOMAIN

This identifier specifies the default domain to which the user will log on, if no domain is specified by the user. This value is valid for Basic authentication only.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

If the value of this identifier is an empty string, and the server is a domain controller, the server will use its own domain name as the default name. If the server is not a domain controller, the computer name of the server machine is used as a domain name.

See Also

DefaultLogonDomain


MD_DIRECTORY_BROWSING

This identifier contains flags that control whether directory browsing is enabled, how much directory and file information is provided if browsing is enabled, and whether there is a default page in the directory.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
MD_DIRBROW_SHOW_DATE |

MD_DIRBROW_SHOW_TIME |

MD_DIRBROW_SHOW_SIZE |

MD_DIRBROW_SHOW_EXTENSION |

MD_DIRBROW_LOADDEFAULT
Constant | Value | Description
MD_DIRBROW_SHOW_DATE | 0x00000002 | Show date
MD_DIRBROW_SHOW_TIME | 0x00000004 | Show time
MD_DIRBROW_SHOW_SIZE | 0x00000008 | Show file size
MD_DIRBROW_SHOW_EXTENSION | 0x00000010 | Show file extension
MD_DIRBROW_LONG_DATE | 0x00000020 | Show full date
MD_DIRBROW_LOADDEFAULT | 0x40000000 | Load default page, if exists
MD_DIRBROW_ENABLED | 0x80000000 | Enable directory browsing

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

Remarks

If a client accesses the directory, but does not provide a file name, and the MD_DIRBROW_LOADDEFAULT flag is set, the server will look for the file specified in the identifier MD_DEFAULT_LOAD_FILE. If the default file does not exist in the directory, then the browser is put in directory browsing mode if the MD_DIREBROW_ENABLED flag is set.

The MD_DIRBROW_LOADDEFAULT flag only applies to the IIsWebVirtualDir and IIsWebDirectory keys.

See Also

DirBrowseFlags


MD_DO_REVERSE_DNS

This identifier indicates whether reverse Domain Name Service (DNS) lookups are performed. In a reverse DNS lookup, the server accesses a DNS provider, and requests the full host name associated with a given IP address. In general, reverse DNS lookups can consume relatively large amounts of system resources.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

EnableReverseDns


MD_DONT_LOG

This identifier indicates whether the server should log all received client requests. A value of TRUE indicates that the server should not log client requests, while a value of FALSE indicates the server should log client requests.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
FALSE (Do log client requests)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/MSFTPSVC/n/ROOT | IIsFtpVirtualDir
/LM/MSFTPSVC/n/ROOT/FtpVirtualDir | IIsFtpVirtualDir
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

DontLog


MD_DOWNLEVEL_ADMIN_INSTANCE

This identifier provides a string that identifies the server instance for remote administration tools.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
1 (String)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/W3SVC | IIsWebService

See Also

DownlevelAdminInstance, MD_ADMIN_INSTANCE


MD_EXIT_MESSAGE

This identifier specifies the string that is sent by the server to an FTP client after the quit command is received from the client.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer

See Also

ExitMessage


MD_FILTER_DESCRIPTION

This identifier specifies a descriptive string that is supplied to IIS by the ISAPI filter.

Attributes

Data type | STRING
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/Filters/Filter | IIsFilter
/LM/W3SVC/n/Filters/Filter | IIsFilter

See Also

FilterDescription


MD_FILTER_ENABLED

This identifier specifies whether the ISAPI filter instance is enabled.

Attributes

Data type | DWORD
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/Filters/Filter | IIsFilter
/LM/W3SVC/n/Filters/Filter | IIsFilter

See Also

FilterEnabled


MD_FILTER_FLAGS

This identifier contains filter notification and priority flags for a filter instance. For detailed information about these flags, see the ISAPI section of the documentation.

Attributes

Data type | DWORD
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable
Constant | Value | Description
MD_NOTIFY_SECURE_PORT | 0x00000001 | Notify only if port secure
MD_NOTIFY_NONSECURE_PORT | 0x00000002 | Notify only if port nonsecure
MD_NOTIFY_READ_RAW_DATA | 0x00008000 | Notify if reading raw data
MD_NOTIFY_PREPROC_HEADERS | 0x00004000 | Notify if preprocessing headers
MD_NOTIFY_AUTHENTICATION | 0x00002000 | Notify if performing authentication
MD_NOTIFY_URL_MAP | 0x00001000 | Notify if mapping URL to physical path
MD_NOTIFY_ACCESS_DENIED | 0x00000800 | Notify if server sending HTTP error 401 to client
MD_NOTIFY_SEND_RESPONSE | 0x00000040 | Notify if response being sent to client
MD_NOTIFY_SEND_RAW_DATA | 0x00000400 | Notify if sending raw data
MD_NOTIFY_LOG | 0x00000200 | Notify if logging
MD_NOTIFY_END_OF_REQUEST | 0x00000080 | Notify if request has ended
MD_NOTIFY_END_OF_NET_SESSION | 0x00000100 | Notify if network session is ending
MD_NOTIFY_ORDER_HIGH | 0x00080000 | High priority for notifications
MD_NOTIFY_ORDER_MEDIUM | 0x00040000 | Medium priority for notifications
MD_NOTIFY_ORDER_LOW, MD_NOTIFY_ORDER_DEFAULT | 0x00020000 | Low priority for notifications

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/Filters/Filter | IIsFilter
/LM/W3SVC/n/Filters/Filter | IIsFilter

Remarks

All flags contained in this identifier should be considered read-only, as only the filter itself can specify, by registering with the server, what notifications it will process and what priority it requires.

See Also

FilterFlags


MD_FILTER_IMAGE_PATH

This identifier specifies the full path to the ISAPI filter .DLL module that will be loaded by IIS on startup.

Attributes

Data type | STRING
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/Filters/Filter | IIsFilter
/LM/W3SVC/n/Filters/Filter | IIsFilter

See Also

FilterPath


MD_FILTER_LOAD_ORDER

This identifier specifies a string containing a comma-delimited list of keys for ISAPI filters to be loaded by IIS at startup. IIS will load the filters in the order specified in the list.

Attributes

Data type | STRING
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/Filters | IIsFilters

See Also

FilterLoadOrder


MD_FILTER_STATE

This identifier indicates whether the particular ISAPI filter is loaded or unloaded.

Attributes

Data type | DWORD
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable
Constant | Value | Description
MD_FILTER_STATE_LOADED | 0x00000001 | Filter loaded
MD_FILTER_STATE_UNLOADED | 0x00000004 | Filter unloaded

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/Filters/Filter | IIsFilter
/LM/W3SVC/n/Filters/Filter | IIsFilter

Remarks

This identifier should be considered read-only.

See Also

FilterState


MD_FOOTER_DOCUMENT

This identifier specifies a default footer that, if the identifier MD_FOOTER_ENABLED is set to TRUE, will be appended to all HTML documents requested from the object. The value can contain the actual text of the footer, or the value can specify the file name of a text or HTML file to be used as the default footer. The format of the string is STRING:FooterText to specify the text of the default footer directly, or FILE:Filename to specify the name of a footer document.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

DefaultDocFooter, MD_FOOTER_ENABLED


MD_FOOTER_ENABLED

This identifier indicates whether the server is to append a default footer document, specified in the identifier MD_FOOTER_DOCUMENT, when an HTML document is requested from the object.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

EnableDocFooter, MD_FOOTER_DOCUMENT


MD_FRONTPAGE_WEB

This identifier specifies whether this server instance is being managed by Front Page Extensions. If the value is set to TRUE, Front Page Manager will create all necessary management files. If the value is set to FALSE, all management files for that server instance are deleted.

Attributes

Data type | DWORD
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/n | IIsWebServer

See Also

FrontPageWeb


MD_GREETING_MESSAGE

This identifier specifies a string that will be sent to the FTP client at the beginning of every FTP session.

Attributes

Data type | MULTI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty list

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer

See Also

GreetingMessage


MD_HTTP_CUSTOM

This identifier contains custom headers that are included by the server in the standard HTML header sent to the client browser. Each string in this identifier is formatted as a key name and value pair, Keyname, Value.

Attributes

Data type | MUTLI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Empty list

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

HttpCustomHeaders


MD_HTTP_EXPIRES

This identifier specifies when an HTML document expires. If a document is accessed by a browser, and the browser, using the value of this identifier, determines that the object has expired, the browser should request an update from the server instead of displaying the cached version of the document.

The expiration time may be set statically or dynamically. If the value is marked as dynamic, the expiration date passed to the client with an HTML document is the current time plus the number of seconds specified. If the value is marked as static, a specific and absolute time and date are passed to the client as an expiration date. If the numeric portion of the value of this identifier is 0xFFFFFFFF, the HTML document never expires. The string format is D,SecondsUntilExpiration for dynamic expiration, or S,ValidGMTTime for an static expiration date.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
D, 0xFFFFFFFF (Never expires)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

HttpExpires


MD_HTTP_PICS

This identifier specifies the World Wide Web Consortium's (W3C) Platform for Internet Content Selection (PICS) rating header. For more information on PICS, see the W3C Web site at http://www.w3.org.

Attributes

Data type | MULTI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Empty list

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

HttpPics


MD_HTTP_REDIRECT

This identifier specifies the directory or URL to which clients are redirected when they attempt to access a specific resource. There are two general forms that the value for this identifier can take, one with wildcards, one without.

The format for the string without wildcards is simply Destination, Flag, where Destination can specify either a URL or a virtual path to a file. Flag can have one of three values: EXACT_DESTINATION indicates that the value provided for Destination should be considered an absolute target location; CHILD_ONLY indicates that the value should be prepended to the filename of the request to be redirected; and PERMANENT indicates that this redirection will be permanent for this resource.

The wildcard format for the value of this string is more complex: *;Wildcard1;Destination1;Wildcard2;Destination2,Flag. Each Wildcard, Destination pair indicates that requests matching the wildcard are redirected to the specified destination. Flag can have the same values as the simple string format.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

HttpRedirect


MD_IISADMIN_EXTENSIONS

This identifier contains a list of CLSIDs for all registered administration extensions installed on the server.

Attributes

Data type | MULTI_SZ
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/IIsAdmin/Extensions/DCOMCLSIDS | Not applicable

Remarks

This identifier should be considered read-only.

See Also

Custom Extensions Interface


MD_IN_PROCESS_ISAPI_APPS

This identifier specifies a list of ISAPI applications that, if loaded, must run in the server process. The string format is Fullpath\Appname.DLL.

Attributes

Data type | MULTI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
ssinc.dll

httpodbc.dll

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService

Remarks

This identifier only indicates what ISAPI applications are required to run in-process. The inclusion of an application in this list does not imply that the application is automatically run at server startup. Note that there can be significant performance issues if too many applications are forced to run outside of the server process.

See Also

InProcessIsapiApps, MD_APP_ISOLATED


MD_IP_SEC

This identifier specifies the IP access restrictions for a URL. It can be used to grant or deny access to client browsers based on either their IP address or DNS host name. For detailed format information, please refer to the header file iiscnfg.h.

Attributes

Data type | BINARY REFERENCE
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
No IP security

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/MSFTPSVC/n/ROOT | IIsFtpVirtualDir
/LM/MSFTPSVC/n/ROOT/FtpVirtualDir | IIsFtpVirtualDir
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

IPSecurity


MD_IS_CONTENT_INDEXED

This identifier indicates whether the files in the directory tree should be indexed by the installed content indexing component.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory

See Also

ContentIndexed


MD_KEY_TYPE

This identifier specifies the type of a metabase key, and the IIS Admin Object that relates to that key. This identifier can be used to specify the key type, such as IIsWebServer or IIsWebVirtualDir, when creating or deleting IIS Admin Objects.

Attributes

Data type | STRING
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at all metabase keys:

See Also

KeyType


MD_LEVELS_TO_SCAN

This identifier specifies the number of virtual directory levels to scan in the metabase from the top of the tree (i.e., the ROOT virtual directory for a server) to build a list of directories to be monitored for file system changes. If a virtual directory is not included in the list then the IIS cache will not be flushed when a file change occurs in the directory. This list is also used for downlevel administration from previous versions (1.0 to 3.0) of IIS.

Attributes

Data type | DWORD
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
0 – 0xFFFFFFFF
Default Value
2

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/W3SVC | IIsWebService

See Also

DirectoryLevelsToScan


MD_LOG_ANONYMOUS

This identifier enables event logging for anonymous FTP user access and activity.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer

See Also

LogAnonymous


MD_LOG_NONANONYMOUS

This identifier enables event logging of nonanonymous FTP user access and activity.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer

See Also

LogNonAnonymous


MD_LOG_PLUGIN_MOD_ID

This identifier specifies the CLSID for the logging module.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/Logging/IIsLogModule | IIsLogModule

See Also

LogModuleId, MD_LOG_PLUGIN_UI_ID


MD_LOG_PLUGIN_ORDER

This identifier specifies the order of the logging modules.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

LogPluginClsid


MD_LOG_PLUGIN_UI_ID

This identifier specifies the CLSID for the logging module's user interface.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/Logging/IIsLogModule | IIsLogModule

See Also

LogModuleUiId, MD_LOG_PLUGIN_MOD_ID


MD_LOG_PLUGINS_AVAILABLE

This identifier specifies a string that contains a comma-delimited list that names the logging modules that are available.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC/INFO | IIsFtpInfo
/LM/W3SVC/INFO | IIsWebInfo

See Also

LogModuleList


MD_LOG_TYPE

This identifier indicates whether logging is enabled for the service.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
MD_LOG_TYPE_ENABLED
Constant | Value | Description
MD_LOG_TYPE_DISABLED | 0x00000000 | Logging disabled
MD_LOG_TYPE_ENABLED | 0x00000001 | Logging enabled

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

This identifier should be considered read-only.

See Also

LogType


MD_LOGEXT_FIELD_MASK

This identifier contains flags that are used to indicate to Microsoft® Windows NT® what types of information are written to the log file during logging events.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
MD_EXTLOG_CLIENT_IP |

MD_EXTLOG_TIME |

MD_EXTLOG_METHOD |

MD_EXTLOG_URI_STEM |

MD_EXTLOG_HTTP_STATUS
Constant | Value | Description
MD_EXTLOG_DATE | 0x00000001 | Log date
MD_EXTLOG_TIME | 0x00000002 | Log time
MD_EXTLOG_CLIENT_IP | 0x00000004 | Log client IP address
MD_EXTLOG_USERNAME | 0x00000008 | Log user name
MD_EXTLOG_SITE_NAME | 0x00000010 | Log site name
MD_EXTLOG_COMPUTER_NAME | 0x00000020 | Log computer name
MD_EXTLOG_SERVER_IP | 0x00000040 | Log server's own IP address
MD_EXTLOG_METHOD | 0x00000080 | Log protocol method
MD_EXTLOG_URI_STEM | 0x00000100 | Log URI stem
MD_EXTLOG_URI_QUERY | 0x00000200 | Log URI query
MD_EXTLOG_HTTP_STATUS | 0x00000400 | Log HTTP status
MD_EXTLOG_WIN32_STATUS | 0x00000800 | Log WIN32 status
MD_EXTLOG_BYTES_SENT | 0x00001000 | Log total bytes sent
MD_EXTLOG_BYTES_RECV | 0x00002000 | Log total bytes received
MD_EXTLOG_TIME_TAKEN | 0x00004000 | Log total time elapsed
MD_EXTLOG_SERVER_PORT | 0x00008000 | Log server port
MD_EXTLOG_USER_AGENT | 0x00010000 | Log user agent
MD_EXTLOG_COOKIE | 0x00020000 | Log cookie
MD_EXTLOG_REFERER | 0x00040000 | Log referrer
MD_EXTLOG_PROTOCOL_VERSION | 0x00080000 | Log client server protocol version

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

LogExtFileFlags


MD_LOGFILE_DIRECTORY

This identifier specifies a default directory for all logging-related information, including the log file.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
%WinDir%\System32\LogFiles

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

LogFileDirectory


MD_LOGFILE_PERIOD

This identifier specifies how often Microsoft® Windows NT® should create a new log file. The value can indicate that the server is to create a new log file daily, weekly, or monthly, or if the value is MD_LOGFILE_PERIOD_MAXSIZE, a new log file is created when the current log file has reached the maximum size specified in MD_LOGFILE_TRUNCATE_SIZE.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
MD_LOGFILE_PERIOD_DAILY
Constant | Value | Description
MD_LOGFILE_PERIOD_MAXSIZE | 0x00000000 | Create log file after reaching maximum size
MD_LOGFILE_PERIOD_DAILY | 0x00000001 | Create new log file daily
MD_LOGFILE_PERIOD_WEEKLY | 0x00000002 | Create new log file weekly
MD_LOGFILE_PERIOD_MONTHLY | 0x00000003 | Create new log file monthly

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

LogFilePeriod, MD_LOGFILE_TRUNCATE_SIZE


MD_LOGFILE_TRUNCATE_SIZE

This identifier specifies the maximum size of the log file, in bytes. If the server is required to write to the log file after the log file has reached its maximum size, a new log file will be created.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
1 – 0xFFFFFFFF (unlimited)
Default Value
2048 (2 MB)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

LogFileTruncateSize


MD_LOGON_METHOD

This identifier specifies the logon method for clear text (Basic) authentication. Each user attempting to log on to the server must have access permissions corresponding to the appropriate logon method.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
MD_LOGON_INTERACTIVE
Constant | Value | Description
MD_LOGON_INTERACTIVE | 0x00000000 | Log on locally
MD_LOGON_BATCH | 0X00000001 | Log on as batch job
MD_LOGON_NETWORK | 0x00000002 | Log on over network

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

LogonMethod


MD_LOGSQL_DATA_SOURCES

This identifier specifies the name of the ODBC data source to which Microsoft® Windows NT® will write data during logging events.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
HTTPLOG

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

The logging module's CLSID determines whether Microsoft® Windows NT® will log to an ODBC data source, or to the file system.

See Also

LogOdbcDataSource


MD_LOGSQL_PASSWORD

This identifier specifies the ODBC database password to be used when writing information to the database during logging events.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

LogOdbcPassword


MD_LOGSQL_TABLE_NAME

This identifier specifies the name of the ODBC database table to which Microsoft® Windows NT® will write information during logging events.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
InternetLog

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

LogOdbcTableName


MD_LOGSQL_USER_NAME

This identifier specifies the ODBC database user name to be used when writing information to the database during logging events.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
InternetAdmin

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

LogOdbcUserName


MD_MAX_BANDWIDTH

This metabase identifier specifies the maximum network bandwidth allowable, in kilobytes per second. This limitation only applies to static files, such as .htm files, not to applications.

Attributes

Data type | DWORD
Default inheritance | Global - Not inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
0 – 0xFFFFFFFF
Default Value
0xFFFFFFFF (Unlimited)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM | IIsComputer
/LM/W3SVC/n | IIsWebServer

Remarks

MD_MAX_BANDWIDTH can be set at either the local machine level or the server level. The identifier is not inheritable, but the value of MD_MAX_BANDWIDTH set at the local machine level applies to all instances of servers that do not have instance-specific MD_MAX_BANDWIDTH settings of their own. Values for this identifier set at the individual server level are permitted to exceed the global values established at the local machine.

See Also

MaxBandWidth


MD_MAX_BANDWIDTH_BLOCKED

This identifier specifies the maximum number of asynchronous requests to be queued in the outstanding idle queue when the maximum bandwidth of the server is exceeded.

Attributes

Data type | DWORD
Default inheritance | Global - Not inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
0 – 0xFFFFFFFF
Default Value
0xFFFFFFFF (unlimited)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM | IIsComputer
/LM/W3SVC/n | IIsWebServer

Remarks

MD_MAX_BANDWIDTH_BLOCKED can be set at either the local machine level or the server level. The identifier is not inheritable, but the value of MD_MAX_BANDWIDTH_BLOCKED set at the local machine level applies to all instances of servers that do not have instance-specific MD_MAX_BANDWIDTH_BLOCKED settings of their own. Values for this identifier set at the individual server level are permitted to exceed the global values established at the local machine.

See Also

MaxBandWidthBlocked


MD_MAX_CLIENTS_MESSAGE

This identifier contains the string that is sent to all clients that attempt to connect to the service or server once the service or server's maximum number of connections, specified in MD_MAX_CONNECTIONS, has been reached.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer

See Also

MaxClientsMessage, MD_MAX_CONNECTIONS


MD_MAX_CONNECTIONS

This property specifies the maximum number of simultaneous network connections to the service or server.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
0 – 0xFFFFFFFF for Microsoft® Windows NT® Server

0 – 10 for Windows NT Workstation and Microsoft Windows™ 95

Default Value
0xFFFFFFFF (unlimited) for Windows NT Server

10 for Windows NT Workstation and Windows 95

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

Users attempting to connect to the service or server after MD_MAX_CONNECTIONS has been reached will be sent the string specified by MD_MAX_CLIENTS_MESSAGE.

See Also

MaxConnections, MD_MAX_CLIENTS_MESSAGE


MD_MAX_ENDPOINT_CONNECTIONS

This identifier specifies the maximum number of listen sockets that will be aggregated to one network endpoint (e.g., a particular port).

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
0 – 0xFFFFFFFF
Default Value
0xFFFFFFFF (unlimited)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

The limits specified in this identifier are imposed, regardless of the number of domains sharing the same network endpoint. For example, if an provider had 1000 Web sites all listening to a single IP:Port address with twenty listen sockets, the server will aggregate the Web site listen sockets up to the value specified in this identifier.

See Also

MaxEndpointConnections


MD_MIME_MAP

This identifier contains a list of Multipurpose Internet Mail Extensions (MIME) file extension associations. This information is used by the computer to determine what applications are capable of processing or viewing a given document type. Each string in the list specifies the MIME type, and the file extension that is associated with that type. The string format for each entry is MIMEType, Extension.

Attributes

Data type | MULTI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM | IIsComputer
/LM/MimeMap | IIsMimeMap
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

The /LM/MimeMap key establishes the default values for the machine. These default values can be overriden at the service or server level.

See Also

MimeMap


MD_MSDOS_DIR_OUTPUT

This identifier specifies the format of the directory listing to be sent to an FTP client when the server receives the list command. A value of TRUE indicates the server will send the file listing in MS-DOS format, while a value of FALSE indicates that the server is to send the listing in UNIX format.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer

See Also

MSDOSDirOutput


MD_NET_LOGON_WKS

This identifier indicates the criteria that will be used by the domain controller for domain logon restrictions from computers running Microsoft® Windows NT® Workstation. If this identifier is set to MD_NETLOGON_WKS_NONE, logon restrictions are based on domain and workstation information. The value MD_NETLOGON_WKS_IP indicates that the domain controller should base restrictions on the workstation IP address, and MD_NETLOGON_WKS_DNS indicates restrictions should be based on the workstation DNS name.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
MD_NETLOGON_WKS_NONE
Constant | Value | Description
MD_NETLOGON_WKS_NONE | 0x00000000 | Workstation restrictions only
MD_NETLOGON_WKS_IP | 0x00000001 | Restrictions based on IP address
MD_NETLOGON_WKS_DNS | 0x00000002 | Restrictions based on DNS host name

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

NetLogonWorkstation


MD_NTAUTHENTICATION_PROVIDERS

This identifier specifies a comma-delimited list of Microsoft® Windows NT® authentication schemes, such as Windows NT Challenge/Response implementation, that are available. This list is provided when the MD_AUTH_NT flag is set in MD_AUTHORIZATION.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
Valid authentication provider
Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

NTAuthenticationProviders


MD_POOL_IDC_TIMEOUT

This identifier specifies the time-out value in seconds for Internet database connection pooling. A value of zero specifies no pooling.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
0 – 0x80000000 (0 to 2GB)
Default Value
30 seconds

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

PoolIDCTimeout


MD_PROCESS_NTCR_IF_LOGGED_ON

This identifier enables Microsoft® Windows NT® Challenge/Response authentication processing.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

ProcessNTCRIfLoggedOn


MD_PUT_READ_SIZE

This identifier specifies the chunk size to be sent to the client in the HTTP 1.1 Transfer Encoding header field.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
0x00000400 – 0x00010000 (1K – 64K bytes)
Default Value
0x00002000 (8K)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

Intranet applications may benefit from values for this property at the upper end of the range. For Internet applications, values at the lower end of the range are more appropriate.

See Also

PutReadSize


MD_REALM

This identifier specifies the realm that is passed to the client when the user has been denied access to an object by Basic authentication.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

Realm


MD_REDIRECT_HEADERS

This identifier specifies additional redirection headers.

Attributes

Data type | String
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

Multiple headers may be specified if they are separated by carriage return/line feed ("\r\n") pairs. There should not be a trailing carriage return/line feed after the final header.

See Also

RedirectHeaders


MD_SCRIPT_MAPS

This identifier specifies the file name extensions of applications for script processor mappings. Two flags are allowed for each extension association. The first flag, MD_SCRIPTMAPFLAG_SCRIPT, indicates that scripts with that particular extension are allowed to run in directories given Script permissions. If this flag is not set, then the script can only be executed in directories flagged for Execute permissions.

If the flag MD_SCRIPTMAPFLAG_CHECK_PATH_INFO is set, the server attempts to access the PATH_INFO portion of the URL, as a file, before starting the scripting engine. If the file can't be opened, or doesn't exist, an error is returned to the client.

The string format is Extension, ScriptProcessor, Flags.

Attributes

Data type | MULTI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Not applicable
Constant | Value | Description
MD_SCRIPTMAPFLAG_SCRIPT | 0x00000001 | Allowed to run if permissions set to script
MD_SCRIPTMAPFLAG_CHECK_PATH_INFO | 0x00000004 | Server checks PATH_INFO

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

ScriptMaps


MD_SCRIPT_TIMEOUT

This identifier specifies the maximum number of seconds the server will wait for a CGI script to finish execution.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
10 – 0x80000000
Default Value
900 (15 minutes)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/n | IIsWebServer

See Also

CGITimeout


MD_SECURE_BINDINGS

This identifier specifies a string that is used by IIS to determine what secure network endpoints are used by the server instance. The string format is IP:Port.

Attributes

Data type | MULTI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty string if no keys installed

:443: if keys installed

Metabase Keys

This identifier is available at the following metabase key:

Metabase Path | Key Type
/LM/W3SVC/n | IIsWebServer

Remarks

The IP component of each string is optional. If it is not provided, IIS assumes that any IP address is allowable (wildcard).

See Also

SecureBindings, MD_SERVER_BINDINGS


MD_SERVER_AUTOSTART

This identifier indicates whether the server instance will start automatically when its parent service is started. A value of TRUE indicates that the server is to restart when the service is started, while a value of FALSE indicates that the server must be started independently from the service.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
TRUE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

This identifier is reset automatically when a server instance is stopped or restarted, to maintain state across service restarts. For example, if a server is stopped, the value of this identifier is set to FALSE so that if the service is stopped and restarted, the server will remain stopped. Likewise, if a server is started, this identifier is set to TRUE, allowing the server to remain running whenever the service is running.

See Also

ServerAutoStart


MD_SERVER_BINDINGS

This identifier specifies a string that is used by IIS to determine what network endpoints are used by the server instance. The string format is IP:Port:Hostname. Both the IP and Hostname parameter of the string are optional. Any unspecified parameters default to an all-inclusive wildcard.

Attributes

Data type | MULTI_SZ
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
:80: for Web Service

:21: for FTP Service

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

Both the IP and Hostname parameter of the string are optional. Any unspecified parameters default to an all-inclusive wildcard. Thus, the default value, :80:, enables IIS to bind to any and all network nodes with the port equal to 80, no matter what the IP address or host name of the remote machine.

See Also

ServerBindings, MD_SECURE_BINDINGS


MD_SERVER_COMMAND

This identifier allows an application to give the server commands to stop, start, pause, or continue. Applications can test the identifier MD_SERVER_STATE to determine if the server has responded to a command issued via the identifier MD_SERVER_COMMAND.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable
Constant | Value | Description
MD_SERVER_COMMAND_START | 0x00000001 | Send start command
MD_SERVER_COMMAND_STOP | 0x00000002 | Send stop command
MD_SERVER_COMMAND_PAUSE | 0x00000003 | Send pause command
MD_SERVER_COMMAND_CONTINUE | 0x00000004 | Send continue command

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC/n | IIsWebServer

Remarks

If the server encounters an error while changing states, the MD_WIN32_ERROR identifier will be set to the appropriate failure code.

See Also

MD_SERVER_STATE, MD_WIN32_ERROR


MD_SERVER_COMMENT

This identifier specifies a comment string for the service or server.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Empty string

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

ServerComment


MD_SERVER_CONFIGURATION_INFO

This identifier contains flags, set by the server upon startup, that can be read by applications to determine if various extensions to server functionality have been installed, including SSL (Secure Sockets Layer).

Attributes

Data type | DWORD
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable
Constant | Value | Description
MD_SERVER_CONFIG_SSL_40 | 0x00000001 | 40-bit SSL processing available on server
MD_SERVER_CONFIG_SSL_128 | 0x00000002 | 128-bit SSL processing available on server
MD_SERVER_CONFIG_ALLOW_ENCRYPT | 0x00000004 | Encryption available on server
MD_SERVER_CONFIG_AUTO_PW_SYNC | 0x00000008 | Subauthenticator is installed on server

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC/INFO | IIsWebInfo

See Also

ServerConfigFlags


MD_SERVER_LISTEN_BACKLOG

This identifier specifies the maximum number of outstanding socket connections that can be queued.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
5 – 500
Default Value
(Depends on MD_SERVER_SIZE)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

The default value for this identifier is based on the value of the MD_SERVER_SIZE identifier as follows: Small server = 5 queued connections, Medium server = 40 queued connections, Large server = 100 queued connections. Change the value of MD_SERVER_LISTEN_BACKLOG only to override the suggested, default values.

See Also

ServerListenBacklog, MD_SERVER_SIZE


MD_SERVER_LISTEN_TIMEOUT

This identifier specifies the number of seconds the server should wait before disconnecting a client who has connected but has not yet sent any data.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
0 – 0xFFFFFFFF
Default Value
120 (2 minutes)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

See Also

ServerListenTimeout


MD_SERVER_SIZE

This identifier specifies how much traffic is anticipated on the service or server.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
MD_SERVER_SIZE_MEDIUM
Constant | Value | Description
MD_SERVER_SIZE_SMALL | 0x00000000 | Anticipate <10,000 requests/day
MD_SERVER_SIZE_MEDIUM | 0x00000001 | Anticipate 10,000 – 100,000 requests/day
MD_SERVER_SIZE_LARGE | 0x00000002 | Anticipate >100,000 requests/day

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC | IIsFtpService
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

This identifier is used internally by IIS to appropriately size a number of its data structures. It is also used in calculating the MD_SERVER_LISTEN_BACKLOG value.

See Also

ServerSize, MD_SERVER_LISTEN_BACKLOG


MD_SERVER_STATE

This identifier indicates the current state of the server instance.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable
Constant | Value | Description
MD_SERVER_STATE_STARTING | 0x00000001 | Server starting
MD_SERVER_STATE_STARTED | 0x00000002 | Server started
MD_SERVER_STATE_STOPPING | 0x00000003 | Server stopping
MD_SERVER_STATE_STOPPED | 0x00000004 | Server stopped
MD_SERVER_STATE_PAUSING | 0x00000005 | Server pausing
MD_SERVER_STATE_PAUSED | 0x00000006 | Server paused
MD_SERVER_STATE_CONTINUING | 0x00000007 | Server continuing

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC/n | IIsFtpServer
/LM/W3SVC/n | IIsWebServer

Remarks

This identifier should be considered read-only. To send commands to the server, use the MD_SERVER_COMMAND identifier.

See Also

ServerState, MD_SERVER_COMMAND


MD_SSI_EXEC_DISABLED

This identifier indicates whether Server Side Includes (SSI) #exec directives are disabled.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
FALSE (SSI enabled)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

SSIExecDisable


MD_SSL_ACCESS_PERM

This metabase identifier contains flags that specify Secure Socket Layer (SSL) permissions attributes for a resource.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
0x00000000 (No SSL protocols required)
Constant | Value | Description
MD_ACCESS_SSL | 0x00000008 | SSL permissions required
MD_ACCESS_NEGO_CERT | 0x00000020 | Client certificate optional
MD_ACCESS_REQUIRE_CERT | 0x00000040 | Client certificate required
MD_ACCESS_MAP_CERT | 0x00000080 | Server will map client certificate to Microsoft® Windows NT® account
MD_ACCESS_SSL128 | 0x00000100 | SSL permissions, with 128-bit key, required

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

If the MD_ACCESS_NEGO_CERT bit is set, and the MD_ACCESS_REQUIRE_CERT bit is unset, the server will request a certificate from the client. If the client is unable to provide the correct, or any, certificate, the connection is nonetheless maintained. However, if both of these bits are set, then the connection will be terminated if the client is unable to provide the correct certificate. Note that if MD_ACCESS_NEGO_CERT is unset, the server will not request a certificate, no matter what the setting of MD_ACCESS_REQUIRE_CERT. Also note that some browsers, including some versions of Internet Explorer, will terminate the connection if they are unable to provide the correct certificate, regardless of the setting of the MD_ACCESS_REQUIRE_CERT bit.

See Also

AccessSSLFlags


MD_SSL_KEY_PASSWORD

This identifier specifies the password for the SSL server certificate private key.

Attributes

Data type | BINARY REFERENCE
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService

See Also

MD_SSL_KEY_REQUEST, MD_SSL_PRIVATE_KEY, MD_SSL_PUBLIC_KEY


MD_SSL_KEY_REQUEST

This identifier specifies the original request that was sent to the authority to get the public key.

Attributes

Data type | BINARY REFERENCE
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService

See Also

MD_SSL_KEY_PASSWORD, MD_SSL_PRIVATE_KEY, MD_SSL_PUBLIC_KEY


MD_SSL_PRIVATE_KEY

This identifier specifies the SSL server certificate private key.

Attributes

Data type | BINARY REFERENCE
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService

See Also

MD_SSL_KEY_PASSWORD, MD_SSL_KEY_REQUEST, MD_SSL_PUBLIC_KEY


MD_SSL_PUBLIC_KEY

This identifier specifies the SSL server certificate private key.

Attributes

Data type | BINARY REFERENCE
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService

See Also

MD_SSL_KEY_PASSWORD, MD_SSL_KEY_REQUEST, MD_SSL_PRIVATE_KEY


MD_UPLOAD_READAHEAD_SIZE

This identifier establishes the number of bytes a Web server will read into a buffer and pass to an ISAPI application. This occurs once. The ISAPI application receives any additional data directly from the client.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
0 – 0xFFFFFFFF (0 to 4GB)
Default Value
C000 (48K bytes)

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

See Also

UploadReadAheadSize


MD_USE_HOST_NAME

This identifier specifies whether the server sends its DNS (Domain Name Service) name to the client on redirects, or if just the IP (Internet Protocol) address is used. A value of TRUE indicates DNS host names are used, while FALSE indicates that only IP addresses are used.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_SERVER

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer

Remarks

If the client sends the host header, as most clients do, the server will use the value specified in the host header for this identifier, regardless of the server's own internal setting.

See Also

UseHostName


MD_VR_PASSTHROUGH

This identifier enables user authentication passthrough, using authentication schemes that support delegation, for gaining access to Universal Naming Convention (UNC) virtual directories.

Attributes

Data type | DWORD
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Value Range
TRUE | FALSE
Default Value
FALSE

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService
/LM/W3SVC/n | IIsWebServer
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory | IIsWebDirectory
/LM/W3SVC/n/ROOT/WebVirtualDir/WebDirectory/WebFile | IIsWebFile

Remarks

Microsoft® Windows NT® Challenge/Response does not support delegation.

See Also

UNCAuthenticationPassthrough


MD_VR_PASSWORD

This identifier specifies the password used to gain access to a Universal Naming Convention (UNC) virtual directory. The password is stored in encrypted form, but is returned and set decrypted.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC/n/ROOT | IIsFtpVirtualDir
/LM/MSFTPSVC/n/ROOT/FtpVirtualDir | IIsFtpVirtualDir
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir

See Also

UNCPassword


MD_VR_PATH

This identifier specifies the actual physical path associated with a virtual directory.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC/n/ROOT | IIsFtpVirtualDir
/LM/MSFTPSVC/n/ROOT/FtpVirtualDir | IIsFtpVirtualDir
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir

See Also

Path


MD_VR_USERNAME

This identifier specifies the account user name for a Universal Naming Convention (UNC) virtual root. The account specified, in combination with the associated password specified in MD_VR_PASSWORD, is used to access UNC virtual directories named in MD_VR_PATH.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/MSFTPSVC/n/ROOT | IIsFtpVirtualDir
/LM/MSFTPSVC/n/ROOT/FtpVirtualDir | IIsFtpVirtualDir
/LM/W3SVC/n/ROOT | IIsWebVirtualDir
/LM/W3SVC/n/ROOT/WebVirtualDir | IIsWebVirtualDir

See Also

UNCUserName, MD_VR_PASSWORD, MD_VR_PATH


MD_WAM_PWD

This property specifies the password for the account that IIS uses by default as the MTS package identity for newly created IIS out-of-process application packages. The values of this property and its companion property, MD_WAM_USER_NAME, are set when IIS is installed, and match the password and user name values in the Microsoft® Windows NT® user account (IWAM_MachineName, where MachineName is the name of the machine on which IIS is installed) established at the same time. It is recommended that you do not change the value of this property. If you do change this value, the Windows NT account password must be changed to the identical value, and you must also synchronize existing IIS out-of-process package identities using MTS Explorer to edit the user name and password values found on the Identity tab of the property sheet for each package. In-process application packages are not affected by these property values.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
Generated by the setup program when IIS is installed.

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService

See Also

WAMUserPass, WAMUserName, MD_WAM_USER_NAME


MD_WAM_USER_NAME

This property specifies the account user name that IIS uses by default as the MTS package identity for newly created IIS out-of-process application packages. The values of this property and its companion property, MD_WAM_PWD, are set when IIS is installed, and match the user name and password values in the Microsoft® Windows NT® user account established at the same time. It is recommended that you do not change the value of this property. If you do change this value, be certain to change it to a valid Windows NT user account, and change MD_WAM_PWD to the corresponding password for the new account.

Note Changes to the value of this property and MD_WAM_PWD may disrupt operation of existing IIS out-of-process application packages. You can synchronize package identities using the MTS Explorer to edit the user name and password values found on the Identity tab of the property sheet for each package. See MD_WAM_PWD for additional information. In-process application packages are not affected by these property values.

Attributes

Data type | STRING
Default inheritance | Inheritable
User type | IIS_MD_UT_FILE

Values

Default Value
IWAM_MachineName, where MachineName is the name of the machine on which IIS is installed.

Metabase Keys

This identifier is available at the following metabase keys:

Metabase Path | Key Type
/LM/W3SVC | IIsWebService

See Also

WAMUserName, WAMUserPass, MD_WAM_PWD


MD_WIN32_ERROR

This identifier indicates the Microsoft® Win32® error status code.

Attributes

Data type | DWORD
Default inheritance | Not inheritable
User type | IIS_MD_UT_SERVER

Values

Default Value
Not applicable

Metabase Keys

This identifier is available at all metabase keys:


Web Application Management Interface

You can manage your Web applications by creating custom C++ programs that use the IWamAdmin interface described in this section, or by using ASP scripts with the IIS Admin Objects, IIsWebVirtualDir and IIsWebDirectory.

This section includes:

  • About Web Application Management explains the overall process of Web application management using the IWamAdmin interface.
  • Using Web Application Management provides details on how you use the IWamAdmin interface to manage your Web applications.
  • IWamAdmin Interface Reference provides the syntax and details of the methods of the IWamAdmin interface.


About Web Application Management

A Web application is composed of script and component files within a directory structure boundary. The application directory structure must be associated with a Web server, and the structure must be mirrored in the IIS Metabase. You can use the Internet Service Manager user interface, the IIS Admin Objects with ASPscripts, or the IIS Admin Base Object with C++ to establish your application's directory structure in the metabase. Every file and directory subordinate to your application's starting point directory will be included in its boundary, except for those directories and files that are contained in a previously defined application.

After you have established your application's directory structure in the metabase, you can use the IIS Admin Objects to create an application definition package that IIS and MTS use to manage the execution of the application. Additional methods are available to delete or unload the application, or to retrieve its status. You can also use special methods to disable an application definition package while retaining the definition, so you can rename the application, or move or copy it to another location in the metabase and then enable its definition package again.

You can find iwamreg.h and other relevant header files in the \inetpub\iissamples\sdk\include directory.


Using Web Application Management

You can use the IWamAdmin interface with your C++ programs to manage your Web applications. This interface provides the same functionality as the Automation methods available in the IIS Admin Objects. You can use the IWamAdmin interface to create Web applications for in-process or out-of-process execution, and to reconfigure them from in-process to out-of-process or the reverse. You can also retrieve the status of your applications and unload applications running out-of-process.

IWamAdmin also enables you to delete applications, which removes the application definitions but does not remove the directories and files that compose the application. You can use special interface methods to mark applications as deleted so that you can move, copy, or rename them in the metabase, and later restore them to application status.


IWamAdmin Interface Reference

The IWamAdmin interface implements the following methods:

Method | Description
IWamAdmin::AppCreate | Creates a new Web application or reconfigures an existing application.
IWamAdmin::AppDelete | Deletes an application definition.
IWamAdmin::AppDeleteRecoverable | Marks a Web application as deleted so it can be moved or copied and then recovered.
IWamAdmin::AppGetStatus | Retrieves the status of a Web application.
IWamAdmin::AppRecover | Restores an application deleted with AppDeleteRecover.
IWamAdmin::AppUnload | Unloads an application that is running out-of-process.


IWamAdmin::AppCreate

The IWamAdmin::AppCreate method creates a Web application definition and marks it as running in-process or out-of-process. If an application already exists at the specified path, this method reconfigures the application from in-process to out-of-process execution or vice versa.

Syntax

HRESULT STDMETHODCALLTYPE AppCreate(
  LPCWSTR szMDPath,  // [string][unique][in]
  BOOL fInProc       // [in]
);

Parameters

szMDPath
Specifies the metabase path to the starting point of the application.
fInProc
Specifies whether the application being created is to run in-process (TRUE) or out-of-process (FALSE). If the application already exists and is running in-process, specifying this flag as FALSE will cause the application definition to be deleted and a new application created to run out-of-process. If the application already exists and is running out-of-process, specifying this flag as TRUE will cause the application definition to be deleted and a new application created to run in-process. If the application exists and the setting of fInProc matches the application's existing in-process/out-of-process status then this method will cause no change to the application definition.

Return Values

The method will return NO_ERROR if the method succeeded, or other error codes converted to HRESULT if the method failed.


IWamAdmin::AppDelete

The IWamAdmin::AppDelete method deletes a Web application definition from this metabase key, and optionally all subordinate keys. If the application is running, it will be shut down. All resources associated with the application, such as out-of-process packages, will be released. This action cannot be undone.

Syntax

HRESULT STDMETHODCALLTYPE AppDelete(
  LPCWSTR szMDPath,  // [string][unique][in]
  BOOL fRecursive    // [in]
);

Parameters

szMDPath
Specifies the metabase path to the starting point of the application.
fRecursive
Specifies whether application definitions are also to be deleted from all subordinate keys (TRUE), or just the application at this key (FALSE).

Return Values

The method will return NO_ERROR if the method succeeded, including the case that no application was defined at the specified path. If the method fails, other error codes converted to HRESULT will be returned.


IWamAdmin::AppDeleteRecoverable

The IWamAdmin::AppDeleteRecoverable method deletes a Web application definition and allows it to be recovered later with the IWamAdmin::AppRecover method. You use this method primarily when moving, copying, or renaming metabase keys.

This method shuts down the specified application if it is running, marks the metabase key as deleted, and frees up resources such as registered MTS transaction packages. The metabase key is marked as stopped and subsequent requests to run the application will return an error. The metabase properties MD_APP_ROOT (Automation name AppRoot) and MD_APP_FRIENDLY_NAME (Automation name AppFriendlyName will not be deleted.

Syntax

HRESULT STDMETHODCALLTYPE AppDeleteRecoverable(
  LPCWSTR szMDPath,  // [string][unique][in]
  BOOL fRecursive    // [in]
);

Parameters

szMDPath
Specifies the metabase path to the starting point of the application.
fRecursive
Specifies whether applications are to be recoverably deleted from this and all subordinate keys (TRUE), or just the application at this key (FALSE).

Return Values

The method will return NO_ERROR if the method succeeded, including the case that no application was defined at the specified path. If the method fails, other error codes converted to HRESULT will be returned.

Remarks

It is recommended, but not strictly necessary, that you use this method when copying metabase keys. However, keys that have not been marked as deleted with this method are available during the copy process and may receive user requests that may cause unexpected results.


IWamAdmin::AppGetStatus

The IWamAdmin::AppGetStatus method retrieves the current status of a Web application.

Syntax

HRESULT STDMETHODCALLTYPE AppGetStatus(
  LPCWSTR szMDPath,           // [string][unique][in]
  DWORD __RPC_FAR *pdwStatus  // [out]
);

Parameters

szMDPath
Specifies the metabase path to the starting point of the application.
pdwStatus
Receives one of the following values indicating the status of the application:
APPSTATUS_NOTDEFINED | No application is defined at the specified path.
APPSTATUS_RUNNING | The application is running
APPSTATUS_STOPPED | The application is not running.

Return Values

The method will return NO_ERROR if the method succeeded, and status is returned in pdwStatus. If the method fails, other error codes converted to HRESULT will be returned.


IWamAdmin::AppRecover

The IWamAdmin::AppRecover method reinstates a Web application definition that was previously deleted with the IWamAdmin::AppDeleteRecoverable method. If the application specified was not previously deleted, it will be reregistered with MTS.

Syntax

HRESULT STDMETHODCALLTYPE AppRecover(
  LPCWSTR szMDPath,  // [string][unique][in]
  BOOL fRecursive    // [in]
);

Parameters

szMDPath
Specifies the metabase path to the starting point of the application.
fRecursive
Specifies whether applications are also to be recovered for all subordinate keys (TRUE), or just the application at this key (FALSE).

Return Values

The method will return NO_ERROR if the method succeeded, including the case that no application was defined at the specified path. If the method fails, other error codes converted to HRESULT will be returned.


IWamAdmin::AppUnload

The IWamAdmin::AppUnload method unloads a Web application that is running out-of-process. All of the application's resources are released and the application's process is terminated. If the application is running in-process, the application is released if it is not being referenced by any other applications.

Syntax

HRESULT STDMETHODCALLTYPE AppUnLoad(
  LPCWSTR szMDPath,  // [string][unique][in]
  BOOL fRecursive    // [in]
);

Parameters

szMDPath
Specifies the metabase path to the starting point of the application.
fRecursive
Specifies whether applications are also to be unloaded from all subordinate keys (TRUE), or just the application at this key (FALSE).

Return Values

The method will return NO_ERROR if the method succeeded, including the cases that no application was defined at the specified path, or the application is not running. If the method fails, other error codes converted to HRESULT will be returned.


Custom Extensions Interface

You can add your custom DCOM interfaces to Internet Information Server (IIS) and make them available to other programs during IIS operation. The IADMEXT interface enables you to specify your interfaces' CLSIDs to the IISADMIN module, which then stores references to them in the metabase. Custom interfaces to extend inter-computer replication, described in the Replication Extension Interface topic, are examples of interfaces registered with IIS using the Custom Extensions Interface.

This section contains:

  • About Custom Extensions, which provides a conceptual outline of how custom extensions work, and how the IISADMIN module processes their installation.
  • Using Custom Extensions, which provides details on how you can use the IADMEXT interface to install your custom extension interfaces.
  • IADMEXT Interface Reference, which lists the syntax and details of the methods your interface should provide so that your custom extensions will be loaded by IISADMIN.


About Custom Extensions

You can register the CLSIDs associated with your custom DCOM interfaces with IIS by creating an in-process COM object that exposes the IADMEXT interface. This interface is discussed in Using Custom Extensions and IADMEXT Interface Reference. IISADMIN calls your interface methods and collects your CLSIDs, then stores them in the metabase where they will be available until IISADMIN terminates IIS services.

The DCOM CLSIDs stored in the metabase can be enumerated and called from other computers, so you should not register in-process COM interfaces.

You can find iadmext.h and other relevant header files in the \inetpub\iissamples\sdk\include directory.


Using Custom Extensions

To take advantage of IIS custom extensions, your program must register itself as an in-process COM interface, and you must place a subkey named by its CLSID in the registry under the key specified by IISADMIN_EXTENSIONS_REG_KEY. IISADMIN will co-create the interface and call your Initialize and EnumDcomCLSIDs methods when the service starts, and your Terminate method when the service terminates. Your program provides DCOM CLSIDs that IISADMIN registers and stores in a list in a metabase property where they are available until IISADMIN terminates IIS services.

The thread on which these are called is initialized as COINIT_MULTITHREADED. The IIS Admin Base Object interface, IMSAdminBase, will be available during these calls to provide access to the IIS Metabase.


IADMEXT Interface Reference

Your IADMEXT COM interface must expose the following methods:

Method | Description
IADMEXT::Initialize | Called by IISADMIN when it starts up to allow your program to perform its own initialization tasks.
IADMEXT::EnumDcomCLSIDs | Called by IISADMIN during its initialization so that your program can return CLSIDs to IISADMIN for registration in the metabase.
IADMEXT::Terminate | Called by IISADMIN when it terminates so your program can perform termination tasks.


IADMEXT::Initialize

The IADMEXT::Initialize method is called by IISADMIN when it initializes. Your program then performs any necessary initialization tasks.

Syntax

virtual HRESULT STDMETHODCALLTYPE Initialize(void) = 0;


IADMEXT::EnumDcomCLSIDs

After the initialization call to IASMEXT::Initialize, IISADMIN will call the IADMEXT::EnumDcomCLSIDs method to collect your DCOM CLSIDs. It will be called with index (dwEnumIndex) starting at zero and incrementing with each call until you return HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS).

Your returned CLSIDs will be added to the list of CLSIDs from other IIS custom extensions in the MULTISZ metabase property MD_IISADMIN_EXTENSIONS (user type IIS_MD_UT_SERVER) under the path /LM/IISADMIN/EXTENSIONS/DCOMCLSIDS.

Syntax

virtual HRESULT STDMETHODCALLTYPE EnumDcomCLSIDs(
  /* [size_is][out] */ CLSID *pclsidDcom,
  /* [in] */ DWORD dwEnumIndex
) = 0;

Parameters

pclsidDcom
Specifies the DCOM CLSID to be registered in the metabase.
dwEnumIndex
Receives an index for the requested CLSID, starting at zero and incrementing with each call until you return HRESULT_FROM_WIN32(ERROR_NO_MORE_ITEMS).


IADMEXT::Terminate

The IADMEXT::Terminate method is called by IISADMIN when it terminates, so your program can perform termination tasks, including unregistering your DCOM class factories.

Syntax

virtual HRESULT STDMETHODCALLTYPE Terminate(void) = 0;


Replication Extension Interface

IIS includes a replication feature that enables you to replicate configuration information from one computer to other computers. You can develop custom interfaces to extend the replication process for your own needs. You can use replication in a Web farm, or in a clustered computer environment using Microsoft® Windows NT ® Server 4.0 Enterprise Edition. In either situation, replication helps you synchronize configurations among computers.

This section includes:

  • About Replication Extensions, which provides an overview of replication and custom replication extensions.
  • Using the Replication Extension Interface, which explains the replication process and how your custom interface interacts with it.
  • IMSAdminReplication Interface Reference, which provides details of the methods you implement in your custom replication extension interface.


About Replication Extensions

You can use iissync.exe, a command line utility, to replicate the metabase, and you can extend this replication functionality by developing custom replication extensions. In addition to replicating the metabase, iissync.exe uses installed system replication extension interfaces to replicate Web application definitions and Microsoft® Transaction Server (MTS) application packages. Iissync.exe replicates data stored in a secure manner as well as non-secure data. You can develop one or more custom replication extension interfaces to use iissync.exe to extend the replication process for your needs. The topics in this section specify the requirements for your interfaces. See Custom Extensions Interface for details on registering your interfaces, and Replication and Clustering in IIS for details about iissync.exe.

Remarks

You can find admex.h and other relevant header files in the \inetpub\iissamples\sdk\include directory.


Using the Replication Extension Interface

Your DCOM replication extension interface must be developed as detailed in the IMSAdminReplication Interface Reference section and registered with IIS as specified in Custom Extensions Interface. Your interface must be installed on all source and target computers.

Iissync.exe replicates the metabase and calls system-installed extensions to replicate Web application definitions and MTS application package definitions, adjusting the registry on the target computer as necessary. Iissync.exe also calls your custom replication interface, enabling you to perform additional replication tasks. Your custom replication interface methods are IMSAdminReplication::GetSignature, IMSAdminReplication::Serialize, IMSAdminReplication::DeSerialize, IMSAdminReplication::Propagate, and IMSAdminReplication::Propagate2. Iissync.exe calls all of these methods, if necessary, except Propagate2, before replicating the metabase. It calls your Propagate2 method after replicating the metabase.

When replicating to multiple target computers, iissync.exe processes each target computer independent of the others. This means that different target computers may be in different steps of the replication process at the same time. The process will be discussed in two scenarios: Scenario A, when you replicate from one source computer to one target computer; and Scenario B, when you replicate from one source computer to multiple target computers.

Scenario A:

  • Iissync.exe calls GetSignature on the source and target computers. Both computers calculate and return custom signatures that represent the state of the configuration data and other data that is to be synchronized.
  • Iissync.exe compares the two signatures. If they are the same, iissync.exe replicates the metabase and then calls Propagate2 on the source computer, identifying the target computer and providing a flag that indicates that the signatures were the same. Your program on the source computer can then perform any termination tasks you require.
  • If the two signatures are not the same, iissync.exe calls Serialize on the source computer. Your program returns data to iissync.exe for presentation to the target computer with a call to DeSerialize. Data stored in a secure manner may be transferred with these methods.
  • If the two signatures are not the same, iissync also calls Propagate on the source computer, identifying the target computer and providing a flag indicating that the signatures were different. Your program on the source computer can then transfer data directly to the target computer. For example, you might use xcopy, or some other network copy utility, to copy data files to the target computer from the source computer or from another computer on the network. Serialize and Propagate are called on the source computer before DeSerialize is called on the target computer. Deserialize will not be called on the target computer if either the Serialize or Propagate method returns an error that causes replication to be terminated.
  • Iissync.exe then calls Propagate2 on the source computer, identifying the target computer and providing a flag that indicates the signatures were not the same. Your program on the source computer can then perform any termination tasks you require associated with this target computer.

Scenario B:

  • The process operates exactly the same for each target computer as described in Scenario A.
  • Iissync.exe calls the source computer's GetSignature method only once. The returned signature is compared against each target computer's signature.
  • If any target computer's signature differs from the source computer, iissync.exe calls the source computer's Serialize method once. Your program returns data to iissync.exe for presentation to all target computers that have different signatures. Iissync.exe also calls the Propagate method on the source computer once for each target computer with a signature mismatch. The data returned from the source computer's Serialize method is presented through the DeSerialize method to those target computers that have different signatures. DeSerialize will not be called on the target computer if either the Serialize or Propagate method returns an error that causes replication to be terminated.
  • After iissync replicates the metabase to a target computer, it calls the Propagate2 method on the source computer, identifying the target computer and providing a flag that indicates whether or not this target computer's signature matches the source computer's signature. Iissync.exe calls the source computer's Propagate2 method once for each target computer, regardless of whether the target computer's signature matches the source computer's signature. Propagate2 will not be called on the source computer for any target computer for which the replication process has been terminated by an error.
  • The source computer's Propagate and Propagate2 methods may be called multiple times in no predictable sequence, except that Propagate2 is called when the replication process is complete for the identified target computer.

Note Replication to multiple target computers is not sequenced. You should not make any assumptions when designing your program in regards to the order in which target computers are selected for replication. Your GetSignature method is called first. On the source computer, calls to other methods may be received multiple times in any order.

Replication Process Flow


IMSAdminReplication Interface Reference

Any interfaces you create must implement the following IMSAdminReplication methods.

Method | Description
IMSAdminReplication::DeSerialize | Receives data on the target computer that is provided by the Serialize method on the source computer.
IMSAdminReplication::GetSignature | Provides your custom-designed signature that indicates the state of the data to be replicated.
IMSAdminReplication::Propagate | Called if signatures differ between source computer and target computer. Receives the name of the target computer so that you can transfer data.
IMSAdminReplication::Propagate2 | Called on the source computer after metabase replication is complete to a target computer. Receives the name of the target computer and signature comparison flag. Used for termination tasks.
IMSAdminReplication::Serialize | Provides your data to be replicated by iissync.exe.


IMSAdminReplication::DeSerialize

The IMSAdminReplication::DeSerialize method, called on the target computer, receives the data provided by the source computer's Serialize method if the source and target computer signatures differ.

virtual HRESULT STDMETHODCALLTYPE DeSerialize(
    /* [in] */ DWORD dwBufferSize,
    /* [size_is][in] */ unsigned char __RPC_FAR *pbBuffer
) = 0;

Parameters

dwBufferSize
Receives the size, in bytes, of pbBuffer.
pbBuffer
Points to the data provided by the source computer.

Return Values

Return NOERROR if your method succeeded. If your method returns any code other than NOERROR, iissync.exe will discontinue the replication process for this target computer.

See also

IMSAdminReplication::GetSignature, IMSAdminReplication::Propagate, IMSAdminReplication::Propagate2, IMSAdminReplication::Serialize


IMSAdminReplication::GetSignature

The IMSAdminReplication::GetSignature method, called on the source computer and all target computers, returns your custom designed signature that indicates the current state of data on the responding computer. Iissync.exe uses the signatures provided by the source and target computers to determine if replication is necessary. You may use checksums, date and time stamps, file lists, or any other indicators that specify the state of data that you want to be synchronized.

virtual HRESULT STDMETHODCALLTYPE GetSignature(
    /* [in] */ DWORD dwBufferSize,
    /* [size_is][out] */ unsigned char __RPC_FAR *pbBuffer,
    /* [out] */ DWORD __RPC_FAR *pdwMDRequiredBufferSize
) = 0;

Parameters

dwBufferSize
Receives the size, in bytes, of pbBuffer.
pbBuffer
Points to a buffer that contains the custom signature calculated by your replication extension, if dwBufferSize is sufficient to contain the signature.
pdwMDRequiredBufferSize
Points to a DWORD that contains the required buffer size for pbBuffer to contain your signature. Provide this value whether or not dwBufferSize is sufficient.

Return Values

Return NOERROR if dwBufferSize is sufficient and pbBuffer contains your signature. If dwBufferSize is insufficient, return HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) so that iissync.exe can call your method again with a buffer at least as large as you specify in pdwMDRequiredBufferSize. If you return any other error code from a target computer, the replication process will be terminated for that target. If you return any other error code from the source computer, the entire replication process will be terminated.

See Also

IMSAdminReplication::Propagate, IMSAdminReplication::Propagate2, IMSAdminReplication::Serialize, IMSAdminReplication::DeSerialize


IMSAdminReplication::Propagate

Iissync.exe calls the IMSAdminReplication::Propagate method on the source computer if the signatures provided by the source and target computers differ. This method receives the name of the target computer so your program can transfer data to the target computer by your choice of means.

virtual HRESULT STDMETHODCALLTYPE Propagate(
    /* [in] */ DWORD dwBufferSize,
    /* [size_is][in] */ unsigned char __RPC_FAR *pszBuffer
) = 0;

Parameters

dwBufferSize
Receives the size of pszBuffer.
pszBuffer
Receives the name of the target computer in ANSI format.

Return Values

Return NOERROR if your method succeeded. If your method returns any code other than NOERROR, iissync.exe will discontinue the replication process for the target computer.

See Also

IMSAdminReplication::GetSignature, IMSAdminReplication::Propagate2, IMSAdminReplication::Serialize, IMSAdminReplication::DeSerialize


IMSAdminReplication::Propagate2

The IMSAdminReplication::Propagate2 method is called on the source computer and provides the name of the target computer along with a flag that indicates whether the source and target computer signatures differ. Iissync.exe calls this method to indicate that replication to the target computer is complete. This method is not called if the replication process to a target computer was previously terminated.

virtual HRESULT STDMETHODCALLTYPE Propagate2(
    /* [in] */ DWORD dwBufferSize,
    /* [size_is][in] */ unsigned char __RPC_FAR *pszBuffer,
    /* [in] */ DWORD dwSignatureMismatch
) = 0;

Parameters

dwBufferSize
Receives the size of pszBuffer.
pszBuffer
Receives the name of the target computer in ANSI format.
dwSignatureMismatch
If TRUE, indicates that the source and target computer signatures do not match.

Return Values

Return NOERROR if your method succeeds. If your method does not succeed, return any code other than NOERROR to indicate the replication process failed for this target computer.

See Also

IMSAdminReplication::GetSignature, IMSAdminReplication::Propagate, IMSAdminReplication::Serialize, IMSAdminReplication::DeSerialize


IMSAdminReplication::Serialize

The IMSAdminReplication::Serialize method returns data from the source computer that iissync.exe presents to the target computer by calling DeSerialize. Iissync.exe only calls these methods if the signatures differ.

virtual HRESULT STDMETHODCALLTYPE Serialize(
    /* [in] */ DWORD dwBufferSize,
    /* [size_is][out] */ unsigned char __RPC_FAR *pbBuffer,
    /* [out] */ DWORD __RPC_FAR *pdwMDRequiredBufferSize
) = 0;

Parameters

dwBufferSize
Receives the size of pbBuffer.
pbBuffer
Points to a buffer that contains the data to be transferred to the target computer, if dwBufferSize is sufficient to contain your data.
pdwMDRequiredBufferSize
Points to a DWORD that contains the required buffer size for pbBuffer to contain your data. Provide this value whether or not dwBufferSize is sufficient.

Return Values

Return NOERROR if dwBufferSize is sufficient and pbBuffer contains your data. If dwBufferSize is insufficient, return HRESULT_FROM_WIN32(ERROR_INSUFFICIENT_BUFFER) so that iissync.exe can call your method again with a buffer at least as large as you specify in pdwMDRequiredBufferSize. If you return any other error code from a target computer, the replication process will be terminated for that target. If you return any other error code from the source computer, the entire replication process will be terminated.

See Also

IMSAdminReplication::GetSignature, IMSAdminReplication::Propagate, IMSAdminReplication::Propagate2, IMSAdminReplication::DeSerialize


Logging Interface

The Microsoft® Internet Information Server (IIS) logging interface provides you with a flexible method for generating server activity logs without interfering with other server processes. Using this architecture, you can move most of the maintenance of event logs from virtual servers to logging modules. A logging module is a COM component that exposes methods to IIS. When a log event occurs, IIS calls the appropriate log module's LogInformation method and provides it with a pointer to an IInetLoginformation interface. The logging module then uses the interface to record the log information. IIS determines which IINetLogInformation methods to expose to the logging module as specified by the MD_LOGEXT_FIELD_MASK identifier in the metabase.

IIS contains four built-in logging modules; you can also create custom logging modules to meet your own needs. To do this, you should create a COM object that exposes the methods specified in ILogPlugin Interface.

The logging architecture is new with this version of IIS. Previously, you could create custom logging capabilities through ISAPI filters that registered interest in particular server events. The new architecture makes use of COM to facilitate the development of customized logging. In this architecture, logging modules are added by registering a COM object that supports the methods required by IIS. The registered object can then be established as the logging module for a virtual directory by setting the MS_LOG_PLUGIN_ORDER property with a script, or by selecting the module through the administrative user interface.

If you create a custom logging module, you should also provide a logging user interface module so that administrators can configure your logging module. The built-in logging modules come with user interface modules that expose general logging properties, such as log file period and location. Your user interface module, however, is not restricted to performing just these tasks.

The new logging architecture relies on three interfaces that are defined in the ilogobj.h file. The IINetLogInformation and ILogPlugin interfaces expose methods that are used to log server transactions, while the ILogUIPlugin interface is implemented by the user interface module for the logging module. All three interfaces inherit the IUnknown interface.

ILogPlugin interface also provides methods that IIS uses to manage a logging module. IIS calls these methods to initialize, shut down, and configure the logging module.


Setting Logging Properties

When IIS processes an HTTP request to a server it also makes an instance of the IInetLogInformation interface available to the server's logging module. IInetLogInformation is COM compliant which means it inherits the IUnknown interface. Logging modules can access IInetLogInformation methods by obtaining a pointer via the IUnknown::QueryInterface method.

The logging module determines which methods to query for by examining the MD_LOGEXT_FIELD_MASK identifier in the metabase. MD_LOGEXT_FIELD_MASK is a DWORD of flag bits that specify individual methods of the IInetLogInformation interface. For example, the constant MD_EXTLOG_BYTES_SENT has been defined as value 0x00001000 for the DWORD. If this constant is specified in the metabase, the logging module will query IInetLogInformation for the GetBytesSent method, which returns the number of bytes sent as a result of the HTTP request.

The flags in the MD_LOGEXT_FIELD_MASK identifier can be set with the Internet Service Manager. This process is described in Logging Web Site Activity topic of the Server Administration section. The flags can also be set by a script that sets the value of an appropriate automation property. For example, the MD_EXTLOG_BYTES_SENT flag corresponds to the LogExtFileBytesSent automation property. The following script uses this automation property to set the MD_EXTLOG_BYTES_SENT flag in the metabase to True.

<%
Dim CurrServer
Set CurrServer = GetObject("IIS:/LocalHost/W3svc/1")
CurrServer.LogExtFileBytesSent = True
CurrServer.SetInfo

%>

A sample script that you can use to enumerate and change logging properties is provided in the Developer Samples section of the documentation. For more information on using automation properties to administer IIS see IIS Administration.


Creating a Custom Logging Module

If the logging modules included with IIS do not meet your particular requirements, you can create a custom logging module. For example, you might need to store log information in a format that matches a database table. To do this, you would need to develop a custom logging module to store the data passed from IIS in the appropriate format.

A custom logging module must expose a base set of methods for IIS to use. A module may also support other proprietary methods that are specific to its specialized functions. It is your responsibility to make sure any logging module you create indicates whether it supports a specific method or not. If a method is not supported, your logging module must return an appropriate error code.

If you decide that the logging modules delivered with IIS 4.0 do not meet your requirements, you can create and install a custom logging module.

To create and install a custom logging module
  • Write a COM component that exposes the required methods specified by the ILogPlugin Interface.
  • Register the COM component with regsvr32 or another registration tool.
  • Add your logging module to the list of available logging modules by adding a key in the /LM/LOGGING path of the metabase.
  • Establish the logging module for a particular Web site either by using the Administrative user interface or by using a script.
  • If you wish to provide a user interface for your custom logging module, see Creating a Logging User Interface Module.


Adding a Logging Module

In order for your logging module to be available through the IIS administrative user interface, you should add it to the /LM/LOGGING path of the metabase. You should give the key the same name as the custom logging module, and it should contain two values: MD_LOG_PLUGIN_MOD_ID and MD_LOG_PLUGIN_UI_ID. MD_LOG_PLUGIN_MOD_ID should contain a string that represents the custom module's GUID, and MD_LOG_PLUGIN_UI_ID should contain a string that represents the GUID of the custom module's user interface.

If you use a script to add a logging module to the /LM/LOGGING path, you should add the GUID for the log module to the LogModuleList automation property.

For more information on using scripts to administer IIS, see Using the IIS Admin Objects.

Note The logging module must be resident and registered on the server machine.


Adding a Custom Logging Module to a Service

Each service defined in the metabase includes a MD_LOG_PLUGINS_AVAILABLE key at the /LM/W3SVC/Info. This key contains a comma delimited list of logging modules available for that particular service. In order for your custom logging module to be available to a particular service, its name must be included in this list. Adding the name can be accomplished by using either the IIS user interface or a script that adds the name to the MD_LOG_PLUGINS_AVAILABLE key. If you use a script to add a custom logging module to a service, you should do so with the LogModuleList automation property.

For more information on using scripts to administer IIS, see Using the IIS Admin Objects.


Creating a Logging User Interface Module

When you create your own custom logging module, you have three user interface options:

  • No user interface module: This option is appropriate if your logging module has no configurable settings, or if you'd rather provide access to your logging module through mechanisms other than those used by IIS.
  • Use a built-in user interface module: You can, in effect, borrow one of the user interface modules provided with the built-in IIS logging modules. The user interface module GUID specified under the Microsoft IIS Log File Format key of the /LM/LOGGING path in the metabase would be most appropriate for this use, because it provides basic configuration functionality.
  • Create a new user interface module: You can create your own COM object that implements the appropriate interfaces.

You are not restricted to performing any set tasks in your user interface module.

To create and install a logging user interface module
  • Either write a COM component that implements the ILogUIPlugin interface, as defined in the ilogobj.h header file, or use one of the built-in user interface modules.
  • Use regsvr32, or some other registration tool, to register the component.
  • Add your logging user interface module GUID to the MD_LOG_PLUGIN_UI_ID key in the metabase.

If you decide to create a new user interface module, you should implement the module in a DLL separate from the logging module. Also, the UI module must be resident and registered on the machine on which Internet Service Manager is running. This requirement is particularly important if you intend to administer your custom logging module remotely; the logging module itself can be running on a remote machine, but the logging UI module must be local.


ILogPlugin Interface

The ILogPlugin interface exposes a set of methods through the IUnknown interface. IIS uses these methods to communicate with logging modules and they are required.

Method | Description
ILogPlugin::GetConfig | This is a private method used by IIS internally.
ILogPlugin::InitializeLog | Initializes the log module.
ILogPlugin::LogInformation | Sends a pointer to an IinetLogInformation interface.
ILogPlugin::QueryExtraLoggingFields | Retrieves logging information that is specific to the logging module.
ILogPlugin::SetConfig | This is a private method used by IIS internally.
ILogPlugin::TerminateLog | Removes a particular instance of the log module.


ILogPlugin::GetConfig

The ILogPlugin::GetConfig method is a private method and is used only for compatibility reasons to support RPC-based server interfaces from previous releases of IIS.

virtual HRESULT STDMETHODCALLTYPE GetConfig(
  IN DWORD cbSize,   //the size of the log configuration object
  PBYTE Log          //a pointer to the configuration information
);

Parameters

cbsize
The size of the log configuration object.
Log
Points to the configuration information.

Remarks

This is a private interface method used by IIS when it calls the built-in logging modules. Custom logging modules should return FALSE when this method is called.

See Also

ILogPlugin::SetConfig


ILogPlugin::InitializeLog

The ILogPlugin::InitializeLog method initializes a plug-in module for a particular virtual server. The plug-in module reads configuration data from the key specified in the MetabasePath parameter.

virtual HRESULT STDMETHODCALLTYPE InitializeLog(
  IN LPCSTR InstanceName,  //identifies the relevant virtual
                           // directory
  IN LPCSTR MetabasePath,  //search path for the metabase key
  IN PCHAR pvIMDCOM        //pointer to a handle to the metabase COM
                           // object.
);

Parameters

InstanceName
[in] Identifies the virtual directory that will send log objects to the logging module
MetabasePath
[in] Specifies the metabase path for the logging key.
PvIMDCOM
[in] Provides a pointer to a handle for manipulating the metabase.

See Also

IIsLogModule


ILogPlugin::LogInformation

The ILogPlugin::LogInformation method sends the logging module a LogInformation interface pointer to communicate the log data.

virtual HRESULT STDMETHODCALLTYPE LogInformation(
  IInetLogInformation *pLogObj  //a pointer to a log object
);

Parameters

pLogObj
Points to the LogInformation interface which contains the information to be logged.

See Also

IIsLogModule


ILogPlugin::QueryExtraLoggingFields

The ILogPlugin::QueryExtraLoggingFields method determines logging information that is specific to a custom logging module.

virtual HRESULT STDMETHODCALLTYPE QueryExtraLoggingFields(
  PDWORD cbSize       //size of the szParameters parameter
  PCHAR szParameters  //defines additional fields for logging
);

Parameters

cbsize
The size of the szParameters parameter.
szParameters
Null-separated strings that list the extra fields to be logged.

Remarks

You can use this method to record data sent by custom headers from the client. For example, to capture a user's cookie, the szParameters parameter would contain the following:

User-Agent\0Cookie\0\0

You could then use the IInetLogInformation::GetExtraHTTPHeaders method to retrieve a list of header information. This list would be null delimited.

See Also

IInetLogInformation::GetExtraHTTPHeaders


ILogPlugin::SetConfig

The ILogPlugin::SetConfig method is a private interface and is used only for compatibility reasons to support RPC-based server interfaces from previous releases of IIS.

virtual HRESULT STDMETHODCALLTYPE SetConfig(
  [IN] DWORD cbSize,  //the size of the log configuration object
  PBYTE Log           //a pointer to the configuration information
);

Parameters

cbsize
The size of the log configuration object
Log
Points to the configuration information

Remarks

This is a private interface method that IIS uses when it calls the built-in logging modules. Custom logging modules should return FALSE when this method is called.

See Also

ILogPlugin::GetConfig


ILogPlugin::TerminateLog

The ILogPlugin::TerminateLog method closes the logging module.

virtual HRESULT STDMETHODCALLTYPE TerminateLog( VOID );


ILogUIPlugin Interface

The ILogUIPlugin interface allows IIS to contact your logging user interface module. The interface defines only one method.

Method | Description
ILogUIPlugin::OnProperties | Invoked when an administrator access the properties associated with your custom logging module.


ILogUIPlugin::OnProperties

The ILogUIPlugin::OnProperties method is invoked by IIS when the administrator clicks Properties... on the site tab of the server Properties dialog in the MMC.

virtual HRESULT STDMETHODCALLTYPE OnProperties(
  [IN] OLECHAR * pocMachineName,  // name of machine on which server is running
  [IN] OLECHAR * pocMetabasePath  // metabase path to server
);

Parameters

pocMachineName
Pointer to a Unicode character array that specifies the name of the machine on which the server is running.
pocMetabasePath
Pointer to Unicode character array that specifies the metabase path to the Web or FTP server.

Remarks

After your implementation of ILogUIPlugin::OnProperties completes execution, IIS will reload the instance of your custom logging module that is assigned to the affected Web or FTP server. This reload, which includes invocation of the custom logging module's ILogPlugin::InitializeLog and ILogPlugin::QueryExtraLoggingFields methods, allows your logging module to re-initialize itself with any values in the metabase that might have been changed by the user interface module.

See Also

ILogPlugin::InitializeLog, ILogPlugin::QueryExtraLoggingFields


IInetLogInformation Interface

The IInetLogInformation interface is defined in ilogobj.h. It implements the IUnknown interface to expose the methods needed to log IIS events. When a log event occurs, the IInetLogInformation object is exposed to the logging module through the IInetLogInformation methods. Custom logging modules can also make use of the following methods to meet specialized requirements.

Method | Description
IInetLogInformation::GetBytesRecvd | Returns the number of bytes received from the client.
IInetLogInformation::GetBytesSent | Returns the number of bytes sent by the client.
IInetLogInformation::GetClientHostName | Returns the IP address of the client.
IInetLogInformation::GetClientUserName | Returns the user name of the client.
IInetLogInformation::GetComputerName | Returns the local machine to which the logging module is applied.
IInetLogInformation::GetExtraHTTPHeaders | Returns a NULL-separated list of parameters requested by the logging module from the Web server.
IInetLogInformation::GetOperation | Retrieves the function to be called.
IInetLogInformation::GetParameters | Retrieves the parameters related to the current operation.
IInetLogInformation::GetPortNumber | Retrieves the number of the port the client is connected to.
IInetLogInformation::GetProtocolStatus | Retrieves the protocol dependent status code returned to the client.
IInetLogInformation::GetServerAddress | Obtains the IP address of the server that is having its activity recorded by the logging module.
IInetLogInformation::GetSiteName | Obtains the name of the server instance which is being logged.
IInetLogInformation::GetTarget | Obtains the target for the current operation.
IInetLogInformation::GetTimeForProcessing | Retrieves the number of milliseconds it took for the operation to complete.
IInetLogInformation::GetWin32Status | Retrieves the Win32 status code of the request.


IInetLogInformation::GetBytesRecvd

The IInetLogInformation::GetBytesRecvd method retrieves the number of bytes received by the server from the client.

virtual DWORD STDMETHODCALLTYPE GetBytesRecvd( VOID );

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_BYTES_RECV flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileBytesRecv, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetBytesSent

The IInetLogInformation::GetBytesSent method retrieves the number of bytes sent by the server to the client.

virtual DWORD STDMETHODCALLTYPE GetBytesSent( VOID );

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_BYTES_SENT flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileBytesSent, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetClientHostName

The IInetLogInformation::GetClientHostName method obtains the IP address of the client.

virtual LPSTR STDMETHODCALLTYPE GetClientHostName(
  IN PCHAR pszClientHostName,
  IN PDWORD pcbSize
);

Parameters

pszClientHostName
[in] Name of the computer that sent the request which triggered the logged event.
pcbsize
[in] Size of the pszClientHostName parameter.

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_CLIENT_IP flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileClientIp, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetClientUserName

The IInetLogInformation::GetClientUserName method obtains the name used by the client to log on.

virtual LPSTR STDMETHODCALLTYPE GetClientUserName(
  IN PCHAR pszClientUserName,
  IN PDWORD pcbSize
);

Parameters

pszClientUserName
[in] User name logged on to the computer that sent the request.
pcbsize
[in] Size of the pszClientUserName parameter.

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_USERNAME flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileUserName, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetComputerName

The IInetLogInformation::GetComputerName method obtains the name of the local machine to which the logging module is being applied.

virtual LPSTR STDMETHODCALLTYPE GetComputerName(
  IN PCHAR pszComputerName,
  IN PDWORD pcbSize
);

Parameters

pszComputerName
[in] Name of the computer whose activity the logging module is capturing.
pcbsize
[in] Size of the pszComputerName parameter.

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_COMPUTER_NAME flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileComputerName, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetExtraHTTPHeaders

The IInetLogInformation::GetExtraHTTPHeaders method retrieves a NULL-separated list of parameters requested by the logging module from the Web server.

virtual LPSTR STDMETHODCALLTYPE GetExtraHTTPHeaders(
  IN PCHAR pszHTTPHeaders,
  IN PDWORD pcbSize
);

Parameters

pszHTTPHeaders
[in] The HTTP headers to be retrieved.
pcbsize
[in] Size of the pszHTTPHeaders parameter.

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_COOKIE, MD_EXTLOG_USER_AGENT or MD_EXTLOG_REFERER metabase identifier.

See Also

LogExtFileCookie, LogExtFileReferer, LogExtFileUserAgent, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetOperation

The IInetLogInformation::GetOperation method retrieves the operation to be called.

virtual LPSTR STDMETHODCALLTYPE GetOperation(
  IN PCHAR pszOperation,
  IN PDWORD pcbSize
);

Parameters

pszOperation
[in] The function to retrieve.
pcbsize
[in] Size of the pszOperation parameter.


IInetLogInformation::GetParameters

The IInetLogInformation::GetParameters method retrieves the parameters related to the current operation.

virtual LPSTR STDMETHODCALLTYPE GetParameters(
  IN PCHAR pszParameters,
  IN PDWORD pcbSize
);

Parameters

pszParameters
[in] The parameter values to be retrieved.
pcbsize
[in] Size of the pszParameters parameter.


IInetLogInformation::GetPortNumber

The IInetLogInformation::GetPortNumber method retrieves the number of the port the client is connected to.

virtual DWORD STDMETHODCALLTYPE GetPortNumber( VOID);

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_SERVER_PORT flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileServerPort, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetProtocolStatus

The IInetLogInformation::GetProtocolStatus method retrieves the protocol-dependent status code returned to the client.

virtual DWORD STDMETHODCALLTYPE GetProtocolStatus( VOID );

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_HTTP_STATUS flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileHttpStatus, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetServerAddress

The IInetLogInformation::GetServerAddress method obtains the IP address of the server that is having its activity recorded by the logging module.

virtual LPSTR STDMETHODCALLTYPE GetServerAddress(
  IN PCHAR pszServerAddress,
  IN PDWORD pcbSize
);

Parameters

pszServerAddress
[in] IP address of the server where the log events are occurring.
pcbsize
[in] Size of the pszServerAddress parameter.

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_SERVER_IP flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileServerIp, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetSiteName

The IInetLogInformation::GetSiteName method obtains the name of the server instance that is being logged.

virtual LPSTR STDMETHODCALLTYPE GetSiteName(
  IN PCHAR pszSiteName,
  IN PDWORD pcbSize
);

Parameters

pszSiteName
[in] Name of the virtual directory whose activity the logging module is capturing.
pcbsize
[in] Size of the pszSiteName parameter.

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_SITE_NAME flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileSiteName, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetTarget

The IInetLogInformation::GetTarget method obtains the target for the current operation.

virtual LPSTR STDMETHODCALLTYPE GetTarget(
  IN PCHAR pszTarget,
  IN PDWORD pcbSize
);

Parameters

pszTarget
[in] The target of the operation.
pcbsize
[in] Size of the pszTarget parameter.


IInetLogInformation::GetTimeForProcessing

The IInetLogInformation::GetTimeForProcessing method retrieves the number of milliseconds it took for the operation to complete.

virtual DWORD STDMETHODCALLTYPE GetTimeForProcessing( VOID );

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_TIME_TAKEN flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileTimeTaken, MD_LOGEXT_FIELD_MASK


IInetLogInformation::GetVersionString

The IInetLogInformation::GetVersionString method captures which version of HTTP was used for the request that generated the log event.

virtual LPSTR STDMETHODCALLTYPE GetVersionString(
  IN PCHAR    pszVersionString,
  IN PDWORD   pcbSize
);

Parameters

pszVersionString
[in] The string that indicates which version of HTTP was used for the request.
pcbsize
[in] Size of the pszVersionString parameter.


IInetLogInformation::GetWin32Status

The IInetLogInformation::GetWin32Status method retrieves the Win32 status code of the request.

virtual DWORD STDMETHODCALLTYPE GetWin32Status( VOID );

Remarks

Logging modules should query for this method if a server instance has set the MD_EXTLOG_WIN32_STATUS flag of the MD_LOGEXT_FIELD_MASK metabase identifier.

See Also

LogExtFileWin32Status, MD_LOGEXT_FIELD_MASK


ISAPI

Internet Server Application Programming Interface (ISAPI) provides a set of interfaces that you can use to create extensions and filters for Microsoft® Internet Information Server (IIS). This document describes the implementation requirements of IIS. It provides general overview material on how to develop ISAPI extensions and filters, and reference information for the functions and structures available to you. This section contains the following broad categories:

  • ISAPI and the Web Application Architecture
  • Developing ISAPI extensions
  • Extension Reference
  • Developing ISAPI filters
  • Filter Reference


ISAPI and the Web Application Architecture

Microsoft® developed the ISAPI model as an alternative to the Common Gateway Interface (CGI). The ISAPI model provides a number of advantages over the CGI model, including low overhead, fast loading, and better scalability.

A detailed comparison of the two models is provided in ISAPI and CGI.

You can assemble ISAPI extensions into Web applications that provide all of the functionality of an application running on your desktop. You can also create ISAPI filters to customize the functionality of IIS. Filters provide a slightly different processing model than extensions. An extension is activated upon request by a client, whereas a filter is activated by IIS directly when a particular request event occurs. Extensions are request-driven, filters are processing event-driven.

IIS builds on the concept of a namespace to identify applications. A namespace can be defined as a way of associating a protocol and network service addressing scheme with a human-friendly name. The IIS application architecture extends the concept of a namespace by enabling the creation of applications through a virtual directory structure.

The namespace provides a way to identify a group of files as belonging together. Scripts and extension dlls within an application boundary form a unit of isolation. A unit of isolation always runs in a single server process. IIS administrators can either run applications in the same server process as IIS, or they can isolate the application by running it in a separate process. The ability to isolate an application is particularly helpful during development and testing. Isolated applications, however, will never perform as well as applications sharing the IIS process.

The following diagram illustrates the concept of an application boundary.

Notice that virtual directories can be nested. Also, notice that you can combine ISAPI dlls and ASP script pages in the same application.

For more information on combining ISAPI dlls and ASP script in an application, see Deploying Your Component and Application Isolation Issues in Creating Components for ASP


Extension Interaction with IIS

At the most basic level, an ISAPI extension only does one thing; it processes input from an HTTP request. The following diagram illustrates this process.

IIS receives the HTTP request from the client and determines its type. If the request is for an HTML page, the server simply formats the page and returns it to the client. If the request is for a CGI script, IIS loads the appropriate CGI EXE into a separate process space. If the request is for an ISAPI extension, as shown in the diagram, a new instance of the extension (implemented through the DLL file) is loaded into the IIS process (if the DLL is not already loaded). The new extension instance is also passed a data structure known as an Extension Control Block (ECB), which contains the input parameters specified in the HTTP request . All communication between IIS and the extension is passed through the ECB. Specific processing stages of an ISAPI extension are outlined in Extension Request Processing.

All ISAPI extensions use the dynamic linking programming model. In the Microsoft® Windows® operating system, dynamic linking provides a way for a process to call a function that is not part of its executable code. The executable code for the function is located in a dynamic-link library (DLL), which contains one or more functions that are compiled, linked, and stored separately from the processes which use them. ISAPI extensions use run-time dynamic linking. When IIS loads an ISAPI extension it uses the LoadLibraryEx and GetProcAddress functions to retrieve the starting point of the DLL functions.

ISAPI DLLs are loaded at run time by IIS and are called at the common entry points of GetExtensionVersion and HttpExtensionProc. For more information on this, see Entry Point Functions.

ISAPI extension DLLs must be multithread-safe since multiple requests will be received simultaneously. For information on how to write multithread-safe DLLs, refer to the related articles on the Microsoft Development Library compact disc, or any of the books on Win32® programming. Similarly, for information on thread-safe DLLs and the scope of usage of C run-time routines in a DLL, see the articles on sharing data in a DLL on the Microsoft Development Library disc.


Filter Interaction with IIS

ISAPI filters are similar to ISAPI extensions in that they respond when IIS receives an HTTP request. They are different from extensions in that they are driven by IIS events rather than by a client request. You can associate an ISAPI filter with a particular IIS event; the filter is then notified every time its associated event occurs.

Filters are also different from extensions in that the data structure sent from IIS to filters is determined by the type of event any particular filter is associated with. IIS always presents an extension with request data through an ECB. The following diagram illustrates interaction between IIS and an ISAPI filter.

ISAPI filters are very powerful and can be used to facilitate applications that do a number of different tasks, including

  • custom authentication schemes
  • compression
  • encryption
  • logging
  • traffic analysis or other request analyses

For further information on how filters process notifications, see Filter Event Processing.


ISAPI and CGI

The chief difference between the CGI programming model and the ISAPI programming model is that CGI creates a unique process for every request, while ISAPI does not. With CGI, every time an HTTP server receives a request it must initiate a new process, which, along with maintaining processes, is very resource intensive. This inherent limitation in CGI has made it difficult to develop responsive applications on the Internet.

The following diagram illustrates the difference between the CGI model and the ISAPI model.

In the ISAPI model, each request received by an HTTP server initiates the creation of a ECB data structure. Creating and maintaining a data structure is much easier and faster than initiating a new process. In addition, since the ECB and the extension are usually both running in the same process as IIS, the server can process requests faster and accommodate a higher volume of requests.

Finally, rather than using process isolation, the ISAPI model uses threads to isolate processing work items. Using multiple threads to synchronize work allows IIS to make more efficient use of system resources than is possible with the CGI model, or other models based on process isolation.

IIS 4.0 supports process isolation for ISAPI DLLs and scripts. IIS uses custom high speed methods to establish communication between the server process and the surrogate process housing the ISAPI DLLs thus providing robustness with high performance. Still, the ISAPI DLLs are only loaded once per isolated process. The application namespace boundary governs how the different processes are created and used.

When IIS receives a request for a particular extension, it loads the DLL into memory where it services other requests. For example, the following HTTP request causes IIS to create an instance of MyISAPI.dll.

http://IIS/Applications/MyISAPI.dll?paramater1,parameter2

When IIS closes the extension, it calls the extension's TerminateExtension function, if present. You are encouraged to use TerminateExtension to clean up any threads and state information that the extension may have used in processing the request.

For more information about CGI, refer to http://hoohoo.ncsa.uiuc.edu/cgi/.


Extension and Filter Version Information

When you load an extension or filter, IIS checks the ISAPI version used to build the DLL. IIS uses this information to determine which functions the extension or filter can use. If you built the extension or filter with a later version of ISAPI than the server supports, IIS will not load the DLL. ISAPI extensions are completely backwards compatible, so all extensions and filters that ran on earlier versions of IIS should run with the most recent release. The following topics provide a summary of the functions offered by the three most recent releases of ISAPI.

  • Functions supported in IIS 2.0
  • Functions supported in IIS 3.0
  • New ISAPI features for IIS 4.0


Functions supported in IIS 2.0

The following ServerSupportFunctions were supported in ISAPI 2.0

HSE_REQ_SEND_URL_REDIRECT_RESP

HSE_REQ_SEND_URL

HSE_REQ_SEND_RESPONSE_HEADER

HSE_REQ_DONE_WITH_SESSION

HSE_REQ_MAP_URL_TO_PATH

HSE_REQ_GET_SSPI_INFO

HSE_APPEND_LOG_PARAMETER

HSE_REQ_SEND_URL_EX

HSE_REQ_IO_COMPLETION

HSE_REQ_TRANSMIT_FILE

HSE_REQ_REFRESH_ISAPI_ACL


Functions supported in IIS 3.0

The following ServerSupportFunctions were supported in ISAPI 3.0, but were not supported in ISAPI 2.0

HSE_REQ_GET_CERT_INFO_EX

HSE_REQ_GET_SSPI_INFO


New ISAPI features for IIS 4.0

IIS 4.0 introduces significant changes to the ways you can develop and implement Internet applications. The changes that affect how you develop ISAPI applications and filters are summarized as follows.

Running ISAPI extensions out of process

In previous releases of IIS, you always ran ISAPI extensions in the same server process as IIS. While this allowed quicker performance, the danger that IIS would become corrupted if your extension did not handle errors properly was greater.

IIS 4.0 allows you to isolate an extension by running it in a separate server process. You can accomplish this by selecting the Run in separate memory space option in the IIS user interface when you create an extension. The configures the extension to map to the DLL which exposes the ISAPI extension entry points.

For more information on isolating applications, see Isolating Applications under Server Administration.

Some of your ISAPI extension DLLs may not be suitable for running in a separate server process. Issues that could prevent an ISAPI extension from running in a separate server process include:

  • requirement for exclusive access to files
  • security considerations
  • design problems
  • combined of ISAPI extension and filter functions in a single DLL
  • performance requirements

You can use the administration property InProcessIsapiApps to specify all ISAPI DLLs that you want to run in the same server process as IIS. This property applies to a WebService. Requests for such ISAPI DLLs are routed to the default application root in IIS (/LM/W3SVC). The default application root is marked in-process only, which guarantees that all such requests will run in-process.

Warning: A software error in ISAPI DLLs will stop the IIS server. Therefore, unless you are sure that your DLL will never run out-of-process, do not add the DLL to this list.

Note Setup will create the InProcessIsapiApps property and populate it with Ssinc.dll and Httpodbc.dll, which only work if running in the same process as IIS.

For more information on using the metabase, see IIS Administration

Specifying filters in the Metabase

IIS 4.0 introduces the metabase, a new data storage location. ISAPI filter information that you formerly stored in the System Registry should now be stored in the metabase. Metabase information can be modified either through the IIS Admin Objects or the IIS Admin Base Object.

Global and Website filters

Previously, you applied ISAPI filters across all levels of a server. There was no way to specify that a filter would only respond to events at a more granular level. In IIS 4.0, you can apply filters to all Web sites on a server or to a particular Web site only. A global filter will be notified of events that occur at any Web site on the server, while Web site filters are only notified of events at the site to which they are applied. You can specify both global and Web site filters with the user interface, or you can set the appropriate key values in the metabase. For more information on setting a filter see IIS Filter and IIS Filters in IIS Admin Objects.

Support for TerminateFilter

TerminateFilter is a new entry point for ISAPI filters introduced in IIS 4.0. If your ISAPI filter exports TerminateFilter, it will be called when the filter is unloaded.

New filter notification

SF_NOTIFY_SEND_RESPONSE is a new notification that can be specified with the HttpFilterProc function.

New Server Variables

Many new server variables that can be specified by the GetServerVariable function have been added.

New ServerSupportFunction () commands for filters

Two new commands for ServerSupportFunction have been added. They are:

SF_REQ_DISABLE_NOTIFICATIONS

SF_REQ_GET_PROPERTY

In addition, three new options have been added to the ServerSupportFunction. They are:

HSE_REQ_SEND_RESPONSE_HEADER_EX

HSE_REQ_GET_CERT_INFO_EX

HSE_REQ_GET_IMPERSONATION_TOKEN

New Members of the HTTP_FILTER_LOG structure

Three new members of the HTTP_FILTER_LOG structure have been added in IIS 4.0. They are:

  • DWORD dwBytesSent;
  • DWORD dwBytesRecvd;
  • DWORD msTimeForProcessing

Support for HTTP 1.1

IIS 4.0 introduces support for HTTP 1.1. Two areas where this has potential impact on ISAPI extension and filter developers is in support for pipelined requests and the transfer encoding header. Pipelined requests are described in Extension Request Processing.

Active Server Pages (ASP) now support the transfer encoding header, which tells the client if a transformation has been applied to the body of the message that is being sent. For example, if the client supports HTTP 1.1, IIS 4.0 can specify the Transfer-encoding value of chunked. When the chunked transformation has been applied, the message is broken into a chucks of varying sizes. Each chunk contains its own size indicator and optional footers for specifying header fields. Chunking improves the overall efficiency of the transmission.

For more information on Transfer encoding, see RFC 2068 published by the World Wide Web consortium. RFC 2068 is available at: http://www.w3.org/protocols. See Developer Samples for information on the sample extension that implements this technology.


Developing ISAPI Extensions

You can reduce server overhead and Web access time if you write an ISAPI extension, a run-time DLL used by IIS. You can load an extensions in the same process as IIS for best performance, or into an isolated process to guard against corruption of the IIS process.

This section contains:

  • Extension Request Processing, which provides a high level overview of the order in which processing events occur.
  • Using Callback Functions, which describes how the extension communicates processing results to IIS.
  • Asynchronous I/O Processing, which illustrates the order of processing events when a function performs asynchronously.
  • Extension Security Issues, which discusses how security context is passed to an ISAPI extension.
  • Basic Extension Framework, which outlines the minimum requirements for an ISAPI extension.
  • Sending a Header, which demonstrates how to use the ServerSupportFunction as a callback function.
  • Reading and Writing Asynchronously, which demonstrates how to use ReadClient for asynchronous processing.
  • Shutting Down an Extension, which demonstrates how to use the TerminateExtension function to unload an extension from memory.
  • Converting Existing CGI Scripts to ISAPI Extensions, which provides some of the development steps that are required to convert an existing CGI application to an extension.
  • Important Notes for Extension Developers, which expands on some general issues regarding developing extensions.


Extension Request Processing

When IIS receives a request for your ISAPI extension, it loads the DLL and calls the GetExtensionVersion entry point function. GetExtensionVersion returns a pointer to an HSE_VERSION_INFO structure. IIS then calls the HttpExtensionProc function with a pointer to an Extension_Control_Block (ECB) structure. Your extension processes the data contained in the ECB and uses the callback functions in ECB to write back responses to the client. When the extension is no longer needed, IIS calls the TerminateExtension function to unload the extension from memory.

After IIS finishes processing a request for an ISAPI, it can either close the connection or keep it open. A request can specify that the connection should remain open by specifying the Connection: Keep-Alive header. (With all HTTP 1.1 requests the Connection Keep-Alive header is included by default.) If you have designed your ISAPI extension to support Keep-Alive requests, you should indicate this to the client by calling the ServerSupporFunction and specifying the HSE_REQ_SEND_RESPONSE_HEADER value for the dwHSERequest parameter. The response header you specify should contain Connection: Keep-Alive. The following code demonstrates sending the Keep-Alive header:

DWORD
SendHeaderToClient(
    LPEXTENSION_BLOCK pECB
    )
{
    BOOL fReturn;
    CHAR szHeader[256] = "";
    DWORD hseStatus = HSE_STATUS_SUCCESS;

    strcpy(szHeader, "Content-type: test/html\r\n\r\n");
    fReturn =
    pECB->ServerSupportFunction(pECB->ConnID,
                                HSE_REQ_SEND_RESPONSE_HEADER,
                                "Connection:Keep-Alive" // Telling the client not to close the connection
                                NULL,
                                (LPDWORD) szHeader);

    if (! fReturn ) {
        hseStatus = HSE_STATUS_ERROR;
    }
    return (hseStatus);
}

If the request has indicated that the connection should remain open, subsequent requests can be sequential or pipelined. When a client pipelines requests, it does not need to wait for earlier requests to be serviced before sending subsequent requests. IIS guarantees that pipelined requests will be returned to the client in the order they were received. IIS manages the ordering of request internally, so your extension does not need to add any special processing for pipelined requests.

For more details on pipelined requests, see RFC 2068 published by the World Wide Web consortium. RFC 2068 is available at http://www.isi.edu.


Using Callback Functions

When your extension processes a request, it needs a way of communicating with IIS. This is the purpose of the callback functions in the ECB. The four callback functions used with ISAPI extensions are:

  • GetServerVariable is used to obtain server variables that contain information about the request and server. Some server variables, such as Request_Method and Content_Length are embedded in the ECB structure. You can use GetServerVariable to obtain information about the request or server that is not included in the ECB.
  • ReadClient is used to read data, supplied by the client, into a buffer.
  • ServerSupportFunction provides a variety of functions that the extension can use in processing a request.
  • WriteClient used to send a response back to the client.

Specific examples showing how to use the callback functions are provided in Sending a Header and Reading and Writing Asynchronously.

For more information on server variables see: http://hoohoo.ncsa.uiuc.edu/cgi/env.html


Asynchronous I/O Processing

It is important that your ISAPI extensions support asynchronous operations because that frees server pool threads to complete I/O operations. In addition, the IIS server engine already has built-in support to manage asynchronous I/O operations using the completion ports and server thread pool. ISAPI 1.0 only supported synchronous I/O operations through the ReadClient and WriteClient callback functions.

There are two basic types of async processing.You can implement WriteClient as an async process by setting the dwReserved parameter to HSE_IO_ASYNC. ReadClient and TransmitFile use the ServerSupportFunction to indicate asynchronous processing. For TransmitFile this is accomplished by calling the ServerSupportFunction with the dwHSERequest parameter set to HSE_REQ_TRANSMIT_FILE. For ReadClient the dwHSERequest parameter is set to HSE_REQ_ASYNC_READ_CLIENT.

ISAPI 2.0 and later versions support asynchronous write operations using the existing WriteClient callback function with a special flag that indicates the operation has to be performed asynchronously. In addition, these versions of ISAPI provide a mechanism to request the server transmit a file using the Win32 API TransmitFile. Only one asynchronous I/O operation can be in process at a time. If your ISAPI extension begins an asynchronous I/O operation, you should wait until the operation completes before starting another one.

The following steps outline the order of events for asynchronous processing
  1. IIS I/O thread calls the ISAPI extension with an ECB.
  2. Extension returns HSE_STATUS_PENDING and puts the ECB in a worker queue.
  3. Extension starts or re-uses a worker thread for the ECB and adds a ServerSupportFunction to the ECB with the dwHSERequest parameter set to HSE_REQ_IO_COMPLETION. The ECB is put on the worker thread.
  4. The worker thread performs the required work using an async processing function.
  5. When the I/O completes IIS calls the Async IO callback function with the context & IO status (bytes & error code). In the callback the ISAPI DLL may do other calls to either WriteClient or ServerSupportFunction until there are no more bytes waiting to be read or written.
  6. When the worker thread is finished processing, it calls the ServerSupportFunction with the dwHSERequest parameter set to HSE_REQ_DONE_WITH_SESSION. When IIS receives this callback, it destroys the ECB.

Note There is exactly one ECB for each ISAPI request. ECBs may be recycled for subsequent requests (only after the completion of the entire request). After calling the ServerSupportFunction with HSE_REQ_DONE_WITH_SESSION the extension should no longer use the ECB for which the call was made.


Extension Security Issues

Security for ISAPI extensions is derived from the Microsoft® Windows NT® security model. If your extension accesses secured system resources, it must obtain the appropriate Windows NT permissions. Several inter-related issues determine how you accomplish this programming task. This topic provides an overview of these security issues and outlines the processing steps required to access secured resources.

The topic is divided into the following sub-sections:

Security Identities

Process Execution

Security Identities

Every Microsoft® Windows NT® process has a unique process identity which is used by the Windows NT object manager for various management tasks. Each process object contains an associated access token, which indicates the type of access rights the process has for secured resources. ISAPI extensions either run in the inetinfo process or in an isolated process. The process identity for applications running in the intetinfo process is SYSTEM. The process identity for isolated applications is IWAM_<machinename>.

A very simple ISAPI extension will be able to respond to the request and immediately return the required information. More complex extensions, however, will rely on worker threads to accomplish their processing. By default, worker threads have the same identity as the process in which they are running. If your ISAPI accesses secured resources, it will need to pass the security context of the logged-on user to a thread. The security context is passed to the thread by obtaining an impersonation token from the process. The detailed steps for obtaining an impersonation token are described in the Process Execution section.

Process Execution

ISAPI extensions can be divided into two broad categories, pending and non-pending. A pending extension returns the value HSE_STATUS_PENDING from the initial call to HttpExtensionProc. The process of obtaining a security token for a thread is slightly different for these two categories. The process for the non-pending case is illustrated in the following diagram.

When IIS processes a request, it verifies that the client has permission to access any requested resources.(Step 1) IIS supports four different authentication schemes for performing this check: anonymous, basic, Windows NT Challenge/Response, and Client Certificates. Regardless of which authentication scheme is used, once the client has been authenticated, the request has an established security context. If the authentication scheme used is anonymous, the security context will be set to IUSR_machinename. If either Basic or NTLM authentication has been used, the security context will be set to the account the user logged in with on the client machine.

After IIS has authenticated the user, it calls SetThreadToken on the current Input/Output thread so that the thread is running as the authenticated user. (Step 2). Because the non-pending ISAPI extensions is called with the security context of the authenticated user, it can access the same secured resources as the authenticated user.

In the case of the pending extension, the process of setting the appropriate security context requires some additional steps. This is illustrated in the following diagram.

Because the pending ISAPI extension needs to access the current security context it calls ServerSupportFunction and specifies HSE_REQ_GET_IMPERSONATION_TOKEN as the value for the dwHSERequest parameter. (Step 3) This function returns a handle that you can use to obtain an impersonation token for a worker thread.

Note The handle for the impersonation token that is returned will be valid for the lifetime of the EXTENSION_CONTROL_BLOCK (ECB). If the call to the ServerSupportFunction was for a synchronous operation, the ECB is valid until the HttpExtensionProc function completes. If the call to the ServerSupportFunction was for an asynchronous operation, the ECB will be valid until your extension calls ServerSupportFunction and specifies a value of HSE_REQ_DONE_WITH_SESSION for the dwHSERequest parameter.

When the thread needs to access secured system resources, it should call either ImpersonateLoggedonUser or SetThreadToken and pass the reference to the handle it received from the ServerSupportFunction as an input parameter. (Step 4) Both ImpersonateLoggedonUser or SetThreadToken are Win32 API functions.

You may want to call the Win32 API RevertToSelf function after the thread has finished using the current security context (Step 5). Calling RevertToSelf will return the thread to the security context of the process in which it is running. For ISAPI extensions running in the INETINFO process, the security context is SYSTEM. For ISAPI extensions running in an isolated process, the security context is IWAM_machinename.

For more information on IIS authentication see Authentication in the Server Administration section.

For more information on the Win32 API's, see the Platform SDK.


Basic Extension Framework

You can develop ISAPI extensions with any tool capable of building a 32-bit DLL. Microsoft® Visual C++® 5.0 includes the ISAPI Extension Wizard, a tool you can use to quickly establish the basic framework for an ISAPI extension. Most of the code shown in this topic is automatically generated by the ISAPI Extension Wizard.

ISAPI extensions can be thought of as having sections that correspond to the three basic functions:

  • Initialization
  • Processing
  • Termination

Initialization

Initialization takes place through the entry point function GetServerVariable. In the C++ environment, you define entry point functions through a .def file. For example, the following code sample would be used to specify the entry point functions in a .def file for an extension called MyExtension.

; MyExtension.def : declares the module parameters for the DLL.

LIBRARY         "MyExtension"

EXPORTS
    HttpExtensionProc
    GetExtensionVersion
    TerminateExtension

The purpose of GetExtensionVersion is to establish the version of ISAPI that was used to build the DLL. The following code accomplishes this task.

BOOL WINAPI
GetExtensionVersion(
    HSE_VERSION_INFO* pVer
    )
{
        pVer->dwExtensionersion =
        MAKELONG(HSE_VERSION_MINOR, HSE_VERSION_MAJOR);
        strcpy(pVer->lpszExtensionDesc, "My ISAPI Extension");

return (TRUE);
}

Processing

You can expose your extension's functionality through the HTTPExtensionProc entry point function. This function receives an EXTENSION_CONTROL_BLOCK (ECB) structure that contains data used for required processing. Also, your extension communicates with IIS through the ECB.

You can obtain the ECB through the HttpExtensionProc function.

When you use HttpExtensionProc, it first sends a header to the client, which provides the client with information, such as the content type that will be returned. After you send the header, you can perform any other processing through the various callback functions provided in the ECB.

Further details on processing can be found in the Reading and Writing Asynchronously topic.

Termination

IIS removes an extension from memory when it is no longer needed. If the extension provides the optional TerminateExtension entry point function, IIS will call the function before removing the extension. You can use TerminateExtension to close down any threads that your extension has initialized during processing.


Sending a Header

Before your extension delivers any output, it must send the client an HTTP response header. This header must be in the correct format or the client will not be able to use it. Among other things, the response header specifies the type of content that you are returning to the client and whether or not the connection should be kept active after the request has been serviced.

To send a response header you should call the ServerSupportFunction (HSE_REQ_SEND_RESPONSE_HEADER_EX). (Note that HSE_REQ_SEND_RESPONSE_HEADER_EX is an upgrade from the HSE_REQ_SEND_RESPONSE_HEADER function.)This function uses the HSE_SEND_HEADER_EX_INFO structure to specify the header information. The processing steps you should build into your extension in order to send a response header are:

  • populate the HSE_SEND_HEADER_EX_INFO structure with the required data
  • call ServerSupportFunction and specify HSE_REQ_SEND_RESPONSE_HEADER_EX as the value for the dwHSERequest parameter
  • handle any error conditions.

The following example demonstrates using the ServerSupportFunction (HSE_REQ_SEND_RESPONSE_HEADER_EX) to send a response header.

*/
GetExtensionVersion

IIS calls this entry point to load the ISAPI DLL.

Returns:
    TRUE on success

Side effects:
    None.
*/
BOOL WINAPI
GetExtensionVersion(
    HSE_VERSION_INFO *pVer
)
{
    pVer->dwExtensionVersion =
        MAKELONG( HSE_VERSION_MINOR, HSE_VERSION_MAJOR );

    lstrcpyn(
        pVer->lpszExtensionDesc
        , "ISAPI SendHeaderEx sample"
        , HSE_MAX_EXT_DLL_NAME_LEN
    );

    return TRUE;
}

/*---------------------------------------------------------------------*
HttpExtensionProc

IIS calls this entry point to process a browser request.

Returns:
    TRUE on success

Side effects:
    None.
*/
DWORD WINAPI
HttpExtensionProc(
    EXTENSION_CONTROL_BLOCK *pECB
)
{

    HSE_SEND_HEADER_EX_INFO    SendHeaderExInfo;

    DWORD cchStatus;
    DWORD cchHeader;
    DWORD cchContent;

    //
    //  NOTE we must send Content-Length header with correct byte count
    //  in order for keep-alive to work.
    //

    char szStatus[]     = "200 OK";
    char szContent[]    =   "<html>"
                            "<br> Usage:"
                            "<br> To keep connection alive: http://localhost/vdir/SendHdrX.dll?Keep-Alive"
                            "<br> To close connection: http://localhost/vdir/SendHdrX.dll"
                            "</html>";
    char szHeaderBase[] = "Content-Length: %lu\r\nContent-type: text/html\r\n\r\n";
    char szHeader[4096];

    cchStatus = lstrlen(szStatus);
    cchHeader = lstrlen(szHeader);
    cchContent = lstrlen(szContent);

    //
    //  fill in byte count in Content-Length header
    //

    sprintf( szHeader, szHeaderBase, cchContent );

    //
    //  Populate SendHeaderExInfo struct
    //

    SendHeaderExInfo.pszStatus = szStatus;
    SendHeaderExInfo.pszHeader = szHeader;
    SendHeaderExInfo.cchStatus = cchStatus;
    SendHeaderExInfo.cchHeader = cchHeader;
    SendHeaderExInfo.fKeepConn = FALSE;

    if ( 0 == lstrcmpi( pECB->lpszQueryString , "Keep-Alive" ) ) {

        SendHeaderExInfo.fKeepConn = TRUE;
    }

    //
    //  Send header
    //

    if ( !pECB->ServerSupportFunction(
                pECB->ConnID
                , HSE_REQ_SEND_RESPONSE_HEADER_EX
                , &SendHeaderExInfo
                , NULL
                , NULL
            ) ) {

        return HSE_STATUS_ERROR;
}

For a complete working sample of an extension that sends a response header to the client, see Developer Samples.


Reading and Writing Asynchronously

ISAPI supports asynchronous I/O operations in three ways. First, your extension can write to the client asynchronously by calling the WriteClient callback function with the dwReserved parameter set to HSE_IO_ASYNC. Your extension can read from the client asynchronously by calling the ServerSupportFunction callback function with the dwHSERequest parameter set to HSE_REQ_ASYNC_READ_CLIENT. Finally, your extension can utilize the Win32® TransmitFile function to transmit a file quickly using the Winsock socket handle. To use TransmitFile, your extension calls the ServerSupportFunction with the dwHSERequest parameter set to HSE_REQ_TRANSMIT_FILE.

The following code establishes an asynchronous reading from a client.

DWORD
DoAsyncRC(
LPEXTENSION_CONTROL_BLOCK pecb
)
{
    char    szHeader[256] = "";
    BOOL    fReturn = TRUE;
    DWORD   dwFlags;
    DWORD   cbTotalToRead = MAX_BUF_SIZE;
    DWORD   hseStatus = HSE_STATUS_PENDING;

    //
    // Initialize the context for ReadClient
    //

    pByteReadSoFar = &(pecb->cbAvailable);

    fReturn =
    pecb->ServerSupportFunction(
            pecb->ConnID,
            HSE_REQ_IO_COMPLETION,
            AsyncReadClientIoCompletion,
            0,
            pByteReadSoFar);

    if (!fReturn) {
        hseStatus = HSE_STATUS_ERROR;
    }

    dwFlags = HSE_IO_ASYNC;
    fReturn =
    pecb->ServerSupportFunction(
            pecb->ConnID,
            HSE_REQ_ASYNC_READ_CLIENT,
            g_ReadBuffer,
            &cbTotalToRead,
            &dwFlags);

    if (!fReturn) {
        hseStatus = HSE_STATUS_ERROR;
    }

    return (hseStatus);
}

For a complete working sample that performs an asynchronous read from a client, see Developer Samples.


Shutting Down an Extension

TerminateExtension is an optional entry point function you can include in your extension. If you do provide this entry point, IIS will call it before removing the extension from memory. It is recommended that you use TerminateExtension to shut down any worker threads that your extension has used during processing.


Converting Existing CGI Scripts to ISAPI Extensions

This section explains the basic requirements for converting existing CGI script-executable files to ISAPI extension DLLs. As with other DLLs, Web server applications should be thread-safe. More than one client will be executing the same function at the same time, so the code should follow safety procedures in modifying a global or 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 in the Platform 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 it from stdin. For any additional data, the extension uses the ReadClient callback function.
  • Accesses common CGI variables through the ECB. For other variables, it calls GetServerVariable. In a CGI executable file, these are retrieved from the environment table using getenv.
  • Sends data back to the client with the WriteClient callback function instead of writing to stdout.
  • Specifies completion status by either sending the header directly using the WriteClient callback function, or calls ServerSupportFunction using the HSE_REQ_SEND_RESPONSE_HEADER, instead of sending a "Status: NNN xxxxx..." to stdout.
  • Redirects requests with a Location: or URL: header, instead of writing the header to stdout, use the HSE_REQ_SEND_URL if the URL is local. However, if the URL is remote or unknown, HSE_REQ_SEND_URL_REDIRECT_RESP in the ServerSupportFunction callback function is used.


Important Notes for Extension Developers

Because the ISAPI extension DLL is loaded in the same process as the HTTP server, access violations by ISAPI extensions can crash some HTTP servers. Therefore, you should thoroughly test all ISAPI extensions to ensure integrity. This is important; if your ISAPI extension malfunctions, it can corrupt the server's memory space, or cause memory or resource leaks.

With IIS 4.0 you can make sure that such suspect ISAPI DLLs run in the namespace marked as Run in separate memory space. This will ensure that IIS will use the process isolation technique to execute the ISAPI DLL in a different process than the IIS process. IIS also does detection and recovery for such exterior processes dedicated for hosting ISAPI DLLs.

To avoid this problem, many HTTP servers wrap the entry points for your ISAPI extensions in a try/except clause so access violations or other exceptions will not directly affect the server. For more information on the try/except clause, refer to the Win32® API documentation.

The main entry point in the ISAPI extensions, HttpExtensionProc, takes only one input parameter: a pointer to the structure type EXTENSION_CONTROL_BLOCK. You are not expected to change any member except lpszLogData in the ECB structure.

However, you are encouraged to initialize your DLL automatically by defining an entry point function for the DLL (for example, DllMain). The operating system calls this entry point function by default the first time a LoadLibrary call or the last time a FreeLibrary call is made for that DLL, or when a new thread is created or destroyed in the process.

You are also encouraged to maintain statistical information, or any information pertaining to the DLL, within the DLL itself. By creating the appropriate forms, you can measure the usage and performance of a DLL remotely. Also, you can integrate this information with the system performance counters so that you can integrate it with PerfMon. You can also use the lpszLogData member of the ECB to record data with the server log.


Extension Reference

You must provide the following functions as entry points to an ISAPI extension. However, TerminateExtension is an optional entry point. HttpExtensionProc

GetExtensionVersion

TerminateExtension

You can use the following callback functions to build ISAPI extensions.

GetServerVariable

ReadClient

ServerSupportFunction

WriteClient


Entry Point Functions

Every ISAPI extension you create must provide two functions: HttpExtensionProc and GetExtensionVersion. These functions are entry points that will be called by IIS when the extension is loaded. You can also provide the TerminateExtension function, which IIS calls when the extension is shut down.


GetExtensionVersion

The GetExtensionVersion function is the first entry point IIS calls. IIS calls this function in the system context and it is called only once. This enables ISAPI extensions to register their version information with IIS.

BOOL WINAPI GetExtensionVersion(
  HSE_VERSION_INFO* pVer
);

Parameters

pVer
Points to Internet Server Extension Version Information.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. The Win32® GetLastError function can be used to determine why the call failed.


HttpExtensionProc

The HttpExtensionProc function is the main entry point for an ISAPI extension called by IIS. It exposes methods to which IIS uses to access the functionality exposed by the extension.

DWORD WINAPI HttpExtensionProc(
  LPEXTENSION_CONTROL_BLOCK lpECB
);

Parameters

lpECB
Points to the EXTENSION_CONTROL_BLOCK structure.

Return Values

Returns a DWORD containing HSE_STATUS codes. Possible return values are:

Value | Meaning
HSE_STATUS_SUCCESS | The extension has finished processing and the server should disconnect and free up allocated resources.
HSE_STATUS_SUCCESS_AND_KEEP_CONN | The extension has finished processing and the server should wait for the next HTTP request if the client supports persistent connections. The extension should only return this if it was able to send the correct Content-Length header to the client. The server is not required to keep the session open.
HSE_STATUS_PENDING | The extension has queued the request for processing and will notify the server when it has finished. See HSE_REQ_DONE_WITH_SESSION under ServerSupportFunction. If the ISAPI extension is using HSE_STATUS_PENDING, then responses can be sent from work done in another thread after returning the status pending.
HSE_STATUS_ERROR | The extension has encountered an error while processing the request and the server can disconnect and free up allocated resources.

Remarks

This entry point is similar to a main() function in a C++ program. The code in this entry point uses callback functions in the EXTENSION_CONTROL_BLOCK to read client data and decide on the action to take. Before returning to the server, a properly formatted response must be sent to the client through either WriteClient or ServerSupportFunction. Return codes are defined in httpext.h.


TerminateExtension

The TerminateExtension function unloads the ISAPI DLL. This is the standard entry point called by IIS as the last function if it is exposed by the extension.

BOOL WINAPI TerminateExtension(
  DWORD dwFlags
);

Parameters

dwFlags
A DWORD that specifies whether IIS should shut down the extension.
Value | Meaning
HSE_TERM_ADVISORY_UNLOAD | IIS is prepared to close the extension; the extension returns TRUE if ready to close, FALSE if not.
HSE_TERM_MUST_UNLOAD | Server indicates the extension is about to be closed; the extension cannot refuse.


Callback Functions

ISAPI extensions communicate with the IIS through the EXTENSION_CONTROL_BLOCK. Once the main entry point for an ISAPI extension, HttpExtensionProc, takes a pointer to the Extension Control Block, the ISAPI extension can also use callback functions to communicate with the IIS.

The following callback functions are available to ISAPI extensions:

GetServerVariable

PFN_HSE_IO_COMPLETION

ReadClient

ServerSupportFunction

WriteClient


GetServerVariable

The GetServerVariable function retrieves information about a connection or about the IIS itself.

BOOL WINAPI GetServerVariable(
  HCONN hConn,
  LPSTR lpszVariableName,
  LPVOID lpvBuffer,
  LPDWORD lpdwSizeofBuffer
);

Parameters

hConn
[in] Specifies the connection handle.
lpszVariableName
[in] A null-terminated string that indicates which variable is requested. These are the possible variables.
ALL_HTTP | Retrieves all HTTP headers that were received. These variables are of the form HTTP_<header field name>. The headers consist of a null-terminated string with the individual headers separated by line feeds.
ALL_RAW | Retrieves all headers in the raw-form. The header-names and values appear as they are sent by the client. Currently, this value is primarily used by Proxy server and other similar applications.
APPL_MD_PATH | Retrieves the metabase path of the application for the ISAPI DLL or the script.
APPL_PHYSICAL_PATH | Retrieves the physical path that corresponds with the metabase path. IIS maps the namespace to the physical directory path ; this allows APPL_MD_PATH to return this value. This is a costly function (in run time) compared to getting just APPL_MD_PATH.
AUTH_PASSWORD | Specifies the value entered in the client's authentication dialog. This variable is only available if Basic authentication is used.
AUTH_TYPE | Specifies the type of authentication used. If the string is empty, then no authentication is used. Possible values are kerberos, user, SSL/PCT, Basic, and NTLM.
AUTH_USER | Specifies the value entered in the client's authentication dialog.
CERT_COOKIE | Specifies a unique ID for a client certificate. Returned as a string. Can be used as a signature for the whole client certificate.
CERT_FLAGS | If bit0 is set to 1, a client certificate is present. If bit1 is set to 1, the Certifying Authority of the client certificate is invalid (not on this server's list of recognized CAs).
CERT_ISSUER | Specifies the issuer field of the client certificate. For example, the following codes might be O=MS, OU=IAS, CN=user name, C=USA, and so on.
CERT_KEYSIZE | Specifies the number of bits in the Secure Sockets Layer (SSL) connection key size.
CERT_SECRETKEYSIZE | Specifies the number of bits in the server certificate private key.
CERT_SERIALNUMBER | Specifies the serial number field of the client certificate.
CERT_SERVER_ISSUER | Specifies the issuer field of the server certificate.
CERT_SERVER_SUBJECT | Specifies the subject field of the server certificate.
CERT_SUBJECT | Specifies the subject field of the client certificate.
CONTENT_LENGTH | Specifies the number of bytes of data which the script or extension can expect to receive from the client. This total does not include headers.
CONTENT_TYPE | Specifies the content type of the information supplied in the body of a POST request.
HTTP_ACCEPT | Specifies the special-case HTTP header.
HTTPS | Returns on if the request came in through secure channel (SSL), or off if the request is for a non-secure channel.
HTTPS_KEYSIZE | Specifies the number of bits in the SSL connection key size.
HTTPS_SECRETKEYSIZE | Specifies the number of bits in server certificate private key.
HTTPS_SERVER_ISSUER | Specifies the issuer field of the server certificate.
HTTPS_SERVER_SUBJECT | Specifies the subject field of the server certificate.
INSTANCE_ID | Specifies the ID for the IIS instance in textual format. If the instance ID is 1, it appears as a string. This value can be used to retrieve the ID of the Web-server instance, in the metabase, to which the request belongs.
INSTANCE_META_PATH | Specifies the metabase path for the instance to which the request belongs.
PATH_INFO | Specifies the additional path information, as given by the client. This consists of the trailing part of the URL after the script name, but before the query string, if any.
PATH_TRANSLATED | Specifies this is the value of PATH_INFO, but with any virtual path expanded into a directory specification.
QUERY_STRING | Specifies the information which follows the question mark in the URL that referenced this script.
REMOTE_ADDR | Specifies the IP address of the client or agent of the client (for example gateway, proxy, or firewall) that sent the request.
REMOTE_HOST | Specifies the host name of the client or agent of the client (for example, gateway, proxy or firewall) that sent the request.
REMOTE_USER | Specifies the user name supplied by the client and authenticated by the server. This comes back as an empty string when the user is anonymous.
REQUEST_METHOD | Specifies the HTTP request method verb.
SCRIPT_NAME | Specifies the name of the script program being executed.
SERVER_NAME | Specifies the server's host name, or IP address, as it should appear in self-referencing URLs.
SERVER_PORT | Specifies the TCP/IP port on which the request was received.
SERVER_PORT_SECURE | Specifies a string of either 0 or 1. If the request is being handled on the secure port, then this will be 1. Otherwise, it will be 0.
SERVER_PROTOCOL | Specifies the name and version of the information retrieval protocol relating to this request.
SERVER_SOFTWARE | Specifies the name and version of the Web server under which the ISAPI Extension DLL program is running.
URL | Specifies the base portion of the URL. Parameter values will not be included. The value is determined when IIS parses the URL from the header.

lpvBuffer
[out] Points to the buffer to receive the requested information.
lpdwSizeofBuffer
[in/out] Points to a DWORD that indicates the size of the buffer pointed to by lpvBuffer. On successful completion, the DWORD contains the size of bytes transferred into the buffer, including the null-terminating byte.

Return Values

If the function succeeds, the return value is TRUE. If the function fails, the return value is FALSE. The Win32® GetLastError function can be used to determine why the call failed. The following are the possible error values.

Value | Meaning
ERROR_INVALID_PARAMETER | Bad connection handle, in either lpszVariableName or lpdwSizeOfBuffer.
ERROR_INVALID_INDEX | Bad or unsupported variable identifier.
ERROR_INSUFFICIENT_BUFFER | Buffer too small. The required buffer size is *lpdwSizeofBuffer.
ERROR_NO_DATA | The data requested is not available.

Remarks

The GetServerVariable function copies information into a buffer supplied by the caller. The information can include CGI variables and information relating to an HTTP connection or to the server itself.

Note In respect to AUTH_TYPE, if the string is not empty it does not mean the user was authenticated (if the authentication scheme is not basic or NTLM). The server allows authentication schemes it does not natively understand since an ISAPI Filter may be able to handle that particular scheme.

The lpszVariableName can be used to retrieve a specific header by using the HTTP_<headername> value. For example, supplying the value HTTP_ACCEPT returns the accept header, and HTTP_VERSION returns the version header.

The values of the fields for the HTTP_ACCEPT variable are concatenated, and separated by a comma (,).

If bit 1 of the Cert_Flags variable is set to 1, indicating that the certificate is invalid, IIS 4.0 will reject the certificate. Earlier versions of IIS will not reject the certificate.


PFN_HSE_IO_COMPLETION

VOID WINAPI * PFN_HSE_IO_COMPLETION(
  EXTENSION_CONTROL_BLOCK * pECB,
  PVOID pContext,
  DWORD cbIO,
  DWORD dwError
);

Parameters

pECB
Points to the EXTENSION_CONTROL_BLOCK for the request.
pContext
Points to the context that can be used to identify the connection. This is the context that was supplied to IIS when the asynchronous I/O callback function was registered.
cbIO
A DWORD that contains the number of bytes of I/O in the last call.
dwError
The error code returned.

Remarks

This is the callback function for handling completions of asynchronous I/O operations. This function performs necessary clean up and resubmits additional I/O, if required. If there is no more work to be done for the current request, this function cleans up the state and notifies IIS that the request is ending by sending a ServerSupportFunction with the HSE_REQ_DONE_WITH_SESSION value.


ReadClient

The ReadClient function reads data from the body of the client's HTTP request.

BOOL ReadClient(
  HCONN hConn,
  LPVOID lpvBuffer,
  LPDWORD lpdwSize
);

Parameters

hConn
[in] A connection handle.
lpvBuffer
[out] Points to the buffer area to receive the requested information.
lpdwSize
[in/out] Points to a DWORD that indicates the number of bytes available in the buffer. On return, lpdwSize will contain the number of bytes actually transferred into the buffer.

Return Values

If the function succeeds, the return value is TRUE. If an error occurs, the return value is FALSE. The Win32® GetLastError function can be called to determine the error.

Remarks

The ReadClient function reads information from the body of the Web client's HTTP request into the buffer supplied by the caller. Thus, the call can be used to read data from an HTML form that uses the POST method. If more than lpdwSize bytes are immediately available to be read, ReadClient will block until some amount of data has been returned, and will return with less than the requested amount of data. In order to ensure that all data has been read, your program should call ReadClient in a loop which continues to run until the amount of data specified in lpdwSize has been read. If the socket on which the server is listening to the client is closed, ReadClient will return TRUE, but with zero bytes read. It is not necessary to call ReadClient unless cbTotalBytes is larger than cbAvailable. CbTotalBytes and cbAvailable are members of the EXTENSION_CONTROL_BLOCK structure for the request. These values are initialized when an ISAPI entry point is called.

If the size specified in lpdwSize is greater than the number of bytes available to be read, it is possible ReadClient will block until the data arrives.


ServerSupportFunction

The ServerSupportFunction is a callback function that is supplied in the ECB (EXTENSION_CONTROL_BLOCK). It supports several auxiliary functions that are not covered by other explicit callback functions in the ECB.

BOOL ServerSupportFunction(
  HCONN ConnID,
  DWORD dwHSERRequest,
  LPVOID lpvBuffer,
  LPDWORD lpdwSize,
  LPDWORD lpdwDataType
);

Parameters

ConnID
Specifies the logical connection identifier of the client to which the response data should be sent.
dwHSERRequest
Specifies a DWORD that contains the HTTP Server Extension Request type which indicates the functions the ISAPI extension requested . Possible values are:
Value | Meaning
HSE_APPEND_LOG_PARAMETER | Appends a string to the log record being written out to the log file.
HSE_REQ_ABORTIVE_CLOSE | Requests an abortive close on disconnect for this connection. Abortive close is one of the two types of closes (the other is graceful close) available for TCP sockets. In an abortive close the server forces an immediate close of the connection once the data is sent. Generally, the abortive close performs much better than the graceful close.
HSE_REQ_ASYNC_READ_CLIENT Enables the ISAPI extension to perform an aynchronous read from the client. The extension should submit a callback function and context by calling ServerSupportFunction with HSE_REQ_IO_COMPLETION specified. If this is not done, the call will fail and the serer will return ERROR_INVALID_PARAMETER. If the read completes with zero bytes read, then the client has closed their connection gracefully so the operation should be terminated.

If this value is specified, the only supported value for lpdwDataType is HSE_IO_ASYNC.
HSE_REQ_DONE_WITH_SESSION | Specifies that if the server extension holds on to the session because of extended processing requirements, the server must be notified when the session is finished so the server can close it and free its related structures. The parameters lpdwSize, and lpdwDataType are ignored. The lpvBuffer parameter may optionally point to a DWORD that contains HSE_STATUS codes. IIS recognizes HSE_STATUS_SUCCESS_WITH_KEEP_CONN for keeping the IIS connection alive if the client also requests to keep the connection alive. This parameter must be sent to the server if the HSE_IO_DISCONNECT_AFTER_SEND parameter has been included in the HSE_TF_INFO structure as part of a HSE_REQ_TRANSMIT_FILE request. This parameter will explicitly close the connection.
HSE_REQ_GET_CERT_INFO_EX Specifies the certificate context for the first certificate in the client's certificate chain.

This option depends upon two structures: the CERT_CONTEXT_EX structure.which contains an embedded CERT_CONTEXT structure.

The CERT_CONTEXT structure contains an embedded buffer, which will hold the certificate.

To use this option, the caller must: 1) instantiate a CERT_CONTEXT_EX structure; 2) allocate the buffer embedded within the CERT_CONTEXT structure; and 3) pass HSE_REQ_GET_CERT_INFO_EX as the second parameter, and the address of the CERT_CONTEXT_EX structure as the third parameter to ServerSupportFunction.

HSE_REQ_GET_IMPERSONATION_TOKEN Specifies a handle to the impersonation token that the request is running. An impersonation token is a handle that represents a user context. Before resources, such as files and registry keys are opened, the thread should be impersonated first with either the ImpersonateLoggedOnUser or SetThreadToken Win32® API. The impersonation token returned by HSE_REQ_GET_IMPERSONATION_TOKEN can be used with these APIs.

The token is owned by IIS. The ISAPI DLL should not call CloseHandle on this token. The lifetime of the token lasts until the current request's ECB is destroyed.

The lpvBuffer parameter points to the HANDLE that will contain the impersonation token.
HSE_REQ_GET_SSPI_INFO Specifies the CtxtHandle and CredHandle structures, as defined in sspi.h, for the server's certificate chain.

The caller can then use these handles to query or manipulate the server certificate information through the standard certificate API's defined in sspi.h.

To use this option, the caller must first instantiate CtxtHandle and CredHandle structures, then pass HSE_REQ_GET_SSPI_INFO as the second parameter, the address of the CtxtHandle structure as the third parameter, and the address of the CredHandle structure as the fifth parameter to ServerSupportFunction.

NOTE: This option is not supported if your extension is running in a separate process from IIS.
HSE_REQ_IO_COMPLETION Enables the ISAPI extension to set a callback function and context that will be used for handling asynchronous I/O operations. The callback function is PFN_HSE_IO_COMPLETION

The callback function is used only if the function pointer passed is non-NULL. Any context value is allowed. If multiple calls are made for this option, the values used in the most recent call to ServerSupportFunction will be used. All old values will be lost.

In case of errors during asynchronous I/O processing, the server makes a single call to the callback function. It is the responsibility of the ISAPI extension to do the cleanup during the call.

When this option is used, lpvBuffer points to the callback function for asynchronous I/O completion and lpdwDataType contains the Context value to use for the callbacks.
HSE_REQ_IS_KEEP_CONN | Obtains the keep-alive status of the connection. If this option is used, lpvBuffer points to a BOOL which will contain the state on return.
HSE_REQ_MAP_URL_TO_PATH | Specifies that the lpvBuffer parameter points to the buffer that contains the logical path on entry and the physical path on exit. The lpdwSize parameter points to the DWORD containing the size of the buffer passed in lpvBuffer on entry, and the number of bytes placed in the buffer on exit. The lpdwDataType parameter is ignored.
HSE_REQ_MAP_URL_TO_PATH_EX | This is an improved version of the HSE_REQ_MAP_URL_TO_PATH function. This version requires that you provide a pointer to the HSE_URL_MAPEX_INFO structure in the lpdwDataType parameter. IIS will fill populate this structure with information concerning the URL, such as any attributes values that have been set.
HSE_REQ_REFRESH_ISAPI_ACL | Forces the server to update the ISAPI DLL ACL dynamically. This option forces the server to re-read the ACL for the ISAPI DLL. If this option is used LpvBuffer is a string that contains the name of the ISAPI DLL.
HSE_REQ_SEND_URL_REDIRECT_RESP | This option sends a 302 message (URL Redirect) to the client. No further processing is needed after the call. This operation is similar to specifying URI: <URL> in a CGI script header. With this option, the lpvBuffer variable points to a null-terminated string of URL. The variable lpdwSize should have the size of lpvBuffer. The variable lpdwDataType is ignored.
HSE_REQ_SEND_URL Sends the data specified by the URL to the client as if the client had requested that URL. The null-terminated URL pointed to by lpvBuffer must be on the server and must not specify protocol information (that is, it must begin with a /). No further processing is required after this call. This value should only be used if you are not sending any response back to the client. The parameter lpdwSize points to a DWORD holding the size of lpvBuffer. The parameter lpdwDataType is ignored.

Support for this value is for compatability with earlier versions of ISAPI. HSE_REQ_SEND_URL_EX should be used instead.
HSE_REQ_SEND_URL_EX | Similar to HSE_REQ_SEND_URL; however, it adds support for specifying the verb to use in the redirect.
HSE_REQ_SEND_RESPONSE_HEADER | Sends a complete HTTP server response header, including the status, server version, message time, and MIME version. The ISAPI extension should append other HTTP headers such as the content type and content length, followed by an extra \r\n. This option allows the function to take only text, up to the first \0 terminator. The function with this parameter should only be called once per request.
HSE_REQ_SEND_RESPONSE_HEADER_EX This is an improved version of HSE_REQ_SEND_RESPONSE_HEADER. This new version allows your extension to specify whether the connection should be kept open through the fKeepConn member of the HSE__SEND_HEADER_EX_INFO structure. You can also use this structure to indicate the lengths of the header and status strings, which will provide better performance than using HSE_REQ_SEND_RESPONSE_HEADER.

This function requires that a pointer to the HSE_SEND_HEADER_EX_INFO structure be included in the lpvbuffer parameter.
HSE_REQ_TRANSMIT_FILE Enables the ISAPI extension to use the Win32 TransmitFile function to send a file to the client. The server performs this operation asynchronously. The extension should either submit a callback function (and context) by setting the values in the HSE_TF_INFO object passed in or should have called ServerSupportFucntion with HSE_REQ_IO_COMPLETION set. If none of the above is done, this call will fail and the server will return an ERROR_INVALID_PARAMETER. Also, the extension should specify the file handle in the structure that is passed in. If all parameters are present, the server submits this operation to its internal asynchronous I/O queue and returns to the caller. The ISAPI extension can at this point return HSE_STATUS_PENDING, if returning from HttpExtenionProc, and later on use HSE_DONE_WITH_SESSION, when the callback that indicates I/O has completed occurs.

If this option is used, lpvBuffer points to the HSE_TF_INFO object. lpdwSize and
lpdwDataType are both ignored.

lpvBuffer
Points to a buffer. The contents of the buffer will vary, depending on the value set for the dwHSERRequest parameter. Details are provided in the table of possible values for the dwHSERRequest parameter.
lpdwSizeofBuffer
Points to a DWORD. The meaning of the DWORD will vary, depending on the value set for the dwHSERRequest parameter. Details are provided in the table of possible values for the dwHSERRequest parameter.
lpdwDataType
Points to a DWORD. The meaning of the DWORD will vary, depending on the value set for the dwHSERRequest parameter. Details are provided in the table of possible values for the dwHSERRequest parameter.


WriteClient

The WriteClient function is a callback function that is supplied in the ECB (EXTENSION_CONTROL_BLOCK) for a request sent to the ISAPI extension. It sends the data present in the given buffer to the client that made the request.

BOOL WriteClient(
  HCONN ConnID,
  LPVOID Buffer,
  LPDWORD lpdwBytes,
  DWORD dwReserved
);

Parameters

ConnID
Specifies the logical connection identifier of the client to which the response data should be sent.
Buffer
Points to the data to be sent.
lpdwSizeofBuffer
Points to a DWORD that contains the number of bytes from the buffer that will be written to the client when the call is made. The DWORD also contains the number of bytes successfully sent out for synchronous write operations. For asynchronous write operations the returned value has no meaning.
dwReserved
Specifies a DWORD that contains flags which indicates how the I/O operation should be handled. Can be either of the following values.
Value | Meaning
HSE_IO_SYNC | Indicates that the I/O operation should be done synchronously
HSE_IO_ASYNC | Indicates that the I/O operation should be done asynchronously. The ISAPI extension should have made a call to ServerSupportFunction( HSE_REQ_IO_COMPLETION) and submitted a callback function and context value for handling completion of asynchronous operations.

Return Values

If the function succeeds, the return value is TRUE. If an error occurs, the return value is FALSE. The Win32® GetLastError function can be called to determine the cause of the error.

Remarks

This function attempts to write the data in the supplied buffer to the socket in which the client request came in. For synchronous writes, it attempts to write in the calling thread. The thread may become blocked while trying to send the data to client. On completion, WriteClient returns the number of bytes sent in *lpdwBytes.

For asynchronous writes, WriteClient submits the write operation to the system asynchronously and returns from the call immediately. At this point the ISAPI extension may choose to do more background processing or return from the HttpExtensionProc function with a HSE_STATUS_PENDING. When the I/O operation completes, the server calls the callback function submitted by ISA with the ECB, context value, number of bytes sent and error codes, if any. It is the responsibility of ISA to do further processing and finally use ServerSupportFunction with HSE_DONE_WITH_SESSION set to notify the server when it is done processing the request.

Only one outstanding asynchronous I/O operation is permitted per request. This includes an asynchronous WriteClient, an asynchronous TransmitFile, or a ServerSupportFunction call with the HSE_REQ_SEND_URL value set.


Structures

This section contains descriptions of the structures that are used by ISAPI extensions.

  • CERT_CONTEXT_EX
  • EXTENSION_CONTROL_BLOCK
  • HSE_TF_INFO
  • HSE_URL_MAPEX_INFO
  • HSE_VERSION_INFO


CERT_CONTEXT_EX

This structure is used to send certificate information to the ISAPI extension when the HSE_REQ_GET_CERT_INFO_EX value is set for the dwHSERRequest parameter of the ServerSupportFunction.

typedef struct _CERT_CONTEXT_EX
{CERT_CONTEXT    CertContext;
DWORD           cbAllocated;
DWORD           dwCertificateFlags;
}

Members

CertContext
A CERT_CONTEXT structure.
cbAllocated
The number of bytes the extension has allocated for the certificate buffer in the CERT_CONTEXT structure.
dwCertificateFlags
A DWORD describing the certificate. Bit0 will be set to 1 if the Client Certificate is present and Bit1 will be set to 1 if the Certifying Authority is invalid.

Remarks

For further information on the CERT_CONTEXT structure, see the CryptoAPI documentation in the Platform SDK.


EXTENSION_CONTROL_BLOCK

This structure is used by IIS and the extension to exchange information.

typedef struct _EXTENSION_CONTROL_BLOCK
{DWORD     cbSize;                // Size of this struct.
DWORD     dwVersion;              // Version info of this spec
HCONN     ConnID;                 // Context number not to be modified!
DWORD     dwHttpStatusCode;       // HTTP Status code
CHAR      lpszLogData[HSE_LOG_BUFFER_LEN];// null terminated log info specific to this Extension DLL
LPSTR     lpszMethod;             // REQUEST_METHOD
LPSTR     lpszQueryString;        // QUERY_STRING
LPSTR     lpszPathInfo;           // PATH_INFO
LPSTR     lpszPathTranslated;     // PATH_TRANSLATED
DWORD     cbTotalBytes;           // Total bytes indicated from client
DWORD     cbAvailable;            // Available number of bytes
LPBYTE    lpbData;                // Pointer to cbAvailable bytes
LPSTR     lpszContentType;        // Content type of client data
BOOL (WINAPI * GetServerVariable);
BOOL (WINAPI * WriteClient);
BOOL (WINAPI * ReadClient);
BOOL (WINAPI * ServerSupportFunction);
}

Members

cbSize (IN)
The size of this structure.
dwVersion (IN)
The version information of this specification. The HIWORD has the major version number and the LOWORD has the minor version number.
connID (IN)
A unique number assigned by the HTTP server which should not be modified.
dwHttpStatusCode (OUT)
The status of the current transaction when the request is completed.
lpszLogData (OUT)
Buffer of size HSE_LOG_BUFFER_LEN. Contains a null-terminated log information string, specific to the ISAPI Extension, of the current transaction. This log information will be entered in the HTTP server log. Maintaining a single log file with both HTTP server and ISAPI extension transactions is very useful for administration purposes.
lpszMethod (IN)
The HTTP method with which the request was made, for example, GET, or POST. This is equivalent to the CGI variable REQUEST_METHOD.
lpszQueryString (IN)
A null-terminated string that contains the query information. This is the part of the URL string that appears after the questions mark (?). This is equivalent to the CGI variable QUERY_STRING.
lpszPathInfo (IN)
A null-terminated string that contains extra path information given by the client. This is the part of the string that appears between the DLL/script name in the URL and the question mark (?). The value is equivalent to the CGI variable PATH_INFO.
lpszPathTranslated (IN)
A null-terminated string that contains the translated path. This is equivalent to the CGI variable PATH_TRANSLATED.
cbTotalBytes (IN)
The total number of bytes to be received from the client. This is equivalent to the CGI variable CONTENT_LENGTH. If this value is 0xffffffff, then there are 4 gigabytes or more of available data. In this case, ReadClient should be called until no more data is returned.
cbAvailable (IN)
The available number of bytes (out of a total of cbTotalBytes) in the buffer pointed to by lpbData. If cbTotalBytes is the same as cbAvailable, the lpbData variable will point to a buffer that contains all the data as sent by the client. Otherwise, cbTotalBytes will contain the total number of bytes of data received. The ISAPI extensions will then need to use the callback function ReadClient to read the rest of the data (beginning from an offset of cbAvailable). With IIS 4.0, you can also use the asynchronous ReadClient facility through ServerSupportFunction with the HSE_REQ_ASYNC_READ_CLIENT value set.
lpbData (IN)
Points to a buffer of size cbAvailable that has the data sent by the client.
lpszContentType (IN)
A null-terminated string containing the content type of the data sent by the client. This is equivalent to the CGI variable CONTENT_TYPE.
GetServerVariable
GetServerVariable retrieves information about a connection or about the server itself.
WriteClient
WriteClient sends the data present in the given buffer to the client that made the request.
ReadClient
ReadClient reads data from the body of the client's HTTP request.
ServerSupportFunction
ServerSupportFunction returns data for several auxiliary functions not covered by other callback functions.

Remarks

When IIS receives a request for an ISAPI extension, it tries to include the amount of data in the lpbData parameter as is specified in the MD_UPLOAD_READAHEAD_SIZE property of the metabase. The default value for this property is 48K, however, it can be set to any size in the range of 0 bytes to 4GB.


HSE_SEND_HEADER_EX_INFO

This structure is used by the ServerSupportFunction HSE_REQ_SEND_RESPONSE_HEADER_EX. An ISAPI extension must fill the structure with the required data and return it to the IIS. You can use this structure to indicate that the connection that is being used to service the current request should be kept active for further processing.

typedef struct _HSE_SEND_HEADER_EX_INFO  {
    // HTTP status code and header
    //
    LPCSTR  pszStatus;  // HTTP status code  eg: "200 OK"
    LPCSTR  pszHeader;  // HTTP header
    DWORD   cchStatus;  // number of characters in status code
    DWORD   cchHeader;  // number of characters in header
    BOOL    fKeepConn;  // keep client connection alive?
} HSE_SEND_HEADER_EX_INFO, * LPHSE_SEND_HEADER_EX_INFO;

Members

pszStatus
The status of the current request.
pszHeader
The header to return.
cchStatus
The number of characters in the status code.
cchHeader
The number of characters in the header.
fKeepConn
A boolean indicating whether of not the connection that was used to process the request should remain active.


HSE_TF_INFO

This structure is used by to communicate information needed to use the Win32® TransmitFile function. It is supplied by the ISAPI extension when the HSE_REQ_TRANSMIT_FILE parameter is specified for the dwHSERRequest parameter of the ServerSupportFunction.

typedef struct _HSE_TF_INFO  {
    PFN_HSE_IO_COMPLETION   pfnHseIO;
    PVOID  pContext;   //open files with FILE_FLAG_SEQUENTIAL_SCAN
    HANDLE hFile;
    LPCSTR pszStatusCode; // HTTP Status Code  eg: "200 OK"
    DWORD  BytesToWrite; // value of "0" means send entire file
    DWORD  Offset;       // offset value within file to start from
    PVOID  pHead;        // pointer to Headers to be sent before file
    DWORD  HeadLength;   // header length
    PVOID  pTail;        // pointer to Tail to be sent after file data
    DWORD  TailLength;   // tail length
    DWORD  dwFlags;      // includes HSE_IO_DISCONNET_AFTER_SEND, ...
} HSE_TF_INFO, * LPHSE_TF_INFO;

Members

pfnHseIO
Points to the callback function that will be called on asynchronous I/O completion. These values, if non-null, will override values set by calling ServerSupportFunction with the HSE_REQ_IO_COMPLETION value set.
pContext
Points to a Context structure that will be used in the asynchronous I/O callback.
hFile
HTTP header and status code. These fields are used only if HSE_IO_SEND_HEADERS is present in dwFlags. The file should be opened using the Win32® CreateFile function with the FILE_FLAG_SEQUENTIAL_SCAN and FILE_FLAG_OVERLAPPED values turned on.
pszStatusCode
The HTTP status code.
BytesToWrite
If the value is set to 0, the entire file will be sent.
Offset
The location in the file to start reading.
pHead
An optional pointer to the headers which are to be sent before the file.
HeadLength
The length of the headers.
pTail
An optional pointer to a tail to be sent after the file.
TailLength
The length of the tail.
dwFlags
Flags that indicate the action to be taken by the server. Can be one of the following values.
Value | Meaning
HSE_IO_ASYNC | This flag must be set if ServerSupportFunction has been called with the HSE_REQ_TRANSMIT_FILE option.
HSE_IO_DISCONNECT_AFTER_SEND | Enables the server to optimally reuse its internal buffers and sockets for future connections. Using this flag improves the responsiveness by using system features optimally. However, the extension will not be able to do any further data transmission if this flag is selected, because the session to the client will be released.
HSE_IO_SEND_HEADERS | Specifies that custom header information should be transmitted to the client. The ISAPI extension can store the status code in the pszStatusCode member of the HSE_TF_INFO structure. When the header flag is turned on, IIS will automatically construct an appropriate HTTP header and send it to the client along with the file contents. If this flag is used for header transmission, the ISAPI extension should not send its own header using the HSE_REQ_SEND_RESPONSE_HEADERS or HSE_REQ_SEND_RESPONSE_HEADERS_EX values in ServerSupportFunction.


HSE_URL_MAPEX_INFO

You can use this structure with the HSE_REQ_MAP_URL_TO_PATH_EX ServerSupportFunction. The structure is returns information regarding the virtual root that is to be mapped to a physical path.

typedef struct _HSE_URL_MAPEX_INFO {
    CHAR   lpszPath[MAX_PATH]; // Physical path mapped to by the URL
    DWORD  dwFlags             // Flags associated with this URL path
    DWORD  cchMatchingPath;    // Number of matching characters in
                               // physical path
    DWORD  cchMatchingURL;     // Number of matching characters in URL
    DWORD  dwReserved1;
    DWORD  dwReserved2;
} HSE_URL_MAPEX_INFO, * LPHSE_URL_MAPEX_INFO;

Members

lpszPath
The physical path the root maps to.
dwFlags
Flags that have been associated with this URL. Indicates if the URL has read, write, or execute permissions. Can also be used to indicate if encryption is required. Can be one of the following:
Value | Meaning
HSE_URL_FLAGS_READ | Allow for Read.
HSE_URL_FLAGS_WRITE | Allow for Write.
HSE_URL_FLAGS_EXECUTE | Allow for Execute.
HSE_URL_FLAGS_SSL | Require SSL.
HSE_URL_FLAGS_DONT_CACHE | Don't cache (v-root only).
HSE_URL_FLAGS_NEGO_CERT | Allow client SSL certifications.
HSE_URL_FLAGS_REQUIRE_CERT | Require client SSL certifications.
HSE_URL_FLAGS_MAP_CERT | Map SSL certification to a Windows NT® account.
HSE_URL_FLAGS_SSL128 | Requires a 128-bit SSL.
HSE_URL_FLAGS_SCRIPT | Allows for script execution.

cchMatchingPath
Number of matching characters in the physical path.
cchMatchingURL
Number of matching characters in the URL.
dwReserved1
Reserved. Do not use.
dwReserved2
Reserved. Do not use.


HSE_VERSION_INFO

This structure passes IIS information regarding the version of the extension.

typedef struct   _HSE_VERSION_INFO {
    DWORD  dwExtensionVersion;
    CHAR   lpszExtensionDesc[HSE_MAX_EXT_DLL_NAME_LEN];
HSE_VERSION_INFO, *LPHSE_VERSION_INFO;

Members

dwExtensionVersion
The version of the extension.
lpszExtensionDescription
A description of the extension.


Developing ISAPI Filters

You can use an ISAPI filter to receive notifications of various events during the processing of HTTP requests. Filters are similar to extensions in that they are implemented as DLLs and run in the same process as IIS. The fundamental difference between filters and extensions is that extensions are only loaded when they are requested by a client. Filters are loaded when you start IIS, and are kept in memory until you shut IIS down. Once a filter is loaded, it indicates the events that IIS should send notification about. Subsequently, IIS will notify the filter each time one of the registered events occurs.

This section contains the following:

  • Filter Event Processing
  • Basic Filter Framework
  • Summary of Event Ordering
  • Obtaining Server Variables
  • Adding to a Response Header
  • Adding a Filter
  • Developer notes for ISAPI filters


Filter Event Processing

Every filter is contained in a separate DLL with two common entry point functions, GetFilterVersion and HttpFilterProc. When the DLL is loaded, GetFilterVersion is called. When the GetFilterVersion entry point is called, it passes an HTTP_FILTER_VERSION structure to the filter. The filter uses this structure to provide IIS with version information, a list of the events that the filter should be informed of, and the priority level for each event.

After this first exchange, every time IIS processes one of the available events, it calls any filters that have registered for that event. If several filters have registered for the same event, the filters are called sequentially. The order that IIS calls the filters depends first on the priority specified in the dwFlags member of the HTTP_FILTER_VERSION structure by GetFilterVersion. If two or more different filters have registered for the same event at the same priority level, the order that the filters were loaded determines the order in which they are called. You can configure the order that filters are loaded by using the metabase. The order in which events are processed is described in detail in Summary of Event Ordering.

When the HttpFilterProc entry point is called, the filter uses the notificationType parameter to determine what action to take. For example, a filter that encrypts data will probably register for events that read or write raw data. When the filter receives notification that a read or write event has occurred, it encrypts the data and uses the WriteClient callback function to write the encrypted data to the client.


Basic Filter Framework

Like ISAPI extensions, ISAPI filters must provide two common entry points, and can optionally provide a termination entry point. The required entry points are GetFilterVersion and HttpFilterProc. Support for a third optional entry point, the TerminateFilter function has been added in ISAPI 4.0. If your filter exposes TerminateFilter, IIS will call this function before it removes the filter from memory. TerminiateFilter is similar to TerminateExtension; it is intended as a way for you to perform any resource maintenance required before shutting down.

The basic structure of an ISAPI filter consists of the functions that accomplish each of the following three tasks:

  • Initializing a filter
  • Processing the event
  • Terminating the filter

Initializing a filter

When IIS loads an ISAPI filter, it calls the GetFilterVersion function. This function returns the HTTP_FILTER_VERSION data structure to IIS. The structure includes a short description of the filter and the server events for which the filter needs to be notified. Server events are specified by the data structure's dwFlags member.

The following code registers a filter for notification before sending raw data to the client and before updating the log file.

BOOL WINAPI GetFilterVersion( PHTTP_FILTER_VERSION pVer )
{

// The next line sets the version of the filter.

    pVer->dwFilterVersion = HTTP_FILTER_REVISION;

// The next line sets the description of the filter.

    lstrcpy( pVer->lpszFilterDesc, "Reading Raw Data and Logging filter" );

// This filter will be notified for the following notifications
    pVer->dwFlags = SF_NOTIFY_SEND_RAW_DATA | SF_NOTIFY_LOG;

    return TRUE;
}

Processing the event

The function responsible for processing the event information is the HTTPFilterProc. IIS calls your filter for every event that you have registered the filter for. When IIS calls HTTPFilterProc, it passes in an HTTP_FILTER_CONTEXT data structure. This structure is similar to the ECB for an ISAPI extension, in that it is associated with a particular request, and is used by IIS to coordinate filter processing. When IIS calls the filter's HTTPFilterProc, it also passes in a DWORD identifying which event has occurred and a pointer to a memory area defined by IIS that contains the event information.

The two examples, Obtaining Server Variables, and Adding to a Response Header, demonstrate the use of HTTPFilterProc.

One important factor in processing events is the order in which they are processed. While there are a number of factors that can have an impact on this order, Summary of Event Ordering provides a general outline of the issues involved.

Terminating the Filter

You can provide the TerminateFilter entry point function as a way to gracefully remove any attachments to system resources that your filter may have developed while running. If you do not provide the TerminateFilter entry point, your filter must remove attachments


Summary of Event Ordering

When a request comes and an event notification occurs, each filter you registered with high priority for that notification will be called. Next, each filter you registered with medium priority for that notification will be called. Finally, each filter you registered with low priority for that notification will be called. The default priority is low. If you register multiple filters with the same priority, the order is determined by the IISFilters FilterLoadOrder property.

Priority is determined by the nature of the notification. For most events setting a high priority means that the filter should be notified before other filters. For events that involve sending a raw data to the client, however, IIS assumes that a high priority means the filter should be notified just before the client is contacted. As a result, if a filter sets a high priority for the SF_NOTIFY_SEND_RAW_DATA event, the filter will be notified after filters with a medium or low priority have been notified.

If you have a filter that is notified of multiple events, you can not set different priorities for each notification within that filter. You establish the filter priority once and the priority applies to all the event notifications within the filter.

The following sequence is the order of events if filters are not loaded that can impact the order of processing.

  1. When a client sends a request, one or more SF_NOTIFY_READ_RAW_DATA notifications will occur. Data will be read until the client has sent all of the HTTP headers associated with the request.
  2. A single SF_NOTIFY_PREPROC_HEADERS notification will occur for each request. This notification indicates that the server has completed pre-processing of the headers associated with the request.
  3. An SF_NOTIFY_URL_MAP notification will occur after the server has converted the URL associated with the request into a physical path on the server. Note that this event may occur for subsequent requests during a single session.
  4. An SF_NOTIFY_AUTHENTICATION notification will occur only on the first request made over a session. If keep-alive is negotiated between the client and server, the client may submit many requests over the session. This notification will not occur for any such subsequent requests.
  5. If the client is sending POST data with the request, and all of the data was not read in the first step, one or more SF_NOTIFY_READ_RAW_DATA notifications will occur here. Data will be read until either 48K of data is received from the client, or until all of the data is read, whichever occurs first. The 48K read size is typical, but it may be varied. For example, if the MD_UPLOAD_READAHEAD_SIZE in the metabase has been set to a value other than 48k, IIS will attempt to read that amount of data. Other factors can impact how much the server reads so filters should not rely on this exact behavior.
  6. The request is handled. This may be done by an ISAPI extension, a CGI application, a script engine (such as ASP, PERL, and so on), or by IIS itself for static files. If the handler calls ReadClient to continue reading POST data beyond 48K, one or more additional SF_NOTIFY_READ_RAW_DATA notifications will occur.
  7. The SF_NOTIFY_SEND_RESPONSE event occurs after the request is handled and before headers are sent back to the client. This event only occurs if the ISAPI extension uses HSE_REQ_SEND_RESPONSE_HEADER to send headers to the client..
  8. As the request handler returns data to the client, one or more SF_NOTIFY_SEND_RAW_DATA notifications will occur. If the handler is an ISAPI extension, each notification will correspond to either a call from the extension to ServerSupportFunction (with either HSE_REQ_SEND_RESPONSE_HEADER or HSE_REQ_SEND_URL_REDIRECT_RESP), or a call from the extension to WriteClient.
  9. At the end of each request, the SF_NOTIFY_END_OF_REQUEST notification occurs. See the notes below for an exception case where this notification does not occur.
  10. After the HTTP request has been completed, the SF_NOTIFY_LOG notification occurs just before the server writes the request to the log.
  11. When the connection between the client and server is closed, the SF_NOTIFY_END_OF_NET_SESSION notification occurs. If keep-alive has been negotiated, it is possible that many HTTP requests occur before this notification occurs.

Some factors which can change this order of events are described in Exceptions to the Event Sequence.

Exceptions to the Event Sequence

ISAPI filters may interrupt or modify the sequence of event notifications. The order of events described in Summary of Event Ordering occurs if no ISAPI filters are installed that change the event sequence. ISAPI filters can modify the behavior of IIS and, therefore, the way the requests are handled. For example, if you return SF_STATUS_REQ_FINISHED from an SF_NOTIFY_PREPROC_HEADERS handler, SF_NOTIFY_URL_MAP will not be called for that request, although some subsequent notifications, such as SF_NOTIFY_END_OF_NET_SESSION, will still be called.

The following points summarize some factors that can change the order of event processing.

  • The SF_NOTIFY_ACCESS_DENIED event notification occurs if a 401 response is sent to the client. With this notification the order of events will change. The next event will be SF_NOTIFY_END_OF_REQUEST.
  • The SF_NOTIFY_URL_MAP event notification can occur multiple times on a single request, occasionally with an empty string for the pszURL member. One known cause of this is a call to ServerSupportFunction with HSE_REQ_MAP_URL_TO_PATH, or with SF_REQ_MAP_URL_TO_PATH if the call is from a filter.
  • If NTLM authentication is being negotiated, there are typically 3 requests and responses between the client and server. The SF_NOTIFY_END_OF_REQUEST notification will not occur on the second request when IIS responds to the client with a challenge. All other notifications occur as expected on this second request and response. For this reason, you should not rely on this notification as a signal to free any memory allocated elsewhere in your filter unless you know NTLM authentication is not being used.
  • SF_NOTIFY_SECURE_PORT and SF_NOTIFY_NONSECURE_PORT are not notifications. They are flags that modify when a given filter will be called. If a filter registers in GetFilterVersion for SF_NOTIFY_SECURE_PORT, its HttpFilterProc function will only be called for requests made over the servers secure HTTP port (i.e., SSL and PCT requests). If SF_NOTIFY_NONSECURE_PORT is registered, HttpFilterProc will get called for requests over the server's non-secure HTTP port. The flags may be combined to allow the HttpFilterProc to be called for all requests.
  • You can use SF_NOTIFY_DISABLE_NOTIFICATIONS to disable expensive notifications if your filter no longer needs to be notified of an event.


Obtaining Server Variables

Server variables provide information about the HTTP server environment. Frequently an ISAPI filter will need to determine the value of a server variable before it can process event information. The following code would return the value of the SERVER_PORT_SECURE server variable.

DWORD WINAPI
HttpFilterProc(
  PHTTP_FILTER_CONTEXT pfc,
  DWORD NotificationType,
  LPVOID pvNotification
)
{
    HTTP_FILTER_PREPROC_HEADERS *pHeaders =
    pvNotification;
    char szServerName[1024], szUrl[1024], szSecure[2],
    szLocationHeader[1034], szRequest[1024];
    DWORD dwBuffSize;
    dwBuffSize = 1024;
    pfc->GetServerVariable(pfc, "URL", szRequest, &dwBuffSize);
    // Determine if request was sent over secure port
    dwBuffSize = 2;
    pfc->GetServerVariable(pfc, "SERVER_PORT_SECURE", szSecure,
    &dwBuffSize);
        if (szSecure[0] == '1')    // Request is on a secure port,
        do not process further
            return SF_STATUS_REQ_NEXT_NOTIFICATION;
            dwBuffSize = 1024;
            pfc->GetServerVariable(pfc, "SERVER_NAME",
            szServerName, &dwBuffSize);
            // pfc->GetServerVariable(pfc, "HTTP_HOST",
            szServerName, &dwBuffSize);
            dwBuffSize = 1024;
            pHeaders->GetHeader(pfc, "url", szUrl, &dwBuffSize);

               wsprintf(szLocationHeader, "Location:
               https://%s%s\r\n\r\n", szServerName, szUrl);
               pfc->AddResponseHeaders(pfc, szLocationHeader, 0);

               pfc->ServerSupportFunction(pfc,
               SF_REQ_SEND_RESPONSE_HEADER, "302 Object Moved",
               (DWORD)"Please resubmit the request using a secure
               port.", 0);

               return SF_STATUS_REQ_FINISHED;
}


Adding to a Response Header

One use of ISAPI filters is to modify a response header before IIS sends it to the client. For example, you might want to modify the expires value. The following code illustrates how to accomplish this.

BOOL WINAPI GetFilterVersion(PHTTP_FILTER_VERSION pVer)
{
    pVer->dwFilterVersion = HTTP_FILTER_REVISION;
    lstrcpy(pVer->lpszFilterDesc, "Filter Template");
    pVer->dwFlags = SF_NOTIFY_ORDER_DEFAULT | SF_NOTIFY_URL_MAP;

    return TRUE;
}

DWORD WINAPI HttpFilterProc(PHTTP_FILTER_CONTEXT pfc, DWORD NotificationType, LPVOID pvNotification)
{
    HTTP_FILTER_URL_MAP *pUrlMap = (HTTP_FILTER_URL_MAP *)pvNotification;
    LPSTR szPtr1;

    // Find the extension of the requested file
    szPtr1 = strrchr(pUrlMap->pszPhysicalPath, '.');

    // If this is a JPG, add an expires header
    if (szPtr1)
    {
        szPtr1++;
        if (!lstrcmpi(szPtr1, "jpg"))
            pfc->AddResponseHeaders(pfc, "Expires: 0\r\n", 0);
    }

    return SF_STATUS_REQ_NEXT_NOTIFICATION;
}

For a complete working sample program that modifies a response header, see Developer Samples.


Adding a Filter

You can install multiple filters in IIS. The notification order is based on the priority you specified in the filter. If you have set two filters to the same priority for a particular event, the order the filters were loaded into memory determines which filter is notified first. You can configure the IISFilters object in the metabase to determine the load order.

In previous versions of IIS, all filters were notified of events they had registered for, regardless of which IIS service was involved. In IIS 4.0 and later versions, filters can be set either globally or they can be configured to only receive notifications for events that take place within a particular service. For example, you can configure a filter to apply only to FTP events, or only to Web events.

Filters can be added to a Web Site either programmatically or with the Internet Service Manager snap-in to the Microsoft Management Console. Information on adding a filter with the Internet Service Manager is available in the Installing and ISAPI filter topic.

The following script demonstrates adding a filter to a Web Site with a script.

<%
Dim CurrServer
Set CurrServer = GetObject("IIS:/LocalHost/W3svc/Filters")
CurrServer.Create("IIsFilter", "MyFilter")
CurrServer.SetInfo

%>

A more complete example is provided in the \Inetpub\iissamples\sdk\admin sub-directory.


Developer Notes for ISAPI Filters

ISAPI filters provide you with a versatile tool for extending IIS functionality to meet your special requirements. There are some important issues you should consider in developing your filter. The following notes provide some general guidelines summarizing these issues.

  • Do not process POST data within an ISAPI filter:

    When IIS receives POST data from the client, it only reads as much as it needs to get the headers. After all of the other pre-request handler notifications are called, the server reads up to 48K more of the POST data, and then handles the request. If you need to process POST data, you should do so in an ISAPI extension, an ASP application, or with other methods that do not affect performance.

  • Use care in changing the physical path in the SF_NOTIFY_URL_MAP notification:

    When changing the pszPhysicalPath member in the HTTP_FILTER_URL_MAP structure, you should not change the type of the file. For example, if the original path was to a static file, such as an .htm file, do not change the path to an .asp file. The request will still be handled as a static file and the effect will be that the raw .asp file is returned to the client. If you need to make this type of redirection, you should modify the URL in SF_NOTIFY_PREPROC_HEADERS.

  • Use SF_NOTIFY_AUTHENTICATE only to map credentials to a Windows NT® account:

    You only call the SF_NOTIFY_AUTHENTICATE event notification when a network session is created. You can make requests over an existing session, but for these, this notification will not be called. You should not rely on this code to deny access for any reason; denial will not happen, and a security hole will result. If you need to do such processing on a per request basis, you should implement the code in an SF_NOTIFY_PREPROC_HEADERS handler. The only reliable action you can take in during SF_NOTIFY_AUTHENTICATE is to assign specific values to pszUser and pszPassword.

  • Do not process requests in ISAPI filters:

    You use ISAPI filters to modify IIS behavior and, because of this, you can potentially call them many times for each request that is made to the server. In most cases, an ISAPI filter should only return data to the client when it handles an exception case (when the request is denied, for example).

    If you need to do extended processing and do not wish to expose a URL to the client that reveals the nature of the component that will be handling the request, create a handler for SF_NOTIFY_PREPROC_HEADERS. Within that handler, modify the requested URL to point to an ISAPI extension to do the work. For example, if you would like to create a proxy to dispatch the request to another server, create an ISAPI extension to communicate with the proxy. Then, use the pre-processing headers filter to change the URL so that it points to the extension you created. If you need to, pass any special information (such as the original URL in the above example) to the extension through the query string.

  • Register for SF_NOTIFY_END_OF_NET_SESSION

    You should register most of your filters for the end of session event, as it is a good time to perform resource maintenance, such as recycling buffers. For performance reasons, most filters keep a pool of filter buffers and only allocate or free them when the pool becomes empty or too large to save on the overhead of the memory management. The end of session event is also an opportune time to recycle any buffers that were used by a client request.

  • Use AllocMem callback function with care

    You can use the Allocmem callback function with the HTTP_FILTER_CONTEXT structure to allocate memory. The memory that is allocated will automatically be freed when the communication with the client is terminated. Managing memory in this way can have a negative impact on performance, since Allocmem results in a heap allocation. It may be preferable to create your own memory pool and only adjust the pool as necessary. This will reduce the overhead caused by allocating and de-allocating memory.

  • Do not register for an event unless you need to

    You should only register your filters to be notified of those events that it needs for processing. Some filter notifications are very expensive in terms of CPU resources and I/O throughput, and can have a significant effect on the speed and scalability of IIS.

  • Limit the scope of filters that read raw data to isolated applications

    If you create a filter that registers for the SF_NOTIFY_READ_RAW_DATA event, you should limit this filter's scope so that it only applies to those applications where it is critical to read the raw data. Implementing a filter that reads raw data introduces some additional complexities. An example of a filter that reads raw data is provided in the \Inetpub\iissamples\sdk\isapi\filters directory. See the Cookie Conversion Filter in the ISAPI Examples section of Developer Samples for more information.

    Filters that register for the SF_NOTIFY_READ_RAW_DATA or SF_NOTIFY_SEND_RAW_DATA events must be applied at the Web Service level. They can not be applied to an individual Web Site. For more information on applying filters see Installing ISAPI Filters in Configuring Applications.

You can add an ISAPI filter programmatically using the IIS Admin Objects. Filters can be added to either the WWW service or to an individual Web site. To add a filter you must first create an IIsFilters object. IIsFilters is a container object that you can populate with IIsFilter objects.

For example, the following script would add an IIsFilters object to the WWW service. Note that a Filters object is created for the WWW service when IIS is installed. For an individual Web site you may need to create this object before you can use it.

Dim FiltersObj
Dim LoadOrder

Set FiltersObj = GetObject("IIS://LocalHost/W3SVC/Filters")
LoadOrder = FiltersObj.FilterLoadOrder
If LoadOrder = "" Then
    LoadOrder = LoadOrder & ","
End If
LoadOrder = LoadOrder & "myFilter"
FiltersObj.FilterLoadOrder = LoadOrder
FiltersObj.SetInfo

Once you have established the IIsFilters container object, you can add your IIsFilter object and set its properties.

For example, the following script adds a new IIsFilter, myFilter, and sets the path and description.

Dim FilterObj
Dim FilterName

FilterName = "myFilter"
FilterPath = "C:\iisfilts\myfilter.dll"
FilterDesc = "This is my filter"

Set FilterObj = FiltersObj.Create("IIsFilter", FilterName)
FilterObj.FilterPath = FilterPath
FilterObj.FilterDescription = FilterDesc
FilterObj.SetInfo

For a working example of an administrative script that adds a filter, see Additional Admin Script Examples in the Developer Samples. For more information on the Admin Objects see IIS Admin Objects.


Filter Reference

You can build ISAPI filters with two types of functions. IIS calls entry point functions when it loads and unloads the filter, or when notifying the filter of requested events. Callback functions are used by the filter to communicate with IIS. Callback functions are determined by the HTTP_FILTER_CONTEXT structure.


Entry Point Functions

Every ISAPI filter must provide two functions, GetFilterVersion and HTTPFilterProc. These functions are entry points that will be called by IIS when the server loads the filter. Filters may also export the TerminateFilter function, which will be called when the filter shuts down.


GetFilterVersion

The GetFilterVersion function is the first entry point for an ISAPI filter called by IIS. The function tells IIS the version of ISAPI that was used to compile the filter.

BOOL WINAPI GetFilterVersion(
  PHTTP_FILTER_VERSION pVer
);

Parameters

pVer
Points to the HTTP_FILTER_VERSION structure that contains both the version information for the server and members for the client to indicate version number, notifications, and priority desired. There is also a space for the filter application to register a description of itself.

Return Values

Returns FALSE if the filter will be unloaded and will not receive any notifications.

Remarks

The GetFilterVersion function, implemented in the ISAPI filter, is the first entry point called by IIS. It is important to specify only the necessary notifications in the pointer to the dwFlags member.

In addition to the notification flags described under the HttpFilterProc function, there are also priority flags to specify the order in which to call the filter. Valid values can be found in the HTTP_FILTER_VERSION structure

See Also

HttpFilterProc, HTTP_FILTER_VERSION


HttpFilterProc

IIS calls the HttpFilterProc entry point for each event notification which the filter has registered. IIS uses this function to pass information to the ISAPI filter regarding the notification. The filter uses this information to respond to the event.

DWORD WINAPI HttpFilterProc(
  PHTTP_FILTER_CONTEXT pfc,
  DWORD notificationType,
  LPVOID pvNotification
);

Parameters

pfc
Points to the HTTP_FILTER_CONTEXT structure that contains context information.
notificationType
Indicates the type of event being processed. Following are the valid types:
Value | Meaning
SF_NOTIFY_AUTHENTICATION | The server is authenticating the client. This event only occurs during authentication of a net session. For example, if a keep-alive request has been negotiated and the client makes multiple requests on the same socket, this notification will not occur once the initial authentication has been completed. This notification is only for Anonymous and Basic authentication requests. Windows NT® Challenge/Response requests are handled internally by the server.
SF_NOTIFY_END_OF_REQUEST | Notify the application that the filter is called at the end of every request, thus allowing the filter to clean up resources on a per-request basis. The network connection will remain open when the notification is called.
SF_NOTIFY_SECURE_PORT | Notify the application only for sessions over a secure port.
SF_NOTIFY_NONSECURE_PORT | Notify the application only for sessions over a nonsecure port.
SF_NOTIFY_READ_RAW_DATA | Allow the application to see the raw data. The data returned will contain both headers and data. This notification may be called more than one time by a single request. Notifications for multiple requests may be made on the same pfc if the client and server have agreed to a keep-alive request.
SF_NOTIFY_PREPROC_HEADERS | The server has preprocessed the headers. This notification occurs once per request. The HTTP_FILTER_CONTEXT GetServerVariable may not retrieve client headers until this notification has occurred.
SF_NOTIFY_URL_MAP The server is mapping a logical URL to a physical path. The server translates the base URL, but it also translates PATH_INFO into PATH_TRANSLATED. In addition, the ISAPI application may translate the URL.

If a filter retrieves the PATH_TRANSLATED or PATH_INFO server variables within the SF_NOTIFY_URL_MAP notification, the filter will be called recursively with the SF_NOTIFY_URL_MAP notification to do the physical translation for the variable. Care should be taken to prevent endless recursion in this specific scenario.
SF_NOTIFY_SEND_RAW_DATA | The server is sending raw data back to the client. This notification may be called more than one time by a single request. Notifications for multiple requests may be made on the same pfc if the client and server have agreed to a keep-alive request.
SF_NOTIFY_LOG | The server is writing information to the server log. This notification occurs once per response.
SF_NOTIFY_END_OF_NET_SESSION | The session with the client is ending. If a keep-alive request has been negotiated between the client and the server and multiple requests are sent over the same socket, this notification will only occur after the net session is closed.
SF_NOTIFY_ACCESS_DENIED | allows an ISAPI Filter to be notified any time the server is about to return a 401 Access Denied error message. This lets the filter analyze the failure and return a custom message.
SF_NOTIFY_SEND_RESPONSE | This is similar in function to SF_NOTIFY_PREPROC_HEADERS, however it concerns headers that are being sent to the client. A filter can inspect, add, or delete headers the client will receive for a particular request.

pvNotification
The notification-specific structure.
Notification Type | pvNotification points to
SF_NOTIFY_READ_RAW_DATA | HTTP_FILTER_RAW_DATA
SF_NOTIFY_SEND_RAW_DATA | HTTP_FILTER_RAW_DATA
SF_NOTIFY_PREPROC_HEADERS | HTTP_FILTER_PREPROC_HEADERS
SF_NOTIFY_AUTHENTICATION | HTTP_FILTER_AUTHENT
SF_NOTIFY_URL_MAP | HTTP_FILTER_URL_MAP
SF_NOTIFY_LOG | HTTP_FILTER_LOG
SF_NOTIFY_ACCESS_DENIED | HTTP_FILTER_ACCESS_DENIED
SF_NOTIFY_SEND_RESPONSE | HTTP_FILTER_SEND_RESPONSE

Return Values

Returns one of the following values that indicate how the application handled the event.

Value | Meaning
SF_STATUS_REQ_FINISHED | The filter has handled the HTTP request. The server should disconnect the session.
SF_STATUS_REQ_FINISHED_KEEP_CONN | This is the same as SF_STATUS_REQ_FINISHED, except that the server should keep the TCP session open if the option was negotiated.
SF_STATUS_REQ_NEXT_NOTIFICATION | The next filter in the notification chain should be called.
SF_STATUS_REQ_HANDLED_NOTIFICATION | This filter handled the notification. No other handlers should be called for this particular notification type.
SF_STATUS_REQ_ERROR | An error occurred. The server should call GetLastError and indicate the error to the client. The HTTP request will generally be aborted when this status is returned. The client should call SetLastError with the nature of the failure.
SF_STATUS_REQ_READ_NEXT | The filter is an opaque stream filter (encrypted/compressed HTTP requests) and the session parameters are being negotiated. This is valid only for raw-read notification. This notification indicates that the full request has not been received yet and the Web server should issue another read and notify the filter with the additional data read.

Remarks

This is where the core work of the ISAPI filters is done. The various structures pointed to by pvNotification contain data and function pointers specific to these operations. See the structure details for more information.

See Also

HTTP_FILTER_CONTEXT, HTTP_FILTER_RAW_DATA, HTTP_FILTER_PREPROC_HEADERS, HTTP_FILTER_AUTHENT, HTTP_FILTER_URL_MAP, HTTP_FILTER_LOG


TerminateFilter

The TerminateFilter is an entry point exposed by ISAPI filters. This function indicates to the filter that it is going to be removed from memory. When this function is called the filter should close any attachments it has made to system resources.

BOOL WINAPI TerminateFilter(
  DWORD dwFlags
);

Parameters

dwFlags
No values for dwFlags have been identified at this time.


Callback Functions

Callback functions are used by the filter to communicate with IIS. When IIS calls an ISAPI filter's HttpFilterProc, it receives a pointer to an HTTP_FILTER_CONTEXT structure which specifies a callback function. Callback functions can also be specified from the HTTP_FILTER_PREPROC_HEADERS structure.

This section contains the callback functions available to ISAPI filters:

AddHeader

AddResponseHeaders

AllocMem

GetHeader

GetServerVariable

ServerSupportFunction

SetHeader

WriteClient


AddHeader

The AddHeadercallback function adds a header to IIS.

BOOL WINAPI * AddHeader (
  struct _HTTP_FILTER_CONTEXT *pfc,
  LPSTR lpszName,
  LPSTR lpszValue
);

Parameters

pfc
Specifies the filter context for this request from the pfc passed to the HttpFilterProc.
lpszName
Points to the name of the header to add.
lpszValue
Points to the new string to change the header to or to \0 to delete the header.


AddResponseHeaders

The AddResponseHeaders callback function specifies a response header for IIS to send to the client.

BOOL WINAPI * AddResponseHeaders(
  struct _HTTP_FILTER_CONTEXT *pfc,
  LPSTR lpszHeaders,
  LPSTR dwReserved
);

Parameters

pfc
Points to a HTTP_FILTER_CONTEXT structure
lpszHeaders
Points to a string that contains the headers to add. The string should be in the following format: header:value\r\n.
dwReserved
Reserved for future use. This must be zero.

Remarks

AddResponseHeaders() can be used to add headers for client before the server processes the request, but not during or after HTTP_FILTER_SEND_RESPONSE notification. If you need to add a header when the HTTP_FILTER_SEND_RESPONSE notification occurs, you may do so by using the AddHeader member of the HTTP_FILTER_SEND_RESPONSE structure.


AllocMem

The AllocMem callback function allocates memory to a buffer. Any memory allocated with this function will automatically be freed when the net session ends.

BOOL WINAPI * AllocMem(
  struct _HTTP_FILTER_CONTEXT * pfc,
  DWORD cbSize,
  DWORD dwReserved
  );

Parameters

pfc
[in] Points to a HTTP_FILTER_CONTEXT structure.
cbSize
[in] The size of this structure, in bytes.
dwReserved
Reserved for use by the server.


GetHeader

The GetHeader callback function retrieves a header from IIS.

BOOL WINAPI * GetHeader(
  LPSTR lpszName,
  LPVOID lpvBuffer,
  LPDWORD lpdwSize
);

Parameters

lpszName
Points to the name of the header to retrieve.
lpvBuffer
Points to a buffer of size lpdwSize where the value of the header will be stored. This should be set to the size of the buffer lpvBuffer, for example, sizeof(achBuffer). After the call, it contains the number of bytes retrieved including the null terminator. Therefore, for retrieved strings it is equal to strlen(lpvBuffer)+1
lpdwSize
The size of the buffer.

Remarks

Header names should include the trailing colon (:). The special values method, url, and version can be used to retrieve the individual portions of the request line. The special values are case sensitive and should not include the trailing colon


GetServerVariable

The GetServerVariable callback function specifies a server variable that the ISAPI filter needs to retrieve from IIS.

BOOL WINAPI * GetServerVariable(
  struct _HTTP_FILTER_CONTEXT * pfc,
  LPSTR lpszVariableName,
  LPVOID lpvBuffer,
  LPDWORD lpdwSize
);

Parameters

pfc
Points to a HTTP_FILTER_CONTEXT structure.
lpszVariableName
Points to a string that contains the variable to retrieve.
lpvBuffer
Points to the buffer to receive the requested information.
lpdwSize
Points to a DWORD that indicates the size of the buffer pointed to by lpvBuffer. On successful completion, the DWORD contains the size of bytes transferred into the buffer, including the null-terminating byte.


ServerSupportFunction

The ServerSupportFunction callback function is used by ISAPI filters to process the information that was included with the event notification.

BOOL WINAPI * ServerSupportFunction(
  struct _HTTP_FILTER_CONTEXT * pfc,
  enum SF_REQ_TYPE sfReq,
  PVOID pData,
  DWORD ul1,
  DWORD ul2
);

Parameters

pfc
Points to a HTTP_FILTER_CONTEXT structure.
sfReq
Points to a function used to extend the ISAPI filter functions. Parameters are specific to the extensions. The possible values follow:
Value | Meaning
SF_REQ_ADD_HEADERS_ON_DENIAL If the server denies the HTTP request, add the specified headers to the server error response. This allows an authentication filter to advertise its services without filtering every request. Generally, the headers will be WWW-Authenticate headers with custom authentication schemes. However, no restriction is placed on which headers can be specified. IIS will advertise both basic and NTLM, individually and collectively, if they are enabled.

This value should only be set by raw data filters the return SF_STATUS_READ_NEXT
SF_REQ_DISABLE_NOTIFICATIONS | Stops the receipt of notifications of specific events.
SF_REQ_GET_CONNID | Returns the connection ID contained in the connID field of an ISAPI extensions Extension_Control_Block. This value can be used to coordinate shared data between filters and extensions.
SF_REQ_GET_PROPERTY | This value is used to get an IIS property as defined in SF_PROPERTY_IIS.
SF_REQ_NORMALIZE_URL | This value is used to normalize a URL.
SF_REQ_SEND_RESPONSE_HEADER | This sends a complete HTTP server response header including the status, server version, message time, and MIME version. Server extensions should append other information, such as content type and content length, followed by an extra \r\n.
SF_REQ_SET_CERTIFICATE_INFO
Sets an SSPI security context and impersonation token derived from a client certificate.
SF_REQ_SET_NEXT_READ_SIZE
This is used only by raw data filters that return SF_STATUS_REQ_READ_NEXT. It determines the amount of data to be read.
SF_REQ_SET_PROXY_INFO
Indicates that the request came from a proxy.

pData
A zero-terminated string pointing to optional status string (for example, 401 Access Denied) or NULL for the default response of 200 OK.
ul1
A DWORD containing information required by the function. The meaning of the parameter is dependent on SF_REQ_TYPE.
ul2
A DWORD containing information required by the function. The meaning of the parameter is dependent on SF_REQ_TYPE.


SetHeader

The SetHeader callback function is used by ISAPI filters to change or delete the value of a header. The function can be used to change the special values included in the request line.

BOOL WINAPI * SetHeader(
  struct _HTTP_FILTER_CONTEXT * pfc
  LPSTR lpszName,
  LPSTR lpszValue

Parameters

pfc
Points to an HTTP_FILTER_CONTEXT structure.
lpszName
Points to the name of the header to change or delete.
lpszValue
Points to the new string for the header or to \0 to delete the header.


WriteClient

The WriteClient callback function is called by an ISAPI filter to send data to the client.

BOOL WINAPI * WriteClient(
  struct _HTTP_FILTER_CONTEXT * pfc
  LPVOID buffer,
  LPDWORD lpdwBytes,
  DWORD dwReserved
);

Parameters

pfc
Points to an HTTP_FILTER_CONTEXT structure.
buffer
A buffer containing data to send to the client.
lpdwBytes
The size of the buffer pointed to by buffer.
dwReserved
Reserved for future use.


Structures

The following structures are used by ISAPI filters.

HTTP_FILTER_ACCESS_DENIED

HTTP_FILTER_AUTHENT

HTTP_FILTER_CONTEXT

HTTP_FILTER_LOG

HTTP_FILTER_PREPROC_HEADERS

HTTP_FILTER_RAW_DATA

HTTP_FILTER_VERSION

HTTP_FILTER_URL_MAP


HTTP_FILTER_ACCESS_DENIED

IIS includes a pointer to this structure when a user is presented with an Access Denied error message. If your filter should be notified for this event, it should register for the SF_NOTIFY_ACCESS_DENIED event.

typedef struct _HTTP_FILTER_ACCESS_DENIED
{
const CHAR * pszURL;           //Requesting URL
const CHAR * pszPhysicalPath;  //Physical path of resource
DWORD        dwReason;         //Bitfield of SF_DENIED flags
} HTTP_FILTER_ACCESS_DENIED, *PHTTP_FILTER_ACCESS_DENIED

Members

pszURL
The URL that requested access to the resource.
pszPhysicalPath
The physical path of the resource that was requested.
dwReason
A DWORD containing flags that indicate the reasons for the denial. Can be one of the following values.
Value | Meaning
SF_DENIED_LOGON | The client could not be logged on.
SF_DENIED_RESOURCE | The resource was security by a Windows NT® ACL.
SF_DENIED_FILTER | An ISAPI Filter denied the request.
SF_DENIED_APPLICATION | An ISAPI or CGI Application denied the request.
SF_DENIED_BY_CONFIG | The server configuration denied the request. For example, disabling Anonymous requests on the server would generate this filter notification when a user without credentials tried to make a request to the server.

Remarks

This structure indicates that the requested resource has been denied by the server. The structure is generated when there has been a logon failure, or if an ISAPI filter has requested a resource that has an associated Access Control List that does not include the logged on user.

The server will automatically include the supported authentication schemes when an ISAPI extension, filter, or CGI script returns a 401 Access Denied error code.


HTTP_FILTER_AUTHENT

IIS includes a pointer to this structure when it is authenticating a user with either anonymous or Basic authentication schemes. If your filter should be notified for this event, it should register for the SF_NOTIFY_AUTHENTICATION event.

typedef struct _HTTP_FILTER_AUTHENT
{
    CHAR *    pszUser;
    DWORD     cbUserBuff;
    CHAR *    pszPassword;
    DWORD     cbPasswordBuff;
} HTTP_FILTER_AUTHENT, *PHTTP_FILTER_AUTHENT;

Members

pszUser
[in/out] Points to a string containing the user name for this request. An empty string indicates an anonymous user.
cbUserBuff
[in] The size of the buffer pointed to by pszUser. This is guaranteed to be at least SF_MAX_USERNAME.
pszPassword
[in/out] Points to a string containing the password for this request.
cbPasswordBuff
[in] The size of the buffer pointed to by pszPassword. This is guaranteed to be at least SF_MAX_PASSWORD.

Remarks

When the server is about to authenticate the client, this structure is pointed to by the pvNotification parameter in the HttpFilterProc function when the notificationType parameter is SF_NOTIFY_AUTHENTICATION. This can be used to implement a different authentication scheme. The pszUser and pszPassword members contain the information sent by the client. After exiting this function, these values must represent a valid Windows NT® user account and password. IIS will then impersonate this account in order to gain access to resources. If the authentication method used is NTLM the password value will not be available.

See Also

HttpFilterProc


HTTP_FILTER_CONTEXT

This structure is used by HTTP_FILTER_PROC to obtain information about the current request. This structure is very similar in function to an ISAPI extension's EXTENSION_CONTROL_BLOCK.

typedef struct _HTTP_FILTER_CONTEXT
{
    DWORD    cbSize;
    DWORD    Revision;
    PVOID    ServerContext;
    DWORD    ulReserved;
    BOOL     fIsSecurePort;
    PVOID    pFilterContext;
BOOL    (WINAPI * GetServerVariable);
BOOL    (WINAPI * AddResponseHeaders);
BOOL    (WINAPI * WriteClient);
VOID *     (WINAPI * AllocMem);
BOOL    (WINAPI * ServerSupportFunction);
} HTTP_FILTER_CONTEXT, *PHTTP_FILTER_CONTEXT;

Members

cbSize
[in] The size of this structure, in bytes.
Revision
[in] The revision level of this structure. This is less than or equal to the version of the document, HTTP_FILTER_REVISION.
ServerContext
[in] Reserved for server use.
ulReserved
[in] Reserved for server use.
fIsSecurePort
[in] A value of TRUE indicates that this event is over a secure port. A value of FALSE indicates that the event is not over a secure port.
pFilterContext
[in/out] Points to any context information that the filter wants to associate with this request. Any memory associated with this request can be safely freed during the SF_NOTIFY_END_OF_NET_SESSION notification.
GetServerVariable
Points to a function that retrieves information about the server and this connection. For some notifications, some variables may not be defined. An example of this are any notifications which occur before PREPROC_HEADERS, such as the READ_RAW_DATA notification.
AddResponseHeaders
Points to the AddResponseHeaders function that adds a header to the HTTP response.
WriteClient
Points to the WriteClient function that sends raw data back to the client.
AllocMem
Points to the AllocMem function used to allocate memory. Any memory allocated with this function will automatically be freed when the net session ends.
ServerSupportFunction
Points to the ServerSupportFunction function used to extend the ISAPI filter functions. Parameters are specific to the extensions.

See Also

GetServerVariable, AddResponseHeaders, WriteClient, AllocMem, ServerSupportFunction


HTTP_FILTER_LOG

IIS includes a pointer to this structure when it is writing information to a log file. If your filter should be notified for this event, it should register for the SF_NOTIFY_LOG event.

typedef struct _HTTP_FILTER_LOG
{
    const CHAR *    pszClientHostName;
    const CHAR *    pszClientUserName;
    const CHAR *    pszServerName;
    const CHAR *    pszOperation;
    const CHAR *    pszTarget;
    const CHAR *    pszParameters;
    DWORD        dwHttpStatus;
    DWORD        dwWin32Status;
    DWORD        dwBytesSent;
    DWORD        dwBytesRecvd;
    DWORD        msTimeForProcessing;
} HTTP_FILTER_LOG, *PHTTP_FILTER_LOG;

Members

pszClientHostName
[in/out] The client's host name.
pszClientUserName
[in/out] The client's user name.
pszServerName
[in/out] The name of the server to which the client is connected.
pszOperation
[in/out] The HTTP command.
pszTarget
[in/out] The target of the HTTP command.
pszParameters
[in/out] The parameters passed to the HTTP command.
dwHttpStatus
[in/out] The HTTP return status.
dwWin32Status
[in/out] The Win32® error code.
dwBytesSent
[in/out] The number of bytes sent from the server to the client.
dwBytesRecvd
[in/out] The number of bytes received by the server from the client.
msTimeForProcessing
[in/out] The time in milliseconds required to process the client request.

Remarks

When the server is about to log information to the server log file, this structure is pointed to by the pvNotification parameter in the HttpFilterProc function when the notificationType parameter is SF_NOTIFY_LOG. The strings cannot be changed, but pointers can be replaced. If string pointers are changed, the memory they point to must remain valid so that the AllocMem callback function in the HTTP_FILTER_CONTEXT structure can be used.


HTTP_FILTER_PREPROC_HEADERS

IIS includes a pointer to this structure when it is preprocessing a request's headers. If your filter should be notified for this event, it should register for the SF_NOTIFY_PREPROC_HEADERS event.

typedef struct _HTTP_FILTER_PREPROC_HEADERS
{
BOOL    (WINAPI * GetHeader) ;
BOOL    (WINAPI * SetHeader) ;
BOOL    (WINAPI * AddHeader) ;
DWORD    HttpStatus;
DWORD    dwReserved;
} HTTP_FILTER_PREPROC_HEADERS, *PHTTP_FILTER_PREPROC_HEADERS;

Members

GetHeader
Points to the GetHeader function, which retrieves the specified header value. Header names should include the trailing colon (:). The special values method, url, and version can be used to retrieve the individual portions of the request line. The special values are case sensitive and should not include the trailing colon.
SetHeader
Points to the SetHeader function, which changes or deletes the value of a header. The function can be used to change the special values included in the request line.
AddHeader
Points to the AddHeader function to add a header to the response.
HttpStatus
The current Http staus code.
dwReserved
A DWORD reserved for later use.

Remarks

When the server is about to process the client headers, this structure is pointed to by the pvNotification parameter in the HttpFilterProc when the notificationType parameter is set to SF_NOTIFY_PREPROC_HEADERS.

See Also

HttpFilterProc, GetHeader, SetHeader, AddHeader


HTTP_FILTER_RAW_DATA

IIS includes a pointer to this structure when it either reading or sending raw data. If your filter should be notified for this event, it should register for either the SF_NOTIFY_READ_RAW_DATA or SF_NOTIFY_SEND_RAW_DATA events.

typedef struct _HTTP_FILTER_RAW_DATA
{
    PVOID pvInData;
    DWORD cbInData;
    DWORD cbInBuffer;
    DWORD dwReserved;
} HTTP_FILTER_RAW_DATA, *PHTTP_FILTER_RAW_DATA;

Members

pvInData
[in] Points to the data buffer (input or output).
cbInData
[in] The amount of data in the buffer pointed to by pvInData.
cbInBuffer
[in] The size of the buffer pointed to by pvInData.
dwReserved
[in] Reserved for future use.

Remarks

This structure is passed to the SF_NOTIFY_READ_RAW_DATA and SF_NOTIFY_SEND_RAW_DATA notification routines. The pvInData pointer can be replaced by filters that want to modify the raw data being sent or received. cbInData and cbInBuffer should also be appropriately updated if the pointer is replaced. The new buffer memory must remain valid until the end of the request by either using AllocMem or by a buffer owned by the filter. In addition, the filter should not attempt to free or otherwise de-allocate the old pvInData pointer. Only the owner of the memory block is allowed to free the buffer. It is not recommended that filters modify the raw data in place. The memory segment may be read only or the data may be cached directly by an ISAPI extension.

Filters that register for the SF_NOTIFY_READ_RAW_DATA or SF_NOTIFY_SEND_RAW_DATA events must be applied at the Web Service level. They can not be applied to an individual Web site. For more information on applying filters see Installing ISAPI Filters in Configuring Applications.

See Also

HttpFilterProc


HTTP_FILTER_SEND_RESPONSE

ISAPI filters receive this notification immediately prior to sending the headers to the client. The filter can inspect, modify, or add headers the client will receive as part of the response to the client's original request The structure contains the same members as HTTP_FILTER_PREPROC_HEADERS. When a filter has registered for the SF_NOTIFY_SEND_RESPONSE event, the pvNotification parameter of HttpFilterProc will point to this structure.

typedef struct HTTP_FILTER_SEND_RESPONSE;
{
BOOL    (WINAPI * GetHeader) ;
BOOL    (WINAPI * SetHeader) ;
BOOL    (WINAPI * AddHeader) ;
DWORD    HttpStatus;
DWORD    dwReserved;
} HTTP_FILTER_SEND_RESPONSE, *PHTTP_FILTER_SEND_RESPONSE;

Members

GetHeader
Points to the GetHeader function, which retrieves the specified header value. Header names should include the trailing colon (:).
SetHeader
Points to the SetHeader function, which changes or deletes the value of a header. The function can be used to change the special values included in the request line.
AddHeader
Points to the AddHeader function to add a header to the response.
HttpStatus
The current Http staus code.
dwReserved
A DWORD reserved for later use.


HTTP_FILTER_URL_MAP

IIS includes a pointer to this structure when it maps a logical URL to a physical directory. If your filter should be notified for this event, it should register for the SF_NOTIFY_URL_MAP event.

typedef struct _HTTP_FILTER_URL_MAP
{
    const CHAR *    pszURL;
    CHAR *          pszPhysicalPath;
    DWORD           cbPathBuff;
} HTTP_FILTER_URL_MAP, *PHTTP_FILTER_URL_MAP;

Members

pszURL
[in] Points to the URL that is being mapped to a physical path.
pszPhysicalPath
[in/out] Points to the buffer where the physical path is stored.
cbPathBuff
[in] The size of the buffer pointed to by pszPhysicalPath.

Remarks

When the server is about to map the specified URL to a physical path, this structure is pointed to by the pvNotification parameter in the HttpFilterProc when the notificationType parameter is set to SF_NOTIFY_URL_MAP. Filters can modify the physical path in place. When this event occurs it is too late in the server processing to use this filter notification to change a URL for a static file into an ISAPI/CGI request or vice versa. If you need to make this change, you must use the SF_NOTIFY_PREPROC_HEADERS notification and change the URL value to modify the client request.

See Also

HttpFilterProc


HTTP_FILTER_VERSION

This structure is used by GetFilterVersion to obtain the version information about the filter.

typedef struct _HTTP_FILTER_VERSION
{
    DWORD     dwServerFilterVersion;
    DWORD     dwFilterVersion;
    CHAR      lpszFilterDesc[SF_MAX_FILTER_DESC_LEN+1];
    DWORD     dwFlags;
} HTTP_FILTER_VERSION, *PHTTP_FILTER_VERSION;

Members

dwServerFilterVersion
[in] The version of the document used by the server. The version of the current header file is HTTP_FILTER_REVISION.
dwFilterVersion
[out] The version of the document used by the server. The version of the current header file is HTTP_FILTER_REVISION.
lpszFilterDesc
[out] The location in which to store a short string description of the ISAPI filter.
dwFlags
[out] The combination of SF_NOTIFY_* flags to specify the events for which the filter should be notified.
Value | Meaning
SF_NOTIFY_ORDER_DEFAULT | Load the filter at the default priority (recommended).
SF_NOTIFY_ORDER_LOW | Load the filter at a low priority.
SF_NOTIFY_ORDER_MEDIUM | Load the filter at a medium priority.
SF_NOTIFY_ORDER_HIGH | Load the filter at a high priority.

See Also

HttpFilterProc


Developer Samples

Welcome to the Developer Samples. This section is designed to expose you to the power and extensibility of IIS, one step at a time, by using clear and simple examples. ASP scripts, ISAPI extensions and filters, and Active Server components, both installable and custom, are included in the samples provided.

These samples have been organized by type and placed in the directories specified below. For each script sample, you will find an HTML page that provides an overview of the sample, as well as the script and any supporting files, such as database or text files. Each ActiveX™ and ISAPI project is placed in its own subdirectory, also with an HTML overview page.

For more information, see %mssdk%\Samples\Internet\IIS\Readme.htm.

ASP Script Examples

Sample scripts are located in the following directories, organized by topic.

%mssdk%\Samples\Internet\IIS\asp\simple
%mssdk%\Samples\Internet\IIS\asp\applications
%mssdk%\Samples\Internet\IIS\asp\interaction
%mssdk%\Samples\Internet\IIS\asp\components
%mssdk%\Samples\Internet\IIS\asp\database
%mssdk%\Samples\Internet\IIS\asp\transactional
%mssdk%\Samples\Internet\IIS\asp\queuing

ISAPI Examples

All Microsoft® Visual C++® project files are provided for each sample ISAPI filter and extension.

%mssdk%\Samples\Internet\IIS\isapi\filter\Authfilt
%mssdk%\Samples\Internet\IIS\isapi\filter\CkyMunge
%mssdk%\Samples\Internet\IIS\isapi\filter\UpCase
%mssdk%\Samples\Internet\IIS\isapi\extensions\simple
%mssdk%\Samples\Internet\IIS\isapi\extensions\com
%mssdk%\Samples\Internet\IIS\isapi\extensions\Keep-Alive
%mssdk%\Samples\Internet\IIS\isapi\extensions\WorkerThread
%mssdk%\Samples\Internet\IIS\isapi\extensions\KeepAliveWithThreads
%mssdk%\Samples\Internet\IIS\isapi\extensions\ServerVariables
%mssdk%\Samples\Internet\IIS\isapi\extensions\Redirect
%mssdk%\Samples\Internet\IIS\isapi\extensions\IO
%mssdk%\Samples\Internet\IIS\isapi\extensions\Formdump
%mssdk%\Samples\Internet\IIS\isapi\extensions\CGIWrap
%mssdk%\Samples\Internet\IIS\isapi\extensions\Chunk

Component Examples

All Microsoft® Visual Basic® 5.0, Visual C++, and Microsoft® Visual J++™ project files are provided for each sample Active Server component.

%mssdk%\Samples\Internet\IIS\components\vb\simple
%mssdk%\Samples\Internet\IIS\components\vb\intermediate
%mssdk%\Samples\Internet\IIS\components\c++\simple
%mssdk%\Samples\Internet\IIS\components\c++\intermediate
%mssdk%\Samples\Internet\IIS\components\java\samples

Admin Script Samples

These sample administrative scripts can be executed using the Windows Scripting Host (WSH).

%mssdk%\Samples\Internet\IIS\admin


Topic Not Found

No matching topic was found. Some possible reasons and remedies are as follows:

  • The file (.chm) that contains the destination topic is not in the expected location.

Remedy: Rerun the MSDN Library Setup.

  • The file (.chm) that contains the current topic or destination topic is out-of-date and the link is no longer valid.

Remedy: Install the latest version of the MSDN Library.

  • The MSDN Library CD is not in the CD-ROM drive.

Remedy: Insert the MSDN Library CD into the CD-ROM drive.


OnEndPage

When the server finishes processing script on an ASP page, it calls the OnEndPage method for all objects, except those of application scope, on that page that implemented this method.

You must use the OnEndPage method to free copies of objects stored by the OnStartPage method and any other resources that do not need to persist beyond current script processing.


OnStartPage

When a user requests a Web page in an ASP application, the server calls the OnStartPage method for all objects (except those with application scope) on that page. This call occurs before the server processes the script.

You can use the OnStartPage method to use the ScriptingContext class to retrieve pointers to the built-in objects. Your object can then use the built-in objects to access its collections, methods and properties. Using OnStartPage and ScriptingContext to retrieve and use built-in objects and their methods, instead of passing built-in objects as parameters, makes your object easier to use in ASP scripts. However, it is recommended that your component access the built-in objects by using the ObjectContext as described above.

For more information about the built-in object interfaces, see C++ Interfaces, Java Class and Interface Definitions, or Visual Basic Object Model, depending on the programming language you intend to use.

For more information about the built-in objects, see Built-in ASP Objects Reference.